kalibr 1.0.28__py3-none-any.whl → 1.1.0a0__py3-none-any.whl

kalibr/__init__.py

@@ -1,5 +1,172 @@
-from .kalibr_app import KalibrApp
+"""Kalibr SDK v1.1.0 - Unified LLM Observability & Multi-Model AI Integration Framework
+
+This SDK combines:
+1. Full LLM Observability with tracing, cost tracking, and analytics
+2. Multi-Model AI Integration (GPT, Claude, Gemini, Copilot)
+3. One-line deployment with Docker and runtime router
+4. Schema generation for all major AI platforms
+5. **NEW in 1.1.0**: Auto-instrumentation of LLM SDKs (OpenAI, Anthropic, Google)
+
+Features:
+- **Auto-Instrumentation**: Zero-config tracing of OpenAI, Anthropic, Google SDK calls
+- **OpenTelemetry**: OTel-compatible spans with OTLP export
+- **Tracing**: Complete telemetry with @trace decorator
+- **Cost Tracking**: Multi-vendor cost calculation (OpenAI, Anthropic, etc.)
+- **Deployment**: One-command deployment to Fly.io, Render, or local
+- **Schema Generation**: Auto-generate schemas for GPT Actions, Claude MCP, Gemini, Copilot
+- **Error Handling**: Automatic error capture with stack traces
+- **Analytics**: ClickHouse-backed analytics and alerting
+
+Usage - Auto-Instrumentation (NEW):
+    from kalibr import Kalibr
+    import openai  # Automatically instrumented!
+
+    app = Kalibr(title="My API")
+
+    @app.action("chat", "Chat with GPT")
+    def chat(message: str):
+        # This OpenAI call is automatically traced!
+        response = openai.chat.completions.create(
+            model="gpt-4",
+            messages=[{"role": "user", "content": message}]
+        )
+        return response.choices[0].message.content
+
+Usage - Manual Tracing:
+    from kalibr import trace
+
+    @trace(operation="chat_completion", vendor="openai", model="gpt-4")
+    def call_openai(prompt):
+        response = openai.chat.completions.create(
+            model="gpt-4",
+            messages=[{"role": "user", "content": prompt}]
+        )
+        return response
+
+CLI Usage:
+    kalibr serve my_app.py              # Run locally
+    kalibr deploy my_app.py --runtime fly  # Deploy to Fly.io
+    kalibr run my_app.py                # Run with auto-tracing
+    kalibr version                       # Show version
+"""
+
+__version__ = "1.1.0-alpha"
+
+# Auto-instrument LLM SDKs on import (can be disabled via env var)
+import os
+
+# ============================================================================
+# OBSERVABILITY & TRACING (from 1023)
+# ============================================================================
+from .client import KalibrClient
+
+# ============================================================================
+# PHASE 1: SDK INSTRUMENTATION & OPENTELEMETRY (v1.1.0)
+# ============================================================================
+from .collector import (
+    get_tracer_provider,
+)
+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 .cost_adapter import (
+    AnthropicCostAdapter,
+    BaseCostAdapter,
+    CostAdapterFactory,
+    OpenAICostAdapter,
+)
+from .instrumentation import auto_instrument, get_instrumented_providers
+
+# ============================================================================
+# SDK & DEPLOYMENT (from 1.0.30)
+# ============================================================================
 from .kalibr import Kalibr
+from .kalibr_app import KalibrApp
+from .models import EventData, TraceConfig
+from .schemas import (
+    generate_copilot_schema,
+    generate_gemini_schema,
+    generate_mcp_schema,
+    get_base_url,
+    get_supported_models,
+)
+from .simple_tracer import trace
+from .trace_capsule import TraceCapsule, get_or_create_capsule
+from .tracer import SpanContext, Tracer
+from .types import FileUpload, Session
+from .utils import load_config_from_env
+
+if os.getenv("KALIBR_AUTO_INSTRUMENT", "true").lower() == "true":
+    # Setup OpenTelemetry collector
+    try:
+        setup_collector(
+            service_name=os.getenv("KALIBR_SERVICE_NAME", "kalibr"),
+            file_export=True,
+            console_export=os.getenv("KALIBR_CONSOLE_EXPORT", "false").lower() == "true",
+        )
+    except Exception as e:
+        print(f"⚠️  Failed to setup OpenTelemetry collector: {e}")
+
+    # Auto-instrument available SDKs
+    try:
+        auto_instrument(["openai", "anthropic", "google"])
+    except Exception as e:
+        print(f"⚠️  Failed to auto-instrument SDKs: {e}")
 
