🔧 Intent Compiler

The Compiler for Human Intent
Transform natural language business requirements into production-ready technical specifications

Quick Start • How It Works • Architecture • Features

---

🎯 What is Intent Compiler?

Intent Compiler treats software specification as a compilation target. Just like a traditional compiler transforms high-level code into machine instructions, this tool transforms high-level business intent into low-level technical specifications.

┌─────────────────────────────┐     ┌─────────────────────────────┐
│   "Build an Uber for        │     │  • 7 Bounded Contexts       │
│    dog walking with         │ ──► │  • 12 Database Tables       │
│    payments and reviews"    │     │  • 42 API Endpoints         │
│                             │     │  • Full Pseudo-code         │
└─────────────────────────────┘     └─────────────────────────────┘
        Human Intent                   Technical Specification

---

✨ Features

Feature	Description
🤖 Multi-Agent Orchestration	4 specialized AI agents working in sequence
🔄 LangGraph State Machine	Cyclic graph with self-correction loops
🧙 Wizard-Style UI	Step-by-step with human approval gates
📊 Mermaid Diagrams	Auto-generated architecture & ER diagrams
🏗️ DDD Module Decomposition	Bounded contexts with traceability
🗄️ 3NF Database Schemas	Normalized relational database design
💻 CSR Pseudo-code	Controller-Service-Repository pattern
� State Persistence	Resume compilation across sessions

---

🚀 Quick Start

1. Clone & Install

git clone https://github.com/yourusername/intent-compiler.git
cd intent-compiler
pip install -r requirements.txt

2. Configure API Key

Create a .env file:

GROQ_API_KEY=your_groq_api_key_here

3. Run

streamlit run app.py

Open http://localhost:8501 and start compiling! 🎉

---

🔍 How It Works

The Intent Compiler uses a 4-stage compilation pipeline, each handled by a specialized AI agent:

flowchart LR
    subgraph Input
        A[📝 Business<br>Requirement]
    end
    
    subgraph Stage1["Stage 1: Lexical Analysis"]
        B[🔍 Analyst<br>Agent]
    end
    
    subgraph Stage2["Stage 2: Structural Analysis"]
        C[🏗️ Architect<br>Agent]
    end
    
    subgraph Stage3["Stage 3: Memory Allocation"]
        D[🗄️ Data Engineer<br>Agent]
    end
    
    subgraph Stage4["Stage 4: Code Generation"]
        E[💻 Developer<br>Agent]
    end
    
    subgraph Output
        F[📦 Technical<br>Specification]
    end
    
    A --> B
    B -->|Requirements<br>User Stories| C
    C -->|Modules<br>Architecture| D
    D -->|Schema<br>ER Diagram| E
    E -->|Pseudo-code| F
    
    D -.->|Self-Correction<br>Loop| D

Loading

The Agents

Agent	Role	Compiler Analogy	Output
🔍 Analyst	Deconstructs requirements	Lexical Analysis	Structured requirements, User stories
🏗️ Architect	Decomposes into modules	Structural Analysis	Bounded contexts, System diagram
🗄️ Data Engineer	Designs database schema	Memory Allocation	3NF ER diagram
💻 Developer	Generates behavioral logic	Code Generation	CSR pseudo-code

---

🏛️ Architecture

LangGraph State Machine

The compiler is built on LangGraph, which enables cyclic, stateful agent orchestration:

stateDiagram-v2
    [*] --> Input: User enters requirements
    Input --> Analyst: Start Compilation
    
    Analyst --> AwaitApproval1: Requirements extracted
    AwaitApproval1 --> Architect: ✅ Approved
    AwaitApproval1 --> Analyst: 🔄 Re-analyze
    
    Architect --> AwaitApproval2: Modules identified
    AwaitApproval2 --> DataEngineer: ✅ Approved
    AwaitApproval2 --> Architect: 🔄 Re-architect
    
    DataEngineer --> Validation: Schema generated
    Validation --> DataEngineer: ❌ Invalid syntax
    Validation --> AwaitApproval3: ✅ Valid
    
    AwaitApproval3 --> Developer: ✅ Approved
    AwaitApproval3 --> DataEngineer: 🔄 Regenerate
    
    Developer --> Complete: Pseudo-code ready
    Complete --> [*]: Export specification

Loading

Global State Schema (The "Symbol Table")

All agents share a persistent state object:

classDiagram
    class CompilerState {
        +str raw_intent
        +list requirements
        +list user_stories
        +str analyst_summary
        +list modules
        +str architecture_diagram
        +str er_diagram
        +bool schema_valid
        +dict pseudo_code
        +int current_stage
        +list messages
    }
    
    class AnalystAgent {
        +extract_entities()
        +generate_user_stories()
        +infer_nfrs()
    }
    
    class ArchitectAgent {
        +identify_bounded_contexts()
        +generate_system_diagram()
        +map_requirements()
    }
    
    class DataEngineerAgent {
        +normalize_to_3nf()
        +generate_er_diagram()
        +validate_syntax()
    }
    
    class DeveloperAgent {
        +generate_controllers()
        +generate_services()
        +generate_repositories()
    }
    
    CompilerState <-- AnalystAgent : reads/writes
    CompilerState <-- ArchitectAgent : reads/writes
    CompilerState <-- DataEngineerAgent : reads/writes
    CompilerState <-- DeveloperAgent : reads/writes

