feat (start): first setup

.gitignore

@@ -0,0 +1,45 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+env/
+venv/
+ENV/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Ollama models (large files)
+.ollama/
+
+# Logs
+*.log
+
+# Environment variables
+.env
+.env.local

Dockerfile

@@ -0,0 +1,53 @@
+FROM python:3.11-slim
+
+# Set working directory
+WORKDIR /app
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y \
+    curl \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install Ollama
+RUN curl -fsSL https://ollama.ai/install.sh | sh
+
+# Copy requirements first for better caching
+COPY requirements.txt .
+
+# Install Python dependencies
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy application files
+COPY server.py .
+COPY static/ ./static/
+
+# Create directory for Ollama models
+RUN mkdir -p /root/.ollama
+
+# Expose port
+EXPOSE 7860
+
+# Set environment variables
+ENV OLLAMA_HOST=0.0.0.0:11434
+ENV PYTHONUNBUFFERED=1
+
+# Create startup script
+RUN echo '#!/bin/bash\n\
+set -e\n\
+\n\
+echo "Starting Ollama server..."\n\
+ollama serve &\n\
+OLLAMA_PID=$!\n\
+\n\
+echo "Waiting for Ollama to be ready..."\n\
+sleep 5\n\
+\n\
+echo "Pulling phi3 model..."\n\
+ollama pull phi3\n\
+\n\
+echo "Starting FastAPI server..."\n\
+uvicorn server:app --host 0.0.0.0 --port 7860\n\
+' > /app/start.sh && chmod +x /app/start.sh
+
+# Run the startup script
+CMD ["/app/start.sh"]

README.md

@@ -1,12 +1,74 @@
 ---
-title: Customizable Sml Agents
-emoji: 🌍
-colorFrom: red
-colorTo: yellow
+title: Customizable SML Agents
+emoji: 🤖
+colorFrom: blue
+colorTo: indigo
 sdk: docker
 pinned: false
 license: gpl-3.0
 short_description: Customizable SML Agents
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Natural Language to SQL - Multi-Agent System
+
+A multi-agent system powered by small language models (SLMs) that converts natural language questions into SQL queries.
+
+## Features
+
+- 🔍 **Schema Analyzer Agent**: Identifies relevant tables and columns
+- ⚙️ **Query Generator Agent**: Converts natural language to SQL
+- ✓ **Syntax Validator Agent**: Validates SQL syntax
+- 🎯 **Semantic Verifier Agent**: Ensures query answers the question
+- 🔄 **Iterative Refinement**: Up to 3 attempts to get the correct query
+- 📋 **Real-time Logging**: See each agent's input and output
+
+## Architecture
+
+This system demonstrates how autonomous agents can interact with Small Language Models (SLMs) running locally to solve complex problems. Each agent has a specific role, and they work together through an iterative pipeline.
+
+## Technology Stack
+
+- **Backend**: FastAPI
+- **Frontend**: React with Tailwind CSS
+- **LLM**: Ollama (phi3 model)
+- **Agent Framework**: LangChain
+
+## Usage
+
+1. Enter your database schema
+2. Customize agent prompts (optional)
+3. Type your question in natural language
+4. Click "Execute Pipeline"
+5. Watch the agents work together to generate SQL
+
+## Example
+
+**Question**: "What were the top 5 products by revenue in 2024?"
+
+**Schema**:
+```
+- products (id, name, category, price)
+- orders (id, customer_id, order_date, total)
+- order_items (id, order_id, product_id, quantity, price)
+```
+
+**Generated SQL**:
+```sql
+SELECT p.name, SUM(oi.quantity * oi.price) AS revenue
+FROM products p
+JOIN order_items oi ON p.id = oi.product_id
+JOIN orders o ON oi.order_id = o.id
+WHERE YEAR(o.order_date) = 2024
+GROUP BY p.id, p.name
+ORDER BY revenue DESC
+LIMIT 5
+```
+
+## Educational Purpose
+
+This application is designed for teaching concepts related to:
+- Multi-agent systems
+- Small Language Models (SLMs)
+- Agent orchestration patterns
+- Iterative refinement techniques
+- Tool integration with LLMs

requirements.txt

@@ -0,0 +1,7 @@
+fastapi==0.109.0
+uvicorn[standard]==0.27.0
+langchain==0.1.0
+langchain-community==0.0.13
+sqlparse==0.4.4
+pydantic==2.5.3
+aiofiles==23.2.1

server.py

