Developer Integration

Developer integration

Full setup guide. Define your goals, pick your models, tell Kalibr what success looks like, and let the Router learn which path works best. If you just want to see it work first, start with the Quickstart.

Using a coding agent? If Claude Code, Codex, or Cursor is writing the integration, give it this prompt and your credentials. It handles everything.

Read https://kalibr.systems/llms.txt and integrate Kalibr into this project.

Then skip to the Verify step at the bottom.

1. Create an API key

Your Tenant ID is assigned when you create an account. Create an API key separately in Settings > API Keys. The key is only shown once. Copy it before closing the dialog.

KALIBR_API_KEY

sk_... (create in Settings > API Keys)

KALIBR_TENANT_ID

user_... (from your account, shown in Settings)

2. Install the SDK

terminal

pip install kalibr openai anthropic

3. Set credentials

.env

KALIBR_API_KEY=sk_...
KALIBR_TENANT_ID=user_...
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...

4. Replace your LLM call

import kalibr must be the first import in the file where your LLM client is created. This is how the SDK patches the provider clients at import time.

agent.py

import kalibr  # must be first import
from kalibr import Router

router = Router(
    goal="summarize",
    paths=["gpt-4o", "claude-sonnet-4-20250514", "deepseek-chat"],
    success_when=lambda out: len(out) > 50
)
response = router.completion(
    messages=[{"role": "user", "content": "Summarize: ..."}]
)
print(response.choices[0].message.content)
# router.report() is called automatically when success_when is set

Manual reporting when your validation is too complex for a lambda:

agent.py

router = Router(goal="book_meeting", paths=["gpt-4o", "claude-sonnet-4-20250514"])
response = router.completion(messages=[...])
# your validation logic
router.report(success=meeting_was_booked)

Continuous scoring for finer-grained quality signals (0.0 to 1.0):

agent.py

router = Router(
    goal="draft_email",
    paths=["gpt-4o", "claude-sonnet-4-20250514"],
    score_when=lambda out: min(1.0, len(out) / 800)
)

terminal

npm install @kalibr/sdk openai

3. Set credentials

.env

KALIBR_API_KEY=sk_...
KALIBR_TENANT_ID=user_...
OPENAI_API_KEY=sk-...

4. Replace your LLM call

agent.ts

import kalibr from "@kalibr/sdk";
import { Router } from "@kalibr/sdk";

const router = new Router({
    goal: "summarize",
    paths: ["gpt-4o", "claude-sonnet-4-20250514"],
    successWhen: (out) => out.length > 50,
});
const response = await router.completion([
    { role: "user", content: "Summarize: ..." }
]);
console.log(response.choices[0].message.content);

terminal

pip install kalibr[langchain] langchain langchain-openai langchain-anthropic

3. Set credentials

.env

KALIBR_API_KEY=sk_...
KALIBR_TENANT_ID=user_...
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...

4. Swap in the Kalibr LLM

router.as_langchain() returns a drop-in LangChain LLM. Use it anywhere you would use ChatOpenAI or ChatAnthropic.

chain.py

from kalibr import Router
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import StrOutputParser

router = Router(goal="summarize_text", paths=["gpt-4o-mini", "claude-sonnet-4-20250514"])
chain = (
    ChatPromptTemplate.from_template("Summarize: {text}")
    | router.as_langchain()
    | StrOutputParser()
)
result = chain.invoke({"text": "Your document..."})
router.report(success=len(result) > 50)

terminal

pip install kalibr[crewai] crewai openai anthropic

Requires Python 3.10 or higher.

3. Set credentials

.env

KALIBR_API_KEY=sk_...
KALIBR_TENANT_ID=user_...
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...

4. Pass router.as_langchain() as your agent LLM

One change. Pass the Kalibr router as the LLM for your CrewAI agent.

crew.py

from kalibr import Router
from crewai import Agent, Task, Crew

router = Router(goal="research_task", paths=["gpt-4o-mini", "claude-sonnet-4-20250514"])
researcher = Agent(
    role="Researcher", goal="Find accurate information",
    backstory="Research assistant.",
    llm=router.as_langchain(),
)
task = Task(description="...", expected_output="...", agent=researcher)
result = Crew(agents=[researcher], tasks=[task]).kickoff()
router.report(success=len(str(result)) > 100)

terminal

pip install kalibr[openai-agents] openai-agents

3. Set credentials

.env

KALIBR_API_KEY=sk_...
KALIBR_TENANT_ID=user_...
OPENAI_API_KEY=sk-...

4. Use Kalibr to pick the model for your Agent

get_policy() returns the current recommended model for a goal. Pass it directly to your Agent.

agent.py

from kalibr import Router, get_policy
from agents import Agent, Runner

router = Router(goal="agent_task", paths=["gpt-4o", "gpt-4o-mini"])
policy = get_policy(goal="agent_task")
agent = Agent(name="Assistant", instructions="...", model=policy["recommended_model"])
result = Runner.run_sync(agent, "Your task")
router.report(success=len(result.final_output) > 0)

terminal

pip install kalibr huggingface_hub

3. Set credentials

.env

KALIBR_API_KEY=sk_...
KALIBR_TENANT_ID=user_...
HF_API_TOKEN=hf_... # optional, avoids free-tier rate limits

4. Route between HuggingFace models

All 17 HuggingFace task types are supported. HuggingFace is not auto-patched on import kalibr. Use router.completion() directly or call kalibr.auto_instrument(["huggingface"]) explicitly.

