kalibr 1.2.6__tar.gz → 1.2.8__tar.gz

{kalibr-1.2.6 → kalibr-1.2.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: kalibr
-Version: 1.2.6
+Version: 1.2.8
 Summary: Adaptive routing for AI agents. Learns which models work best and routes automatically.
 Author-email: Kalibr Team <support@kalibr.systems>
 License: Apache-2.0
@@ -67,7 +67,7 @@ Requires-Dist: ruff>=0.1.0; extra == "dev"
 
 # Kalibr
 
-Adaptive routing for AI agents. Kalibr learns which models, tools, and configs work best for each task and routes automatically.
+Adaptive routing for AI agents. Kalibr learns which models work best for your tasks and routes automatically.
 
 [![PyPI](https://img.shields.io/pypi/v/kalibr)](https://pypi.org/project/kalibr/)
 [![Python](https://img.shields.io/pypi/pyversions/kalibr)](https://pypi.org/project/kalibr/)
@@ -83,24 +83,32 @@ pip install kalibr
 from kalibr import Router
 
 router = Router(
-    goal="book_meeting",
-    paths=["gpt-4o", "claude-sonnet-4-20250514", "gpt-4o-mini"],
-    success_when=lambda output: "confirmed" in output.lower()
+    goal="extract_company",
+    paths=["gpt-4o", "claude-sonnet-4-20250514"]
 )
 
 response = router.completion(
-    messages=[{"role": "user", "content": "Book a meeting with John tomorrow"}]
+    messages=[{"role": "user", "content": "Extract the company: Hi, I'm Sarah from Stripe."}]
 )
+
+router.report(success=True)
 ```
 
-Kalibr picks the best model, makes the call, checks success, and learns for next time.
+Kalibr picks the best model, makes the call, and learns from the outcome.
+
+## How It Works
+
+1. **You define paths** - models (and optionally tools/params) that can handle your task
+2. **Kalibr picks** - uses Thompson Sampling to balance exploration vs exploitation
+3. **You report outcomes** - tell Kalibr if it worked
+4. **Kalibr learns** - routes more traffic to what works
 
 ## Paths
 
 A path is a model + optional tools + optional params:
 ```python
 # Just models
-paths = ["gpt-4o", "claude-sonnet-4-20250514"]
+paths = ["gpt-4o", "claude-sonnet-4-20250514", "gpt-4o-mini"]
 
 # With tools
 paths = [
@@ -115,7 +123,78 @@ paths = [
 ]
 ```
 
-## Manual Outcome Reporting
+## Advanced Path Configuration
+
+### Routing Between Parameters
+
+Kalibr can route between different parameter configurations of the same model:
+```python
+from kalibr import Router
+
+router = Router(
+    goal="creative_writing",
+    paths=[
+        {"model": "gpt-4o", "params": {"temperature": 0.3}},
+        {"model": "gpt-4o", "params": {"temperature": 0.9}},
+        {"model": "claude-sonnet-4-20250514", "params": {"temperature": 0.7}}
+    ]
+)
+
+response = router.completion(messages=[...])
+router.report(success=True)
+```
+
+Each unique `(model, params)` combination is tracked separately. Kalibr learns which configuration works best for your specific goal.
+
+### Routing Between Tools
+```python
+router = Router(
+    goal="research_task",
+    paths=[
+        {"model": "gpt-4o", "tools": ["web_search"]},
+        {"model": "gpt-4o", "tools": ["code_interpreter"]},
+        {"model": "claude-sonnet-4-20250514"}
+    ]
+)
+```
+
+### When to Use get_policy() Instead of Router
+
+For most use cases, use `Router`. It handles provider dispatching and response conversion automatically.
+
+Use `get_policy()` for advanced scenarios:
+- Integrating with frameworks like LangChain that wrap LLM calls
+- Custom retry logic or provider-specific features
+- Building tools that need fine-grained control
+```python
+from kalibr import get_policy, report_outcome
+
+policy = get_policy(goal="summarize")
+model = policy["recommended_model"]
+
+# You call the provider yourself
+if model.startswith("gpt"):
+    client = OpenAI()
+    response = client.chat.completions.create(model=model, messages=[...])
+
+report_outcome(trace_id=trace_id, goal="summarize", success=True)
+```
+
+## Outcome Reporting
+
+### Automatic (with success_when)
+```python
+router = Router(
+    goal="summarize",
+    paths=["gpt-4o", "claude-sonnet-4-20250514"],
+    success_when=lambda output: len(output) > 100
+)
+
+response = router.completion(messages=[...])
+# Outcome reported automatically based on success_when
+```
+
+### Manual
 ```python
 router = Router(goal="book_meeting", paths=["gpt-4o", "claude-sonnet-4-20250514"])
 response = router.completion(messages=[...])
@@ -139,7 +218,7 @@ chain = prompt | llm | parser
 
 ## Auto-Instrumentation
 
-Kalibr auto-instruments OpenAI, Anthropic, and Google SDKs when imported:
+Kalibr auto-instruments OpenAI, Anthropic, and Google SDKs on import:
 ```python
 import kalibr  # Must be first import
 from openai import OpenAI
@@ -151,19 +230,39 @@ response = client.chat.completions.create(model="gpt-4o", messages=[...])
 
 Disable with `KALIBR_AUTO_INSTRUMENT=false`.
 
+## Low-Level API
+
+For advanced use cases, you can use the intelligence API directly:
+```python
+from kalibr import register_path, decide, report_outcome
+
+# Register paths
+register_path(goal="book_meeting", model_id="gpt-4o")
+register_path(goal="book_meeting", model_id="claude-sonnet-4-20250514")
+
+# Get routing decision
+decision = decide(goal="book_meeting")
+model = decision["model_id"]
+
+# Make your own LLM call, then report
+report_outcome(trace_id="...", goal="book_meeting", success=True)
+```
+
 ## Other Integrations
 ```bash
 pip install kalibr[crewai]        # CrewAI
 pip install kalibr[openai-agents] # OpenAI Agents SDK
+pip install kalibr[langchain-all] # LangChain with all providers
 ```
 
 ## Configuration
 
 | Variable | Description | Default |
 |----------|-------------|---------|
-| `KALIBR_API_KEY` | API key | Required |
-| `KALIBR_TENANT_ID` | Tenant ID | `default` |
-| `KALIBR_AUTO_INSTRUMENT` | Auto-instrument SDKs | `true` |
+| `KALIBR_API_KEY` | API key from dashboard | Required |
+| `KALIBR_TENANT_ID` | Tenant ID from dashboard | Required |
+| `KALIBR_AUTO_INSTRUMENT` | Auto-instrument LLM SDKs | `true` |
+| `KALIBR_INTELLIGENCE_URL` | Intelligence service URL | `https://kalibr-intelligence.fly.dev` |
 
 ## Development
 ```bash
@@ -183,5 +282,6 @@ Apache-2.0
 
 ## Links
 
-- [Docs](https://kalibr.systems/docs)
+- [Docs](https://kalibr.dev/docs)
 - [Dashboard](https://dashboard.kalibr.systems)
+- [GitHub](https://github.com/kalibr-ai/kalibr-sdk-python)

kalibr-1.2.8/README.md

@@ -0,0 +1,220 @@
+# Kalibr
+
+Adaptive routing for AI agents. Kalibr learns which models work best for your tasks and routes automatically.
+
+[![PyPI](https://img.shields.io/pypi/v/kalibr)](https://pypi.org/project/kalibr/)
+[![Python](https://img.shields.io/pypi/pyversions/kalibr)](https://pypi.org/project/kalibr/)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
+
+## Installation
+```bash
+pip install kalibr
+```
+
+## Quick Start
+```python
+from kalibr import Router
+
+router = Router(
+    goal="extract_company",
+    paths=["gpt-4o", "claude-sonnet-4-20250514"]
+)
+
+response = router.completion(
+    messages=[{"role": "user", "content": "Extract the company: Hi, I'm Sarah from Stripe."}]
+)
+
+router.report(success=True)
+```
+
+Kalibr picks the best model, makes the call, and learns from the outcome.
+
+## How It Works
+
+1. **You define paths** - models (and optionally tools/params) that can handle your task
+2. **Kalibr picks** - uses Thompson Sampling to balance exploration vs exploitation
+3. **You report outcomes** - tell Kalibr if it worked
+4. **Kalibr learns** - routes more traffic to what works
+
+## Paths
+
+A path is a model + optional tools + optional params:
+```python
+# Just models
+paths = ["gpt-4o", "claude-sonnet-4-20250514", "gpt-4o-mini"]
+
+# With tools
+paths = [
+    {"model": "gpt-4o", "tools": ["web_search"]},
+    {"model": "claude-sonnet-4-20250514", "tools": ["web_search", "browser"]},
+]
+
+# With params
+paths = [
+    {"model": "gpt-4o", "params": {"temperature": 0.7}},
+    {"model": "gpt-4o", "params": {"temperature": 0.2}},
+]
+```
+
+## Advanced Path Configuration
+
+### Routing Between Parameters
+
+Kalibr can route between different parameter configurations of the same model:
+```python
+from kalibr import Router
+
+router = Router(
+    goal="creative_writing",
+    paths=[
+        {"model": "gpt-4o", "params": {"temperature": 0.3}},
+        {"model": "gpt-4o", "params": {"temperature": 0.9}},
+        {"model": "claude-sonnet-4-20250514", "params": {"temperature": 0.7}}
+    ]
+)
+
+response = router.completion(messages=[...])
+router.report(success=True)
+```
+
+Each unique `(model, params)` combination is tracked separately. Kalibr learns which configuration works best for your specific goal.
+
+### Routing Between Tools
+```python
+router = Router(
+    goal="research_task",
+    paths=[
+        {"model": "gpt-4o", "tools": ["web_search"]},
+        {"model": "gpt-4o", "tools": ["code_interpreter"]},
+        {"model": "claude-sonnet-4-20250514"}
+    ]
+)
+```
+
+### When to Use get_policy() Instead of Router
+
+For most use cases, use `Router`. It handles provider dispatching and response conversion automatically.
+
+Use `get_policy()` for advanced scenarios:
+- Integrating with frameworks like LangChain that wrap LLM calls
+- Custom retry logic or provider-specific features
+- Building tools that need fine-grained control
+```python
+from kalibr import get_policy, report_outcome
+
+policy = get_policy(goal="summarize")
+model = policy["recommended_model"]
+
+# You call the provider yourself
+if model.startswith("gpt"):
+    client = OpenAI()
+    response = client.chat.completions.create(model=model, messages=[...])
+
+report_outcome(trace_id=trace_id, goal="summarize", success=True)
+```
+
+## Outcome Reporting
+
+### Automatic (with success_when)
+```python
+router = Router(
+    goal="summarize",
+    paths=["gpt-4o", "claude-sonnet-4-20250514"],
+    success_when=lambda output: len(output) > 100
+)
+
+response = router.completion(messages=[...])
+# Outcome reported automatically based on success_when
+```
+
+### Manual
+```python
+router = Router(goal="book_meeting", paths=["gpt-4o", "claude-sonnet-4-20250514"])
+response = router.completion(messages=[...])
+
+meeting_created = check_calendar_api()
+router.report(success=meeting_created)
+```
+
+## LangChain Integration
+```bash
+pip install kalibr[langchain]
+```
+```python
+from kalibr import Router
+
+router = Router(goal="summarize", paths=["gpt-4o", "claude-sonnet-4-20250514"])
+llm = router.as_langchain()
+
+chain = prompt | llm | parser
+```
+
+## Auto-Instrumentation
+
+Kalibr auto-instruments OpenAI, Anthropic, and Google SDKs on import:
+```python
+import kalibr  # Must be first import
+from openai import OpenAI
+
+client = OpenAI()
+response = client.chat.completions.create(model="gpt-4o", messages=[...])
+# Traced automatically
+```
+
+Disable with `KALIBR_AUTO_INSTRUMENT=false`.
+
+## Low-Level API
+
+For advanced use cases, you can use the intelligence API directly:
+```python
+from kalibr import register_path, decide, report_outcome
+
+# Register paths
+register_path(goal="book_meeting", model_id="gpt-4o")
+register_path(goal="book_meeting", model_id="claude-sonnet-4-20250514")
+
+# Get routing decision
+decision = decide(goal="book_meeting")
+model = decision["model_id"]
+
+# Make your own LLM call, then report
+report_outcome(trace_id="...", goal="book_meeting", success=True)
+```
+
+## Other Integrations
+```bash
+pip install kalibr[crewai]        # CrewAI
+pip install kalibr[openai-agents] # OpenAI Agents SDK
+pip install kalibr[langchain-all] # LangChain with all providers
+```
+
+## Configuration
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `KALIBR_API_KEY` | API key from dashboard | Required |
+| `KALIBR_TENANT_ID` | Tenant ID from dashboard | Required |
+| `KALIBR_AUTO_INSTRUMENT` | Auto-instrument LLM SDKs | `true` |
+| `KALIBR_INTELLIGENCE_URL` | Intelligence service URL | `https://kalibr-intelligence.fly.dev` |
+
+## Development
+```bash
+git clone https://github.com/kalibr-ai/kalibr-sdk-python.git
+cd kalibr-sdk-python
+pip install -e ".[dev]"
+pytest
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+Apache-2.0
+
+## Links
+
+- [Docs](https://kalibr.dev/docs)
+- [Dashboard](https://dashboard.kalibr.systems)
+- [GitHub](https://github.com/kalibr-ai/kalibr-sdk-python)

{kalibr-1.2.6 → kalibr-1.2.8}/kalibr/__init__.py

@@ -1,4 +1,4 @@
-"""Kalibr SDK v1.2.0 - LLM Observability & Tracing Framework
+"""Kalibr SDK v1.2.7 - LLM Observability & Tracing Framework
 
 Features:
 - **Auto-Instrumentation**: Zero-config tracing of OpenAI, Anthropic, Google SDK calls
@@ -36,7 +36,7 @@ CLI Usage:
     kalibr version                       # Show version
 """
 
-__version__ = "1.2.0"
+__version__ = "1.2.7"
 
 # Auto-instrument LLM SDKs on import (can be disabled via env var)
 import os

{kalibr-1.2.6 → kalibr-1.2.8}/kalibr/cli/capsule_cmd.py

@@ -23,7 +23,7 @@ def capsule(
         None,
         "--api-url",
         "-u",
-        help="Kalibr API base URL (default: from env KALIBR_API_URL or https://api.kalibr.systems)",
+        help="Kalibr API base URL (default: from env KALIBR_API_URL or https://kalibr-backend.fly.dev)",
         envvar="KALIBR_API_URL",
     ),
     output: Optional[Path] = typer.Option(
@@ -63,10 +63,10 @@ def capsule(
         kalibr capsule abc-123-def --export --output capsule.json
 
         # Specify custom API URL
-        kalibr capsule abc-123-def -u https://api.kalibr.systems
+        kalibr capsule abc-123-def -u https://kalibr-backend.fly.dev
     """
     # Determine API base URL
-    base_url = api_url or "https://api.kalibr.systems"
+    base_url = api_url or "https://kalibr-backend.fly.dev"
     base_url = base_url.rstrip("/")
 
     # Build endpoint URL

{kalibr-1.2.6 → kalibr-1.2.8}/kalibr/cli/run.py

@@ -47,7 +47,7 @@ def run(
         kalibr run weather.py --runtime fly.io
 
         # Custom backend
-        kalibr run weather.py --backend-url https://api.kalibr.systems
+        kalibr run weather.py --backend-url https://kalibr-backend.fly.dev
     """
     # Validate file exists
     agent_path = Path(file_path).resolve()
@@ -56,7 +56,7 @@ def run(
         raise typer.Exit(1)
 
     # Configure backend
-    backend = backend_url or os.getenv("KALIBR_BACKEND_URL", "https://api.kalibr.systems")
+    backend = backend_url or os.getenv("KALIBR_BACKEND_URL", "https://kalibr-backend.fly.dev")
     api_key = os.getenv("KALIBR_API_KEY")
     if not api_key:
         console.print("[yellow]⚠️  KALIBR_API_KEY not set. Set it for trace authentication.[/yellow]")

{kalibr-1.2.6 → kalibr-1.2.8}/kalibr/client.py

@@ -70,7 +70,7 @@ class KalibrClient:
 
         self.api_key = api_key or env_config.get("auth_token", "")
         self.endpoint = endpoint or env_config.get(
-            "api_endpoint", "https://api.kalibr.systems/api/v1/traces"
+            "api_endpoint", "https://kalibr-backend.fly.dev/api/v1/traces"
         )
         self.tenant_id = tenant_id or env_config.get("tenant_id", "default")
         self.environment = environment or env_config.get("environment", "prod")