ciris-agent 1.7.7__py3-none-any.whl

ciris_engine/logic/adapters/api/app.py

@@ -0,0 +1,272 @@
+"""
+FastAPI application for CIRIS API v1.
+
+This module creates and configures the FastAPI application with all routes.
+"""
+
+from contextlib import asynccontextmanager
+from typing import Any, AsyncIterator, Callable
+
+from fastapi import FastAPI, Request, Response
+from fastapi.middleware.cors import CORSMiddleware
+
+# Import rate limiting middleware
+from .middleware.rate_limiter import RateLimitMiddleware
+
+# Import all route modules from adapter
+from .routes import (
+    agent,
+    audit,
+    auth,
+    billing,
+    config,
+    connectors,
+    consent,
+    dsar,
+    dsar_multi_source,
+    emergency,
+    memory,
+    partnership,
+    setup,
+    system,
+    system_extensions,
+    telemetry,
+    tickets,
+    tools,
+    transparency,
+    users,
+    verification,
+    wa,
+)
+
+# Import auth service
+from .services.auth_service import APIAuthService
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI) -> AsyncIterator[None]:
+    """Manage application lifecycle."""
+    # Startup
+    print("Starting CIRIS API...")
+    yield
+    # Shutdown
+    print("Shutting down CIRIS API...")
+
+
+def create_app(runtime: Any = None, adapter_config: Any = None) -> FastAPI:
+    """
+    Create and configure the FastAPI application.
+
+    Args:
+        runtime: Optional runtime instance for service access
+        adapter_config: Optional APIAdapterConfig instance
+
+    Returns:
+        Configured FastAPI application
+    """
+    # Determine root_path for reverse proxy support
+    root_path = ""
+    if adapter_config and hasattr(adapter_config, "proxy_path") and adapter_config.proxy_path:
+        root_path = adapter_config.proxy_path
+        print(f"Configuring FastAPI with root_path='{root_path}' for reverse proxy support")
+
+    app = FastAPI(
+        title="CIRIS API v1",
+        description="Autonomous AI Agent Interaction and Observability API (Pre-Beta)",
+        version="1.0.0",
+        lifespan=lifespan,
+        root_path=root_path or "",  # This tells FastAPI it's behind a proxy at this path
+    )
+
+    # Add CORS middleware
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=["*"],  # Configure based on deployment
+        allow_credentials=True,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+
+    # Add rate limiting middleware if enabled in config
+    if adapter_config and getattr(adapter_config, "rate_limit_enabled", False):
+        rate_limit = getattr(adapter_config, "rate_limit_per_minute", 60)
+
+        # Create middleware instance
+        rate_limit_middleware = RateLimitMiddleware(requests_per_minute=rate_limit)
+
+        # Add middleware using a wrapper function
+        @app.middleware("http")
+        async def rate_limit_wrapper(request: Request, call_next: Callable[..., Any]) -> Response:
+            return await rate_limit_middleware(request, call_next)
+
+        print(f"Rate limiting enabled: {rate_limit} requests per minute")
+
+    # Store runtime in app state for access in routes
+    if runtime:
+        app.state.runtime = runtime
+
+        # Initialize auth service - will be properly initialized later with authentication service
+        app.state.auth_service = APIAuthService()
+
+        # Services will be injected later in ApiPlatform.start() after they're initialized
+        # For now, just set placeholders to None
+
+        # === THE 21 CORE CIRIS SERVICES ===
+        # Graph Services (6)
+        app.state.memory_service = None
+        app.state.consent_manager = None  # Consent manager for Consensual Evolution Protocol (includes DSAR automation)
+        app.state.config_service = None
+        app.state.telemetry_service = None
+        app.state.audit_service = None
+        app.state.incident_management_service = None
+        app.state.tsdb_consolidation_service = None
+
+        # Infrastructure Services (7)
+        app.state.time_service = None
+        app.state.shutdown_service = None
+        app.state.initialization_service = None
+        app.state.authentication_service = None
+        app.state.resource_monitor = None
+        app.state.database_maintenance_service = None
+        app.state.secrets_service = None
+
+        # Governance Services (4)
+        app.state.wise_authority_service = None
+        app.state.wa_service = None  # Alias for wise_authority_service
+        app.state.adaptive_filter_service = None
+        app.state.visibility_service = None
+        app.state.self_observation_service = None
+
+        # Runtime Services (3)
+        app.state.llm_service = None
+        app.state.runtime_control_service = None
+        app.state.task_scheduler = None
+
+        # Tool Services (1)
+        app.state.secrets_tool_service = None
+
+        # === INFRASTRUCTURE COMPONENTS (not part of the 22 services) ===
+        app.state.service_registry = None
+        app.state.agent_processor = None
+        app.state.message_handler = None
+        # Adapter-created services
+        app.state.communication_service = None
+        app.state.tool_service = None
+        # Adapter configuration service (for interactive adapter setup)
+        app.state.adapter_configuration_service = None
+        # Message buses (injected from bus_manager)
+        app.state.tool_bus = None
+        app.state.memory_bus = None
+
+    # Mount v1 API routes (all routes except emergency under /v1)
+    v1_routers = [
+        setup.router,  # Setup wizard (first-run + reconfiguration) - MUST be first for first-run detection
+        agent.router,  # Agent interaction
+        billing.router,  # Billing & credits (frontend proxy) - LLM credits
+        tools.router,  # Tool balance & credits (web_search, etc.) - separate from LLM credits
+        memory.router,  # Memory operations
+        system_extensions.router,  # Extended system operations (queue, services, processors) - MUST be before system.router
+        system.router,  # System operations (includes health, time, resources, runtime)
+        config.router,  # Configuration management
+        telemetry.router,  # Telemetry & observability
+        audit.router,  # Audit trail
+        wa.router,  # Wise Authority
+        auth.router,  # Authentication
+        users.router,  # User management
+        consent.router,  # Consent management (Consensual Evolution Protocol)
+        dsar.router,  # Data Subject Access Requests (GDPR compliance - single source)
+        dsar_multi_source.router,  # Multi-source DSAR (CIRIS + external databases)
+        connectors.router,  # External data connector management (SQL, REST, HL7)
+        tickets.router,  # Universal Ticket System (DSAR + custom workflows)
+        verification.router,  # Deletion proof verification (public, no auth)
+        partnership.router,  # Partnership management dashboard (admin only)
+        transparency.router,  # Public transparency feed (no auth)
+    ]
+
+    # Include all v1 routes with /v1 prefix
+    for router in v1_routers:
+        app.include_router(router, prefix="/v1")
+
+    # Mount emergency routes at root level (no /v1 prefix)
+    # This is special - requires signed commands, no auth
+    app.include_router(emergency.router)
+
+    # Mount GUI static assets (if available) - MUST be LAST for proper route priority
+    # This enables serving the CIRISGUI frontend when bundled in the wheel
+    # ONLY in installed/standalone mode - NOT in managed/Docker mode
+    from pathlib import Path
+
+    from ciris_engine.logic.utils.path_resolution import is_android, is_managed
+
+    # Path resolution for GUI static assets
+    # Need 4 parent levels: api -> adapters -> logic -> ciris_engine
+    package_root = Path(__file__).resolve().parent.parent.parent.parent
+
+    # On Android, prefer android_gui_static (built from CIRISGUI-Android)
+    # Otherwise fall back to gui_static (bundled in wheel for desktop/server)
+    android_gui_dir = package_root.parent / "android_gui_static"
+    gui_static_dir = package_root / "gui_static"
+
+    # Choose the appropriate GUI directory
+    if is_android() and android_gui_dir.exists() and any(android_gui_dir.iterdir()):
+        gui_static_dir = android_gui_dir
+        print(f"📱 Using Android GUI static assets: {gui_static_dir}")
+
+    # Skip GUI in managed/Docker mode - manager provides its own frontend
+    if is_managed():
+        print("ℹ️  GUI disabled in managed mode (manager provides frontend)")
+
+        # API-only mode for managed deployments
+        @app.get("/")
+        def root() -> dict[str, str]:
+            return {
+                "name": "CIRIS API",
+                "version": "1.0.0",
+                "docs": "/docs",
+                "redoc": "/redoc",
+                "openapi": "/openapi.json",
+                "gui": "managed_mode",
+                "message": "Running in managed mode - GUI provided by CIRIS Manager",
+            }
+
+    elif gui_static_dir.exists() and any(gui_static_dir.iterdir()):
+        from fastapi.staticfiles import StaticFiles
+
+        # Serve GUI at root (/) - catch-all, lowest priority
+        # This works because FastAPI matches routes in order:
+        # 1. /v1/* routes (highest priority)
+        # 2. /emergency/* routes
+        # 3. /docs, /redoc, /openapi.json (FastAPI built-ins)
+        # 4. /* GUI static files (lowest priority, catch-all)
+        app.mount("/", StaticFiles(directory=str(gui_static_dir), html=True), name="gui")
+        print(f"✅ GUI enabled at / (static assets: {gui_static_dir})")
+    else:
+        # No GUI - API-only mode
+        @app.get("/")
+        def root() -> dict[str, str]:
+            return {
+                "name": "CIRIS API",
+                "version": "1.0.0",
+                "docs": "/docs",
+                "redoc": "/redoc",
+                "openapi": "/openapi.json",
+                "gui": "not_available",
+                "message": "Install from PyPI for the full package with GUI: pip install ciris-agent",
+            }
+
+        print("ℹ️  API-only mode (no GUI assets found)")
+
+    return app
+
+
+# For running standalone (development)
+if __name__ == "__main__":
+    import os
+
+    import uvicorn
+
+    app = create_app()
+    # Use environment variable or secure default (localhost only)
+    host = os.environ.get("CIRIS_API_HOST", "127.0.0.1")
+    port = int(os.environ.get("CIRIS_API_PORT", "8000"))
+    uvicorn.run(app, host=host, port=port)

