Initial commit: KORA routing agent skeleton for AMD hackathon Track 1

Author: hkalbertkim

.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+.env
+results.json
+
+# internal handoff - never commit to public repo
+HANDOFF.md

Dockerfile

@@ -0,0 +1,26 @@
+# KORA token-efficient routing agent, container image.
+#
+# The routing core is pure Python with a single runtime dependency (the
+# OpenAI-compatible client used for remote Fireworks calls), so the base image
+# stays slim. The local small-model layer (e.g. Gemma weights + runtime) is
+# added on launch day once the allowed models and scoring environment are known.
+
+FROM python:3.11-slim
+
+ENV PYTHONUNBUFFERED=1 \
+    PYTHONDONTWRITEBYTECODE=1
+
+WORKDIR /app
+
+COPY requirements.txt ./
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY kora_router ./kora_router
+
+# FIREWORKS_API_KEY and REMOTE_MODEL are supplied at run time via env vars.
+# Example:
+#   docker run --rm -e FIREWORKS_API_KEY=... -e REMOTE_MODEL=accounts/fireworks/models/... \
+#     -v "$PWD":/data kora-router \
+#     python -m kora_router.main --tasks /data/tasks.json --out /data/results.json
+
+ENTRYPOINT ["python", "-m", "kora_router.main"]

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Krako Labs, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,74 @@
+# KORA Router (AMD Developer Hackathon, Track 1)
+
+A token-efficient routing agent. KORA decides, before any remote inference, how
+each unit of work should be handled: resolved by cheap deterministic or local
+computation, or escalated to a remote model only when nothing cheaper is
+confident. Remote token usage is a direct, measurable consequence of that
+routing.
+
+## Status
+
+This is the launch-day skeleton. The pipeline runs end to end with a placeholder
+routing policy that escalates every task to the remote model, so the container
+is runnable and testable before the task set is published. The real routing
+logic (deterministic rules first, a local small model for cheap-but-non-trivial
+work, remote only when needed) is added once the task I/O format and the allowed
+models are known.
+
+## Layout
+
+```
+kora_router/
+  main.py             entry point: load tasks, route each, write results
+  router.py           Route / RouteDecision / Router
+  local_model.py      local backend
+  fireworks_client.py remote backend (OpenAI-compatible Fireworks endpoint)
+Dockerfile            python:3.11-slim image, single runtime dependency
+requirements.txt      openai client (local backend deps added on launch day)
+```
+
+## Setup
+
+```
+pip install -r requirements.txt
+```
+
+Remote calls use the OpenAI-compatible Fireworks endpoint. Supply credentials
+and the model id at run time via environment variables:
+
+```
+export FIREWORKS_API_KEY=...
+export REMOTE_MODEL=accounts/fireworks/models/<model>
+```
+
+## Usage
+
+```
+python -m kora_router.main --tasks tasks.json --out results.json
+```
+
+Arguments:
+
+- `--tasks` path to the task JSON (required). Accepts either a list of tasks or
+  an object with a `tasks` key.
+- `--out` output path (default `results.json`).
+- `--remote-model` Fireworks model id. Falls back to the `REMOTE_MODEL`
+  environment variable.
+
+The output records, per task, the chosen route and the remote token count, plus
+a summary with total remote tokens, remote call count, and route counts.
+
+## Docker
+
+```
+docker build -t kora-router .
+docker run --rm \
+  -e FIREWORKS_API_KEY=... \
+  -e REMOTE_MODEL=accounts/fireworks/models/<model> \
+  -v "$PWD":/data \
+  kora-router --tasks /data/tasks.json --out /data/results.json
+```
+
+## License
+
+MIT. See LICENSE.

kora_router/__init__.py

@@ -0,0 +1,5 @@
+"""KORA token-efficient routing agent (AMD Hackathon ACT II, Track 1)."""
+
+from .router import Route, RouteDecision, Router, TaskResult
+
+__all__ = ["Route", "RouteDecision", "Router", "TaskResult"]

kora_router/fireworks_client.py

