ciris-agent 1.7.7__py3-none-any.whl

ciris_adapters/mock_llm/README.md

@@ -0,0 +1,117 @@
+# MockLLM Modular Service
+
+The first modular service in CIRIS - demonstrates how to package services for external contribution.
+
+## Overview
+
+MockLLMService simulates LLM responses for testing without requiring API keys or network access.
+
+**⚠️ WARNING: TEST ONLY - NOT FOR PRODUCTION USE**
+
+## Structure
+
+```
+mock_llm/
+├── manifest.json       # Service metadata and registration info
+├── adapter.py          # BaseAdapterProtocol wrapper for dynamic loading
+├── configurable.py     # ConfigurableAdapterProtocol implementation
+├── protocol.py         # Protocol definition (extends LLMService)
+├── schemas.py          # Pydantic schemas for config/status
+├── service.py          # Main service implementation
+├── responses.py        # Base response templates
+├── responses_*.py      # Specialized response modules
+├── __init__.py         # Package initialization
+└── README.md          # This file
+```
+
+## Manifest Format
+
+The `manifest.json` file declares:
+- Service metadata (name, version, type)
+- Capabilities provided
+- Dependencies on core CIRIS protocols/schemas
+- Configuration options
+- Export paths for dynamic loading
+
+## Integration
+
+When CIRIS starts with `--mock-llm` flag:
+1. Service loader reads manifest.json
+2. Validates dependencies are available
+3. Dynamically imports service class
+4. Registers with ServiceRegistry
+5. Service is available through standard bus
+
+## Wizard Configuration
+
+The mock_llm adapter now supports interactive configuration via the ConfigurableAdapterProtocol:
+
+### Configuration Options (all optional)
+
+1. **Response Delay** - Simulate API latency
+   - Range: 0-60000 milliseconds
+   - Default: 100ms
+   - Environment variable: `MOCK_LLM_DELAY_MS`
+
+2. **Response Mode** - Control mock behavior
+   - Options: deterministic, random, echo
+   - Default: deterministic
+   - Environment variable: `MOCK_LLM_RESPONSE_MODE`
+
+3. **Failure Rate** - Simulate errors for testing
+   - Range: 0.0-1.0 (probability)
+   - Default: 0.0
+   - Environment variable: `MOCK_LLM_FAILURE_RATE`
+
+### Using the Configuration Wizard
+
+Via Android app or API:
+```bash
+# Start configuration session
+POST /adapters/mock_llm/configure/start
+
+# Configure each step
+POST /adapters/configure/{session_id}/step
+{
+  "step_id": "configure_delay",
+  "data": {"delay_ms": 500}
+}
+
+# Complete configuration
+POST /adapters/configure/{session_id}/complete
+```
+
+Or programmatically:
+```python
+from ciris_adapters.mock_llm import MockLLMConfigurableAdapter
+
+# Create and configure
+config_adapter = MockLLMConfigurableAdapter()
+await config_adapter.apply_config({
+    "delay_ms": 500,
+    "response_mode": "random",
+    "failure_rate": 0.1
+})
+
+# Load the adapter
+from ciris_adapters.mock_llm import MockLLMAdapter
+adapter = MockLLMAdapter(runtime, context)
+await adapter.start()
+```
+
+## Creating Your Own Modular Service
+
+1. Copy this structure as a template
+2. Update manifest.json with your service details
+3. Implement required protocols
+4. Define schemas for your data structures
+5. Place in ciris_adapters/ directory
+6. CIRIS will auto-discover on startup
+
+## Testing
+
+```python
+# Your service is automatically available when loaded
+llm_service = service_registry.get_service(ServiceType.LLM)
+response = await llm_service.generate_structured_response(request)
+```

ciris_adapters/mock_llm/__init__.py

@@ -0,0 +1,21 @@
+"""
+MockLLM modular service.
+
+This is the first modular service in CIRIS, demonstrating:
+- Self-contained service packaging
+- MOCK safety enforcement
+- Module-based architecture
+- Wizard-configurable adapter support
+"""
+
+from .adapter import Adapter, MockLLMAdapter
+from .configurable import MockLLMConfigurableAdapter
+from .service import MockLLMClient, MockLLMService
+
+__all__ = [
+    "MockLLMService",
+    "MockLLMClient",
+    "MockLLMAdapter",
+    "MockLLMConfigurableAdapter",
+    "Adapter",
+]