@@ -0,0 +1,185 @@
+from fastapi import FastAPI, HTTPException
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import StreamingResponse, FileResponse
+from fastapi.staticfiles import StaticFiles
+from pydantic import BaseModel
+from langchain_community.llms import Ollama
+from langchain.prompts import PromptTemplate
+from langchain.chains import LLMChain
+import sqlparse
+import json
+import asyncio
+from typing import AsyncGenerator
+from pathlib import Path
+import os
+
+app = FastAPI(title="NL to SQL Multi-Agent System")
+
+# Enable CORS for web interface
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# Mount static files directory
+static_dir = Path(__file__).parent / "static"
+static_dir.mkdir(exist_ok=True)
+
+app.mount("/static", StaticFiles(directory=static_dir), name="static")
+
+# Request model
+class ExecutionRequest(BaseModel):
+    schema: str
+    schema_prompt: str
+    query_prompt: str
+    syntax_prompt: str
+    semantic_prompt: str
+    question: str
+    model: str = "phi3"
+    max_iterations: int = 3
+
+# Initialize LLM
+def get_llm(model_name: str):
+    return Ollama(model=model_name, temperature=0.1)
+
+# Syntax validator (deterministic)
+def validate_syntax(sql_query: str):
+    try:
+        parsed = sqlparse.parse(sql_query)
+        if not parsed:
+            return False, "Empty or invalid SQL"
+        return True, "Syntax valid"
+    except Exception as e:
+        return False, f"Syntax error: {str(e)}"
+
+# Stream event helper
+def create_event(event_type: str, **kwargs):
+    data = {"type": event_type, **kwargs}
+    return f"data: {json.dumps(data)}\n\n"
+
+# Main agent pipeline
+async def execute_pipeline(request: ExecutionRequest) -> AsyncGenerator[str, None]:
+    try:
+        # Initialize LLM
+        llm = get_llm(request.model)
+        
+        yield create_event("agent_start", agent="Schema Analyzer")
+        yield create_event("agent_input", content=f"Schema: {request.schema[:100]}... | Question: {request.question}")
+        
+        # Agent 1: Schema Analyzer
+        schema_prompt = PromptTemplate(
+            input_variables=["schema", "question"],
+            template=request.schema_prompt
+        )
+        schema_chain = LLMChain(llm=llm, prompt=schema_prompt)
+        
+        relevant_schema_result = schema_chain.invoke({
+            "schema": request.schema,
+            "question": request.question
+        })
+        relevant_schema = relevant_schema_result.get('text', relevant_schema_result) if isinstance(relevant_schema_result, dict) else relevant_schema_result
+        
+        yield create_event("agent_output", content=relevant_schema.strip())
+        
+        # Iteration loop
+        sql_query = None
+        for iteration in range(request.max_iterations):
+            yield create_event("iteration", iteration=iteration + 1)
+            
+            # Agent 2: Query Generator
+            yield create_event("agent_start", agent="Query Generator")
+            yield create_event("agent_input", content=f"Relevant schema: {relevant_schema[:100]}...")
+            
+            query_prompt = PromptTemplate(
+                input_variables=["question", "relevant_schema"],
+                template=request.query_prompt
+            )
+            sql_chain = LLMChain(llm=llm, prompt=query_prompt)
+            
+            sql_result = sql_chain.invoke({
+                "question": request.question,
+                "relevant_schema": relevant_schema
+            })
+            sql_query = sql_result.get('text', sql_result) if isinstance(sql_result, dict) else sql_result
+            sql_query = sql_query.strip()
+            
+            yield create_event("agent_output", content=sql_query)
+            
+            # Agent 3: Syntax Validator
+            yield create_event("agent_start", agent="Syntax Validator")
+            is_valid, syntax_msg = validate_syntax(sql_query)
+            
+            if is_valid:
+                yield create_event("validation", content=syntax_msg, status="pass")
+            else:
+                yield create_event("validation", content=syntax_msg, status="fail")
+                continue
+            
+            # Agent 4: Semantic Verifier
+            yield create_event("agent_start", agent="Semantic Verifier")
+            yield create_event("agent_input", content=f"Checking if SQL answers: {request.question}")
+            
+            verify_prompt = PromptTemplate(
+                input_variables=["question", "sql_query"],
+                template=request.semantic_prompt
+            )
+            verify_chain = LLMChain(llm=llm, prompt=verify_prompt)
+            
+            verification_result = verify_chain.invoke({
+                "question": request.question,
+                "sql_query": sql_query
+            })
+            verification = verification_result.get('text', verification_result) if isinstance(verification_result, dict) else verification_result
+            
+            yield create_event("agent_output", content=verification.strip())
+            
+            if "YES" in verification.upper():
+                yield create_event("validation", content="Query is semantically correct", status="pass")
+                break
+            else:
+                yield create_event("validation", content="Query has semantic issues", status="fail")
+        
+        # Final result
+        yield create_event("final_result", sql=sql_query if sql_query else "No valid SQL generated")
+        
+    except Exception as e:
+        yield create_event("error", message=str(e))
+
+@app.get("/")
+async def root():
+    """Serve the main web interface"""
+    index_file = static_dir / "index.html"
+    if index_file.exists():
+        return FileResponse(index_file)
+    return {"message": "Place index.html in the static/ directory"}
+
+@app.post("/execute")
+async def execute(request: ExecutionRequest):
+    """Execute the multi-agent NL to SQL pipeline with streaming logs"""
+    return StreamingResponse(
+        execute_pipeline(request),
+        media_type="text/event-stream"
+    )
+
+@app.get("/health")
+async def health():
+    """Health check endpoint"""
+    return {"status": "ok"}
+
+@app.get("/models")
+async def list_models():
+    """List available Ollama models"""
+    # This would require calling ollama CLI or API
+    # For now, return common models
+    return {
+        "models": ["phi3", "llama3.2:3b", "gemma2:2b", "mistral"]
+    }
+
+if __name__ == "__main__":
+    import uvicorn
+    # HuggingFace Spaces uses port 7860
+    port = int(os.environ.get("PORT", 7860))
+    uvicorn.run(app, host="0.0.0.0", port=port)

