kalibr 1.1.3a0__py3-none-any.whl → 1.3.0__py3-none-any.whl

kalibr/__init__.py

@@ -1,4 +1,4 @@
-"""Kalibr SDK v1.1.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.1.0-alpha"
+__version__ = "1.2.7"
 
 # Auto-instrument LLM SDKs on import (can be disabled via env var)
 import os
@@ -56,7 +56,17 @@ from .collector import is_configured as is_collector_configured
 from .collector import (
     setup_collector,
 )
-from .context import get_parent_span_id, get_trace_id, new_trace_id, trace_context
+from .context import (
+    get_parent_span_id,
+    get_trace_id,
+    new_trace_id,
+    trace_context,
+    # Goal context (v1.3.0)
+    goal,
+    set_goal,
+    get_goal,
+    clear_goal,
+)
 from .cost_adapter import (
     AnthropicCostAdapter,
     BaseCostAdapter,
@@ -71,6 +81,19 @@ from .trace_capsule import TraceCapsule, get_or_create_capsule
 from .tracer import SpanContext, Tracer
 from .utils import load_config_from_env
 
+# ============================================================================
+# INTELLIGENCE & OUTCOME ROUTING (v1.2.0)
+# ============================================================================
+from .intelligence import (
+    KalibrIntelligence,
+    get_policy,
+    report_outcome,
+    get_recommendation,
+    register_path,
+    decide,
+)
+from .router import Router
+
 if os.getenv("KALIBR_AUTO_INSTRUMENT", "true").lower() == "true":
     # Setup OpenTelemetry collector
     try:
@@ -104,6 +127,11 @@ __all__ = [
     "get_trace_id",
     "get_parent_span_id",
     "new_trace_id",
+    # Goal Context (v1.3.0)
+    "goal",
+    "set_goal",
+    "get_goal",
+    "clear_goal",
     # Tracer
     "Tracer",
     "SpanContext",
@@ -127,4 +155,14 @@ __all__ = [
     "setup_collector",
     "get_tracer_provider",
     "is_collector_configured",
+    # ========================================================================
+    # INTELLIGENCE & OUTCOME ROUTING (v1.2.0)
+    # ========================================================================
+    "KalibrIntelligence",
+    "get_policy",
+    "report_outcome",
+    "get_recommendation",
+    "register_path",
+    "decide",
+    "Router",
 ]

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.io
+        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/cli/main.py

@@ -30,9 +30,9 @@ def version():
     from kalibr import __version__
 
     console.print(f"[bold]Kalibr SDK version:[/bold] {__version__}")
-    console.print("Enhanced multi-model AI integration framework")
-    console.print("Supports: GPT Actions, Claude MCP, Gemini Extensions, Copilot Plugins")
-    console.print("GitHub: https://github.com/devonakelley/kalibr-sdk")
+    console.print("LLM Observability & Execution Intelligence")
+    console.print("Auto-instrumentation for OpenAI, Anthropic, Google AI")
+    console.print("GitHub: https://github.com/kalibr-ai/kalibr-sdk-python")
 
 
 @app.command()

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.io
+        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/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")

kalibr/collector.py

@@ -3,14 +3,21 @@ OpenTelemetry Collector Setup
 
 Configures OpenTelemetry tracer provider with multiple exporters:
 1. OTLP exporter for sending to OpenTelemetry collectors
-2. File exporter for local JSONL fallback
+2. Kalibr HTTP exporter for sending to Kalibr backend
+3. File exporter for local JSONL fallback
+
+Thread-safe singleton pattern for collector setup.
 """
 
 import json
 import os
+import threading
+from datetime import datetime, timezone
 from pathlib import Path
 from typing import Optional
 
+import requests
+
 from opentelemetry import trace
 from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
 from opentelemetry.sdk.resources import SERVICE_NAME, Resource
@@ -21,6 +28,7 @@ from opentelemetry.sdk.trace.export import (
     SpanExporter,
     SpanExportResult,
 )
+from opentelemetry.trace import StatusCode
 
 try:
     from opentelemetry.sdk.trace import ReadableSpan
@@ -81,8 +89,156 @@ class FileSpanExporter(SpanExporter):
         }
 
 