ciris_engine/logic/adapters/api/auth.py

@@ -0,0 +1,159 @@
+"""
+Authentication utilities for API routes.
+"""
+
+from typing import Any, Optional
+
+from fastapi import Depends, HTTPException, Request, status
+from fastapi.security import HTTPBearer
+
+from .models import TokenData
+
+# HTTP Bearer token security scheme
+security = HTTPBearer(auto_error=False)
+
+
+def _extract_token_string(token: Optional[str]) -> str:
+    """Extract token string from HTTPBearer object or raw string."""
+    if not token:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Missing authentication token",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+    return token.credentials if hasattr(token, "credentials") else str(token)
+
+
+def _get_auth_services(request: Request) -> tuple[Optional[Any], Optional[Any]]:
+    """Get authentication services from app state."""
+    wa_auth_service = getattr(request.app.state, "authentication_service", None)
+    api_auth_service = getattr(request.app.state, "auth_service", None)
+    return wa_auth_service, api_auth_service
+
+
+def _create_fallback_token_data() -> TokenData:
+    """Create fallback token data for development mode."""
+    return TokenData(username="admin", email="admin@ciris.ai", role="SYSTEM_ADMIN")
+
+
+def _try_api_key_validation(token_str: str, api_auth_service: Optional[Any], logger: Any) -> Optional[TokenData]:
+    """Try to validate token as an API key. Returns TokenData if valid, None otherwise."""
+    if not token_str.startswith("ciris_"):
+        return None
+
+    logger.debug("[AUTH] Detected API key format - attempting API key validation")
+
+    if not api_auth_service:
+        logger.warning("[AUTH] API auth service not available for API key validation")
+        return None
+
+    stored_key = api_auth_service.validate_api_key(token_str)
+    logger.debug(f"[AUTH] API key validation result: {stored_key is not None}")
+
+    if not stored_key:
+        logger.warning("[AUTH] API key validation failed - invalid or expired")
+        return None
+
+    # Get user from API auth service
+    user = api_auth_service.get_user(stored_key.user_id)
+    if not user or not user.is_active:
+        return None
+
+    logger.debug(f"[AUTH] API key validated for user: {user.name}, role: {user.api_role.value}")
+    return TokenData(
+        username=user.name,
+        email=user.oauth_email,
+        role=user.api_role.value,
+        exp=stored_key.expires_at,
+    )
+
+
+async def _try_jwt_validation(token_str: str, wa_auth_service: Optional[Any], logger: Any) -> Optional[TokenData]:
+    """Try to validate token as a JWT. Returns TokenData if valid, None otherwise."""
+    if not wa_auth_service:
+        return None
+
+    logger.debug("[AUTH] Attempting JWT token verification")
+
+    verification = await wa_auth_service.verify_token(token_str)
+    logger.debug(
+        f"[AUTH] JWT verification result: valid={verification.valid if verification else None}, role={verification.role if verification else None}"
+    )
+
+    if not verification or not verification.valid:
+        return None
+
+    # Convert WA role to API role format
+    role_mapping = {
+        "OBSERVER": "OBSERVER",
+        "ADMIN": "ADMIN",
+        "AUTHORITY": "AUTHORITY",
+        "SYSTEM_ADMIN": "SYSTEM_ADMIN",
+    }
+
+    api_role = role_mapping.get(verification.role, "OBSERVER")
+
+    return TokenData(
+        username=verification.name or verification.wa_id,
+        email=None,  # WA tokens don't include email
+        role=api_role,
+        exp=verification.expires_at,
+    )
+
+
+async def get_current_user(request: Request, token: Optional[str] = Depends(security)) -> TokenData:
+    """
+    Get the current authenticated user from the token.
+
+    Validates both API keys and JWT tokens.
+    """
+    import logging
+
+    logger = logging.getLogger(__name__)
+
+    logger.debug(f"[AUTH] get_current_user called, token present: {token is not None}")
+
+    # Extract and validate token
+    token_str = _extract_token_string(token)
+    logger.debug(
+        f"[AUTH] Token extracted, type: {type(token)}, first 20 chars: {token_str[:20] if token_str else 'None'}..."
+    )
+
+    # Get authentication services
+    wa_auth_service, api_auth_service = _get_auth_services(request)
+    logger.debug(
+        f"[AUTH] WA auth service available: {wa_auth_service is not None}, API auth service available: {api_auth_service is not None}"
+    )
+
+    # Fallback to development mode if no services available
+    if not wa_auth_service and not api_auth_service:
+        return _create_fallback_token_data()
+
+    try:
+        # Try API key validation first
+        api_key_result = _try_api_key_validation(token_str, api_auth_service, logger)
+        if api_key_result:
+            return api_key_result
+
+        # Try JWT validation as fallback
+        jwt_result = await _try_jwt_validation(token_str, wa_auth_service, logger)
+        if jwt_result:
+            return jwt_result
+
+        # Both validation methods failed
+        logger.warning("[AUTH] Both API key and JWT validation failed")
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Invalid or expired token",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.debug(f"[AUTH] Exception during token validation: {type(e).__name__}: {str(e)}")
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail=f"Token validation failed: {str(e)}",
+            headers={"WWW-Authenticate": "Bearer"},
+        )

