Metadata-Version: 2.4
Name: x25-sdk
Version: 0.1.0
Summary: Autonomous LLM routing agent. Self-learning, cost-aware, auditable.
Author-email: X25 <team@x25.ai>
License: MIT
Project-URL: Homepage, https://github.com/x25ai/x25
Project-URL: Documentation, https://github.com/x25ai/x25#readme
Keywords: llm,routing,agent,openrouter,cost-optimization
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.28.0
Requires-Dist: pydantic>=2.10.0
Provides-Extra: gateway
Requires-Dist: fastapi>=0.115.0; extra == "gateway"
Requires-Dist: uvicorn[standard]>=0.32.0; extra == "gateway"
Requires-Dist: langgraph>=0.2.60; extra == "gateway"
Requires-Dist: langchain-core>=0.3.28; extra == "gateway"
Requires-Dist: openai>=1.76.0; extra == "gateway"
Requires-Dist: numpy>=2.0.0; extra == "gateway"
Requires-Dist: aiosqlite>=0.20.0; extra == "gateway"
Requires-Dist: python-dotenv>=1.0.0; extra == "gateway"
Requires-Dist: websockets>=14.0; extra == "gateway"

# X25 — Autonomous LLM Routing Agent

X25 routes every LLM call to the cheapest model that meets your quality bar. It learns per-organization using Thompson Sampling, audits every decision in a tamper-evident hash chain, and fine-tunes a custom model on your call history at Stage 4.

```python
from x25 import X25

agent = X25(api_key="sk-x25-...", gateway_url="http://localhost:8000")

result = agent.complete(
    "Summarize this paper abstract...",
    hint="summary"
)

print(result.text)          # the answer
print(result.model_used)    # which model X25 picked
print(result.cost_saved_usd)  # how much cheaper vs frontier
```

## Install

```bash
pip install x25-sdk
```

## What it does

- **Routes** each call to the cheapest tier (SLM / Mid / Frontier) likely to pass quality
- **Learns** per org using Thompson Sampling — converges in 50-200 calls
- **Judges** quality automatically using LLM-as-judge scoring
- **Escalates** automatically if quality fails — no manual fallback logic
- **Audits** every decision in a cryptographic hash chain
- **Fine-tunes** a custom SLM on your call history at Stage 4 (500+ calls)

## Stages

| Stage | Calls | What happens |
|-------|-------|-------------|
| 1: Explore | 0-49 | Tries all tiers, learns your task mix |
| 2: Exploit | 50-199 | Converges to cheapest reliable tier |
| 3: Feedback | 200-499 | Asks for labelled examples |
| 4: Fine-tune | 500+ | Trains custom LoRA, enters routing pool |
