kalibr 1.0.17__py3-none-any.whl → 1.0.18__py3-none-any.whl

kalibr/kalibr.py

@@ -0,0 +1,249 @@
+# kalibr/kalibr.py
+
+from fastapi import FastAPI, Request
+from fastapi.responses import JSONResponse
+from typing import Callable, Dict, Any, get_type_hints
+import inspect
+
+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".
+        """
+        self.app = FastAPI(title=title, version=version)
+        self.base_url = base_url
+        self.actions = {}  # Stores registered actions and their metadata
+        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.
+        """
+        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
+        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 {}
+        
+        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 = "array"
+                else:
+                    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
+    
+    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.
+        - An MCP (Model Communication Protocol) manifest endpoint ("/mcp.json")
+          for AI model integrations.
+        - Customizes OpenAPI schema generation to include server URLs.
+        """
+        
+        @self.app.get("/")
+        def root():
+            """
+            Root endpoint providing API status and a list of available actions.
+            """
+            return {"message": "Kalibr API is running", "actions": list(self.actions.keys())}
+        
+        @self.app.get("/mcp.json")
+        def mcp_manifest():
+            """
+            Generates the MCP manifest (Claude specific) for registered actions.
+
+            This manifest describes the available tools (actions) and their input schemas
+            in a format consumable by Claude.
+            """
+            tools = []
+            for action_name, action_data in self.actions.items():
+                properties = {}
+                required = []
+                
+                # Construct the input schema for the tool
+                for param_name, param_info in action_data["params"].items():
+                    properties[param_name] = {"type": param_info["type"]}
+                    if param_info["required"]:
+                        required.append(param_name)
+                
+                tools.append({
+                    "name": action_name,
+                    "description": action_data["description"],
+                    "input_schema": {
+                        "type": "object",
+                        "properties": properties,
+                        "required": required
+                    },
+                    # The server URL points to the proxy endpoint for this action
+                    "server": {
+                        "url": f"{self.base_url}/proxy/{action_name}"
+                    }
+                })
+            
+            # Return the MCP manifest structure
+            return {
+                "mcp": "1.0",
+                "name": "kalibr",  # Name of the AI agent or toolset
+                "tools": tools
+            }
+        
+        # Override FastAPI's default OpenAPI generation to include servers configuration
+        def custom_openapi():
+            """
+            Customizes the OpenAPI schema generation.
+
+            Adds a 'servers' block to the OpenAPI schema, which is often required
+            by AI model integrations (e.g., OpenAI function calling).
+            """
+            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.
+        """
+        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.")

kalibr/kalibr_app.py

@@ -1,38 +1,68 @@
-import importlib.util
-import os
-import uvicorn
 from fastapi import FastAPI
+import importlib.util
+import json
+import inspect
+from pydantic import BaseModel
+
+class KalibrApp:
+    """
+    Minimal Kalibr SDK App that auto-generates schemas
+    for GPT Actions, Claude MCP, Gemini, etc.
+    """
+
+    def __init__(self, file_path: str):
+        self.file_path = file_path
+        self.app = FastAPI(title="Kalibr App")
+        self.functions = self._load_tools()
+
+    def _load_tools(self):
+        """Dynamically import all @tool-decorated functions from the user app."""
+        spec = importlib.util.spec_from_file_location("user_app", self.file_path)
+        user_app = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(user_app)
+        funcs = {}
+
+        for name, obj in inspect.getmembers(user_app, inspect.isfunction):
+            if hasattr(obj, "_kalibr_tool"):
+                funcs[name] = obj
+                self._register_route(name, obj)
+
+        return funcs
+
+    def _register_route(self, name, func):
+        """Register each tool as a POST endpoint."""
+        class RequestSchema(BaseModel):
+            __annotations__ = {k: v for k, v in func.__annotations__.items() if k != "return"}
 
-class KalibrApp(FastAPI):
-    def __init__(self):
-        super().__init__()
-        print("🚀 KalibrApp initialized. Ready to serve AI tools.")
+        async def route(payload: RequestSchema):
+            result = func(**payload.dict())
+            return {"result": result}
 