-__all__ = ["Kalibr", "KalibrApp"]
-__version__ = "1.0.28"
+__all__ = [
+    # ========================================================================
+    # OBSERVABILITY & TRACING
+    # ========================================================================
+    # Simple tracing API (recommended)
+    "trace",
+    # Capsule propagation (Phase 6)
+    "TraceCapsule",
+    "get_or_create_capsule",
+    # Client
+    "KalibrClient",
+    # Context
+    "trace_context",
+    "get_trace_id",
+    "get_parent_span_id",
+    "new_trace_id",
+    # Tracer
+    "Tracer",
+    "SpanContext",
+    # Cost Adapters
+    "BaseCostAdapter",
+    "OpenAICostAdapter",
+    "AnthropicCostAdapter",
+    "CostAdapterFactory",
+    # Models
+    "TraceConfig",
+    "EventData",
+    # Utils
+    "load_config_from_env",
+    # ========================================================================
+    # SDK & DEPLOYMENT
+    # ========================================================================
+    # SDK Classes
+    "Kalibr",
+    "KalibrApp",
+    # Types
+    "FileUpload",
+    "Session",
+    # Schema Generation
+    "get_base_url",
+    "generate_mcp_schema",
+    "generate_gemini_schema",
+    "generate_copilot_schema",
+    "get_supported_models",
+    # ========================================================================
+    # PHASE 1: SDK INSTRUMENTATION & OPENTELEMETRY (v1.1.0)
+    # ========================================================================
+    # Auto-instrumentation
+    "auto_instrument",
+    "get_instrumented_providers",
+    # OpenTelemetry collector
+    "setup_collector",
+    "get_tracer_provider",
+    "is_collector_configured",
+]

kalibr/__main__.py

@@ -1,206 +1,6 @@
-import typer
-import uvicorn
-import sys
-import importlib.util
-from pathlib import Path
-import os
-import requests
-import json
+"""Entry point for python -m kalibr"""
 