agent.py

import kalibr
kalibr.auto_instrument(["huggingface"])
from kalibr import Router

router = Router(
    goal="transcribe_calls",
    paths=["openai/whisper-large-v3", "facebook/seamless-m4t-v2-large"],
    success_when=lambda out: len(out) > 50
)
result = router.execute(task="automatic_speech_recognition", input_data=audio_bytes)
router.report(success=True)

terminal

pip install kalibr openai # DeepSeek uses the OpenAI SDK

3. Set credentials

.env

KALIBR_API_KEY=sk_...
KALIBR_TENANT_ID=user_...
DEEPSEEK_API_KEY=sk-... # from platform.deepseek.com

4. Route between DeepSeek and other models

Use deepseek-chat and deepseek-reasoner as path names. Mix with other providers freely.

agent.py

import kalibr  # must be first import
from kalibr import Router

router = Router(
    goal="classify_icp",
    paths=["gpt-4o-mini", "deepseek-chat", "claude-sonnet-4-20250514"],
    success_when=lambda out: len(out) > 0
)
response = router.completion(messages=[{"role": "user", "content": "..."}])
print(response.choices[0].message.content)

terminal

pip install kalibr[voice] # ElevenLabs + Deepgram + OpenAI Audio

3. Set credentials

.env

KALIBR_API_KEY=sk_...
KALIBR_TENANT_ID=user_...
OPENAI_API_KEY=sk-...
ELEVENLABS_API_KEY=...
DEEPGRAM_API_KEY=...

4. Route TTS and STT

voice_agent.py

import kalibr  # patches ElevenLabs + Deepgram
from kalibr import Router

tts = Router(goal="narrate", paths=["eleven_multilingual_v2", "tts-1"])
audio = tts.synthesize("Hello from Kalibr.", voice="alloy").audio

stt = Router(goal="transcribe_calls", paths=["whisper-1", "nova-2"])
transcript = stt.transcribe(audio_bytes, audio_duration_seconds=30.0).text

Auto-healing

Pass healing=True on router.completion() to let Kalibr recover from failed calls automatically. The Router runs the structural gate, classifies any failure, repairs the meta prompt or swaps to the next path, and retries — all inside the same call.

agent.py

from kalibr import Router

router = Router(
    goal="summarize",
    paths=["gpt-4o", "claude-sonnet-4-20250514"],
    success_when=lambda out: len(out) > 50,
)

response = router.completion(
    messages=[{"role": "user", "content": "Summarize: ..."}],
    healing=True,
)

HealConfig

Pass HealConfig to tune retry budget and which gates run:

agent.py

from kalibr import Router, HealConfig

config = HealConfig(
    max_retries=2,           # heal attempts before giving up
    gate2_enabled=True,      # LLM-judge quality gate
    meta_prompt_enabled=True,# repair meta prompt before model swap
)

response = router.completion(
    messages=[{"role": "user", "content": "Summarize: ..."}],
    healing=True,
    heal_config=config,
)

Multi-step pipelines

router.pipeline() runs a sequence of routed, gated, healed steps as one call. Each step picks its own goal and messages. Set "chain": True on any step to receive the previous step's output as context.

agent.py

result = router.pipeline(
    [
        {"goal": "research", "messages": [...]},
        {"goal": "outreach_generation", "messages": [...], "chain": True},
    ],
    healing=True,
    pipeline_id="my-pipeline",
)

Each step routes and heals independently. If a step fails after exhausting retries, the pipeline returns a partial result with the failure attached.

Pipeline isolation

Pass pipeline_id to scope outcome learning to a single pipeline (or agent). Calls that share a goal but live in different pipeline_ids will not bleed routing signals into each other. Use the same id across calls that should share learning, a different id for anything you want kept separate.

agent.py

router.completion(
    messages=[...],
    healing=True,
    pipeline_id="sales-outreach-prod",
)

router.completion(
    messages=[...],
    healing=True,
    pipeline_id="sales-outreach-staging",  # separate bandit
)

5. Verify

Run this after your first call. It confirms the SDK is installed, credentials are valid, and traces are arriving.

terminal

kalibr verify

The first successful trace activates Kalibr's routing engine. After 20 to 50 outcomes per path, routing converges on the model that actually works best for each goal.

How routing works

Kalibr sits between your code and the LLM providers. Every call goes through the Router, which:

Picks the best model using Thompson Sampling over tracked outcomes
Checks the output against your success_when or score_when criteria
Retries on failure with a different model, automatically
Reports the outcome back to the routing engine so it learns

Calls go directly to the provider. Kalibr is not a proxy. It does not read or modify prompt content.

For the full explanation, see How Kalibr works.

How Kalibr works

API reference

Production guide

1. Create an API key

2. Install the SDK

3. Set credentials

4. Replace your LLM call

3. Set credentials

4. Replace your LLM call

3. Set credentials

4. Swap in the Kalibr LLM

3. Set credentials

4. Pass router.as_langchain() as your agent LLM

3. Set credentials

4. Use Kalibr to pick the model for your Agent

3. Set credentials

4. Route between HuggingFace models

3. Set credentials

4. Route between DeepSeek and other models

3. Set credentials

4. Route TTS and STT

Auto-healing

HealConfig

Multi-step pipelines

Pipeline isolation

5. Verify

How routing works

Next