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

kalibr/instrumentation/registry.py

@@ -0,0 +1,153 @@
+"""
+Instrumentation Registry
+
+Handles auto-discovery and registration of LLM SDK instrumentations.
+Provides a central place to manage which SDKs are instrumented.
+"""
+
+import os
+from typing import Dict, List, Set
+
+# Track which providers have been instrumented
+_instrumented_providers: Set[str] = set()
+
+
+def auto_instrument(providers: List[str] = None) -> Dict[str, bool]:
+    """
+    Auto-discover and instrument LLM SDKs
+
+    Args:
+        providers: List of provider names to instrument.
+                   If None, attempts to instrument all supported providers.
+                   Supported: ["openai", "anthropic", "google"]
+
+    Returns:
+        Dictionary mapping provider names to instrumentation success status
+    """
+    global _instrumented_providers
+
+    # Default to all providers if none specified
+    if providers is None:
+        providers = ["openai", "anthropic", "google"]
+
+    results = {}
+
+    for provider in providers:
+        provider_lower = provider.lower()
+
+        # Skip if already instrumented
+        if provider_lower in _instrumented_providers:
+            results[provider_lower] = True
+            continue
+
+        try:
+            if provider_lower == "openai":
+                from . import openai_instr
+
+                success = openai_instr.instrument()
+                results[provider_lower] = success
+                if success:
+                    _instrumented_providers.add(provider_lower)
+                    print(f"✅ Instrumented OpenAI SDK")
+
+            elif provider_lower == "anthropic":
+                from . import anthropic_instr
+
+                success = anthropic_instr.instrument()
+                results[provider_lower] = success
+                if success:
+                    _instrumented_providers.add(provider_lower)
+                    print(f"✅ Instrumented Anthropic SDK")
+
+            elif provider_lower == "google":
+                from . import google_instr
+
+                success = google_instr.instrument()
+                results[provider_lower] = success
+                if success:
+                    _instrumented_providers.add(provider_lower)
+                    print(f"✅ Instrumented Google Generative AI SDK")
+
+            else:
+                print(f"⚠️  Unknown provider: {provider}")
+                results[provider_lower] = False
+
+        except ImportError as e:
+            print(f"⚠️  {provider} SDK not installed, skipping instrumentation")
+            results[provider_lower] = False
+        except Exception as e:
+            print(f"❌ Failed to instrument {provider}: {e}")
+            results[provider_lower] = False
+
+    return results
+
+
+def uninstrument_all() -> Dict[str, bool]:
+    """
+    Remove instrumentation from all previously instrumented SDKs
+
+    Returns:
+        Dictionary mapping provider names to uninstrumentation success status
+    """
+    global _instrumented_providers
+
+    results = {}
+    providers_to_uninstrument = list(_instrumented_providers)
+
+    for provider in providers_to_uninstrument:
+        try:
+            if provider == "openai":
+                from . import openai_instr
+
+                success = openai_instr.uninstrument()
+                results[provider] = success
+                if success:
+                    _instrumented_providers.discard(provider)
+                    print(f"✅ Uninstrumented OpenAI SDK")
+
+            elif provider == "anthropic":
+                from . import anthropic_instr
+
+                success = anthropic_instr.uninstrument()
+                results[provider] = success
+                if success:
+                    _instrumented_providers.discard(provider)
+                    print(f"✅ Uninstrumented Anthropic SDK")
+
+            elif provider == "google":
+                from . import google_instr
+
+                success = google_instr.uninstrument()
+                results[provider] = success
+                if success:
+                    _instrumented_providers.discard(provider)
+                    print(f"✅ Uninstrumented Google Generative AI SDK")
+
+        except Exception as e:
+            print(f"❌ Failed to uninstrument {provider}: {e}")
+            results[provider] = False
+
+    return results
+
+
+def get_instrumented_providers() -> List[str]:
+    """
+    Get list of currently instrumented providers
+
+    Returns:
+        List of provider names that are currently instrumented
+    """
+    return list(_instrumented_providers)
+
+
+def is_instrumented(provider: str) -> bool:
+    """
+    Check if a specific provider is instrumented
+
+    Args:
+        provider: Provider name to check
+
+    Returns:
+        True if provider is instrumented, False otherwise
+    """
+    return provider.lower() in _instrumented_providers

kalibr/kalibr.py

@@ -1,259 +1,173 @@
-# kalibr/kalibr.py
+"""Kalibr - Simple function-level API builder"""
 
