Intelligence API PRO

Execution intelligence for multi-agent systems. Query Kalibr to get the best model, tool, and parameters for your goal based on historical outcomes.

Full Execution Routing NEW

Kalibr doesn't just recommend models — it recommends the full execution recipe: model, tool, and parameters, all optimized based on what's actually worked for each goal.

from kalibr import get_policy, report_outcome

# Get full execution policy
policy = get_policy(
    goal="fetch_webpage",
    include_tools=True,                    # Get tool recommendations
    include_params=["timeout", "retries"], # Get param recommendations
)

# Use the recommendations
model = policy["recommended_model"]           # "gpt-4o"
tool = policy.get("recommended_tool")         # "browserless"
params = policy.get("recommended_params", {}) # {"timeout": "30", "retries": "2"}

# Execute your task with recommended config...

# Report outcome with full context
report_outcome(
    trace_id=trace_id,
    goal="fetch_webpage",
    success=True,
    tool_id=tool,                    # What tool you used
    execution_params=params,         # What params you used
)

Python SDK

get_policy()

from kalibr import get_policy

policy = get_policy(
    goal="book_meeting",           # Required
    task_type="scheduling",        # Optional filter
    constraints={                  # Optional
        "max_cost_usd": 0.05,
        "max_latency_ms": 3000,
        "min_confidence": 0.7,
        "max_risk": 0.3,
    },
    window_hours=168,              # Default: 1 week
    include_tools=True,            # Include tool recommendations
    include_params=["temperature"], # Include param recommendations
)

# Response
{
    "goal": "book_meeting",
    "recommended_model": "gpt-4o",
    "recommended_provider": "openai",
    "outcome_success_rate": 0.87,
    "outcome_sample_count": 234,
    "confidence": 0.92,
    "risk_score": 0.15,
    "reasoning": "Best success rate with acceptable cost",
    "alternatives": [...],
    
    # Tool routing (when include_tools=True)
    "recommended_tool": "calendar_api",
    "tool_success_rate": 0.91,
    "tool_sample_count": 156,
    "tool_alternatives": [...],
    
    # Parameter routing (when include_params specified)
    "recommended_params": {"temperature": "0.3"},
    "param_details": {
        "temperature": {
            "recommended_value": "0.3",
            "success_rate": 0.89,
            "sample_count": 98,
            "alternatives": [...]
        }
    }
}

report_outcome()

from kalibr import report_outcome, get_trace_id

# Success with full context
report_outcome(
    trace_id=get_trace_id(),
    goal="book_meeting",
    success=True,
    tool_id="calendar_api",              # What tool was used
    execution_params={                   # What params were used
        "temperature": "0.3",
        "timeout": "30"
    },
)

# Failure with context
report_outcome(
    trace_id="abc123",
    goal="book_meeting",
    success=False,
    score=0.3,                           # Optional: quality 0-1
    failure_reason="calendar_conflict",
    tool_id="calendar_api",
    execution_params={"temperature": "0.7"},
    metadata={"attendees": 5},
)

get_alternative()

Get a fallback model after the primary recommendation failed. Useful for retry logic.

from kalibr import get_alternative

# Primary model failed, get next best option
alt = get_alternative(
    goal="book_meeting",
    exclude_models=["gpt-4o"],     # Models already tried
    task_type="scheduling",        # Optional
    constraints={...},             # Optional
)

# Response
{
    "goal": "book_meeting",
    "recommended_model": "claude-3-sonnet",
    "recommended_provider": "anthropic",
    "outcome_success_rate": 0.82,
    "confidence": 0.78,
    "reasoning": "Next best after excluding gpt-4o",
    "remaining_alternatives": 2
}

get_recommendation()

from kalibr import get_recommendation

rec = get_recommendation(
    task_type="summarization",
    goal="summarize_document",     # Optional
    optimize_for="balanced",       # cost, quality, latency, balanced, cost_efficiency
    constraints={...},
    window_hours=168,
)

KalibrIntelligence Class

from kalibr import KalibrIntelligence

client = KalibrIntelligence(
    api_key="sk_...",
    tenant_id="my-tenant",
    base_url="https://kalibr-intelligence.fly.dev",
    timeout=10.0,
)

policy = client.get_policy(
    goal="book_meeting",
    include_tools=True,
    include_params=["temperature"]
)
client.close()

REST API

Base URL: https://kalibr-intelligence.fly.dev/api/v1/intelligence

Authentication

X-API-Key: YOUR_API_KEY
X-Tenant-ID: YOUR_TENANT_ID
Content-Type: application/json

Endpoints

POST /policy

curl -X POST https://kalibr-intelligence.fly.dev/api/v1/intelligence/policy \
  -H "X-API-Key: $API_KEY" \
  -H "X-Tenant-ID: $TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "goal": "book_meeting",
    "include_tools": true,
    "include_params": ["temperature", "timeout"]
  }'

POST /report-outcome

curl -X POST https://kalibr-intelligence.fly.dev/api/v1/intelligence/report-outcome \
  -H "X-API-Key: $API_KEY" \
  -H "X-Tenant-ID: $TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "trace_id": "abc123",
    "goal": "book_meeting",
    "success": true,
    "tool_id": "calendar_api",
    "execution_params": {"temperature": "0.3"}
  }'

POST /get-alternative

Get the next best model after your primary choice failed.

curl -X POST https://kalibr-intelligence.fly.dev/api/v1/intelligence/get-alternative \
  -H "X-API-Key: $API_KEY" \
  -H "X-Tenant-ID: $TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "goal": "book_meeting",
    "exclude_models": ["gpt-4o"],
    "task_type": "scheduling"
  }'

POST /clear-realtime-stats

Clear real-time statistics. Useful for testing or resetting learning.

curl -X POST "https://kalibr-intelligence.fly.dev/api/v1/intelligence/clear-realtime-stats?goal=book_meeting" \
  -H "X-API-Key: $API_KEY" \
  -H "X-Tenant-ID: $TENANT_ID"

Request Parameters

get_policy / POST /policy

report_outcome / POST /report-outcome

get_alternative / POST /get-alternative

Optimization Targets

Constraints

{
  "max_cost_usd": 0.05,      // Max cost per request
  "max_latency_ms": 2000,    // Max latency
  "min_quality": 0.8,        // Min quality score (0-1)
  "min_confidence": 0.7,     // Min statistical confidence
  "max_risk": 0.3            // Max risk score (0-1)
}

How It Works

The Intelligence service uses:

• Wilson Score: Statistical confidence intervals for success rates
• Risk Assessment: Variance and tail behavior analysis
• Efficiency Scoring: Quality-per-dollar metrics
• Pareto Frontier: Identifies optimal tradeoff models
• Tool Patterns: Tracks success rates per tool for each goal
• Parameter Patterns: Tracks success rates per parameter value

Patterns are aggregated every 5 minutes from trace and outcome data.

Configuration

Availability

The Intelligence API is available on Pro and Enterprise plans. Free tier users receive a 403 response.

Next Steps

• Python SDK — Full SDK documentation
• API Reference — All REST endpoints