Loading

---

📊 Example Output

Input

"Build an app like Uber but for dog walking services. Dog owners can request walks, see nearby walkers, track the walk in real-time, and pay through the app."

Stage 1: Requirements Analysis

{
  "requirements": [
    {"id": "REQ-001", "type": "Functional", "priority": "Must Have", 
     "description": "Dog owners can register dogs with profiles"},
    {"id": "REQ-002", "type": "Functional", "priority": "Must Have",
     "description": "Dog owners can request walks specifying time and location"},
    {"id": "REQ-003", "type": "Non-Functional", "priority": "Should Have",
     "description": "Real-time location tracking with < 5 second latency"}
  ],
  "user_stories": [
    "As a Dog Owner, I want to register my dog with its profile, so that walkers know my dog's needs",
    "As a Dog Walker, I want to set my availability, so that I receive relevant walk requests"
  ]
}

Stage 2: Architecture Diagram

graph TD
    subgraph UserContext["👤 User Management"]
        Auth[Authentication Service]
        Profile[Profile Service]
    end
    
    subgraph WalkContext["🦮 Walk Management"]
        Request[Request Service]
        Match[Matching Service]
        Track[Tracking Service]
    end
    
    subgraph PayContext["💳 Payment Processing"]
        Payment[Payment Service]
        Wallet[Wallet Service]
    end
    
    subgraph ReviewContext["⭐ Rating & Review"]
        Review[Review Service]
    end
    
    subgraph NotifyContext["🔔 Notifications"]
        Push[Push Service]
    end
    
    Auth --> Request
    Request --> Match
    Match --> Track
    Track --> Payment
    Payment --> Review
    Track -.->|Events| Push
    Payment -.->|Events| Push

Loading

Stage 3: Database Schema

