SpecForge — Natural Language → AppSpec Pipeline

SpecForge converts a plain-English app description into a fully validated, machine-readable application specification in seconds. Describe what you want to build; the pipeline extracts intent, generates a relational data schema, and produces a complete AppSpec — pages, API endpoints, auth rules, integration hooks, and workflow stubs — ready for a downstream code generator to consume.

---

Quick Start

git clone <your-repo-url>
cd AI_Final-main
cp .env.example .env.local   # fill in at least one provider key
npm install
npm run dev

Open http://localhost:3000. The app is live. You need at minimum one API key — the pipeline auto-routes to whatever providers are available.

Total time from clone to running: under 3 minutes.

---

Environment Variables

Create .env.local in the project root. All keys are optional — the gateway skips providers with no key configured and falls back automatically.

# Fast / cheap models — intent extraction
OPENAI_API_KEY=          # GPT-4o, GPT-4o-mini
GROQ_API_KEY=            # Llama 3.1 8B, Llama 3.3 70B, Mixtral (recommended — fast & free tier)
MISTRAL_API_KEY=         # Mistral Small, Mistral Large
NVIDIA_API_KEY=          # Llama / Mistral via NVIDIA NIM (free tier available)

# Capable models — schema & appspec generation
GEMINI_API_KEY=          # Gemini 1.5 Flash, Gemini 1.5 Pro
DEEPSEEK_API_KEY=        # DeepSeek Chat (strong on structured output)

# Universal fallback — kicks in on 429 / 5xx from primary providers
OPENROUTER_API_KEY=      # Llama, Mistral, Gemma via OpenRouter (free models available)

---

Pipeline Architecture

User Prompt
     │
     ▼
┌─────────────────────┐
│  Stage 1 · Intent   │  Fast model (Groq Llama / GPT-4o-mini / Mistral Small)
│  Extraction         │  → AppIntent: appName, appType, features, entities,
└────────┬────────────┘    integrations_requested, assumptions
         │ Validation ──► Repair Engine (structural / field / consistency)
         ▼
┌─────────────────────┐
│  Stage 2 · Schema   │  Capable model (Llama 3.3 70B / GPT-4o / DeepSeek)
│  Generation         │  → DataSchema: EntitySchema[], relations, tenantId
└────────┬────────────┘
         │ Validation ──► Repair Engine
         ▼
┌─────────────────────┐
│  Stage 3 · AppSpec  │  Capable model (same tier, can differ by provider)
│  Generation         │  → AppSpec: pages, apiEndpoints, authRules,
└────────┬────────────┘    integrationHooks, workflowStubs
         │ Validation ──► Repair Engine
         ▼
     AppSpec Output  ──► SSE stream to frontend in real time

Model Routing

Routing is config-driven in src/pipeline/config.ts — no model names are hardcoded in stage implementations. Each stage has a primary model, an ordered fallback list, and a repair model:

Stage	Primary	Fallbacks
Intent Extraction	Groq Llama 3.1 8B	NVIDIA Llama, Mistral Small, GPT-4o-mini, OpenRouter
Schema Generation	Groq Llama 3.3 70B	GPT-4o, NVIDIA Mixtral, Gemini Pro, DeepSeek, OpenRouter
AppSpec Generation	Groq Llama 3.3 70B	GPT-4o, NVIDIA Mixtral, Gemini Pro, DeepSeek, OpenRouter
Repair	GPT-4o-mini	OpenRouter Llama, NVIDIA Llama, Mistral Small

OpenRouter is the universal fallback — if a primary provider returns 429 or 5xx, the gateway retries via OpenRouter automatically.

Repair Engine

Three classified strategies — not blind retries:

• Structural — malformed or truncated JSON. Balances braces, strips markdown fences, fills typed defaults for terminal missing keys.
• Field — missing or wrongly typed field. Supplies a default or re-prompts that field in isolation with a narrow correction prompt.
• Consistency — broken cross-layer reference (page references non-existent entity, workflow stubs unregistered integration). Resolved programmatically where deterministic; re-prompted only if not.