+import inspect
+import os
+from typing import Any, Callable, Dict, List, Optional
+
+import uvicorn
 from fastapi import FastAPI, Request
 from fastapi.responses import JSONResponse
-from typing import Callable, Dict, Any, get_type_hints
-import inspect
+from kalibr.middleware.auto_tracer import AutoTracerMiddleware
+from kalibr.schemas import (
+    generate_copilot_schema,
+    generate_gemini_schema,
+    generate_mcp_schema,
+    get_base_url,
+    get_supported_models,
+)
+from pydantic import BaseModel, create_model
+
 
 class Kalibr:
-    """
-    A framework for creating API endpoints that can be easily integrated with AI models.
-    Kalibr simplifies the process of exposing Python functions as API actions,
-    providing automatic documentation, request handling, and metadata generation
-    for services like Claude's MCP and OpenAI's function calling.
-    """
-    def __init__(self, title="Kalibr API", version="1.0.0", base_url="http://localhost:8000"):
-        """
-        Initializes the Kalibr API.
-
-        Args:
-            title (str): The title of the API. Defaults to "Kalibr API".
-            version (str): The version of the API. Defaults to "1.0.0".
-            base_url (str): The base URL of the API, used for generating tool URLs.
-                            Defaults to "http://localhost:8000".
-        """
+    """Simple function-level API builder for multi-model integration"""
+
+    def __init__(
+        self,
+        title: str = "Kalibr API",
+        version: str = "1.0.0",
+        auto_trace: bool = True,
+        agent_name: str = None,
+    ):
         self.app = FastAPI(title=title, version=version)
-        self.base_url = base_url
-        self.actions = {}  # Stores registered actions and their metadata
+        self.actions: List[Dict[str, Any]] = []
+        self.base_url = get_base_url()
+        self.agent_name = agent_name or title
+
+        # Phase 3B: Auto-attach tracing middleware
+        if auto_trace and os.getenv("KALIBR_TRACE_ENABLED", "true").lower() == "true":
+            self.app.add_middleware(
+                AutoTracerMiddleware,
+                agent_name=self.agent_name,
+            )
+
         self._setup_routes()
 
     def action(self, name: str, description: str = ""):
-        """
-        Decorator to register a Python function as an API action.
-
-        This decorator automatically handles request routing (both GET and POST),
-        parameter extraction, and response formatting. It also generates metadata
-        required by AI model integrations.
-
-        Args:
-            name (str): The unique name of the action. This will be used as the
-                        API endpoint path and in AI model tool definitions.
-            description (str): A human-readable description of what the action does.
-                               This is used in AI model tool descriptions. Defaults to "".
-
-        Returns:
-            Callable: A decorator function.
-        """
+        """Decorator to register a function as an action"""
+
         def decorator(func: Callable):
-            # Store the function and its metadata
-            self.actions[name] = {
-                "func": func,
-                "description": description,
-                "params": self._extract_params(func)
-            }
-            
-            # Define the endpoint path for this action
-            endpoint_path = f"/proxy/{name}"
-            
-            # Create a unified handler that accepts both GET (query params) and POST (JSON body)
-            async def endpoint_handler(request: Request):
-                params = {}
-                if request.method == "POST":
-                    # For POST requests, try to get parameters from the JSON body
-                    try:
-                        body = await request.json()
-                        params = body if isinstance(body, dict) else {}
-                    except Exception:
-                        # If JSON parsing fails or body is not a dict, treat as empty params
-                        params = {}
-                else:
-                    # For GET requests, use query parameters
-                    params = dict(request.query_params)
-                
-                # Call the original registered function with extracted parameters
-                try:
-                    result = func(**params)
-                    # If the result is a coroutine, await it
-                    if inspect.isawaitable(result):
-                        result = await result
-                    return JSONResponse(content=result)
-                except Exception as e:
-                    # Basic error handling for function execution
-                    return JSONResponse(content={"error": str(e)}, status_code=500)
-            
-            # Register both POST and GET endpoints for the same path
-            self.app.post(endpoint_path)(endpoint_handler)
-            self.app.get(endpoint_path)(endpoint_handler)
-            
-            return func  # Return the original function
+            # Extract function signature
+            sig = inspect.signature(func)
+            schema = self._generate_schema(sig)
+
+            # Store action metadata
+            self.actions.append(
+                {
+                    "name": name,
+                    "description": description or func.__doc__ or "",
+                    "function": func,
+                    "schema": schema,
+                }
+            )
+
+            # Register proxy endpoint
+            self._register_proxy_endpoint(name, func, schema)
+
+            return func
+
         return decorator
