kalibr 1.0.28__tar.gz → 1.1.0__tar.gz

kalibr-1.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Kalibr
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

kalibr-1.1.0/PKG-INFO

@@ -0,0 +1,97 @@
+Metadata-Version: 2.4
+Name: kalibr
+Version: 1.1.0
+Summary: Unified LLM Observability & Multi-Model AI Integration Framework - Deploy to GPT, Claude, Gemini, Copilot with full telemetry
+Author-email: Kalibr Team <team@kalibr.dev>
+License: MIT
+Project-URL: Homepage, https://github.com/devonakelley/kalibr-sdk
+Project-URL: Documentation, https://github.com/devonakelley/kalibr-sdk#readme
+Project-URL: Repository, https://github.com/devonakelley/kalibr-sdk
+Project-URL: Issues, https://github.com/devonakelley/kalibr-sdk/issues
+Keywords: ai,mcp,gpt,claude,gemini,copilot,openai,anthropic,google,microsoft,observability,telemetry,tracing,llm,schema-generation,api,multi-model
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: tiktoken>=0.8.0
+Requires-Dist: fastapi>=0.110.1
+Requires-Dist: uvicorn>=0.25.0
+Requires-Dist: pydantic>=2.6.4
+Requires-Dist: typer>=0.9.0
+Requires-Dist: python-multipart>=0.0.9
+Requires-Dist: rich>=10.0.0
+Requires-Dist: requests>=2.31.0
+Requires-Dist: opentelemetry-api>=1.20.0
+Requires-Dist: opentelemetry-sdk>=1.20.0
+Requires-Dist: opentelemetry-exporter-otlp>=1.20.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Dynamic: license-file
+
+# Kalibr Python SDK
+
+Production-grade observability for LLM applications.
+
+## Installation
+```bash
+pip install kalibr
+```
+
+## Quickstart
+```python
+from kalibr import trace
+import openai
+
+@trace(api_key="your-kalibr-api-key")
+def my_agent():
+    response = openai.chat.completions.create(
+        model="gpt-4",
+        messages=[{"role": "user", "content": "Hello!"}]
+    )
+    return response
+```
+
+## Features
+
+- ✅ Zero-code instrumentation for OpenAI, Anthropic, Google AI
+- ✅ Automatic parent-child trace relationships
+- ✅ Real-time cost tracking
+- ✅ Token usage monitoring
+- ✅ Performance metrics
+
+## CLI Tools
+```bash
+# Run your app locally
+kalibr serve myapp.py
+
+# Deploy to Fly.io
+kalibr deploy myapp.py
+
+# Fetch trace data
+kalibr capsule <trace-id>
+```
+
+## Examples
+
+See `examples/` directory for complete examples.
+
+## Documentation
+
+Full docs at https://docs.kalibr.systems
+
+## License
+
+MIT

kalibr-1.1.0/README.md

@@ -0,0 +1,54 @@
+# Kalibr Python SDK
+
+Production-grade observability for LLM applications.
+
+## Installation
+```bash
+pip install kalibr
+```
+
+## Quickstart
+```python
+from kalibr import trace
+import openai
+
+@trace(api_key="your-kalibr-api-key")
+def my_agent():
+    response = openai.chat.completions.create(
+        model="gpt-4",
+        messages=[{"role": "user", "content": "Hello!"}]
+    )
+    return response
+```
+
+## Features
+
+- ✅ Zero-code instrumentation for OpenAI, Anthropic, Google AI
+- ✅ Automatic parent-child trace relationships
+- ✅ Real-time cost tracking
+- ✅ Token usage monitoring
+- ✅ Performance metrics
+
+## CLI Tools
+```bash
+# Run your app locally
+kalibr serve myapp.py
+
+# Deploy to Fly.io
+kalibr deploy myapp.py
+
+# Fetch trace data
+kalibr capsule <trace-id>
+```
+
+## Examples
+
+See `examples/` directory for complete examples.
+
+## Documentation
+
+Full docs at https://docs.kalibr.systems
+
+## License
+
+MIT

kalibr-1.1.0/kalibr/__init__.py

@@ -0,0 +1,172 @@
+"""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"
+
+# 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__ = [
+    # ========================================================================
+    # 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-1.1.0/kalibr/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for python -m kalibr"""
+
+from kalibr.cli.main import app
+
+if __name__ == "__main__":
+    app()

kalibr-1.1.0/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-1.1.0/kalibr/cli/__init__.py

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

kalibr-1.1.0/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