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):

{
  "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:

{
  "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)

{
  "prompt": "Create a Redis token bucket rate limiter in Python",
  "language": "python",
  "max_tokens": 1024
}

2. Repair Broken Code (POST /v1/coder/fix)

{
  "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:

{
  "prompt": "Futuristic dark minimalist Kontyra AI glowing neon cyber emblem, 3d isometric render",
  "n": 1,
  "size": "1024x1024",
  "response_format": "url"
}

• Response (HTTP 200):

{
  "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:

{
  "image": "data:image/png;base64,iVBORw0KGgoAAA...",
  "prompt": "Convert this dashboard mockup into clean Tailwind CSS components.",
  "task_type": "ui_to_code"
}

• Response (HTTP 200):

{
  "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:

{
  "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):

{
  "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:

{
  "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:

   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:

   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:

# 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.

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:

   uv run python gateway.py --port 8000
   

2. In a second terminal, launch a free Cloudflare Tunnel:

   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:

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:

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:

  curl -X GET "https://your-custom-endpoint.com/health"
  

• OpenAI Coder Completion:

  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:

  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:

  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.