-    
-    def _extract_params(self, func: Callable) -> Dict:
-        """
-        Extracts parameter names, types, and requirements from a function's signature.
-
-        This method inspects the function's signature and type hints to generate
-        a schema representation of its parameters, suitable for API documentation
-        and AI model integrations.
-
-        Args:
-            func (Callable): The function to inspect.
-
-        Returns:
-            Dict: A dictionary where keys are parameter names and values are dictionaries
-                  containing 'type' (JSON schema type) and 'required' (boolean) information.
-        """
-        sig = inspect.signature(func)
-        params = {}
-        
-        # Get type hints from annotations if available
-        type_hints = get_type_hints(func) if hasattr(func, '__annotations__') else {}
-        
+
+    def _generate_schema(self, sig: inspect.Signature) -> Dict[str, Any]:
+        """Generate JSON schema from function signature"""
+        properties = {}
+        required = []
+
         for param_name, param in sig.parameters.items():
-            param_type = "string"  # Default type if none is inferred
-            
-            # Determine the annotation for the parameter
-            if param_name in type_hints:
-                anno = type_hints[param_name]
-            elif param.annotation != inspect.Parameter.empty:
-                anno = param.annotation
-            else:
-                anno = str  # Fallback to string if no annotation
-            
-            # Map common Python types to their JSON schema equivalents
-            if anno == int:
-                param_type = "integer"
-            elif anno == bool:
-                param_type = "boolean"
-            elif anno == float:
-                param_type = "number"
-            elif anno == list or anno == dict:
-                # For lists and dicts, we can't automatically infer element/key types
-                # without more complex introspection or explicit type hints like List[str], Dict[str, int]
-                # For simplicity, we'll mark them as general objects/arrays.
-                # A more robust implementation might use a library like pydantic for schema generation.
-                if anno == list:
+            param_type = "string"  # Default type
+
+            # Map Python types to JSON schema types
+            if param.annotation != inspect.Parameter.empty:
+                if param.annotation == int:
+                    param_type = "integer"
+                elif param.annotation == float:
+                    param_type = "number"
+                elif param.annotation == bool:
+                    param_type = "boolean"
+                elif param.annotation == list:
                     param_type = "array"
-                else:
+                elif param.annotation == dict:
                     param_type = "object"
-            
-            # Determine if the parameter is required
-            is_required = param.default == inspect.Parameter.empty
-            
-            params[param_name] = {
-                "type": param_type,
-                "required": is_required
-            }
-        
-        return params
-    
+
+            properties[param_name] = {"type": param_type}
+
+            # Check if parameter is required (no default value)
+            if param.default == inspect.Parameter.empty:
+                required.append(param_name)
+
+        return {"type": "object", "properties": properties, "required": required}
+
+    def _register_proxy_endpoint(self, name: str, func: Callable, schema: Dict[str, Any]):
+        """Register a proxy endpoint for the action"""
+        # Create Pydantic model for request validation
+        fields = {}
+        for prop_name, prop_schema in schema["properties"].items():
+            field_type = str  # Default
+            if prop_schema["type"] == "integer":
+                field_type = int
+            elif prop_schema["type"] == "number":
+                field_type = float
+            elif prop_schema["type"] == "boolean":
+                field_type = bool
+
+            # Check if required
+            if prop_name in schema.get("required", []):
+                fields[prop_name] = (field_type, ...)
+            else:
+                fields[prop_name] = (Optional[field_type], None)
+
+        RequestModel = create_model(f"{name}_Request", **fields)
+
+        @self.app.post(f"/proxy/{name}")
+        async def proxy_endpoint(request: RequestModel):
+            try:
+                result = func(**request.dict(exclude_none=True))
+                return result
+            except Exception as e:
+                return JSONResponse(status_code=500, content={"error": str(e)})
+
     def _setup_routes(self):
-        """
-        Sets up the core routes for the Kalibr API.
-
-        This includes:
-        - A root endpoint ("/") for basic API status and available actions.
-        - Multi-model schema endpoints for all major AI platforms:
-          - /openapi.json (GPT Actions)
-          - /mcp.json (Claude MCP)
-          - /schemas/gemini (Google Gemini)
-          - /schemas/copilot (Microsoft Copilot)
-        """
-        from kalibr.schema_generators import (
-            OpenAPISchemaGenerator, 
-            MCPSchemaGenerator, 
-            GeminiSchemaGenerator, 
-            CopilotSchemaGenerator
-        )
-        
+        """Setup built-in routes"""
+
         @self.app.get("/")