-app = typer.Typer()
-
-def _load_user_module(file: str):
-    file_path = Path(file).resolve()
-    if not file_path.exists():
-        print(f"❌ Error: {file} not found")
-        raise typer.Exit(1)
-    spec = importlib.util.spec_from_file_location("user_app", file_path)
-    if not spec or not spec.loader:
-        print(f"❌ Error: Could not load {file}")
-        raise typer.Exit(1)
-    module = importlib.util.module_from_spec(spec)
-    sys.modules["user_app"] = module
-    try:
-        spec.loader.exec_module(module)
-    except Exception as e:
-        print(f"❌ Error loading {file}: {e}")
-        raise typer.Exit(1)
-    return module
-
-@app.command()
-def serve(
-    file: str = typer.Argument("kalibr_app.py", help="Python file with Kalibr app"),
-    host: str = typer.Option("0.0.0.0", "--host", "-h"),
-    port: int = typer.Option(8000, "--port", "-p"),
-    base_url: str = typer.Option("http://localhost:8000", "--base-url", "-b"),
-):
-    """Serve a Kalibr-powered API locally."""
-    module = _load_user_module(file)
-
-    # Import Kalibr classes
-    from kalibr import Kalibr, KalibrApp
-    kalibr_instance = None
-    for attr_name in dir(module):
-        attr = getattr(module, attr_name)
-        if isinstance(attr, Kalibr) or (KalibrApp and isinstance(attr, KalibrApp)):
-            kalibr_instance = attr
-            kalibr_instance.base_url = base_url
-            break
-    if not kalibr_instance:
-        print(f"❌ Error: No Kalibr/KalibrApp instance found in {file}")
-        raise typer.Exit(1)
-
-    if hasattr(kalibr_instance, 'get_app'):
-        fastapi_app = kalibr_instance.get_app()
-    elif hasattr(kalibr_instance, 'app'):
-        fastapi_app = kalibr_instance.app
-    else:
-        print(f"❌ Error: Kalibr instance has no get_app() method or app attribute")
-        raise typer.Exit(1)
-
-    is_enhanced = 'KalibrApp' in str(type(kalibr_instance))
-    print(f"🚀 Starting {'Enhanced ' if is_enhanced else ''}Kalibr server from {file}")
-    print(f"📍 GPT (OpenAPI):     {base_url}/openapi.json")
-    print(f"📍 Claude (MCP):      {base_url}/mcp.json")
-    if is_enhanced:
-        print(f"📍 Gemini:            {base_url}/schemas/gemini")
-        print(f"📍 Copilot:           {base_url}/schemas/copilot")
-        print(f"📍 Supported Models:  {base_url}/models/supported")
-        print(f"📍 Health Check:      {base_url}/health")
-    print(f"📍 Swagger UI:        {base_url}/docs")
-    print(f"🔌 Actions registered: {list(kalibr_instance.actions.keys())}")
-
-    uvicorn.run(fastapi_app, host=host, port=port)
-
-@app.command()
-def package(
-    app_dir: str = typer.Option(".", "--app-dir", "-d", help="Directory containing your app"),
-    output: str = typer.Option("kalibr_bundle.zip", "--output", "-o", help="Bundle file"),
-    models: str = typer.Option("mcp,gpt-actions,gemini,copilot", "--models", "-m", help="Comma-separated models supported")
-):
-    """Create a deployable MCP bundle (code + schemas + metadata)."""
-    from kalibr.packager import package_app
-    try:
-        models_supported = [x.strip() for x in models.split(",") if x.strip()]
-        # Version best-effort
-        try:
-            from kalibr import __version__ as kalibr_version
-        except Exception:
-            kalibr_version = "unknown"
-        bundle_path = package_app(app_dir=app_dir, output=output, models_supported=models_supported, kalibr_version=kalibr_version)
-        print(f"📦 Bundle created: {bundle_path}")
-    except Exception as e:
-        print(f"❌ Packaging error: {e}")
-        raise typer.Exit(1)
-
-@app.command()
-def deploy(
-    file: str = typer.Argument(..., help="Python file to serve/deploy (e.g., kalibr_app.py)"),
-    name: str = typer.Option("", "--name", "-n", help="App name (defaults to filename)"),
-    runtime: str = typer.Option("local", "--runtime", "-r", help="Runtime: local|fly|render"),
-    host: str = typer.Option("0.0.0.0", "--host"),
-    port: int = typer.Option(8000, "--port"),
-    base_url: str = typer.Option("http://localhost:8000", "--base-url"),
-):
-    """Deploy via runtime router (no hosting burden on Kalibr)."""
-    from kalibr.runtime_router import deploy as router_deploy
-    file_path = Path(file)
-    if not file_path.exists():
-        print(f"❌ Error: {file} not found")
-        raise typer.Exit(1)
-    if not name:
-        name = file_path.stem.replace('_', '-').replace('.', '-')
-    try:
-        result = router_deploy(runtime=runtime, app_name=name, app_file=str(file_path), host=host, port=port, base_url=base_url)
-        if result.get("status") in ("success", "started"):
-            print("🎉 Deploy OK")
-            eps = result.get("endpoints", {})
-            if eps:
-                print("📍 Endpoints:")
-                for k, v in eps.items():
-                    print(f"   - {k}: {v}")
-        else:
-            print("⚠️  Deploy finished with unknown status:", result)
-    except Exception as e:
-        print(f"❌ Deployment error: {e}")
-        raise typer.Exit(1)
-
-@app.command()
-def validate(
-    url: str = typer.Option("http://localhost:8000/mcp.json", "--mcp-url", help="URL to MCP manifest"),
-):
-    """Validate MCP manifest against minimal JSON schema & version hint."""
-    from kalibr.validator import validate_mcp_manifest
-    try:
-        resp = requests.get(url, timeout=10)
-        resp.raise_for_status()
-        manifest = resp.json()
-        validate_mcp_manifest(manifest)
-        print("✅ MCP manifest looks structurally valid.")
-    except Exception as e:
-        print(f"❌ Validation failed: {e}")
-        raise typer.Exit(1)
-
-@app.command()
-def update_schemas():
-    """Stub: instruct users to upgrade SDK and regenerate manifests."""
-    from kalibr.validator import update_schemas as _upd
-    _upd()
-
-@app.command()
-def status(
-    app_url: str = typer.Argument(..., help="URL of deployed Kalibr app"),
-    verbose: bool = typer.Option(False, "--verbose", "-v", help="Show detailed information")
-):
-    """Check status of a deployed Kalibr app."""
-    try:
-        health_url = f"{app_url.rstrip('/')}/health"
-        response = requests.get(health_url, timeout=10)
-        if response.status_code == 200:
-            health_data = response.json()
-            print(f"✅ App is healthy at {app_url}")
-            print(f"   Version: {health_data.get('version', 'unknown')}")
-            print(f"   Features: {health_data.get('features', {})}")
-            if verbose:
-                schemas = ["mcp.json", "openapi.json", "schemas/gemini", "schemas/copilot"]
-                print(f"\n📊 Available AI model schemas:")
-                for schema in schemas:
-                    schema_url = f"{app_url.rstrip('/')}/{schema}"
-                    try:
-                        schema_response = requests.get(schema_url, timeout=5)
-                        status_emoji = "✅" if schema_response.status_code == 200 else "❌"
-                        model_name = schema.replace(".json", "").replace("schemas/", "")
-                        print(f"   {status_emoji} {model_name.upper()}: {schema_url}")
-                    except:
-                        print(f"   ❌ {schema}: Connection failed")
-        else:
-            print(f"❌ App at {app_url} is not responding (HTTP {response.status_code})")
-            raise typer.Exit(1)
-    except requests.exceptions.RequestException as e:
-        print(f"❌ Cannot connect to {app_url}: {e}")
-        raise typer.Exit(1)
-
-@app.command()
-def version():
-    try:
-        from kalibr import __version__
-    except (ImportError, AttributeError):
-        __version__ = "unknown"
-    print(f"Kalibr SDK version: {__version__}")
-    print("Enhanced multi-model AI integration framework")
-    print("Supports: GPT Actions, Claude MCP, Gemini Extensions, Copilot Plugins")
-    print("GitHub: https://github.com/devonakelley/kalibr-sdk")
-
-def main():
-    config_file = Path.home() / ".kalibr" / "config.json"
-    if config_file.exists():
-        try:
-            config = json.loads(config_file.read_text())
-            if "api_token" in config and not os.environ.get("KALIBR_TOKEN"):
-                os.environ["KALIBR_TOKEN"] = config["api_token"]
-        except:
-            pass
-    app()
+from kalibr.cli.main import app
 
 if __name__ == "__main__":