ciris_engine/logic/adapters/api/config.py

@@ -0,0 +1,101 @@
+"""Configuration schema for API adapter."""
+
+from pydantic import BaseModel, Field
+
+from ciris_engine.constants import DEFAULT_API_HOST, DEFAULT_API_PORT
+
+
+class APIAdapterConfig(BaseModel):
+    """Configuration for the API adapter.
+
+    Security Note:
+    - Default host is 127.0.0.1 (localhost only) for security
+    - Set host to 0.0.0.0 only when you need external access
+    - Always use proper firewall rules when binding to all interfaces
+    - Consider using a reverse proxy (nginx, etc.) for production deployments
+    """
+
+    host: str = Field(
+        default=DEFAULT_API_HOST,
+        description="API server host (127.0.0.1 for localhost only, 0.0.0.0 for all interfaces)",
+    )
+    port: int = Field(default=DEFAULT_API_PORT, description="API server port")
+
+    cors_enabled: bool = Field(default=True, description="Enable CORS support")
+    cors_origins: list[str] = Field(default_factory=lambda: ["*"], description="Allowed CORS origins")
+
+    max_request_size: int = Field(default=1024 * 1024, description="Maximum request size in bytes")
+    request_timeout: float = Field(default=30.0, description="Request timeout in seconds")
+
+    enable_swagger: bool = Field(default=True, description="Enable Swagger/OpenAPI documentation")
+    enable_redoc: bool = Field(default=True, description="Enable ReDoc documentation")
+
+    rate_limit_enabled: bool = Field(default=True, description="Enable rate limiting")
+    rate_limit_per_minute: int = Field(default=60, description="Requests per minute limit")
+
+    auth_enabled: bool = Field(default=True, description="Enable authentication")
+
+    # Timeout configuration
+    interaction_timeout: float = Field(default=55.0, description="Timeout for agent interactions in seconds")
+
+    # Proxy configuration
+    proxy_path: str = Field(
+        default="", description="Base path when running behind reverse proxy (e.g., /api/sage-2wnuc8)"
+    )
+    agent_id: str = Field(default="", description="Agent ID when running in managed mode")
+
+    def get_home_channel_id(self, host: str, port: int) -> str:
+        """Get the home channel ID for this API adapter instance."""
+        return f"api_{host}_{port}"
+
+    def load_env_vars(self) -> None:
+        """Load configuration from environment variables if present."""
+        from ciris_engine.logic.config.env_utils import get_env_var
+
+        env_host = get_env_var("CIRIS_API_HOST")
+        if env_host:
+            self.host = env_host
+
+        env_port = get_env_var("CIRIS_API_PORT")
+        if env_port:
+            try:
+                self.port = int(env_port)
+            except ValueError:
+                pass
+
+        env_cors = get_env_var("CIRIS_API_CORS_ENABLED")
+        if env_cors is not None:
+            self.cors_enabled = env_cors.lower() in ("true", "1", "yes", "on")
+
+        env_auth = get_env_var("CIRIS_API_AUTH_ENABLED")
+        if env_auth is not None:
+            self.auth_enabled = env_auth.lower() in ("true", "1", "yes", "on")
+
+        env_timeout = get_env_var("CIRIS_API_INTERACTION_TIMEOUT")
+        if env_timeout:
+            try:
+                self.interaction_timeout = float(env_timeout)
+            except ValueError:
+                pass
+
+        env_cors_origins = get_env_var("CIRIS_API_CORS_ORIGINS")
+        if env_cors_origins:
+            try:
+                import json
+
+                self.cors_origins = json.loads(env_cors_origins)
+            except (ValueError, json.JSONDecodeError):
+                pass
+
+        # Check for proxy/managed mode configuration
+        env_agent_id = get_env_var("CIRIS_AGENT_ID")
+        if env_agent_id:
+            self.agent_id = env_agent_id
+            # When agent ID is set, we're likely behind a proxy
+            # Set the proxy path to the standard format
+            self.proxy_path = f"/api/{env_agent_id}"
+
+        # Allow explicit override of proxy path
+        env_proxy_path = get_env_var("CIRIS_PROXY_PATH")
+        if env_proxy_path:
+            self.proxy_path = env_proxy_path