static/index.html

@@ -0,0 +1,278 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>NL to SQL Multi-Agent System</title>
+    <script crossorigin src="https://unpkg.com/react@18/umd/react.production.min.js"></script>
+    <script crossorigin src="https://unpkg.com/react-dom@18/umd/react-dom.production.min.js"></script>
+    <script src="https://unpkg.com/@babel/standalone/babel.min.js"></script>
+    <script src="https://cdn.tailwindcss.com"></script>
+</head>
+<body>
+    <div id="root"></div>
+    
+    <script type="text/babel">
+        const { useState } = React;
+
+        const NLtoSQLApp = () => {
+          const [isExecuting, setIsExecuting] = useState(false);
+          const [logs, setLogs] = useState('');
+          
+          const [schema, setSchema] = useState(`Tables:
+- products (id, name, category, price)
+- orders (id, customer_id, order_date, total)
+- order_items (id, order_id, product_id, quantity, price)`);
+
+          const [schemaPrompt, setSchemaPrompt] = useState(`Given this database schema:
+{schema}
+
+For the question: "{question}"
+
+List only the relevant tables and columns needed. Be concise.
+
+Relevant schema:`);
+
+          const [queryPrompt, setQueryPrompt] = useState(`Convert this question to SQL using only these tables/columns:
+{relevant_schema}
+
+Question: {question}
+
+SQL query (return only the query, no explanation):`);
+
+          const [syntaxPrompt, setSyntaxPrompt] = useState(`Check if this SQL query is syntactically valid:
+{sql_query}
+
+Answer with "VALID" or "INVALID" and explain any issues.
+
+Answer:`);
+
+          const [semanticPrompt, setSemanticPrompt] = useState(`Does this SQL query correctly answer the question?
+
+Question: {question}
+SQL: {sql_query}
+
+Answer with "YES" or "NO" and briefly explain why.
+
+Answer:`);
+
+          const [question, setQuestion] = useState("What were the top 5 products by revenue in 2024?");
+
+          const addLog = (message, type = 'info') => {
+            const timestamp = new Date().toLocaleTimeString();
+            const prefix = type === 'error' ? '❌' : type === 'success' ? '✅' : type === 'agent' ? '🤖' : 'ℹ️';
+            setLogs(prev => `${prev}[${timestamp}] ${prefix} ${message}\n`);
+          };
+
+          const executeAgentPipeline = async () => {
+            setIsExecuting(true);
+            setLogs('');
+            
+            addLog('Starting NL to SQL conversion...', 'info');
+            addLog(`Question: "${question}"`, 'info');
+            
+            try {
+              const response = await fetch('/execute', {
+                method: 'POST',
+                headers: {
+                  'Content-Type': 'application/json',
+                },
+                body: JSON.stringify({
+                  schema,
+                  schema_prompt: schemaPrompt,
+                  query_prompt: queryPrompt,
+                  syntax_prompt: syntaxPrompt,
+                  semantic_prompt: semanticPrompt,
+                  question
+                }),
+              });
+
+              if (!response.ok) {
+                throw new Error(`HTTP error! status: ${response.status}`);
+              }
+
+              const reader = response.body.getReader();
+              const decoder = new TextDecoder();
+
+              while (true) {
+                const { done, value } = await reader.read();
+                if (done) break;
+                
+                const chunk = decoder.decode(value);
+                const lines = chunk.split('\n');
+                
+                for (const line of lines) {
+                  if (line.startsWith('data: ')) {
+                    try {
+                      const data = JSON.parse(line.slice(6));
+                      
+                      if (data.type === 'agent_start') {
+                        addLog(`Agent: ${data.agent}`, 'agent');
+                      } else if (data.type === 'agent_input') {
+                        addLog(`Input: ${data.content}`, 'info');
+                      } else if (data.type === 'agent_output') {
+                        addLog(`Output: ${data.content}`, 'info');
+                      } else if (data.type === 'validation') {
+                        addLog(`Validation: ${data.content}`, data.status === 'pass' ? 'success' : 'error');
+                      } else if (data.type === 'iteration') {
+                        addLog(`--- Iteration ${data.iteration} ---`, 'info');
+                      } else if (data.type === 'final_result') {
+                        addLog(`\n=== FINAL SQL QUERY ===\n${data.sql}`, 'success');
+                      } else if (data.type === 'error') {
+                        addLog(`Error: ${data.message}`, 'error');
+                      }
+                    } catch (e) {
+                      // Skip malformed JSON
+                    }
+                  }
+                }
+              }
+              
+            } catch (error) {
+              addLog(`Error: ${error.message}`, 'error');
+            } finally {
+              setIsExecuting(false);
+            }
+          };
+
+          return (
+            <div className="min-h-screen bg-gradient-to-br from-blue-50 to-indigo-100 p-6">
+              <div className="max-w-7xl mx-auto">
+                <div className="bg-white rounded-lg shadow-xl p-6 mb-6">
+                  <div className="flex items-center gap-3 mb-6">
+                    <svg className="w-8 h-8 text-indigo-600" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                      <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M4 7v10c0 2.21 3.582 4 8 4s8-1.79 8-4V7M4 7c0 2.21 3.582 4 8 4s8-1.79 8-4M4 7c0-2.21 3.582-4 8-4s8 1.79 8 4m0 5c0 2.21-3.582 4-8 4s-8-1.79-8-4" />
+                    </svg>
+                    <h1 className="text-3xl font-bold text-gray-800">Natural Language to SQL</h1>
+                    <svg className="w-8 h-8 text-indigo-600" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                      <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M9.663 17h4.673M12 3v1m6.364 1.636l-.707.707M21 12h-1M4 12H3m3.343-5.657l-.707-.707m2.828 9.9a5 5 0 117.072 0l-.548.547A3.374 3.374 0 0014 18.469V19a2 2 0 11-4 0v-.531c0-.895-.356-1.754-.988-2.386l-.548-.547z" />
+                    </svg>
+                  </div>
+                  <p className="text-gray-600 mb-4">Multi-Agent System with Small Language Models</p>
+                </div>
+
+                <div className="grid grid-cols-1 lg:grid-cols-2 gap-6">
+                  {/* Left Column - Configuration */}
+                  <div className="space-y-4">
+                    {/* Database Schema */}
+                    <div className="bg-white rounded-lg shadow p-4">
+                      <label className="block text-sm font-semibold text-gray-700 mb-2">
+                        📊 Database Schema
+                      </label>
+                      <textarea
+                        value={schema}
+                        onChange={(e) => setSchema(e.target.value)}
+                        className="w-full h-32 p-3 border border-gray-300 rounded-lg font-mono text-sm focus:ring-2 focus:ring-indigo-500 focus:border-transparent"
+                        placeholder="Enter database schema..."
+                      />
+                    </div>
+
+                    {/* Schema Analyzer Prompt */}
+                    <div className="bg-white rounded-lg shadow p-4">
+                      <label className="block text-sm font-semibold text-gray-700 mb-2">
+                        🔍 Schema Analyzer Prompt
+                      </label>
+                      <textarea
+                        value={schemaPrompt}
+                        onChange={(e) => setSchemaPrompt(e.target.value)}
+                        className="w-full h-32 p-3 border border-gray-300 rounded-lg font-mono text-sm focus:ring-2 focus:ring-indigo-500 focus:border-transparent"
+                      />
+                    </div>
+
+                    {/* Query Generator Prompt */}
+                    <div className="bg-white rounded-lg shadow p-4">
+                      <label className="block text-sm font-semibold text-gray-700 mb-2">
+                        ⚙️ Query Generator Prompt
+                      </label>
+                      <textarea
+                        value={queryPrompt}
+                        onChange={(e) => setQueryPrompt(e.target.value)}
+                        className="w-full h-32 p-3 border border-gray-300 rounded-lg font-mono text-sm focus:ring-2 focus:ring-indigo-500 focus:border-transparent"
+                      />
+                    </div>
+
+                    {/* Syntax Validator Prompt */}
+                    <div className="bg-white rounded-lg shadow p-4">
+                      <label className="block text-sm font-semibold text-gray-700 mb-2">
+                        ✓ Syntax Validator Prompt
+                      </label>
+                      <textarea
+                        value={syntaxPrompt}
+                        onChange={(e) => setSyntaxPrompt(e.target.value)}
+                        className="w-full h-32 p-3 border border-gray-300 rounded-lg font-mono text-sm focus:ring-2 focus:ring-indigo-500 focus:border-transparent"
+                      />
+                    </div>
+
+                    {/* Semantic Verifier Prompt */}
+                    <div className="bg-white rounded-lg shadow p-4">
+                      <label className="block text-sm font-semibold text-gray-700 mb-2">
+                        🎯 Semantic Verifier Prompt
+                      </label>
+                      <textarea
+                        value={semanticPrompt}
+                        onChange={(e) => setSemanticPrompt(e.target.value)}
+                        className="w-full h-32 p-3 border border-gray-300 rounded-lg font-mono text-sm focus:ring-2 focus:ring-indigo-500 focus:border-transparent"
+                      />
+                    </div>
+
+                    {/* User Question */}
+                    <div className="bg-white rounded-lg shadow p-4">
+                      <label className="block text-sm font-semibold text-gray-700 mb-2">
+                        💬 User Question
+                      </label>
+                      <textarea
+                        value={question}
+                        onChange={(e) => setQuestion(e.target.value)}
+                        className="w-full h-24 p-3 border border-gray-300 rounded-lg text-sm focus:ring-2 focus:ring-indigo-500 focus:border-transparent"
+                        placeholder="Enter your question in natural language..."
+                      />
+                    </div>
+
+                    {/* Execute Button */}
+                    <button
+                      onClick={executeAgentPipeline}
+                      disabled={isExecuting}
+                      className="w-full bg-indigo-600 hover:bg-indigo-700 disabled:bg-gray-400 text-white font-semibold py-3 px-6 rounded-lg shadow-lg transition-colors duration-200 flex items-center justify-center gap-2"
+                    >
+                      {isExecuting ? (
+                        <>
+                          <svg className="w-5 h-5 animate-spin" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                            <circle className="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" strokeWidth="4"></circle>
+                            <path className="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z"></path>
+                          </svg>
+                          Executing...
+                        </>
+                      ) : (
+                        <>
+                          <svg className="w-5 h-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                            <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M14.752 11.168l-3.197-2.132A1 1 0 0010 9.87v4.263a1 1 0 001.555.832l3.197-2.132a1 1 0 000-1.664z" />
+                            <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M21 12a9 9 0 11-18 0 9 9 0 0118 0z" />
+                          </svg>
+                          Execute Pipeline
+                        </>
+                      )}
+                    </button>
+                  </div>
+
+                  {/* Right Column - Logs */}
+                  <div className="bg-white rounded-lg shadow p-4">
+                    <label className="block text-sm font-semibold text-gray-700 mb-2">
+                      📋 Execution Log
+                    </label>
+                    <textarea
+                      value={logs}
+                      readOnly
+                      className="w-full h-[calc(100vh-200px)] p-3 border border-gray-300 rounded-lg font-mono text-xs bg-gray-50 focus:outline-none overflow-auto"
+                      placeholder="Logs will appear here when you execute the pipeline..."
+                    />
+                  </div>
+                </div>
+              </div>
+            </div>
+          );
+        };
+
+        ReactDOM.render(<NLtoSQLApp />, document.getElementById('root'));
+    </script>
+</body>
+</html>