-    def run(self, host="127.0.0.1", port=8000):
-        print(f"🚀 Starting Kalibr server on http://{host}:{port}")
-        uvicorn.run(self, host=host, port=port)
+        self.app.post(f"/tools/{name}")(route)
 
-# --- CLI helper functions ---
+    def generate_schemas(self):
+        """Generate model-specific schemas for GPT Actions, Claude MCP, Gemini."""
+        schemas = {}
+        for name, func in self.functions.items():
+            sig = inspect.signature(func)
+            params = {
+                k: str(v.annotation) for k, v in sig.parameters.items()
+            }
+            schemas[name] = {
+                "description": func.__doc__ or "",
+                "parameters": params,
+                "returns": str(sig.return_annotation),
+            }
+        return {
+            "gpt_actions": schemas,
+            "claude_mcp": schemas,
+            "gemini_tools": schemas,
+        }
 
 def serve_app(file_path: str):
-    """Run a Kalibr app file (e.g. demo_app.py) locally."""
-    if not os.path.exists(file_path):
-        print(f"❌ File not found: {file_path}")
-        return
-
-    module_name = os.path.splitext(os.path.basename(file_path))[0]
-    spec = importlib.util.spec_from_file_location(module_name, file_path)
-    module = importlib.util.module_from_spec(spec)
-    spec.loader.exec_module(module)
-
-    app = getattr(module, "app", None)
-    if not app:
-        print("❌ No `app` instance found in the provided file.")
-        return
-
-    print(f"🚀 Serving {file_path} locally...")
-    uvicorn.run(app, host="127.0.0.1", port=8000)
-
-def deploy_app(file_path: str):
-    """Stub for future deploy command."""
-    print(f"🚀 Deploying {file_path} (stub). Future versions will handle cloud deploys.")
+    """Run the Kalibr app locally."""
+    from uvicorn import run
+    app_instance = KalibrApp(file_path)
+    print("✅ Generated Schemas:")
+    print(json.dumps(app_instance.generate_schemas(), indent=2))
+    run(app_instance.app, host="127.0.0.1", port=8000)

kalibr/schema_generators.py