ciris_engine/logic/adapters/api/constants.py

@@ -0,0 +1,55 @@
+"""
+Constants for API adapter.
+
+This module defines constants used across the API adapter to avoid
+duplicate string literals and improve maintainability.
+"""
+
+# Error Messages
+ERROR_ADAPTER_MANAGER_NOT_AVAILABLE = "Adapter manager not available"
+ERROR_AUDIT_SERVICE_NOT_AVAILABLE = "Audit service not available"
+ERROR_CONFIG_SERVICE_NOT_AVAILABLE = "Config service not available"
+ERROR_RUNTIME_CONTROL_SERVICE_NOT_AVAILABLE = "Runtime control service not available"
+ERROR_TIME_SERVICE_NOT_AVAILABLE = "Time service not available"
+ERROR_RESOURCE_MONITOR_NOT_AVAILABLE = "Resource monitor service not available"
+ERROR_MEMORY_SERVICE_NOT_AVAILABLE = "Memory service not available"
+ERROR_SHUTDOWN_SERVICE_NOT_AVAILABLE = "Shutdown service not available"
+ERROR_TELEMETRY_SERVICE_NOT_AVAILABLE = "Telemetry service not available"
+ERROR_WISE_AUTHORITY_SERVICE_NOT_AVAILABLE = "Wise Authority service not available"
+
+# Field Descriptions
+DESC_RESULTS_OFFSET = "Results offset"
+DESC_CONFIGURATION_KEY = "Configuration key"
+DESC_AUDIT_ENTRY_ID = "Audit entry ID"
+DESC_ADAPTER_ID = "Adapter ID"
+DESC_ADAPTER_TYPE = "Adapter type"
+
+# Service Unavailable Messages
+# These are used when a service is not available in the app state
+SERVICE_UNAVAILABLE_TEMPLATE = "{} service not available"
+
+# Common Field Descriptions for Query Parameters
+DESC_LIMIT = "Maximum results"
+DESC_OFFSET = "Results offset"
+DESC_START_TIME = "Start of time range"
+DESC_END_TIME = "End of time range"
+DESC_SEARCH_TEXT = "Search text"
+DESC_HUMAN_READABLE_STATUS = "Human-readable status message"
+DESC_CURRENT_COGNITIVE_STATE = "Current cognitive state"
+
+# Common Field Descriptions for Path Parameters
+DESC_ID_PARAM = "{} ID"
+DESC_KEY_PARAM = "{} key"
+DESC_NAME_PARAM = "{} name"
+
+# Response Messages
+MSG_NOT_FOUND = "{} '{}' not found"
+MSG_DELETED = "{} '{}' deleted successfully"
+MSG_UPDATED = "{} '{}' updated successfully"
+MSG_CREATED = "{} '{}' created successfully"
+
+# Permission Messages
+MSG_INSUFFICIENT_PERMISSIONS = "Insufficient permissions. Requires {} role or higher."
+MSG_SENSITIVE_CONFIG_PERMISSION = "Cannot {} sensitive config '{}' without {} role"
+MSG_SYSTEM_CONFIG_PERMISSION = "Cannot modify system config '{}' without SYSTEM_ADMIN role"
+MSG_WITHOUT_SYSTEM_ADMIN_ROLE = " without SYSTEM_ADMIN role"

ciris_engine/logic/adapters/api/dependencies/__init__.py

@@ -0,0 +1 @@
+"""API dependencies module."""