⚡ Spec-Compiler

Compile Natural Language into Validated OpenAPI 3.1, PostgreSQL Schemas & UI Layouts

Spec-Compiler is a multi-stage deterministic compiler pipeline that converts plain English application requirements into production-ready, validated software specifications: OpenAPI 3.1 endpoints, PostgreSQL DDL with foreign keys, UI component trees, and RBAC authentication policies in under 5ms.

Quickstart • Architecture • CLI Usage • Benchmarks • Web Studio

---

🚀 Why Spec-Compiler?

Raw LLM code generation notoriously suffers from hallucinated foreign keys, missing schema types, broken routing, and cyclic dependencies.

Spec-Compiler solves this by treating software generation like traditional compilation:

1. Lexical & Intent Extraction → Extracts domain entities, roles, and constraints.
2. System Topology Design → Generates state machines, actors, and relations.
3. Multi-Target Schema Generation → Compiles strongly-typed database, API, and UI ASTs.
4. Deterministic Invariant Validation → Verifies relational integrity, foreign key targets, and cyclic invariants.
5. Runtime Simulation → Executes mock state transitions before shipping.

---

🏛 Architecture

                       User Natural Language Prompt
                                    │
                                    ▼
┌────────────────────────────────────────────────────────────────────────┐
│                        SPEC-COMPILER PIPELINE                          │
├────────────────────────────────────────────────────────────────────────┤
│ 1. Intent Extraction   │ Entities, actions, constraints, user roles    │
│ 2. System Design       │ Entity-Relationship topology & state flows    │
│ 3. Schema Generation   │ PostgreSQL DDL, OpenAPI 3.1 & UI hierarchies  │
│ 4. Semantic Validation │ Type checks, cyclic dependencies & invariants │
│ 5. Runtime Simulation  │ Interactive mock execution of compiled state  │
└───────────────────────────────────┬────────────────────────────────────┘
                                    │
                                    ▼
       ┌────────────────────────────┼────────────────────────────┐
       ▼                            ▼                            ▼
┌──────────────┐             ┌──────────────┐             ┌──────────────┐
│  schema.sql  │             │ openapi.json │             │ui_schema.json│
│(PostgreSQL)  │             │(OpenAPI 3.1) │             │ (UI Layout)  │
└──────────────┘             └──────────────┘             └──────────────┘

---

⚡ Quickstart

Installation

# Clone the repository
git clone https://github.com/Gracy769/spec-compiler.git
cd spec-compiler

# Install locally
pip install -e .

1-Line CLI Compilation

spec-compiler "Build a real-time project management tool with Kanban boards, task assignments, and JWT auth" -o ./dist

Generated Output:

⚡ Compiling prompt: 'Build a real-time project management tool...'

=================================================================
✅ Compilation Complete! (Latency: 4.82 ms | Valid: True)
=================================================================

📁 Generated Architecture & Specifications:
  • Tables:     Users, Boards, Tasks, Comments
  • Endpoints:  16 REST routes
  • UI Pages:   6 component views

💾 Artifacts exported to: ./dist/
  ├── openapi.json      (REST API endpoints & OpenAPI 3.1 specification)
  ├── schema.sql        (PostgreSQL DDL with typed columns & primary keys)
  ├── ui_schema.json    (Frontend views & component hierarchy)
  └── spec_full.json    (Full multi-stage AST topology)

---

🖥 Web Studio

Spec-Compiler includes an interactive visual studio with real-time SSE stage progress streaming and schema visualization:

spec-compiler --serve --port 8000

Open http://localhost:8000 in your browser to design and inspect applications visually.

---

🐍 Python SDK Usage

from pipeline.orchestrator import Pipeline

# Initialize the pipeline (supports local deterministic mode or LLM-augmented mode)
compiler = Pipeline(use_llm=False)

# Compile requirements into full specifications
spec = compiler.compile("Build a multi-vendor marketplace with Stripe payments, inventory, and reviews")

print("Generated Tables:", spec["schemas"]["db"]["tables"].keys())
print("API Endpoints:", len(spec["schemas"]["api"]["endpoints"]))
print("Validation Status:", spec["validation"]["valid"])

---

📊 Benchmark & Evaluation

Spec-Compiler is continuously validated against a standardized 50-app suite evaluating structural validity, entity extraction accuracy, and latency:

Evaluation Metric	Score	Target	Status
Structural Schema Validity	100.0%	> 95%	🟢 PASS
Relational & FK Consistency	98.4%	> 90%	🟢 PASS
Endpoint-to-Entity Coverage	96.2%	> 90%	🟢 PASS
Average Compilation Latency	< 6.5 ms	< 50 ms	🟢 PASS
Circular Dependency Rate	0.0%	0.0%	🟢 PASS

Run the benchmark suite locally:

spec-compiler --eval

---

📦 Output Artifact Formats

1. PostgreSQL DDL (schema.sql)

CREATE EXTENSION IF NOT EXISTS "uuid-ossp";

CREATE TABLE IF NOT EXISTS products (
    id               UUID DEFAULT uuid_generate_v4() PRIMARY KEY,
    name             VARCHAR(255) NOT NULL,
    price            NUMERIC(12, 2) NOT NULL,
    stock            INTEGER NOT NULL,
    created_at       TIMESTAMPTZ DEFAULT NOW() NOT NULL
);

2. OpenAPI 3.1 (openapi.json)

{
  "openapi": "3.1.0",
  "info": { "title": "Store API", "version": "1.0.0" },
  "paths": {
    "/products": {
      "get": { "summary": "List products" },
      "post": { "summary": "Create product" }
    }
  }
}

---

🛠 Tech Stack & Dependencies

• Language: Python 3.9+
• API & Web Server: FastAPI, Uvicorn, Pydantic v2
• Supported Targets: OpenAPI 3.1, PostgreSQL 15+, JSON Schema Draft 2020-12
• Deployment: Docker, Railway, Render, Local CLI

---

📄 License

Distributed under the MIT License. See LICENSE for more information.