+class KalibrHTTPSpanExporter(SpanExporter):
+    """Export spans to Kalibr backend via HTTP POST"""
+
+    DEFAULT_URL = "https://kalibr-backend.fly.dev/api/ingest"
+
+    def __init__(
+        self,
+        url: Optional[str] = None,
+        api_key: Optional[str] = None,
+        tenant_id: Optional[str] = None,
+    ):
+        """Initialize the Kalibr HTTP exporter.
+
+        Args:
+            url: Kalibr collector URL (default: from KALIBR_COLLECTOR_URL env var)
+            api_key: API key (default: from KALIBR_API_KEY env var)
+            tenant_id: Tenant ID (default: from KALIBR_TENANT_ID env var)
+        """
+        self.url = url or os.getenv("KALIBR_COLLECTOR_URL", self.DEFAULT_URL)
+        self.api_key = api_key or os.getenv("KALIBR_API_KEY")
+        self.tenant_id = tenant_id or os.getenv("KALIBR_TENANT_ID", "default")
+        self.environment = os.getenv("KALIBR_ENVIRONMENT", "production")
+
+    def export(self, spans) -> SpanExportResult:
+        """Export spans to Kalibr backend"""
+        if not self.api_key:
+            print("[Kalibr SDK] ⚠️  KALIBR_API_KEY not set, spans will not be sent to backend")
+            return SpanExportResult.SUCCESS
+
+        try:
+            events = [self._convert_span(span) for span in spans]
+
+            headers = {
+                "X-API-Key": self.api_key,
+                "X-Tenant-ID": self.tenant_id,
+                "Content-Type": "application/json",
+            }
+
+            payload = {"events": events}
+
+            response = requests.post(
+                self.url,
+                headers=headers,
+                json=payload,
+                timeout=30,
+            )
+
+            if not response.ok:
+                print(
+                    f"[Kalibr SDK] ❌ Backend rejected spans: {response.status_code} - {response.text}"
+                )
+                return SpanExportResult.FAILURE
+
+            return SpanExportResult.SUCCESS
+
+        except Exception as e:
+            print(f"[Kalibr SDK] ❌ Failed to export spans to backend: {e}")
+            return SpanExportResult.FAILURE
+
+    def shutdown(self):
+        """Shutdown the exporter"""
+        pass
+
+    def _nanos_to_iso(self, nanos: int) -> str:
+        """Convert nanoseconds since epoch to ISO format timestamp"""
+        if nanos is None:
+            return datetime.now(timezone.utc).isoformat()
+        seconds = nanos / 1_000_000_000
+        dt = datetime.fromtimestamp(seconds, tz=timezone.utc)
+        return dt.isoformat()
+
+    def _get_attr(self, span, *keys, default=None):
+        """Get attribute value from span, trying multiple keys"""
+        attrs = dict(span.attributes) if span.attributes else {}
+        for key in keys:
+            if key in attrs:
+                return attrs[key]
+        return default
+
+    def _convert_span(self, span) -> dict:
+        """Convert OTel span to Kalibr event format"""
+
+        # Calculate duration from span times (nanoseconds to milliseconds)
+        duration_ms = 0
+        if span.start_time and span.end_time:
+            duration_ms = int((span.end_time - span.start_time) / 1_000_000)
+
+        # Determine status
+        is_error = (
+            hasattr(span.status, "status_code") and span.status.status_code == StatusCode.ERROR
+        )
+        status = "error" if is_error else "success"
+
+        # Extract provider and model
+        provider = self._get_attr(span, "llm.vendor", "llm.system", "gen_ai.system", default="")
+        model_id = self._get_attr(
+            span, "llm.request.model", "llm.response.model", "gen_ai.request.model", default=""
+        )
+
+        # Extract token counts
+        input_tokens = self._get_attr(
+            span, "llm.usage.prompt_tokens", "gen_ai.usage.prompt_tokens", default=0
+        )
+        output_tokens = self._get_attr(
+            span, "llm.usage.completion_tokens", "gen_ai.usage.completion_tokens", default=0
+        )
+        total_tokens = self._get_attr(
+            span, "llm.usage.total_tokens", "gen_ai.usage.total_tokens", default=0
+        )
+
+        # If total_tokens not provided, calculate it
+        if not total_tokens and (input_tokens or output_tokens):
+            total_tokens = (input_tokens or 0) + (output_tokens or 0)
+
+        # Build event payload
+        event = {
+            "schema_version": "1.0",
+            "trace_id": format(span.context.trace_id, "032x"),
+            "span_id": format(span.context.span_id, "016x"),
+            "parent_id": format(span.parent.span_id, "016x") if span.parent else None,
+            "tenant_id": self.tenant_id,
+            "provider": provider,
+            "model_id": model_id,
+            "model_name": model_id,
+            "operation": span.name,
+            "endpoint": span.name,
+            "input_tokens": input_tokens or 0,
+            "output_tokens": output_tokens or 0,
+            "total_tokens": total_tokens or 0,
+            "cost_usd": self._get_attr(span, "llm.cost_usd", "gen_ai.usage.cost", default=0.0),
+            "latency_ms": self._get_attr(span, "llm.latency_ms", default=duration_ms),
+            "duration_ms": duration_ms,
+            "status": status,
+            "error_type": self._get_attr(span, "error.type", default=None) if is_error else None,
+            "error_message": (
+                self._get_attr(span, "error.message", default=None) if is_error else None
+            ),
+            "timestamp": self._nanos_to_iso(span.end_time),
+            "ts_start": self._nanos_to_iso(span.start_time),
+            "ts_end": self._nanos_to_iso(span.end_time),
+            "goal": self._get_attr(span, "kalibr.goal", default=""),
+            "environment": self.environment,
+        }
+
+        return event
+
+
 _tracer_provider: Optional[TracerProvider] = None
 _is_configured = False
