KORA_UNIFIED_API_SPEC.md

# 🌐 KORA UNIFIED API & ENDPOINT MASTER SPECIFICATION

> **TARGET AGENT**: API Architect & Backend Infrastructure Engineer  
> **MISSION**: Implement and deploy the unified API gateway and webhook system for the entire **Kontyra / Kora ecosystem** (Chat, Reasoning, Coding, Vision & Image Generation).  
> **SCOPE**: Cloud, Container, DevOS Integrations, and Vercel Hybrid Deployment.

---

## 1. Ecosystem Architectural Overview: "One Kora, Two Runtimes"

The Kontyra / Kora ecosystem operates as a unified platform spanning two coordinated runtimes:
1. **Edge Frontend & Fast Inference (Vercel)**: Hosts the web interface and the ultra-lightweight **NanoKora-25M** ONNX model (<26 MB) for sub-millisecond conversation and arithmetic.
2. **Dedicated Cloud Compute (Your Self-Hosted Custom Endpoint)**: Hosts the heavy computational models (**Kora Coder 0.5B**, **Watermark-Free Image Generator**, **Vision UI-to-Code**, and **Multi-Agent Task Orchestrator**).

```
                            ┌──────────────────────────────────────────────┐
                            │               USER / CLIENT                  │
                            │      (Web Browser, DevOS, CLI, Agents)       │
                            └──────────────────────┬───────────────────────┘
                                                   │
                                                   │ HTTPS (kora-three-alpha.vercel.app)
                                                   ▼
                            ┌──────────────────────────────────────────────┐
                            │            VERCEL EDGE LAYER (KORA)          │
                            │                                              │
                            │ • Kontyra Docs Design System UI              │
                            │ • NanoKora-25M ONNX Runtime (CPU, <26 MB)    │
                            │ • Smart Router & Proxy (api/chat.py)         │
                            └──────┬────────────────────────────────┬──────┘
                                   │                                │
                [General Chat /    │                                │ [Coding / Images / Vision /
                 Math / Low Latency]│                               │  Multi-Agent Swarm]
                                   ▼                                │
                        ┌────────────────────┐                      │ (Proxies via HTTPS using
                        │ NanoKora-25M Local │                      │  KORA_CUSTOM_ENDPOINT)
                        │ (In-Memory ONNX)   │                      ▼
                        └────────────────────┘    ┌────────────────────────────────────────┐
                                                  │       YOUR CUSTOM CLOUD ENDPOINT       │
                                                  │           (gateway.py :8000)           │
                                                  │                                        │
                                                  │  • Kora Coder (Qwen2.5-Coder-0.5B)     │
                                                  │  • Image Studio (Watermark-Free)       │
                                                  │  • Vision Analyzer (UI-to-Code)        │
                                                  │  • Multi-Agent Swarm Orchestrator      │
                                                  │  • DevOS Webhook Engine                │
                                                  └────────────────────────────────────────┘
```

> **Why a Custom Endpoint?**  
> Vercel has a strict 250 MB serverless deployment bundle limit and 10–60s execution timeouts. Multi-gigabyte models like Qwen2.5-Coder and generative image diffusion pipelines cannot be bundled into Vercel directly. By hosting your own custom endpoint, Kora on Vercel acts as **ONE unified frontend and gateway** that transparently delegates heavy tasks to your custom endpoint while handling quick interactions locally.

---

## 2. Master Route Table to Implement

Your custom endpoint (`gateway.py`) must expose the following standard endpoints:

| Endpoint | Method | Engine | Description |
|---|---|---|---|
| `/health` | `GET` | All | Aggregate health status across all active engines |
| `/v1/models` | `GET` | Gateway | Lists available models (`nanokora-25m`, `kora-coder-0.5b`, `kora-vision`, `kora-image`, `kora-agent`) |
| `/v1/chat/completions` | `POST` | Kora Coder / NanoKora | Standard OpenAI chat completions (supports SSE streaming) |
| `/v1/coder/generate` | `POST` | Kora Coder | Production-ready code generation with strict anti-tutorial filter |
| `/v1/coder/fix` | `POST` | Kora Coder | Automated bug diagnosis and syntax/logic code repair |
| `/v1/images/generations` | `POST` | Kora Image Studio | OpenAI-compatible text-to-image generation (pristine, 100% watermark-free) |
| `/v1/vision/analyze` | `POST` | Kora Vision | Upload screenshot/mockup $\to$ outputs clean HTML/Tailwind code |
| `/v1/agent/distribute` | `POST` | Agent Swarm | Decomposes complex goals into Backend, Frontend, and QA subtasks |
| `/api/devos/webhook` | `POST` | DevOS Bridge | Webhook dispatcher for background coding events, PR reviews, and build repair |

---

## 3. Detailed Endpoint Specifications