@@ -0,0 +1,74 @@
+"""Remote model client for the Fireworks AI inference API.
+
+Fireworks exposes an OpenAI-compatible endpoint, so the standard `openai`
+client works by pointing `base_url` at the Fireworks inference host. Every
+call records prompt/completion token usage, which the routing layer uses to
+account for remote spend (local tokens are free under the challenge scoring).
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+
+from openai import OpenAI
+
+FIREWORKS_BASE_URL = "https://api.fireworks.ai/inference/v1"
+
+
+@dataclass
+class RemoteUsage:
+    """Running tally of remote token spend."""
+
+    prompt_tokens: int = 0
+    completion_tokens: int = 0
+    calls: int = 0
+
+    @property
+    def total_tokens(self) -> int:
+        return self.prompt_tokens + self.completion_tokens
+
+    def add(self, prompt: int, completion: int) -> None:
+        self.prompt_tokens += prompt
+        self.completion_tokens += completion
+        self.calls += 1
+
+
+@dataclass
+class RemoteResult:
+    text: str
+    prompt_tokens: int
+    completion_tokens: int
+    model: str
+
+
+class FireworksClient:
+    """Thin wrapper over the OpenAI-compatible Fireworks chat endpoint."""
+
+    def __init__(self, model: str, api_key: str | None = None,
+                 base_url: str = FIREWORKS_BASE_URL) -> None:
+        key = api_key or os.getenv("FIREWORKS_API_KEY")
+        if not key:
+            raise RuntimeError("FIREWORKS_API_KEY is not set")
+        self._client = OpenAI(base_url=base_url, api_key=key)
+        self.model = model
+        self.usage = RemoteUsage()
+
+    def chat(self, messages: list[dict], *, temperature: float = 0.0,
+             max_tokens: int = 512) -> RemoteResult:
+        resp = self._client.chat.completions.create(
+            model=self.model,
+            messages=messages,
+            temperature=temperature,
+            max_tokens=max_tokens,
+        )
+        usage = resp.usage
+        prompt = getattr(usage, "prompt_tokens", 0) or 0
+        completion = getattr(usage, "completion_tokens", 0) or 0
+        self.usage.add(prompt, completion)
+        return RemoteResult(
+            text=resp.choices[0].message.content or "",
+            prompt_tokens=prompt,
+            completion_tokens=completion,
+            model=self.model,
+        )

kora_router/local_model.py

@@ -0,0 +1,56 @@
+"""Local small-model wrapper.
+
+The routing layer sends "easy" work here instead of the remote model. Under
+the challenge scoring, tokens spent locally count as zero, so the local model
+should be sized to run inside the standardized scoring environment (a small
+open model such as Gemma is the intended fit).
+
+The concrete backend is deliberately pluggable: the exact model and runtime
+(transformers, llama.cpp, a served endpoint, etc.) are fixed on launch day once
+the allowed models and environment constraints are published. Everything above
+this module only depends on the `LocalResult` shape and the `generate` method,
+so swapping the backend does not touch the router.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Protocol
+
+
+@dataclass
+class LocalResult:
+    text: str
+    # Local tokens are free under scoring, but we still track them for analysis.
+    prompt_tokens: int = 0
+    completion_tokens: int = 0
+
+
+class LocalBackend(Protocol):
+    def generate(self, messages: list[dict], *, temperature: float,
+                 max_tokens: int) -> LocalResult:
+        ...
+
+
+class EchoBackend:
+    """Placeholder backend used until the real local model is wired in.
+
+    Returns an empty completion so the pipeline is runnable end-to-end before
+    launch day. Replaced by the actual small-model backend once the allowed
+    models are known.
+    """
+
+    def generate(self, messages: list[dict], *, temperature: float = 0.0,
+                 max_tokens: int = 512) -> LocalResult:
+        return LocalResult(text="", prompt_tokens=0, completion_tokens=0)
+
+
+class LocalModel:
+    def __init__(self, backend: LocalBackend | None = None) -> None:
+        self._backend = backend or EchoBackend()
+
+    def chat(self, messages: list[dict], *, temperature: float = 0.0,
+             max_tokens: int = 512) -> LocalResult:
+        return self._backend.generate(
+            messages, temperature=temperature, max_tokens=max_tokens
+        )

kora_router/main.py

@@ -0,0 +1,92 @@
+"""Entry point for running the KORA routing agent over a task set.
+
+Usage (finalized on launch day once the task I/O format is published):
+
+    python -m kora_router.main --tasks tasks.json --out results.json
+
+For now this wires the pipeline end-to-end with a placeholder decision function
+so the container is runnable and testable before the tasks are released.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+from .fireworks_client import FireworksClient
+from .local_model import LocalModel
+from .router import Route, RouteDecision, Router
+
+
+def default_decision(task: dict[str, Any]) -> RouteDecision:
+    """Placeholder routing policy.
+
+    Replaced on launch day with the real KORA decision logic (deterministic
+    rules first, local model for cheap-but-non-trivial work, remote only when
+    nothing cheaper is confident). Until then, everything escalates to remote so
+    the pipeline produces answers end-to-end.
+    """
+    return RouteDecision(route=Route.REMOTE, reason="placeholder: escalate all")
+
+
+def load_tasks(path: Path) -> list[dict[str, Any]]:
+    data = json.loads(path.read_text(encoding="utf-8"))
+    if isinstance(data, dict) and "tasks" in data:
+        return list(data["tasks"])
+    if isinstance(data, list):
+        return data
+    raise ValueError("unrecognized task file shape")
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--tasks", required=True, help="path to task JSON")
+    ap.add_argument("--out", default="results.json")
+    ap.add_argument("--remote-model",
+                    default=os.getenv("REMOTE_MODEL", ""),
+                    help="Fireworks model id (accounts/fireworks/models/...)")
+    args = ap.parse_args()
+
+    tasks = load_tasks(Path(args.tasks))
+    local = LocalModel()
+    remote = FireworksClient(model=args.remote_model)
+    router = Router(decide=default_decision, local=local, remote=remote)
+
+    results = []
+    for task in tasks:
+        r = router.run_task(task)
+        results.append({
+            "id": r.task_id,
+            "answer": r.answer,
+            "route": r.route.value,
+            "reason": r.reason,
+            "remote_tokens": r.remote_tokens,
+        })
+
+    total_remote = sum(r["remote_tokens"] for r in results)
+    payload = {
+        "results": results,
+        "summary": {
+            "n_tasks": len(results),
+            "total_remote_tokens": total_remote,
+            "remote_calls": remote.usage.calls,
+            "route_counts": _route_counts(results),
+        },
+    }
+    Path(args.out).write_text(json.dumps(payload, indent=2), encoding="utf-8")
+    print(f"wrote {args.out}: {len(results)} tasks, "
+          f"{total_remote} remote tokens, {remote.usage.calls} remote calls")
+
+
+def _route_counts(results: list[dict]) -> dict[str, int]:
+    counts: dict[str, int] = {}
+    for r in results:
+        counts[r["route"]] = counts.get(r["route"], 0) + 1
+    return counts
+
+
+if __name__ == "__main__":
+    main()