erDiagram
    DogOwner ||--o{ Dog : owns
    DogOwner ||--o{ WalkRequest : creates
    Walker ||--o{ WalkRequest : accepts
    WalkRequest ||--|| Walk : becomes
    Walk ||--|| Payment : requires
    Walk ||--o| Review : receives
    Walker ||--o{ Availability : sets
    
    DogOwner {
        int id PK
        string email UK
        string name
        string phone
        timestamp created_at
    }
    
    Dog {
        int id PK
        int owner_id FK
        string name
        string breed
        string size
        text special_needs
    }
    
    Walker {
        int id PK
        string email UK
        string name
        text experience
        decimal rating
        boolean is_active
    }
    
    WalkRequest {
        int id PK
        int dog_id FK
        int owner_id FK
        int walker_id FK
        timestamp request_time
        timestamp walk_time
        int duration
        string status
    }
    
    Walk {
        int id PK
        int request_id FK
        timestamp start_time
        timestamp end_time
        string current_location
    }
    
    Payment {
        int id PK
        int walk_id FK
        decimal amount
        decimal tip
        string status
        timestamp processed_at
    }
    
    Review {
        int id PK
        int walk_id FK
        int rating
        text comment
        timestamp created_at
    }

Loading

Stage 4: Pseudo-code (Sample)

MODULE: WalkScheduling

# ═══════════════════════════════════════════════════════════════
# CONTROLLER LAYER
# ═══════════════════════════════════════════════════════════════

FUNCTION POST /walks/request(dog_id, time, duration, location):
    ACTION: Create a new walk request
    
    CONDITION: Validate authentication token
        IF fails: RETURN 401 Unauthorized
    
    CONDITION: Check dog belongs to authenticated owner
        IF fails: RETURN 403 Forbidden
    
    CONDITION: Validate time is in future
        IF fails: RETURN 400 Bad Request("Walk must be scheduled in future")
    
    RESULT: Create walk request
        walk_request = WalkService.create_request(dog_id, time, duration, location)
        NotificationService.notify_nearby_walkers(walk_request)
        RETURN 201 Created(walk_request)

# ═══════════════════════════════════════════════════════════════
# SERVICE LAYER
# ═══════════════════════════════════════════════════════════════

FUNCTION create_request(dog_id, time, duration, location):
    ACTION: Process walk request creation
    
    CONDITION: Check dog has no pending walks
        existing = WalkRepository.find_pending_by_dog(dog_id)
        IF existing: RAISE ConflictError("Dog already has pending walk")
    
    CONDITION: Check available walkers in area
        walkers = WalkerRepository.find_available(location, time)
        IF walkers.empty: RAISE NoWalkersError("No walkers available")
    
    RESULT: Create and return request
        request = WalkRepository.create({
            dog_id: dog_id,
            time: time,
            duration: duration,
            location: location,
            status: "pending"
        })
        RETURN request

# ═══════════════════════════════════════════════════════════════
# REPOSITORY LAYER
# ═══════════════════════════════════════════════════════════════

FUNCTION find_available(location, time):
    RESULT: Query available walkers
        SELECT w.* FROM Walker w
        JOIN Availability a ON w.id = a.walker_id
        WHERE w.is_active = TRUE
        AND ST_Distance(w.location, $location) < 5000
        AND a.start_time <= $time
        AND a.end_time >= $time
        ORDER BY w.rating DESC

---

🛠️ Tech Stack

graph TB
    subgraph Frontend["🖥️ Frontend"]
        Streamlit[Streamlit]
        Mermaid[Mermaid.js]
    end
    
    subgraph Orchestration["🔄 Orchestration"]
        LangGraph[LangGraph]
        LangChain[LangChain Core]
    end
    
    subgraph LLM["🧠 LLM Provider"]
        Groq[Groq API]
        Llama[LLaMA 3.3 70B]
    end
    
    subgraph State["💾 State"]
        MemorySaver[MemorySaver]
        SessionState[Session State]
    end
    
    Frontend --> Orchestration
    Orchestration --> LLM
    Orchestration --> State

Loading

Component	Technology	Purpose
Orchestration	LangGraph	Stateful, cyclic multi-agent coordination
LLM	Groq + LLaMA 3.3 70B	Fast inference for all agents
Frontend	Streamlit	Interactive wizard UI
Visualization	Mermaid.js	Architecture & ER diagrams
State	MemorySaver	Persistent compilation state
Validation	Pydantic	Structured output schemas

---

📁 Project Structure

intent-compiler/
├── app.py                    # Main Streamlit application
├── requirements.txt          # Python dependencies
├── .env                      # API keys (local, not in git)
├── .gitignore               # Git ignore rules
├── .streamlit/
│   └── config.toml          # Streamlit configuration
├── secrets.toml.example     # Template for secrets
├── Procfile                 # Heroku/Railway deployment
├── runtime.txt              # Python version
└── README.md                # This file

---

🚀 Deployment

Option 1: Streamlit Cloud (Recommended)

The easiest way to deploy - free hosting from Streamlit!

1. Push to GitHub

   git init
   git add .
   git commit -m "Initial commit"
   git remote add origin https://github.com/yourusername/intent-compiler.git
   git push -u origin main

2. Deploy on Streamlit Cloud

   • Go to share.streamlit.io
   • Click "New app"
   • Select your repository
   • Set main file: app.py
   • Click "Deploy"

3. Add Secrets

   • Go to your app's settings → Secrets
   • Add your API key:

     GROQ_API_KEY = "your_groq_api_key_here"

flowchart LR
    A[GitHub Repo] --> B[Streamlit Cloud]
    B --> C[Live App]
    D[Secrets Panel] --> B

Loading

---

Option 2: Railway

1. Connect Repository

   • Go to railway.app
   • Click "New Project" → "Deploy from GitHub"
   • Select your repository

2. Configure Environment

   • Add environment variable: GROQ_API_KEY
   • Railway auto-detects the Procfile

3. Deploy

   • Railway builds and deploys automatically
   • Get your public URL from the dashboard

---

Option 3: Render

1. Create Web Service

   • Go to render.com
   • Click "New" → "Web Service"
   • Connect your GitHub repo

2. Configure

   Build Command: pip install -r requirements.txt
   Start Command: streamlit run app.py --server.port=$PORT --server.address=0.0.0.0

3. Add Environment Variables

   • Add GROQ_API_KEY in the Environment tab

---

Option 4: Heroku

1. Install Heroku CLI

   # Login and create app
   heroku login
   heroku create intent-compiler-app

2. Set Config Vars

   heroku config:set GROQ_API_KEY=your_key_here

3. Deploy

   git push heroku main

---

Option 5: Docker

FROM python:3.11-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt

COPY . .

EXPOSE 8501
CMD ["streamlit", "run", "app.py", "--server.port=8501", "--server.address=0.0.0.0"]

Build and run:

docker build -t intent-compiler .
docker run -p 8501:8501 -e GROQ_API_KEY=your_key intent-compiler

---

🔧 Configuration

Environment Variables

Variable	Required	Description
GROQ_API_KEY	✅	Your Groq API key

Customization

You can modify the agent prompts in app.py:

• ANALYST_PROMPT - Requirements extraction strategy
• ARCHITECT_PROMPT - Module decomposition rules
• DATA_ENGINEER_PROMPT - Schema normalization rules
• DEVELOPER_PROMPT - Code generation patterns

---

🔮 Future Enhancements

• SQLite Persistence - "Time Travel" across sessions
• Token Tracking - Cost estimation per compilation
• Streaming Output - Real-time agent "thinking"
• Code Export - Generate actual code files
• Multiple LLM Support - OpenAI, Anthropic, local models

---

📜 License

MIT License - See LICENSE for details.

---

Built with ❤️ using LangGraph, Groq, and Streamlit By DynoSuprovo