ciris_adapters/mock_llm/adapter.py

@@ -0,0 +1,131 @@
+"""
+Mock LLM Adapter for CIRIS.
+
+Provides the BaseAdapterProtocol-compliant wrapper around MockLLMService
+so it can be loaded dynamically via RuntimeAdapterManager.load_adapter().
+"""
+
+import asyncio
+import logging
+from typing import Any, List, Optional
+
+from ciris_engine.logic.adapters.base import Service
+from ciris_engine.logic.registries.base import Priority
+from ciris_engine.schemas.adapters import AdapterServiceRegistration
+from ciris_engine.schemas.runtime.adapter_management import AdapterConfig, RuntimeAdapterStatus
+from ciris_engine.schemas.runtime.enums import ServiceType
+
+from .service import MockLLMService
+
+logger = logging.getLogger(__name__)
+
+
+class MockLLMAdapter(Service):
+    """
+    Mock LLM adapter platform for CIRIS.
+
+    Wraps MockLLMService to provide the BaseAdapterProtocol interface
+    required for dynamic adapter loading via RuntimeAdapterManager.
+
+    This is a testing/development adapter that simulates LLM responses
+    without requiring external API calls.
+    """
+
+    def __init__(self, runtime: Any, context: Optional[Any] = None, **kwargs: Any) -> None:
+        """Initialize Mock LLM adapter."""
+        super().__init__(config=kwargs.get("adapter_config"))
+        self.runtime = runtime
+        self.context = context
+
+        # Create the underlying mock LLM service
+        # It reads config from environment variables set by MockLLMConfigurableAdapter.apply_config()
+        self.llm_service = MockLLMService()
+
+        # Track adapter state
+        self._running = False
+        self._lifecycle_task: Optional[asyncio.Task[None]] = None
+
+        logger.info("Mock LLM adapter initialized")
+
+    def get_services_to_register(self) -> List[AdapterServiceRegistration]:
+        """Get services provided by this adapter."""
+        registrations = []
+
+        # Register the Mock LLM service as an LLM service with its capabilities
+        registrations.append(
+            AdapterServiceRegistration(
+                service_type=ServiceType.LLM,
+                provider=self.llm_service,
+                priority=Priority.CRITICAL,
+                capabilities=[
+                    "call_llm_structured",
+                    "provider:mock",
+                ],
+            )
+        )
+
+        return registrations
+
+    async def start(self) -> None:
+        """Start the Mock LLM adapter."""
+        logger.info("Starting Mock LLM adapter")
+        await self.llm_service.start()
+        self._running = True
+        logger.info("Mock LLM adapter started")
+
+    async def stop(self) -> None:
+        """Stop the Mock LLM adapter."""
+        logger.info("Stopping Mock LLM adapter")
+        self._running = False
+
+        if self._lifecycle_task and not self._lifecycle_task.done():
+            self._lifecycle_task.cancel()
+            try:
+                await self._lifecycle_task
+            except asyncio.CancelledError:
+                pass
+
+        # Stop the LLM service
+        await self.llm_service.stop()
+
+        logger.info("Mock LLM adapter stopped")
+
+    async def run_lifecycle(self, agent_task: Any) -> None:
+        """Run the adapter lifecycle.
+
+        For Mock LLM, we just wait for the agent task to complete
+        since the mock service doesn't need continuous polling.
+        """
+        logger.info("Mock LLM adapter lifecycle started")
+        try:
+            # Wait for the agent task to signal shutdown
+            await agent_task
+        except asyncio.CancelledError:
+            logger.info("Mock LLM adapter lifecycle cancelled")
+        finally:
+            await self.stop()
+
+    def get_config(self) -> AdapterConfig:
+        """Get adapter configuration."""
+        return AdapterConfig(
+            adapter_type="mock_llm",
+            enabled=self._running,
+            settings={
+                "model": "mock-model",
+                "provider": "mock",
+            },
+        )
+
+    def get_status(self) -> RuntimeAdapterStatus:
+        """Get adapter status."""
+        return RuntimeAdapterStatus(
+            adapter_id="mock_llm",
+            adapter_type="mock_llm",
+            is_running=self._running,
+            loaded_at=None,
+            error=None,
+        )
+
+
+# Export as Adapter for load_adapter() compatibility
+Adapter = MockLLMAdapter