-        def root():
-            """
-            Root endpoint providing API status and a list of available actions.
-            """
+        async def root():
             return {
-                "message": "Kalibr API is running", 
-                "actions": list(self.actions.keys()),
+                "message": "Kalibr API is running",
+                "actions": [action["name"] for action in self.actions],
                 "schemas": {
                     "gpt_actions": f"{self.base_url}/gpt-actions.json",
                     "openapi_swagger": f"{self.base_url}/openapi.json",
                     "claude_mcp": f"{self.base_url}/mcp.json",
                     "gemini": f"{self.base_url}/schemas/gemini",
-                    "copilot": f"{self.base_url}/schemas/copilot"
-                }
+                    "copilot": f"{self.base_url}/schemas/copilot",
+                },
             }
-        
-        # Initialize schema generators
-        openapi_gen = OpenAPISchemaGenerator()
-        mcp_gen = MCPSchemaGenerator()
-        gemini_gen = GeminiSchemaGenerator()
-        copilot_gen = CopilotSchemaGenerator()
-        
+
         @self.app.get("/gpt-actions.json")
-        def gpt_actions_schema():
-            """
-            Generates OpenAPI 3.0 schema for GPT Actions integration.
-            (Alternative endpoint since /openapi.json is used by FastAPI)
-            """
-            return openapi_gen.generate_schema(self.actions, self.base_url)
-        
+        async def gpt_actions_schema():
+            """Generates OpenAPI 3.0 schema for GPT Actions integration.
+            (Alternative endpoint since /openapi.json is used by FastAPI)"""
+            return self.app.openapi()
+
         @self.app.get("/mcp.json")
-        def mcp_manifest():
-            """
-            Generates Claude MCP manifest for AI model integration.
-            """
-            return mcp_gen.generate_schema(self.actions, self.base_url)
-        
+        async def mcp_schema():
+            return generate_mcp_schema(self.actions, self.base_url)
+
         @self.app.get("/schemas/gemini")
-        def gemini_schema():
-            """
-            Generates Google Gemini Extensions schema.
-            """
-            return gemini_gen.generate_schema(self.actions, self.base_url)
-        
+        async def gemini_schema():
+            return generate_gemini_schema(self.actions, self.base_url)
+
         @self.app.get("/schemas/copilot")
-        def copilot_schema():
-            """
-            Generates Microsoft Copilot plugin schema.
-            """
-            return copilot_gen.generate_schema(self.actions, self.base_url)
-        
-        # Override FastAPI's default OpenAPI generation to include servers configuration
-        def custom_openapi():
-            """
-            Customizes the OpenAPI schema generation for Swagger UI.
-            """
-            if self.app.openapi_schema:
-                return self.app.openapi_schema
-            
-            from fastapi.openapi.utils import get_openapi
-            # Generate the default OpenAPI schema
-            openapi_schema = get_openapi(
-                title=self.app.title,
-                version=self.app.version,
-                routes=self.app.routes,
-            )
-            
-            # Add the 'servers' block to the schema
-            openapi_schema["servers"] = [{"url": self.base_url}]
-            
-            self.app.openapi_schema = openapi_schema
-            return self.app.openapi_schema
-        
-        # Assign the custom OpenAPI generator to the FastAPI app
-        self.app.openapi = custom_openapi
-    
-    def get_app(self):
-        """
-        Returns the FastAPI application instance.
-
-        This allows the Kalibr API to be run using standard ASGI servers like Uvicorn.
-
-        Returns:
-            FastAPI: The configured FastAPI application.
-        """
+        async def copilot_schema():
+            return generate_copilot_schema(self.actions, self.base_url)
+
+        @self.app.get("/models/supported")
+        async def models_supported():
+            return get_supported_models()
+
+    def get_app(self) -> FastAPI:
+        """Get the FastAPI app instance"""
         return self.app
 
-if __name__ == '__main__':
-    print("Kalibr SDK loaded. Use this class to build your API.")
-    print("See the __main__ block for example usage.")
+    def run(self, host: str = "0.0.0.0", port: int = 8000):
+        """Run the Kalibr server"""
+        uvicorn.run(self.app, host=host, port=port)