# Kalibr Setup Reference
# Machine-readable installation, configuration, and API reference
# Version: 3.0 | Updated: 2026-02

## PACKAGE

name: kalibr
pypi: https://pypi.org/project/kalibr/
install: pip install kalibr
language: python
min_python: 3.10
license: MIT
version: 1.5.0

## AUTHENTICATION

### Option A: Manual
KALIBR_API_KEY=sk_...        # from dashboard.kalibr.systems/settings
KALIBR_TENANT_ID=tenant_...  # from dashboard.kalibr.systems/settings

### Option B: Autonomous provisioning
KALIBR_PROVISIONING_TOKEN=prov_live_...  # human creates at dashboard
Then run: kalibr init
Provisions sk_ key + tenant_id, writes to .env, scans and instruments codebase.

Provisioning API:
POST https://kalibr-backend.fly.dev/api/provisioning/provision
Body: {"provisioning_token": "prov_live_...", "name": "agent-name", "source": "claude-code"}
Response: {"api_key": "sk_...", "tenant_id": "...", "next_steps": [...]}

## CLI COMMANDS

kalibr init [directory]
  Scans for bare LLM calls, proposes Router rewrites, auto-provisions credentials.

kalibr verify
  Checks credentials and connectivity.

## SDK — Router CLASS

```python
from kalibr import Router

router = Router(
    goal: str,                                    # required — task name
    paths: list[str | dict] = None,               # models to route between
    success_when: Callable[[str], bool] = None,   # auto-evaluate success from output
    exploration_rate: float = None,               # default 0.1 (10%)
    auto_register: bool = True,                   # auto-register paths with service
)

response = router.completion(
    messages: list[dict],       # OpenAI-format messages
    force_model: str = None,    # override routing
    **kwargs                    # passed to provider
)
# Returns OpenAI-compatible ChatCompletion with kalibr_trace_id attribute

router.report(
    success: bool,              # required
    reason: str = None,         # failure reason
    score: float = None,        # quality score 0-1
    trace_id: str = None,       # uses last completion's trace_id if not provided
    failure_category: str = None,  # structured category (see FAILURE_CATEGORIES)
)

router.add_path(model: str, tools: list = None, params: dict = None)
```

Path formats:
- Simple: ["gpt-4o", "claude-sonnet-4-20250514"]
- With tools: [{"model": "gpt-4o", "tools": ["search"]}]
- With params: [{"model": "gpt-4o", "params": {"temperature": 0.7}}]

## SDK — INTELLIGENCE FUNCTIONS

All importable from kalibr:

```python
from kalibr import (
    decide, get_policy, report_outcome, update_outcome,
    get_insights, register_path, FAILURE_CATEGORIES,
)
```

### decide(goal, task_risk_level="low") → dict
Routing decision: model_id, tool_id, params, trace_id, reason, confidence.
Used internally by Router.completion().

### get_policy(goal, task_type=None, constraints=None, window_hours=168) → dict
Best-performing path historically for a goal.

### report_outcome(trace_id, goal, success, ...) → dict
Reports execution outcome. Teaches Kalibr what works.
Optional: score, failure_reason, failure_category, metadata, tool_id, execution_params, model_id.

### update_outcome(trace_id, goal, ...) → dict
Updates existing outcome with late-arriving signal (DELETE + INSERT for correct stats).
Optional: success, score, failure_reason, failure_category, metadata.
404 if original outcome not found.

### get_insights(goal=None, window_hours=168) → dict
Structured diagnostics per goal. schema_version "1.0".
Returns: goals list with status, success_rate, trend, top_failure_modes, paths,
param_sensitivity, actionable_signals.
Signal types: path_underperforming, failure_mode_dominant, param_sensitivity_detected,
drift_detected, cost_inefficiency, low_confidence, goal_healthy.

### register_path(goal, model_id, tool_id=None, params=None, risk_level="low") → dict
Registers new routing path. Returns path_id.

### FAILURE_CATEGORIES
["timeout", "context_exceeded", "tool_error", "rate_limited",
 "validation_failed", "hallucination_detected", "user_unsatisfied",
 "empty_response", "malformed_output", "auth_error", "provider_error", "unknown"]
Client-side validation: ValueError if invalid category passed.

## FRAMEWORK INTEGRATIONS

### LangChain
from kalibr import Router
router = Router(goal="summarize", paths=["gpt-4o", "claude-sonnet-4-20250514"])
llm = router.as_langchain()

### CrewAI
from kalibr_crewai import KalibrCrewAIInstrumentor
KalibrCrewAIInstrumentor(tenant_id="your-tenant-id").instrument()

### OpenAI Agents SDK
from kalibr_openai_agents import setup_kalibr_tracing
setup_kalibr_tracing(tenant_id="your-tenant-id")

### Auto-instrumentation
import kalibr  # first import patches OpenAI, Anthropic, Google

## INSTALL EXTRAS

pip install kalibr                    # Core
pip install kalibr[langchain]         # LangChain
pip install kalibr[crewai]            # CrewAI
pip install kalibr[openai-agents]     # OpenAI Agents SDK
pip install kalibr[tokens]            # Token counting

## REST API ENDPOINTS

Base: https://kalibr-intelligence.fly.dev
Auth header: x-api-key: sk_...

### Intelligence
POST /api/v1/intelligence/report-outcome    — report execution outcome
POST /api/v1/intelligence/update-outcome    — update outcome (late-arriving signal)
GET  /api/v1/intelligence/insights          — structured diagnostics per goal
POST /api/v1/intelligence/policy            — execution policy for a goal
POST /api/v1/intelligence/recommend         — get recommendation for task type
POST /api/v1/intelligence/compare           — compare models for a goal
POST /api/v1/intelligence/get-alternative   — get alternative model
GET  /api/v1/intelligence/goals             — list active goals
GET  /api/v1/intelligence/health            — health check

### Routing
POST /api/v1/routing/decide                 — routing decision
POST /api/v1/routing/paths                  — register path
GET  /api/v1/routing/paths                  — list paths
DELETE /api/v1/routing/paths/{path_id}      — disable path
POST /api/v1/routing/config                 — set exploration config
GET  /api/v1/routing/config                 — get exploration config
GET  /api/v1/routing/stats                  — goal statistics
GET  /api/v1/routing/outcomes               — outcomes history
GET  /api/v1/routing/data-quality           — data quality check

### Provisioning (app backend)
POST https://kalibr-backend.fly.dev/api/provisioning/provision  — auto-provision credentials

## LINKS

docs: https://kalibr.systems/docs
dashboard: https://dashboard.kalibr.systems
pypi: https://pypi.org/project/kalibr/
github: https://github.com/kalibr-ai/kalibr-sdk-python
quickstart: https://kalibr.systems/docs/quickstart