X25: Autonomous LLM Routing

X25 routes every LLM call to the cheapest model that meets your quality bar. It learns per project using Thompson Sampling, judges quality automatically, escalates when needed, and trains a custom model on your call history at Stage 4.

5-minute setup

1. Install the SDK

   pip install x25-sdk
   bash

2. Generate your API key

   Log into your dashboard with appropriate credentials after creating an account. Go to the hamburger menu on the top navigation bar and click on Generate API Key. Check your organisation name, then click Proceed. You can now copy your retrieved API key to authenticate your SDK calls.

3. Route your first call

   from  x25 import X25
   
   agent = X25(
       api_key="sk-x25-a1b2c3d4...",
       prompt="your-prompt",
       org="my-research-lab")
   
   result = agent.complete()
   
   print(result)
   python

Installation

The SDK has two components: the Python client (lightweight, just httpx) and the gateway server (runs locally or on your infrastructure).

SDK only

pip install x25-sdk
bash

Gateway + full stack

pip install -r requirements.txt
# includes FastAPI, LangGraph, LangChain, OpenAI, aiosqlite, numpy
bash

Environment variables

# .env
OPENROUTER_API_KEY=sk-or-...    # required, routes to 300+ models
OPENAI_API_KEY=sk-...           # required, LLM-as-judge + classifier
bash

Authentication

Every project gets an API key scoped to org. X25 uses this to isolate learning, savings, and audit records per project.

Pass the key as a Bearer token on every request:

Authorization: Bearer sk-x25-a1b2c3d4...
http

X25()

Create an agent instance. The agent holds your project config and re-uses it across calls.

X25(
    org: str = "default",
    optimize_for: dict = {"cost": 0.33, "quality": 0.34, "latency": 0.33},
    policy: dict = {},
    gateway_url: str = "http://localhost:8000",
    api_key: str = None,
)
python

agent.complete()

Route a prompt to the best available model. X25 classifies the task, selects a tier, dispatches, judges quality, escalates if needed, and updates its own learning. All in one call.

agent.complete(
    prompt: str,
    hint: str = None,
) -> X25Response
python

X25Response

@dataclass
class X25Response:
    text:             str    # the model's answer
    model_used:       str    # e.g. "deepseek/deepseek-v4-flash"
    provider:         str    # e.g. "deepseek"
    task_type:        str    # classified task: "summary", "code", etc.
    cost_usd:         float  # actual cost of this call
    latency_ms:       float  # end-to-end latency in milliseconds
    quality_score:    float  # 0.0–1.0, LLM-as-judge
    cascade_steps:    int    # 1 = first tier passed, 2+ = escalated
    audit_hash:       str    # SHA-256 hash, tamper-evident
    goal_match:       dict   # per-dimension score vs your optimize_for
python

optimize_for

Tell X25 what matters most for your project. Weights must sum to 1.0. X25 normalises automatically if they don't.

Common profiles

# Cost-first, for high-volume pipelines
optimize_for={"cost": 0.7, "quality": 0.2, "latency": 0.1}

# Quality-first, for research and publication
optimize_for={"cost": 0.1, "quality": 0.8, "latency": 0.1}

# Balanced, default
optimize_for={"cost": 0.33, "quality": 0.34, "latency": 0.33}

# Latency-first, for real-time use
optimize_for={"cost": 0.1, "quality": 0.2, "latency": 0.7}
python

POST /route

The core routing endpoint. The SDK calls this on every agent.complete().

GET /stats/{project}

Aggregated stats for a project. Use all to aggregate across all projects.

GET /stage/{project}

Current stage and progression for a project.

GET /thompson/{project}

Live Thompson Sampling state. Shows Beta distributions for each tier.

Stages

X25 autonomously advances through four stages as calls accumulate. Each stage unlocks new capabilities.

Thompson Sampling

X25 models each tier as a Beta distribution Beta(α, β) representing the posterior over "reward probability": how often this tier passes quality on your tasks.

# Each call:
θ_slm      = Beta(α_slm, β_slm).sample()
θ_mid      = Beta(α_mid, β_mid).sample()
θ_frontier = Beta(α_frontier, β_frontier).sample()
tier       = argmax([θ_slm, θ_mid, θ_frontier])

# After observing quality, update the dispatched arm:
α += reward
β += (1 - reward)
python

Cheaper tiers naturally receive more traffic as their α grows. Frontier is selected only when SLM and mid lack sufficient evidence.

Audit trail

Every routing decision is written to a hash-chained audit log. Any modification to a historical record breaks the chain.

# Each record contains:
record_hash = SHA256(prev_hash + record_content)

# Verify integrity:
curl http://localhost:8000/verify
# → {"intact": true, "total_records": 301}
bash

Fine-tuning (Stage 4)

At 500 calls, X25 extracts your highest-quality call history and generates a LoRA fine-tuning script for Llama 3.2 3B.

# Trigger at Stage 4:
curl -X POST http://localhost:8000/improve/my-research-lab \
  -H "Authorization: Bearer sk-x25-..."
bash

Manager terminal

A business-facing view of X25. Shows weekly savings, call volume, model mix, and a chat interface where managers can ask questions about AI spend and routing decisions. No code required.

What managers see