-    main()
+    app()

kalibr/capsule_middleware.py

@@ -0,0 +1,108 @@
+"""
+Kalibr Capsule Middleware for FastAPI.
+
+Automatically extracts, propagates, and injects trace capsules in HTTP requests.
+
+Usage in FastAPI app:
+    from kalibr.capsule_middleware import add_capsule_middleware
+
+    app = FastAPI()
+    add_capsule_middleware(app)
+
+    # Now all requests have request.state.capsule available
+    @app.get("/")
+    def endpoint(request: Request):
+        capsule = request.state.capsule
+        # Use capsule...
+"""
+
+import logging
+
+from fastapi import FastAPI, Request
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.responses import Response
+
+from .trace_capsule import TraceCapsule, get_or_create_capsule
+
+logger = logging.getLogger(__name__)
+
+CAPSULE_HEADER = "X-Kalibr-Capsule"
+
+
+class CapsuleMiddleware(BaseHTTPMiddleware):
+    """Middleware that extracts and propagates Kalibr trace capsules.
+
+    This middleware:
+    1. Extracts capsule from incoming X-Kalibr-Capsule header
+    2. Attaches capsule to request.state for access in endpoints
+    3. Automatically injects updated capsule in response headers
+    """
+
+    async def dispatch(self, request: Request, call_next):
+        """Process request and response with capsule handling.
+
+        Args:
+            request: Incoming HTTP request
+            call_next: Next middleware/endpoint in chain
+
+        Returns:
+            Response with X-Kalibr-Capsule header attached
+        """
+        # Extract capsule from header (or create new one)
+        capsule_header = request.headers.get(CAPSULE_HEADER)
+
+        if capsule_header:
+            capsule = TraceCapsule.from_json(capsule_header)
+            logger.debug(f"📦 Received capsule: {capsule}")
+        else:
+            capsule = TraceCapsule()
+            logger.debug(f"📦 Created new capsule: {capsule.trace_id}")
+
+        # Attach capsule to request state
+        request.state.capsule = capsule
+
+        # Process request
+        response = await call_next(request)
+
+        # Inject updated capsule in response headers
+        try:
+            capsule_json = capsule.to_json()
+            response.headers[CAPSULE_HEADER] = capsule_json
+            logger.debug(f"📦 Sending capsule: {capsule}")
+        except Exception as e:
+            logger.warning(f"⚠️ Failed to serialize capsule: {e}")
+
+        return response
+
+
+def add_capsule_middleware(app: FastAPI) -> None:
+    """Add capsule middleware to FastAPI application.
+
+    Args:
+        app: FastAPI application instance
+
+    Example:
+        app = FastAPI()
+        add_capsule_middleware(app)
+    """
+    app.add_middleware(CapsuleMiddleware)
+    logger.info("✅ Kalibr Capsule middleware added")
+
+
+def get_capsule(request: Request) -> TraceCapsule:
+    """Get capsule from request state (convenience function).
+
+    Args:
+        request: FastAPI Request object
+
+    Returns:
+        TraceCapsule attached to request
+
+    Raises:
+        AttributeError: If middleware not installed
+    """
+    if not hasattr(request.state, "capsule"):
+        logger.warning("⚠️ Capsule middleware not installed, creating new capsule")
+        request.state.capsule = TraceCapsule()
+
+    return request.state.capsule