ciris_adapters/mock_llm/configurable.py

@@ -0,0 +1,237 @@
+"""
+Mock LLM ConfigurableAdapterProtocol implementation.
+
+Provides minimal interactive configuration workflow for Mock LLM adapter.
+This is a testing adapter, so configuration is optional and simple.
+
+Configuration options:
+1. Response delay - Simulate API latency (optional)
+2. Response mode - Deterministic, random, or echo (optional)
+3. Failure simulation - Enable random failures for testing (optional)
+"""
+
+import logging
+import os
+from typing import Any, Dict, List, Optional, Tuple
+
+logger = logging.getLogger(__name__)
+
+
+class MockLLMConfigurableAdapter:
+    """Mock LLM configurable adapter with minimal configuration.
+
+    Implements ConfigurableAdapterProtocol for Mock LLM with a simple
+    configuration workflow. Since this is a testing adapter, all options
+    are optional and have sensible defaults.
+
+    Configuration workflow:
+        1. Configure response delay (optional)
+        2. Select response mode (optional)
+        3. Configure failure simulation (optional)
+        4. Confirm configuration
+    """
+
+    # Available response modes
+    RESPONSE_MODES = {
+        "deterministic": {
+            "label": "Deterministic",
+            "description": "Consistent responses based on input patterns",
+            "default": True,
+        },
+        "random": {
+            "label": "Random",
+            "description": "Randomized responses for variety testing",
+            "default": False,
+        },
+        "echo": {
+            "label": "Echo",
+            "description": "Echo user input back (minimal processing)",
+            "default": False,
+        },
+    }
+
+    def __init__(self, config: Optional[Dict[str, Any]] = None) -> None:
+        """Initialize the Mock LLM configurable adapter.
+
+        Args:
+            config: Optional existing configuration
+        """
+        self.config = config or {}
+        self._applied_config: Optional[Dict[str, Any]] = None
+
+        logger.info("MockLLMConfigurableAdapter initialized")
+
+    async def discover(self, discovery_type: str) -> List[Dict[str, Any]]:
+        """Mock LLM doesn't require discovery.
+
+        Args:
+            discovery_type: Type of discovery to perform (unused)
+
+        Returns:
+            Empty list (no discovery needed)
+        """
+        logger.info("Mock LLM discovery called (no-op)")
+        return []
+
+    async def get_oauth_url(
+        self,
+        base_url: str,
+        state: str,
+        code_challenge: Optional[str] = None,
+        callback_base_url: Optional[str] = None,
+        redirect_uri: Optional[str] = None,
+        platform: Optional[str] = None,
+    ) -> str:
+        """Mock LLM doesn't use OAuth.
+
+        Args:
+            base_url: Base URL (unused)
+            state: State parameter (unused)
+            code_challenge: PKCE code challenge (unused)
+            callback_base_url: Callback base URL (unused)
+            redirect_uri: Redirect URI (unused)
+            platform: Platform hint (unused)
+
+        Returns:
+            Empty string (OAuth not supported)
+        """
+        logger.info("Mock LLM OAuth URL requested (not supported)")
+        return ""
+
+    async def handle_oauth_callback(
+        self,
+        code: str,
+        state: str,
+        base_url: str,
+        code_verifier: Optional[str] = None,
+        callback_base_url: Optional[str] = None,
+        redirect_uri: Optional[str] = None,
+        platform: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Mock LLM doesn't use OAuth.
+
+        Args:
+            code: Authorization code (unused)
+            state: State parameter (unused)
+            base_url: Base URL (unused)
+            code_verifier: PKCE verifier (unused)
+            callback_base_url: Callback base URL (unused)
+            redirect_uri: Redirect URI (unused)
+            platform: Platform hint (unused)
+
+        Returns:
+            Empty dict (OAuth not supported)
+        """
+        logger.info("Mock LLM OAuth callback called (not supported)")
+        return {}
+
+    async def get_config_options(self, step_id: str, context: Dict[str, Any]) -> List[Dict[str, Any]]:
+        """Get options for a selection step.
+
+        Args:
+            step_id: ID of the configuration step
+            context: Current configuration context
+
+        Returns:
+            List of available options
+        """
+        logger.info(f"Getting config options for step: {step_id}")
+
+        if step_id == "select_mode":
+            # Return available response modes
+            return [
+                {
+                    "id": mode_id,
+                    "label": mode["label"],
+                    "description": mode["description"],
+                    "metadata": {"default": mode["default"]},
+                }
+                for mode_id, mode in self.RESPONSE_MODES.items()
+            ]
+
+        return []
+
+    async def validate_config(self, config: Dict[str, Any]) -> Tuple[bool, Optional[str]]:
+        """Validate Mock LLM configuration.
+
+        Performs basic validation:
+        - Response delay must be non-negative
+        - Failure rate must be between 0.0 and 1.0
+        - Response mode must be valid
+
+        Args:
+            config: Complete configuration to validate
+
+        Returns:
+            (is_valid, error_message) tuple
+        """
+        logger.info("Validating Mock LLM configuration")
+
+        if not config:
+            # Empty config is valid - use defaults
+            return True, None
+
+        # Validate response delay if present
+        delay_ms = config.get("delay_ms")
+        if delay_ms is not None:
+            if not isinstance(delay_ms, (int, float)):
+                return False, "delay_ms must be a number"
+            if delay_ms < 0:
+                return False, "delay_ms must be non-negative"
+            if delay_ms > 60000:
+                return False, "delay_ms must be <= 60000 (1 minute max)"
+
+        # Validate failure rate if present
+        failure_rate = config.get("failure_rate")
+        if failure_rate is not None:
+            if not isinstance(failure_rate, (int, float)):
+                return False, "failure_rate must be a number"
+            if failure_rate < 0.0 or failure_rate > 1.0:
+                return False, "failure_rate must be between 0.0 and 1.0"
+
+        # Validate response mode if present
+        mode = config.get("response_mode")
+        if mode is not None:
+            if mode not in self.RESPONSE_MODES:
+                valid_modes = ", ".join(self.RESPONSE_MODES.keys())
+                return False, f"Invalid response_mode: {mode}. Valid modes: {valid_modes}"
+
+        logger.info("Mock LLM configuration validated successfully")
+        return True, None
+
+    async def apply_config(self, config: Dict[str, Any]) -> bool:
+        """Apply the configuration.
+
+        Stores configuration and sets up environment for the service.
+
+        Args:
+            config: Validated configuration to apply
+
+        Returns:
+            True if applied successfully
+        """
+        logger.info("Applying Mock LLM configuration")
+
+        self._applied_config = config.copy()
+
+        # Set environment variables for the Mock LLM service
+        # These match the configuration schema in manifest.json
+        if "delay_ms" in config:
+            os.environ["MOCK_LLM_DELAY_MS"] = str(config["delay_ms"])
+        if "failure_rate" in config:
+            os.environ["MOCK_LLM_FAILURE_RATE"] = str(config["failure_rate"])
+        if "response_mode" in config:
+            os.environ["MOCK_LLM_RESPONSE_MODE"] = config["response_mode"]
+
+        # Log sanitized config
+        logger.info(f"Mock LLM configuration applied: {config}")
+
+        return True
+
+    def get_applied_config(self) -> Optional[Dict[str, Any]]:
+        """Get the currently applied configuration.
+
+        Returns:
+            Applied configuration or None if not configured
+        """
+        return self._applied_config

ciris_adapters/mock_llm/manifest.json

@@ -0,0 +1,106 @@
+{
+  "module": {
+    "name": "mockllm",
+    "version": "1.0.0",
+    "description": "Mock LLM service for testing - simulates AI responses",
+    "author": "CIRIS Team",
+    "MOCK": true
+  },
+  "services": [{
+    "type": "LLM",
+    "priority": "CRITICAL",
+    "class": "mock_llm.service.MockLLMService",
+    "capabilities": ["call_llm_structured"]
+  }],
+  "capabilities": [
+    "call_llm_structured"
+  ],
+  "dependencies": {
+    "protocols": [
+      "ciris_engine.protocols.services.LLMService"
+    ],
+    "schemas": [
+      "ciris_engine.schemas.services.llm_core",
+      "ciris_engine.schemas.runtime.models"
+    ]
+  },
+  "exports": {
+    "service_class": "mock_llm.service.MockLLMService",
+    "configurable": "mock_llm.configurable.MockLLMConfigurableAdapter",
+    "protocol": "mock_llm.protocol.MockLLMProtocol",
+    "schemas": "mock_llm.schemas"
+  },
+  "interactive_config": {
+    "required": false,
+    "workflow_type": "simple_config",
+    "steps": [
+      {
+        "step_id": "configure_delay",
+        "step_type": "input",
+        "title": "Configure Response Delay",
+        "description": "Set simulated API latency in milliseconds (0-60000)",
+        "field_name": "delay_ms",
+        "default": 100,
+        "optional": true,
+        "validation": {
+          "min": 0,
+          "max": 60000
+        }
+      },
+      {
+        "step_id": "select_mode",
+        "step_type": "select",
+        "title": "Select Response Mode",
+        "description": "Choose how the mock LLM generates responses",
+        "field_name": "response_mode",
+        "options_method": "get_config_options",
+        "default": "deterministic",
+        "optional": true
+      },
+      {
+        "step_id": "configure_failures",
+        "step_type": "input",
+        "title": "Configure Failure Rate",
+        "description": "Probability of simulated failures for testing (0.0-1.0)",
+        "field_name": "failure_rate",
+        "default": 0.0,
+        "optional": true,
+        "validation": {
+          "min": 0.0,
+          "max": 1.0
+        }
+      },
+      {
+        "step_id": "confirm",
+        "step_type": "confirm",
+        "title": "Confirm Configuration",
+        "description": "Review and apply your Mock LLM configuration"
+      }
+    ],
+    "completion_method": "apply_config"
+  },
+  "configuration": {
+    "delay_ms": {
+      "type": "integer",
+      "env": "MOCK_LLM_DELAY_MS",
+      "default": 100,
+      "description": "Simulated response delay in milliseconds"
+    },
+    "failure_rate": {
+      "type": "float",
+      "env": "MOCK_LLM_FAILURE_RATE",
+      "default": 0.0,
+      "description": "Probability of simulated failures (0.0-1.0)"
+    },
+    "response_mode": {
+      "type": "string",
+      "env": "MOCK_LLM_RESPONSE_MODE",
+      "default": "deterministic",
+      "description": "Response generation mode: deterministic, random, or echo"
+    }
+  },
+  "metadata": {
+    "warning": "MOCK LLM - NOT FOR PRODUCTION USE",
+    "provider": "mock"
+  }
+}

ciris_adapters/mock_llm/protocol.py

@@ -0,0 +1,37 @@
+"""
+Protocol definition for MockLLM service.
+
+This demonstrates how modular services define their own protocols
+while implementing core CIRIS protocols.
+"""
+
+from typing import Protocol, runtime_checkable
+
+# Import core protocol that we implement
+from ciris_engine.protocols.services import LLMService
+
+
+@runtime_checkable
+class MockLLMProtocol(LLMService, Protocol):
+    """
+    MockLLM-specific protocol extensions.
+
+    Inherits from core LLMService protocol and adds mock-specific capabilities.
+    """
+
+    # Mock-specific methods
+    def set_response_delay(self, delay_ms: int) -> None:  # noqa: ARG002
+        """Set simulated response delay."""
+        ...
+
+    def set_failure_rate(self, rate: float) -> None:
+        """Set probability of simulated failures (0.0-1.0)."""
+        ...
+
+    def get_response_count(self) -> int:
+        """Get number of responses generated."""
+        ...
+
+    def reset_mock_state(self) -> None:
+        """Reset all mock state and counters."""
+        ...