# 🌐 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": "
\n \n
" } ``` --- ### 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.