Documentation

Ship TALON in two lines

Quickstart, core routing concepts, SDK reference, agent framework wrappers, and self-hosted deployment for the KEEL Core engine.

Get started

Quickstart — 2-minute integration

01

Install the SDK

TALON ships wire-compatible clients for Python 3.9+ and Node 18+. No sidecar, no infrastructure changes.

terminal
# Python
pip install talon-ai

# TypeScript / Node
npm i @talon/sdk
02

Set environment variables

Create a key in the dashboard, then export it. TALON_BASE_URL is optional and only needed for self-hosted VPC instances.

terminal
export TALON_API_KEY="tl_live_xxxxxxxxxxxxxxxx"

# Optional: Only needed for self-hosted VPC instances
export TALON_BASE_URL="http://localhost:4000/v1"
03

Replace provider client

Swap the constructor. Every request, stream, and tool call keeps the same shape — cascading and strip-mining are on by default.

main.py
from talon import Talon

client = Talon(api_key=os.environ["TALON_API_KEY"])

resp = client.chat.completions.create(
    model="talon/auto",  # Cognitive routing decides the optimal tier
    messages=[{"role": "user", "content": "Classify this ticket."}],
)
04

Verify routing metrics locally

Run the local control plane on port 4000 to watch tier decisions, tokens saved, and P99 overhead in real time.

terminal
$ talon dev --port 4000
# Watching local proxy at http://localhost:4000
✔ route: slm:llama-3.1-8b | overhead: 7.2ms | saved: $0.0091
Get started

Model Cascading

Every request passes a Tier 1 regex/schema heuristic (<1ms) and a Tier 2 quantized INT8 ONNX classifier (3–8ms). Low-reasoning prompts resolve on a local SLM; only genuinely hard prompts reach a frontier model. A deterministic circuit breaker escalates automatically when an SLM returns malformed output.

cascade.py
resp = client.chat.completions.create(
    model="talon/auto",
    messages=messages,
    talon={
        "cascade": "aggressive",  # "conservative" | "balanced" | "aggressive"
        "min_tier": "slm",
        "max_tier": "frontier",
        "fallback": "gpt-4o",
        "schema_retry": 1,
    },
)
Get started

Context Pruning

Strip-mining hashes stable system prompts so they are billed once and replayed at zero cost, then removes duplicated retrieval chunks and dead context before egress. Output fidelity is preserved — pruning is lossless with respect to the answer surface.

pruning.py
resp = client.chat.completions.create(
    model="talon/auto",
    messages=messages,
    talon={"strip_mining": True, "dedupe_chunks": True, "max_context": 8000},
)

print(f"Tokens Saved: {resp.talon.tokens_saved}")  # Output: 4812
print(f"Prompt Hash: {resp.talon.prompt_hash}")    # Output: sha256:1f9c (cached)
SDK Reference

talon-python & talon-ts

Both clients mirror the OpenAI surface: chat.completions.create, streaming, tool calls, and embeddings. Every response carries a talon block with the chosen route, overhead, and savings.

main.py·pip install talon-python
1import talon
2 
3client = talon.Client(api_key="tl_live_...") # Drop-in replacement for OpenAI
4 
5resp = client.chat.completions.create(
6 model="talon/auto", # Cognitive routing decides the optimal tier
7 messages=[{"role": "user", "content": "Extract the invoice total."}],
8 talon={"max_tier": "frontier", "strip_mining": True}
9)
10 
11print(resp.choices[0].message.content)
12 
13# Response metadata:
14# talon.route -> "slm:llama-3.1-8b" | Latency: 42ms | Saved: $0.0089
Agent Frameworks

LangChain, CrewAI & AutoGen

Drop-in wrappers keep long agent loops cheap: the system prompt is hashed once and replayed across every step.

langchain.py
from talon.langchain import ChatTalon

llm = ChatTalon(model="talon/auto", strip_mining=True)
chain = prompt | llm
crew.py
from talon.crewai import TalonRouter

router = TalonRouter(policy="cost_first", fallback="claude-3-5-sonnet")
researcher = Agent(role="Researcher", llm=router.llm())
autogen.py
from autogen import AssistantAgent

config_list = [{
    "model": "talon/auto",
    "api_key": os.environ["TALON_API_KEY"],
    "base_url": "https://api.talon.ai/v1",
}]

assistant = AssistantAgent("planner", llm_config={"config_list": config_list})
Deployment

Docker, Kubernetes & Helm

Run KEEL Core inside your own VPC for zero-data-retention, SOC2, and HIPAA workloads. The Rust data plane is a single static binary; telemetry ships asynchronously.

docker-compose.yml
services:
  keel:
    image: ghcr.io/talon-ai/keel-core:v1.0
    ports:
      - "4000:4000"
    environment:
      TALON_API_KEY: "${TALON_API_KEY}"
      TALON_ZDR: "true"
keel-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: keel-core
spec:
  replicas: 3
  template:
    spec:
      containers:
        - name: keel
          image: ghcr.io/talon-ai/keel-core:v1.0
          ports:
            - containerPort: 4000
terminal
helm repo add talon https://charts.talon.ai

helm install keel talon/keel-core \
  --set zdr.enabled=true \
  --set autoscaling.minReplicas=3

Stop Paying Top-Tier Prices for Basic String Utilities.

Route intelligently, prune aggressively, and reserve frontier reasoning for the requests that actually need it. Two lines of code, sub-10ms overhead.