kalibr/cli/__init__.py

@@ -0,0 +1,5 @@
+"""Kalibr CLI package"""
+
+from kalibr.cli.main import app
+
+__all__ = ["app"]

kalibr/cli/capsule_cmd.py

@@ -0,0 +1,174 @@
+"""
+Capsule Reconstruction CLI Command
+Fetch and export trace capsules from Kalibr Platform
+"""
+
+import json
+import sys
+from pathlib import Path
+from typing import Optional
+
+import requests
+import typer
+from rich import print as rprint
+from rich.console import Console
+from rich.table import Table
+
+console = Console()
+
+
+def capsule(
+    trace_id: str = typer.Argument(..., help="Trace ID to reconstruct capsule for"),
+    api_url: Optional[str] = typer.Option(
+        None,
+        "--api-url",
+        "-u",
+        help="Kalibr API base URL (default: from env KALIBR_API_URL or http://localhost:8001)",
+        envvar="KALIBR_API_URL",
+    ),
+    output: Optional[Path] = typer.Option(
+        None,
+        "--output",
+        "-o",
+        help="Output file path (JSON format). If not specified, prints to stdout.",
+    ),
+    export: bool = typer.Option(
+        False,
+        "--export",
+        "-e",
+        help="Use export endpoint to download as file",
+    ),
+    pretty: bool = typer.Option(
+        True,
+        "--pretty/--no-pretty",
+        "-p/-np",
+        help="Pretty print JSON output",
+    ),
+):
+    """
+    Reconstruct and fetch a trace capsule by trace_id.
+
+    The capsule contains all linked trace events, aggregated metrics,
+    and metadata for a complete execution chain.
+
+    Examples:
+
+        # Fetch capsule and display in terminal
+        kalibr capsule abc-123-def
+
+        # Save capsule to file
+        kalibr capsule abc-123-def --output capsule.json
+
+        # Use export endpoint
+        kalibr capsule abc-123-def --export --output capsule.json
+
+        # Specify custom API URL
+        kalibr capsule abc-123-def -u https://api.kalibr.io
+    """
+    # Determine API base URL
+    base_url = api_url or "http://localhost:8001"
+    base_url = base_url.rstrip("/")
+
+    # Build endpoint URL
+    if export:
+        endpoint = f"{base_url}/api/capsule/{trace_id}/export"
+    else:
+        endpoint = f"{base_url}/api/capsule/{trace_id}"
+
+    console.print(f"[cyan]Fetching capsule for trace_id:[/cyan] [bold]{trace_id}[/bold]")
+    console.print(f"[dim]Endpoint: {endpoint}[/dim]")
+
+    try:
+        # Make API request
+        response = requests.get(endpoint, timeout=30)
+        response.raise_for_status()
+
+        # Parse response
+        capsule_data = response.json()
+
+        # Display summary
+        console.print("\n[green]✓ Capsule reconstructed successfully[/green]\n")
+
+        # Create summary table
+        table = Table(title="Capsule Summary", show_header=False)
+        table.add_column("Field", style="cyan", no_wrap=True)
+        table.add_column("Value", style="white")
+
+        table.add_row("Capsule ID", capsule_data.get("capsule_id", "N/A"))
+        table.add_row("Total Cost (USD)", f"${capsule_data.get('total_cost_usd', 0):.6f}")
+        table.add_row("Total Latency (ms)", str(capsule_data.get("total_latency_ms", 0)))
+        table.add_row("Hop Count", str(capsule_data.get("hop_count", 0)))
+        table.add_row("Providers", ", ".join(capsule_data.get("providers", [])))
+        table.add_row("Reconstructed At", capsule_data.get("reconstructed_at", "N/A"))
+
+        console.print(table)
+
+        # Output to file or stdout
+        if output:
+            output_path = Path(output)
+            output_path.parent.mkdir(parents=True, exist_ok=True)
+
+            with open(output_path, "w") as f:
+                if pretty:
+                    json.dump(capsule_data, f, indent=2, sort_keys=True)
+                else:
+                    json.dump(capsule_data, f)
+
+            console.print(f"\n[green]✓ Capsule saved to:[/green] {output_path}")
+        else:
+            # Print to stdout
+            console.print("\n[bold]Capsule Data:[/bold]")
+            if pretty:
+                rprint(json.dumps(capsule_data, indent=2, sort_keys=True))
+            else:
+                print(json.dumps(capsule_data))
+
+        # Display event details
+        events = capsule_data.get("events", [])
+        if events:
+            console.print(f"\n[bold]Events ({len(events)}):[/bold]")
+            event_table = Table()
+            event_table.add_column("Trace ID", style="cyan")
+            event_table.add_column("Provider", style="yellow")
+            event_table.add_column("Model", style="magenta")
+            event_table.add_column("Operation", style="blue")
+            event_table.add_column("Duration (ms)", justify="right", style="green")
+            event_table.add_column("Cost (USD)", justify="right", style="green")
+            event_table.add_column("Status", style="white")
+
+            for event in events:
+                event_table.add_row(
+                    event.get("trace_id", "")[:12] + "...",
+                    event.get("provider", "N/A"),
+                    event.get("model_id", "N/A")[:20],
+                    event.get("operation", "N/A"),
+                    str(event.get("duration_ms", 0)),
+                    f"${event.get('cost_usd', 0):.6f}",
+                    event.get("status", "N/A"),
+                )
+
+            console.print(event_table)
+
+        return 0
+
+    except requests.exceptions.HTTPError as e:
+        if e.response.status_code == 404:
+            console.print(f"[red]✗ Capsule not found for trace_id: {trace_id}[/red]")
+            console.print("[yellow]Make sure the trace_id exists and has been ingested.[/yellow]")
+        else:
+            console.print(f"[red]✗ API Error ({e.response.status_code}):[/red] {e.response.text}")
+        return 1
+
+    except requests.exceptions.ConnectionError:
+        console.print(f"[red]✗ Connection Error:[/red] Unable to connect to {base_url}")
+        console.print("[yellow]Make sure the Kalibr backend is running and accessible.[/yellow]")
+        return 1
+
+    except requests.exceptions.Timeout:
+        console.print("[red]✗ Timeout:[/red] Request took too long to complete")
+        return 1
+
+    except Exception as e:
+        console.print(f"[red]✗ Unexpected Error:[/red] {str(e)}")
+        console.print("[yellow]Run with --help for usage information[/yellow]")
+        return 1