+_collector_lock = threading.Lock()
 
 
 def setup_collector(
@@ -94,6 +250,8 @@ def setup_collector(
     """
     Setup OpenTelemetry collector with multiple exporters
 
+    Thread-safe: Uses double-checked locking to ensure single initialization.
+
     Args:
         service_name: Service name for the tracer provider
         otlp_endpoint: OTLP collector endpoint (e.g., "http://localhost:4317")
@@ -106,50 +264,67 @@ def setup_collector(
     """
     global _tracer_provider, _is_configured
 
+    # First check without lock (fast path)
     if _is_configured and _tracer_provider:
         return _tracer_provider
 
-    # Create resource with service name
-    resource = Resource(attributes={SERVICE_NAME: service_name})
-
-    # Create tracer provider
-    provider = TracerProvider(resource=resource)
-
-    # Add OTLP exporter if endpoint is configured
-    otlp_endpoint = otlp_endpoint or os.getenv("OTEL_EXPORTER_OTLP_ENDPOINT")
-    if otlp_endpoint:
-        try:
-            otlp_exporter = OTLPSpanExporter(endpoint=otlp_endpoint)
-            provider.add_span_processor(BatchSpanProcessor(otlp_exporter))
-            print(f"✅ OTLP exporter configured: {otlp_endpoint}")
-        except Exception as e:
-            print(f"⚠️  Failed to configure OTLP exporter: {e}")
-
-    # Add file exporter for local fallback
-    if file_export:
-        try:
-            file_exporter = FileSpanExporter("/tmp/kalibr_otel_spans.jsonl")
-            provider.add_span_processor(BatchSpanProcessor(file_exporter))
-            print("✅ File exporter configured: /tmp/kalibr_otel_spans.jsonl")
-        except Exception as e:
-            print(f"⚠️  Failed to configure file exporter: {e}")
-
-    # Add console exporter for debugging
-    if console_export:
-        try:
-            console_exporter = ConsoleSpanExporter()
-            provider.add_span_processor(BatchSpanProcessor(console_exporter))
-            print("✅ Console exporter configured")
-        except Exception as e:
-            print(f"⚠️  Failed to configure console exporter: {e}")
-
-    # Set as global tracer provider
-    trace.set_tracer_provider(provider)
-
-    _tracer_provider = provider
-    _is_configured = True
-
-    return provider
+    # Acquire lock for initialization
+    with _collector_lock:
+        # Double-check inside lock
+        if _is_configured and _tracer_provider:
+            return _tracer_provider
+
+        # Create resource with service name
+        resource = Resource(attributes={SERVICE_NAME: service_name})
+
+        # Create tracer provider
+        provider = TracerProvider(resource=resource)
+
+        # Add OTLP exporter if endpoint is configured
+        otlp_endpoint = otlp_endpoint or os.getenv("OTEL_EXPORTER_OTLP_ENDPOINT")
+        if otlp_endpoint:
+            try:
+                otlp_exporter = OTLPSpanExporter(endpoint=otlp_endpoint)
+                provider.add_span_processor(BatchSpanProcessor(otlp_exporter))
+                print(f"✅ OTLP exporter configured: {otlp_endpoint}")
+            except Exception as e:
+                print(f"⚠️  Failed to configure OTLP exporter: {e}")
+
+        # Add Kalibr HTTP exporter if API key is configured
+        kalibr_api_key = os.getenv("KALIBR_API_KEY")
+        if kalibr_api_key:
+            try:
+                kalibr_exporter = KalibrHTTPSpanExporter()
+                provider.add_span_processor(BatchSpanProcessor(kalibr_exporter))
+                print(f"✅ Kalibr backend exporter configured: {kalibr_exporter.url}")
+            except Exception as e:
+                print(f"⚠️  Failed to configure Kalibr backend exporter: {e}")
+
+        # Add file exporter for local fallback
+        if file_export:
+            try:
+                file_exporter = FileSpanExporter("/tmp/kalibr_otel_spans.jsonl")
+                provider.add_span_processor(BatchSpanProcessor(file_exporter))
+                print("✅ File exporter configured: /tmp/kalibr_otel_spans.jsonl")
+            except Exception as e:
+                print(f"⚠️  Failed to configure file exporter: {e}")
+
+        # Add console exporter for debugging
+        if console_export:
+            try:
+                console_exporter = ConsoleSpanExporter()
+                provider.add_span_processor(BatchSpanProcessor(console_exporter))
+                print("✅ Console exporter configured")
+            except Exception as e:
+                print(f"⚠️  Failed to configure console exporter: {e}")
+
+        # Set as global tracer provider
+        trace.set_tracer_provider(provider)
+
+        _tracer_provider = provider
+        _is_configured = True
+
+        return provider
 
 
 def get_tracer_provider() -> Optional[TracerProvider]:
@@ -163,11 +338,15 @@ def is_configured() -> bool:
 
 
 def shutdown_collector():
-    """Shutdown the tracer provider and flush all spans"""
+    """Shutdown the tracer provider and flush all spans.
+
+    Thread-safe: Uses lock to protect shutdown operation.
+    """
     global _tracer_provider, _is_configured
 
-    if _tracer_provider:
-        _tracer_provider.shutdown()
-        _tracer_provider = None
-        _is_configured = False
-        print("✅ Tracer provider shutdown")
+    with _collector_lock:
+        if _tracer_provider:
+            _tracer_provider.shutdown()
+            _tracer_provider = None
+            _is_configured = False
+            print("✅ Tracer provider shutdown")

kalibr/context.py

@@ -8,6 +8,7 @@ HTTP requests to SDK calls (OpenAI, Anthropic, Google).
 import random
 import string
 import uuid
+from contextlib import contextmanager
 from contextvars import ContextVar
 from typing import Dict, Optional
 
@@ -130,3 +131,44 @@ def inject_kalibr_context_into_span(span: Span):
             span.set_attribute("kalibr.http_trace_id", ctx["trace_id"])
         if ctx.get("span_id"):
             span.set_attribute("kalibr.http_span_id", ctx["span_id"])
+
+
+# ============================================================================
+# Goal Context for Outcome Tracking (v1.3.0)
+# ============================================================================
+
+_goal_context: ContextVar[Optional[str]] = ContextVar("goal_context", default=None)
+
+
+def set_goal(goal: str):
+    """Set the current goal for all subsequent Kalibr traces."""
+    _goal_context.set(goal)
+
+
+def get_goal() -> Optional[str]:
+    """Get the current goal."""
+    return _goal_context.get()
+
+
+def clear_goal():
+    """Clear the current goal."""
+    _goal_context.set(None)
+
+
+@contextmanager
+def goal(goal_name: str):
+    """Context manager to set goal for a block of code.
+
+    Usage:
+        with kalibr.goal("research_company"):
+            agent.run("Research Weights & Biases")
+    """
+    previous = get_goal()
+    set_goal(goal_name)
+    try:
+        yield
+    finally:
+        if previous:
+            set_goal(previous)
+        else:
+            clear_goal()