@@ -1,13 +1,212 @@
-import json
-
-def generate_openapi_schema(app):
-    return app.openapi()
-
-def generate_mcp_schema(app):
-    return {
-        "mcp": "1.0",
-        "tools": [
-            {"name": name, "description": func.__doc__ or ""}
-            for name, func in app.actions.items()
-        ],
-    }
+"""
+Multi-model schema generators for different AI platforms
+"""
+from typing import Dict, Any, List
+from abc import ABC, abstractmethod
+
+class BaseSchemaGenerator(ABC):
+    """Base class for AI model schema generators"""
+    
+    @abstractmethod
+    def generate_schema(self, actions: Dict, base_url: str) -> Dict[str, Any]:
+        """Generate schema for the specific AI model"""
+        pass
+
+class MCPSchemaGenerator(BaseSchemaGenerator):
+    """Claude MCP schema generator"""
+    
+    def generate_schema(self, actions: Dict, base_url: str) -> Dict[str, Any]:
+        tools = []
+        for action_name, action_data in actions.items():
+            properties = {}
+            required = []
+            
+            # Construct the input schema for the tool
+            for param_name, param_info in action_data["params"].items():
+                properties[param_name] = {"type": param_info["type"]}
+                if param_info["required"]:
+                    required.append(param_name)
+            
+            tools.append({
+                "name": action_name,
+                "description": action_data["description"],
+                "input_schema": {
+                    "type": "object",
+                    "properties": properties,
+                    "required": required
+                },
+                "server": {
+                    "url": f"{base_url}/proxy/{action_name}"
+                }
+            })
+        
+        return {
+            "mcp": "1.0",
+            "name": "kalibr-enhanced",
+            "tools": tools
+        }
+
+class OpenAPISchemaGenerator(BaseSchemaGenerator):
+    """GPT Actions OpenAPI schema generator"""
+    
+    def generate_schema(self, actions: Dict, base_url: str) -> Dict[str, Any]:
+        paths = {}
+        
+        for action_name, action_data in actions.items():
+            properties = {}
+            required = []
+            
+            for param_name, param_info in action_data["params"].items():
+                properties[param_name] = {"type": param_info["type"]}
+                if param_info["required"]:
+                    required.append(param_name)
+            
+            paths[f"/proxy/{action_name}"] = {
+                "post": {
+                    "summary": action_data["description"],
+                    "operationId": action_name,
+                    "requestBody": {
+                        "required": True,
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "type": "object",
+                                    "properties": properties,
+                                    "required": required
+                                }
+                            }
+                        }
+                    },
+                    "responses": {
+                        "200": {
+                            "description": "Successful response",
+                            "content": {
+                                "application/json": {
+                                    "schema": {"type": "object"}
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        
+        return {
+            "openapi": "3.0.0",
+            "info": {
+                "title": "Kalibr Enhanced API",
+                "version": "2.0.0",
+                "description": "Enhanced Kalibr API with app-level capabilities"
+            },
+            "servers": [{"url": base_url}],
+            "paths": paths
+        }
+
+class GeminiSchemaGenerator(BaseSchemaGenerator):
+    """Google Gemini Extensions schema generator"""
+    
+    def generate_schema(self, actions: Dict, base_url: str) -> Dict[str, Any]:
+        functions = []
+        
+        for action_name, action_data in actions.items():
+            parameters = {
+                "type": "object",
+                "properties": {},
+                "required": []
+            }
+            
+            for param_name, param_info in action_data["params"].items():
+                parameters["properties"][param_name] = {
+                    "type": param_info["type"],
+                    "description": f"Parameter {param_name}"
+                }
+                if param_info["required"]:
+                    parameters["required"].append(param_name)
+            
+            functions.append({
+                "name": action_name,
+                "description": action_data["description"],
+                "parameters": parameters,
+                "server": {
+                    "url": f"{base_url}/proxy/{action_name}"
+                }
+            })
+        
+        return {
+            "gemini_extension": "1.0",
+            "name": "kalibr_enhanced",
+            "description": "Enhanced Kalibr API for Gemini integration",
+            "functions": functions
+        }
+
+class CopilotSchemaGenerator(BaseSchemaGenerator):
+    """Microsoft Copilot plugin schema generator"""
+    
+    def generate_schema(self, actions: Dict, base_url: str) -> Dict[str, Any]:
+        apis = []
+        
+        for action_name, action_data in actions.items():
+            request_schema = {
+                "type": "object",
+                "properties": {},
+                "required": []
+            }
+            
+            for param_name, param_info in action_data["params"].items():
+                request_schema["properties"][param_name] = {
+                    "type": param_info["type"]
+                }
+                if param_info["required"]:
+                    request_schema["required"].append(param_name)
+            
+            apis.append({
+                "name": action_name,
+                "description": action_data["description"],
+                "url": f"{base_url}/proxy/{action_name}",
+                "method": "POST",
+                "request_schema": request_schema,
+                "response_schema": {
+                    "type": "object",
+                    "description": "API response"
+                }
+            })
+        
+        return {
+            "schema_version": "v1",
+            "name_for_model": "kalibr_enhanced",
+            "name_for_human": "Enhanced Kalibr API",
+            "description_for_model": "Enhanced Kalibr API with advanced capabilities",
+            "description_for_human": "API for advanced AI model integrations",
+            "auth": {
+                "type": "none"
+            },
+            "api": {
+                "type": "openapi",
+                "url": f"{base_url}/openapi.json"
+            },
+            "apis": apis
+        }
+
+class CustomModelSchemaGenerator(BaseSchemaGenerator):
+    """Extensible generator for future AI models"""
+    
+    def __init__(self, model_name: str, schema_format: str):
+        self.model_name = model_name
+        self.schema_format = schema_format
+    
+    def generate_schema(self, actions: Dict, base_url: str) -> Dict[str, Any]:
+        # Generic schema format that can be customized
+        return {
+            "model": self.model_name,
+            "format": self.schema_format,
+            "version": "2.0.0",
+            "base_url": base_url,
+            "actions": [
+                {
+                    "name": name,
+                    "description": data["description"],
+                    "parameters": data["params"],
+                    "endpoint": f"{base_url}/proxy/{name}"
+                }
+                for name, data in actions.items()
+            ]
+        }

kalibr/types.py

@@ -0,0 +1,106 @@
+"""
+Enhanced data types for Kalibr app-level framework
+"""
+from pydantic import BaseModel, Field
+from typing import Optional, Dict, Any, List, Union, AsyncGenerator
+from datetime import datetime
+import uuid
+import io
+
+class FileUpload(BaseModel):
+    """Enhanced file upload handling for AI model integrations"""
+    filename: str
+    content_type: str
+    size: int
+    content: bytes
+    upload_id: str = Field(default_factory=lambda: str(uuid.uuid4()))
+    uploaded_at: datetime = Field(default_factory=datetime.now)
+    
+    class Config:
+        arbitrary_types_allowed = True
+
+class ImageData(BaseModel):
+    """Image data type for AI vision capabilities"""
+    filename: str
+    content_type: str
+    width: Optional[int] = None
+    height: Optional[int] = None
+    format: str  # jpeg, png, webp, etc.
+    content: bytes
+    image_id: str = Field(default_factory=lambda: str(uuid.uuid4()))
+    
+    class Config:
+        arbitrary_types_allowed = True
+
+class TableData(BaseModel):
+    """Structured table data for AI analysis"""
+    headers: List[str]
+    rows: List[List[Any]]
+    table_id: str = Field(default_factory=lambda: str(uuid.uuid4()))
+    metadata: Optional[Dict[str, Any]] = None
+
+class StreamingResponse(BaseModel):
+    """Base class for streaming responses"""
+    chunk_id: str
+    content: Any
+    is_final: bool = False
+    timestamp: datetime = Field(default_factory=datetime.now)
+
+class Session(BaseModel):
+    """Session management for stateful interactions"""
+    session_id: str = Field(default_factory=lambda: str(uuid.uuid4()))
+    user_id: Optional[str] = None
+    created_at: datetime = Field(default_factory=datetime.now)
+    last_accessed: datetime = Field(default_factory=datetime.now)
+    data: Dict[str, Any] = Field(default_factory=dict)
+    expires_at: Optional[datetime] = None
+    
+    def get(self, key: str, default=None):
+        """Get session data"""
+        return self.data.get(key, default)
+    
+    def set(self, key: str, value: Any):
+        """Set session data"""
+        self.data[key] = value
+        self.last_accessed = datetime.now()
+    
+    def delete(self, key: str):
+        """Delete session data"""
+        if key in self.data:
+            del self.data[key]
+
+class AuthenticatedUser(BaseModel):
+    """Authenticated user context"""
+    user_id: str
+    username: str
+    email: Optional[str] = None
+    roles: List[str] = Field(default_factory=list)
+    permissions: List[str] = Field(default_factory=list)
+    auth_method: str  # "jwt", "oauth", "api_key", etc.
+    
+class FileDownload(BaseModel):
+    """File download response"""
+    filename: str
+    content_type: str
+    content: bytes
+    
+    class Config:
+        arbitrary_types_allowed = True
+
+class AnalysisResult(BaseModel):
+    """Generic analysis result structure"""
+    result_id: str = Field(default_factory=lambda: str(uuid.uuid4()))
+    status: str  # "success", "error", "pending"
+    data: Dict[str, Any] = Field(default_factory=dict)
+    created_at: datetime = Field(default_factory=datetime.now)
+    processing_time: Optional[float] = None
+    metadata: Optional[Dict[str, Any]] = None
+
+class WorkflowState(BaseModel):
+    """Workflow state management"""
+    workflow_id: str = Field(default_factory=lambda: str(uuid.uuid4()))
+    step: str
+    status: str
+    data: Dict[str, Any] = Field(default_factory=dict)
+    created_at: datetime = Field(default_factory=datetime.now)
+    updated_at: datetime = Field(default_factory=datetime.now)