### A. Health & Diagnostics (`GET /health`)
**Response (HTTP 200)**:
```json
{
  "status": "healthy",
  "device": "cuda",
  "models": {
    "coder": "Qwen2.5-Coder-0.5B-Instruct",
    "vision": "Kora Multimodal Engine",
    "image": "Kora Clean Studio Engine",
    "agent": "Kora Autonomous Orchestrator"
  },
  "cors": "enabled"
}
```

---

### B. Chat & Code Completions (`POST /v1/chat/completions`)
Full OpenAI-compatible request body:
```json
{
  "model": "kora-coder-0.5b",
  "messages": [
    {"role": "system", "content": "You are Kora Coder in DevOS. Direct production code only."},
    {"role": "user", "content": "Write a FastAPI route with Pydantic validation for user onboarding."}
  ],
  "temperature": 0.2,
  "max_tokens": 1024,
  "stream": true
}
```
* **Routing Logic**:
  * Default model: `kora-coder-0.5b` (Qwen2.5-Coder).
  * Auto-injects anti-tutorial system prompt if not present.
* **Streaming Protocol**: When `stream: true`, return chunks via Server-Sent Events (`data: {...}\n\n`) terminating with `data: [DONE]\n\n`.

---

### C. Direct Code Generation & Repair

#### 1. Generate (`POST /v1/coder/generate`)
```json
{
  "prompt": "Create a Redis token bucket rate limiter in Python",
  "language": "python",
  "max_tokens": 1024
}
```

#### 2. Repair Broken Code (`POST /v1/coder/fix`)
```json
{
  "broken_code": "def query_db(uid):\n  cursor.execute('SELECT * FROM users WHERE id = ' + uid)",
  "error_message": "SQL injection vulnerability detected / Syntax error on string concat",
  "language": "python"
}
```

---

### D. Image Generation (`POST /v1/images/generations`)
DALL-E compatible request body:
```json
{
  "prompt": "Futuristic dark minimalist Kontyra AI glowing neon cyber emblem, 3d isometric render",
  "n": 1,
  "size": "1024x1024",
  "response_format": "url"
}
```
* **Response (HTTP 200)**:
```json
{
  "created": 1728073200,
  "data": [
    {
      "revised_prompt": "Futuristic dark minimalist Kontyra AI glowing neon cyber emblem, 3d isometric render",
      "url": "https://kora.kontyra.name.ng/assets/kontyra_emblem_clean.png"
    }
  ]
}
```
* **Pristine Quality Guarantee**: Must run watermark-stripping filter (`nologo=true` + PIL boundary scan) to ensure zero unwanted third-party stamps or logos.

---

### E. Multimodal Vision UI-to-Code (`POST /v1/vision/analyze`)
Request Body:
```json
{
  "image": "data:image/png;base64,iVBORw0KGgoAAA...",
  "prompt": "Convert this dashboard mockup into clean Tailwind CSS components.",
  "task_type": "ui_to_code"
}
```
* **Response (HTTP 200)**:
```json
{
  "task_type": "ui_to_code",
  "analysis": "Identified top navigation bar, 3 metric cards, and a dark themed activity table.",
  "code": "<div class=\"min-h-screen bg-black text-white p-6\">\n  <!-- Kontyra Dashboard Component -->\n</div>"
}
```

---

### F. Multi-Agent Task Distribution (`POST /v1/agent/distribute`)
Deconstructs complex high-level engineering objectives into synchronized subagents:
```json
{
  "goal": "Build an authentication service with JWT and SQLite",
  "context": "Needs refresh token rotation and bcrypt hashing",
  "subagents": ["architect", "backend", "frontend", "tester"]
}
```
* **Response (HTTP 200)**:
```json
{
  "goal": "Build an authentication service with JWT and SQLite",
  "status": "completed",
  "orchestrator": "Kora Swarm v2",
  "plan": "1. Architect: SQLite schema & token lifetime...\n2. Backend: FastAPI auth router...\n3. Frontend: Login dialog...\n4. Tester: Pytest edge cases",
  "deliverables": {
    "backend_code": "import jwt\nfrom datetime import datetime...",
    "frontend_code": "export default function LoginForm() { ... }"
  }
}
```

---

### G. DevOS Webhook Dispatcher (`POST /api/devos/webhook`)
Handles automated triggers from DevOS:
```json
{
  "event_type": "build_failure",
  "repository": "kontyra/core",
  "branch": "master",
  "error_log": "TypeError: Cannot read properties of undefined (reading 'map') at line 42"
}
```
* **Action**: Parses the error log, isolates the faulty file/line, and returns the concrete patch.

---

## 4. Running Alongside Kora on Vercel as One System

To make Vercel and your custom endpoint act as **ONE unified platform**, follow these two configuration steps:

### Step 1: Vercel Environment Configuration
In your Vercel Project Settings (`kora-three-alpha`):
1. Navigate to **Settings** $\to$ **Environment Variables**.
2. Add the variable:
   ```env
   KORA_CUSTOM_ENDPOINT = https://your-custom-endpoint-domain.com
   ```
   *(e.g., `https://kora-gateway.modal.run`, `https://kora-coder.yourdomain.com`, or your public Cloudflare Tunnel URL).*
3. (Optional) If you protect your endpoint with a secret token:
   ```env
   KORA_API_KEY = your_kontyra_master_secret_key
   ```

### Step 2: How Vercel Routes Requests Seamlessly (`api/chat.py`)
The Vercel function inspects each incoming payload:
```python
# Conceptual routing inside api/chat.py on Vercel:
custom_endpoint = os.environ.get("KORA_CUSTOM_ENDPOINT", "")

# 1. If user asks for general chat / math or no custom endpoint is set:
if not custom_endpoint or requested_model == "nanokora-25m":
    # Run locally on Vercel serverless CPU with NanoKora ONNX (<26MB, sub-millisecond)
    return run_local_nanokora(prompt)

# 2. If user requests Kora Coder, Image Studio, Vision, or Agent Swarm:
elif requested_model in ["kora-coder", "kora-image", "kora-vision", "kora-agent"]:
    # Transparently proxy outbound HTTPS request to your custom endpoint
    upstream_url = f"{custom_endpoint}/v1/chat/completions" # or /v1/images/generations
    return proxy_to_custom_endpoint(upstream_url, payload)
```

**Result**:
- End users always visit `https://kora-three-alpha.vercel.app`.
- API clients always hit `https://kora-three-alpha.vercel.app/api/chat`.
- Vercel automatically acts as the intelligent edge router, making both runtimes appear as **a single cohesive service**.

---

## 5. Deployment Recipes for Your Custom Endpoint

The custom endpoint script is provided in the repository at [`gateway.py`](file:///C:/Users/user/Documents/GitHub/kora/gateway.py).

### Recipe A: Expose Local Machine with Cloudflare Tunnel (Zero Cost)
If you already have the models downloaded locally on your PC or USB drive (`D:\kora_storage`):
1. Start the gateway locally:
   ```powershell
   uv run python gateway.py --port 8000
   ```
2. In a second terminal, launch a free Cloudflare Tunnel:
   ```powershell
   cloudflared tunnel --url http://localhost:8000
   ```
3. Copy the generated public URL (e.g. `https://rapid-fox-xyz.trycloudflare.com`).
4. Set this URL as `KORA_CUSTOM_ENDPOINT` in Vercel. Your Vercel deployment is now connected to your own PC running 0.5B Coder and Vision!

### Recipe B: Deploy to Modal (Serverless GPU)
Create a `modal_app.py`:
```python
import modal

app = modal.App("kora-gateway")
image = modal.Image.debian_slim().pip_install(
    "fastapi", "uvicorn", "transformers", "torch", "pillow", "pydantic"
)

@app.function(image=image, gpu="T4", timeout=300)
@modal.asgi_app()
def fastapi_app():
    from gateway import app
    return app
```
Deploy with: `modal deploy modal_app.py`.

### Recipe C: Deploy with Docker to Render / RunPod / DigitalOcean VPS
`Dockerfile`:
```dockerfile
FROM python:3.11-slim

WORKDIR /app
RUN apt-get update && apt-get install -y git curl && rm -rf /var/lib/apt/lists/*

COPY requirements.txt pyproject.toml ./
RUN pip install --no-cache-dir fastapi uvicorn torch transformers pillow pydantic

COPY . .

EXPOSE 8000
CMD ["python", "gateway.py", "--host", "0.0.0.0", "--port", "8000"]
```

---

## 6. Verification Checklist for the Engineer

Before marking the deployment complete, verify each endpoint:

- [ ] **Health Check**:
  ```bash
  curl -X GET "https://your-custom-endpoint.com/health"
  ```
- [ ] **OpenAI Coder Completion**:
  ```bash
  curl -X POST "https://your-custom-endpoint.com/v1/chat/completions" \
       -H "Content-Type: application/json" \
       -d '{"model":"kora-coder-0.5b","messages":[{"role":"user","content":"Write a binary search in Python"}]}'
  ```
- [ ] **Watermark-Free Image Generation**:
  ```bash
  curl -X POST "https://your-custom-endpoint.com/v1/images/generations" \
       -H "Content-Type: application/json" \
       -d '{"prompt":"Kontyra dark minimalist neon icon","size":"1024x1024"}'
  ```
- [ ] **Agent Swarm Decomposition**:
  ```bash
  curl -X POST "https://your-custom-endpoint.com/v1/agent/distribute" \
       -H "Content-Type: application/json" \
       -d '{"goal":"Create user login API"}'
  ```
- [ ] **Vercel Integration Test**:
  Make a request to `https://kora-three-alpha.vercel.app/api/chat` with `{"model": "kora-coder", "message": "hello"}` and confirm it delegates to the custom endpoint.