Every repair attempt is logged: strategy applied, error input, outcome (repaired | escalated | failed).

---

API Reference

Method	Endpoint	Description
POST	/api/generate	Submit prompt → returns { jobId }
GET	/api/generate/:jobId/stream	SSE stream — stage_start, stage_complete, stage_failed, generation_complete. Replays on reconnect.
GET	/api/generate/:jobId	Full job status, AppSpec output, repair log, cost breakdown, latency per stage
POST	/api/generate/:jobId	Manually trigger repair — body { stage, errorHint }
GET	/api/integrations	Full integration registry
GET	/api/health	Health check

---

Integration Registry

14 integrations registered. 7 fully implemented with correct trigger descriptors, action schemas, and payload shapes. 7 stubbed with complete interfaces — a developer can implement the actual HTTP call from the stub alone.

Fully Implemented

Integration	Auth	Key Triggers	Key Actions
Slack	OAuth2	record_created, status_changed	send_message, send_dm, post_block
Salesforce	OAuth2	crm_synced	create_lead, update_contact, create_opportunity
WhatsApp (Twilio)	API Key	user_action	send_template, send_notification
Gmail / Google Workspace	OAuth2	record_event	send_email, create_calendar_event, update_sheet
Stripe	API Key	payment_event	create_customer, create_charge, manage_subscription
Webhook (Generic)	HMAC Secret	any	post_payload (with HMAC signature)
Zapier	Webhook	any	send_structured_payload

Stubbed (interface complete, HTTP call not implemented)

HubSpot · Notion · Airtable · Twilio SMS · Google Sheets · Jira · GitHub

Integration hooks in the AppSpec reference integration IDs from this registry. A hook referencing an unregistered ID or invalid action is a validation error — caught before the output is passed downstream.

---

Frontend

• Prompt input — plain-English description with Cmd+Enter submit
• Eval suite chips — all 7 standard + 5 edge-case prompts one-click
• Pipeline progress — real-time stage status via SSE (running / complete / failed), model used, latency, cost per stage
• AppSpec output panel — Intent tab, Schema tab (entities as collapsible field tables), AppSpec tab (pages as HTML table, API endpoints as HTML table, auth rules, workflow stubs, integration hooks)
• Validation & Repair panel — live errors, repair log with strategy and outcome
• Integration panel — full registry with triggers and actions
• Download JSON — exports { appIntent, dataSchema, appSpec } as a single JSON file

---

Running the Evaluation Suite

npm run eval

Runs all 12 prompts (7 standard + 5 edge cases) and writes results to evaluation-log.json in the project root. Each entry includes: success, stage that failed (if any), repair strategy used, retry count, latency (ms), estimated token cost, integrations correctly detected.

---

Stack

• Frontend — Next.js 15, React 19, TailwindCSS 4
• Backend — Next.js API routes, TypeScript strict mode
• Validation — Zod schemas for every pipeline stage output
• Streaming — Native SSE via Next.js Route Handlers
• No database — in-memory job store (replace with Redis/Postgres for production)

---

What Is and Isn't Implemented

Feature	Status
3-stage pipeline (intent → schema → appspec)	✅
Zod validation after every stage	✅
Repair engine — 3 classified strategies	✅
SSE streaming with event replay	✅
Config-driven model routing	✅
7+ provider support	✅
OpenRouter as universal fallback	✅
Cost logging per stage	✅
Integration registry (14 integrations)	✅
Workflow stubs with typed payload maps	✅
Manual repair endpoint	✅
Evaluation runner (12 prompts)	✅
Live OAuth flows for integrations	❌ Stubbed by design — out of scope per spec
Persistent job storage	❌ In-memory only — resets on server restart
Real-time chat / clarification loop	❌ Vague prompts proceed with documented assumptions