ciris-agent 1.7.7__py3-none-any.whl

ciris_engine/protocols/services/runtime/llm.py

@@ -0,0 +1,50 @@
+"""LLM Service Protocol."""
+
+from abc import abstractmethod
+from typing import List, Optional, Protocol, Tuple, Type, TypedDict
+
+from pydantic import BaseModel
+
+from ....schemas.runtime.resources import ResourceUsage
+from ...runtime.base import ServiceProtocol
+
+
+class MessageDict(TypedDict):
+    """Typed dict for LLM messages."""
+
+    role: str
+    content: str
+
+
+class LLMServiceProtocol(ServiceProtocol, Protocol):
+    """Protocol for LLM service.
+
+    This protocol defines the contract that all LLM services must implement.
+    The primary method is call_llm_structured which uses instructor for
+    structured output parsing.
+    """
+
+    @abstractmethod
+    async def call_llm_structured(
+        self,
+        messages: List[MessageDict],
+        response_model: Type[BaseModel],
+        max_tokens: int = 1024,
+        temperature: float = 0.0,
+        thought_id: Optional[str] = None,
+        task_id: Optional[str] = None,
+    ) -> Tuple[BaseModel, ResourceUsage]:
+        """Make a structured LLM call.
+
+        Args:
+            messages: List of message dicts with 'role' and 'content' keys
+            response_model: Pydantic model class for the expected response
+            max_tokens: Maximum tokens to generate
+            temperature: Sampling temperature (0.0 = deterministic)
+            thought_id: Optional thought ID for tracing (last 8 chars used)
+            task_id: Optional task ID for tracing (last 8 chars used)
+
+        Returns:
+            Tuple of (parsed response model instance, resource usage)
+        """
+        ...

ciris_engine/protocols/services/runtime/runtime_control.py

@@ -0,0 +1,193 @@
+"""Runtime Control Service Protocol - Unified control plane for CIRIS runtime operations."""
+
+from abc import abstractmethod
+from typing import TYPE_CHECKING, Dict, List, Optional, Protocol
+
+from ciris_engine.schemas.services.core.runtime import (
+    AdapterInfo,
+    AdapterOperationResponse,
+    ConfigBackup,
+    ConfigOperationResponse,
+    ConfigSnapshot,
+    ConfigValidationResponse,
+    ProcessorControlResponse,
+    ProcessorQueueStatus,
+    RuntimeEvent,
+    RuntimeStateSnapshot,
+    RuntimeStatusResponse,
+    ServiceHealthStatus,
+    ServiceSelectionExplanation,
+)
+from ciris_engine.schemas.services.shutdown import EmergencyShutdownStatus, WASignedCommand
+
+from ...runtime.base import ServiceProtocol
+
+if TYPE_CHECKING:
+    from ciris_engine.schemas.services.runtime_control import (
+        CircuitBreakerResetResponse,
+        CircuitBreakerStatus,
+        ServicePriorityUpdateResponse,
+    )
+
+
+class RuntimeControlServiceProtocol(ServiceProtocol, Protocol):
+    """
+    Protocol for runtime control service.
+
+    This service provides centralized control over the CIRIS runtime,
+    including processor management, adapter lifecycle, configuration,
+    and emergency operations. It's an adapter-provided service (not core).
+    """
+
+    # ========== Processor Control ==========
+
+    @abstractmethod
+    async def pause_processing(self) -> ProcessorControlResponse:
+        """Pause the processor."""
+        ...
+
+    @abstractmethod
+    async def resume_processing(self) -> ProcessorControlResponse:
+        """Resume the processor."""
+        ...
+
+    @abstractmethod
+    async def single_step(self) -> ProcessorControlResponse:
+        """Execute one processing step for debugging."""
+        ...
+
+    @abstractmethod
+    async def get_processor_queue_status(self) -> ProcessorQueueStatus:
+        """Get detailed processor queue metrics."""
+        ...
+
+    @abstractmethod
+    async def shutdown_runtime(self, reason: str) -> ProcessorControlResponse:
+        """Initiate graceful runtime shutdown."""
+        ...
+
+    # ========== Adapter Management ==========
+
+    @abstractmethod
+    async def load_adapter(
+        self,
+        adapter_type: str,
+        adapter_id: Optional[str] = None,
+        config: Optional[Dict[str, object]] = None,
+        auto_start: bool = True,
+    ) -> AdapterOperationResponse:
+        """Dynamically load a new adapter."""
+        ...
+
+    @abstractmethod
+    async def unload_adapter(self, adapter_id: str, force: bool = False) -> AdapterOperationResponse:
+        """Unload an adapter from runtime."""
+        ...
+
+    @abstractmethod
+    async def list_adapters(self) -> List[AdapterInfo]:
+        """List all loaded adapters."""
+        ...
+
+    @abstractmethod
+    async def get_adapter_info(self, adapter_id: str) -> Optional[AdapterInfo]:
+        """Get detailed information about a specific adapter."""
+        ...
+
+    # ========== Configuration Management ==========
+
+    @abstractmethod
+    async def get_config(self, path: Optional[str] = None, include_sensitive: bool = False) -> ConfigSnapshot:
+        """Get configuration values."""
+        ...
+
+    @abstractmethod
+    async def update_config(
+        self,
+        path: str,
+        value: object,
+        scope: str = "runtime",
+        validation_level: str = "full",
+        reason: Optional[str] = None,
+    ) -> ConfigOperationResponse:
+        """Update configuration value."""
+        ...
+
+    @abstractmethod
+    async def validate_config(
+        self, config_data: Dict[str, object], config_path: Optional[str] = None
+    ) -> ConfigValidationResponse:
+        """Validate configuration without applying."""
+        ...
+
+    @abstractmethod
+    async def backup_config(self, backup_name: Optional[str] = None) -> ConfigOperationResponse:
+        """Create configuration backup."""
+        ...
+
+    @abstractmethod
+    async def restore_config(self, backup_name: str) -> ConfigOperationResponse:
+        """Restore configuration from backup."""
+        ...
+
+    @abstractmethod
+    async def list_config_backups(self) -> List[ConfigBackup]:
+        """List available configuration backups."""
+        ...
+
+    # ========== Runtime Status ==========
+
+    @abstractmethod
+    async def get_runtime_status(self) -> RuntimeStatusResponse:
+        """Get current runtime status summary."""
+        ...
+
+    @abstractmethod
+    async def get_runtime_snapshot(self) -> RuntimeStateSnapshot:
+        """Get complete runtime state snapshot."""
+        ...
+
+    @abstractmethod
+    async def get_service_health_status(self) -> ServiceHealthStatus:
+        """Get comprehensive service health report."""
+        ...
+
+    @abstractmethod
+    def get_events_history(self, limit: int = 100) -> List[RuntimeEvent]:
+        """Get recent runtime events for audit/debugging."""
+        ...
+
+    # ========== Service Management ==========
+
+    @abstractmethod
+    async def update_service_priority(
+        self,
+        provider_name: str,
+        new_priority: str,
+        new_priority_group: Optional[int] = None,
+        new_strategy: Optional[str] = None,
+    ) -> "ServicePriorityUpdateResponse":
+        """Update service provider priority and selection strategy."""
+        ...
+
+    @abstractmethod
+    async def reset_circuit_breakers(self, service_type: Optional[str] = None) -> "CircuitBreakerResetResponse":
+        """Reset circuit breakers for services."""
+        ...
+
+    @abstractmethod
+    async def get_circuit_breaker_status(self, service_type: Optional[str] = None) -> Dict[str, "CircuitBreakerStatus"]:
+        """Get circuit breaker status for services."""
+        ...
+
+    @abstractmethod
+    async def get_service_selection_explanation(self) -> ServiceSelectionExplanation:
+        """Get explanation of service selection logic."""
+        ...
+
+    # ========== Emergency Operations ==========
+
+    @abstractmethod
+    async def handle_emergency_shutdown(self, command: WASignedCommand) -> EmergencyShutdownStatus:
+        """Process WA-authorized emergency shutdown."""
+        ...

ciris_engine/protocols/services/runtime/secrets.py

@@ -0,0 +1,100 @@
+"""Secrets Service Protocol."""
+
+from abc import abstractmethod
+from typing import Any, Dict, List, Optional, Protocol, Tuple
+
+from ciris_engine.schemas.secrets.core import SecretReference
+from ciris_engine.schemas.secrets.service import (
+    DecapsulationContext,
+    FilterUpdateRequest,
+    FilterUpdateResult,
+    SecretRecallResult,
+)
+from ciris_engine.schemas.services.core.secrets import SecretsServiceStats
+from ciris_engine.schemas.types import JSONDict
+
+# ActionParameters and FilterConfig don't exist as concrete types - use JSONDict
+ActionParameters = JSONDict
+FilterConfig = JSONDict
+
+from ...runtime.base import ServiceProtocol
+
+
+class SecretsServiceProtocol(ServiceProtocol, Protocol):
+    """Protocol for secrets service."""
+
+    @abstractmethod
+    async def encrypt(self, plaintext: str) -> str:
+        """Encrypt a secret."""
+        ...
+
+    @abstractmethod
+    async def decrypt(self, ciphertext: str) -> str:
+        """Decrypt a secret."""
+        ...
+
+    @abstractmethod
+    async def store_secret(self, key: str, value: str) -> None:
+        """Store an encrypted secret."""
+        ...
+
+    @abstractmethod
+    async def retrieve_secret(self, key: str) -> Optional[str]:
+        """Retrieve and decrypt a secret."""
+        ...
+
+    @abstractmethod
+    async def process_incoming_text(self, text: str, source_message_id: str) -> Tuple[str, List[SecretReference]]:
+        """Process incoming text to detect and store secrets."""
+        ...
+
+    @abstractmethod
+    async def decapsulate_secrets_in_parameters(
+        self, action_type: str, action_params: ActionParameters, context: DecapsulationContext
+    ) -> ActionParameters:
+        """Replace secret UUIDs with decrypted values in action parameters."""
+        ...
+
+    @abstractmethod
+    async def list_stored_secrets(self, limit: int = 10) -> List[SecretReference]:
+        """List all stored secrets (metadata only, no decryption)."""
+        ...
+
+    @abstractmethod
+    async def get_filter_config(self) -> FilterConfig:
+        """Get current filter configuration."""
+        ...
+
+    @abstractmethod
+    async def recall_secret(
+        self, secret_uuid: str, purpose: str, accessor: str = "agent", decrypt: bool = False
+    ) -> Optional["SecretRecallResult"]:
+        """Recall a stored secret for agent use."""
+        ...
+
+    @abstractmethod
+    async def forget_secret(self, secret_uuid: str, accessor: str = "agent") -> bool:
+        """Forget (delete) a stored secret."""
+        ...
+
+    @abstractmethod
+    async def update_filter_config(
+        self, updates: "FilterUpdateRequest", accessor: str = "agent"
+    ) -> "FilterUpdateResult":
+        """Update secrets filter configuration."""
+        ...
+
+    @abstractmethod
+    async def get_service_stats(self) -> "SecretsServiceStats":
+        """Get comprehensive service statistics."""
+        ...
+
+    @abstractmethod
+    async def is_healthy(self) -> bool:
+        """Check if the secrets service is healthy."""
+        ...
+
+    @abstractmethod
+    async def reencrypt_all(self, new_master_key: bytes) -> bool:
+        """Re-encrypt all stored secrets with a new master key."""
+        ...

ciris_engine/protocols/services/runtime/tool.py

@@ -0,0 +1,123 @@
+"""Tool Service Protocol."""
+
+from abc import abstractmethod
+from typing import Any, Dict, List, Optional, Protocol
+
+from ciris_engine.schemas.adapters.tools import ToolExecutionResult, ToolInfo, ToolParameterSchema
+from ciris_engine.schemas.types import JSONDict
+
+# ToolParameters is a JSONDict for flexible parameter passing
+ToolParameters = JSONDict
+
+from ...runtime.base import ServiceProtocol
+
+
+class ToolServiceProtocol(ServiceProtocol, Protocol):
+    """Protocol for tool execution service."""
+
+    @abstractmethod
+    async def execute_tool(self, tool_name: str, parameters: ToolParameters) -> ToolExecutionResult:
+        """Execute a tool with validated parameters.
+
+        Note: parameters is a plain dict that has been validated against the tool's schema.
+        The protocol accepts dict to allow flexibility in parameter types.
+        """
+        ...
+
+    @abstractmethod
+    async def list_tools(self) -> List[str]:
+        """List available tools."""
+        ...
+
+    @abstractmethod
+    async def get_tool_schema(self, tool_name: str) -> Optional[ToolParameterSchema]:
+        """Get parameter schema for a specific tool."""
+        ...
+
+    @abstractmethod
+    async def get_available_tools(self) -> List[str]:
+        """Get list of all available tools.
+
+        Returns:
+            List of tool names that are currently available for execution.
+        """
+        ...
+
+    @abstractmethod
+    async def get_tool_info(self, tool_name: str) -> Optional[ToolInfo]:
+        """Get detailed information about a specific tool.
+
+        Args:
+            tool_name: Name of the tool to get info for.
+
+        Returns:
+            ToolInfo object if tool exists, None otherwise.
+        """
+        ...
+
+    @abstractmethod
+    async def get_all_tool_info(self) -> List[ToolInfo]:
+        """Get detailed information about all available tools.
+
+        Returns:
+            List of ToolInfo objects for all available tools.
+        """
+        ...
+
+    @abstractmethod
+    async def validate_parameters(self, tool_name: str, parameters: ToolParameters) -> bool:
+        """Validate parameters for a specific tool without executing it.
+
+        Args:
+            tool_name: Name of the tool to validate parameters for.
+            parameters: Dictionary of parameters to validate.
+
+        Returns:
+            True if parameters are valid, False otherwise.
+        """
+        ...
+
+    @abstractmethod
+    async def get_tool_result(self, correlation_id: str, timeout: float = 30.0) -> Optional[ToolExecutionResult]:
+        """Get the result of a previously executed tool by correlation ID.
+
+        Args:
+            correlation_id: Unique identifier for the tool execution.
+            timeout: Maximum time to wait for result in seconds.
+
+        Returns:
+            ToolExecutionResult if found within timeout, None otherwise.
+        """
+        ...
+
+    def get_service_metadata(self) -> Dict[str, Any]:
+        """Get service metadata including data source information.
+
+        Returns:
+            Dict with metadata:
+            {
+                "data_source": bool,              # Whether tool accesses external data source
+                "data_source_type": str,          # Type: sql, rest, hl7, file, api, etc.
+                "contains_pii": bool,             # Whether source contains PII
+                "gdpr_applicable": bool,          # Whether GDPR applies
+                "connector_id": str,              # Unique connector identifier
+                "data_retention_days": int,       # Data retention period (optional)
+                "encryption_at_rest": bool,       # Whether data is encrypted (optional)
+                "geographic_location": str,       # Data location for compliance (optional)
+                "compliance_certifications": list # SOC2, HIPAA, etc. (optional)
+            }
+
+        Default implementation returns empty dict (not a data source).
+        Tool services that access external data should override this method.
+
+        Example:
+            def get_service_metadata(self) -> Dict[str, Any]:
+                return {
+                    "data_source": True,
+                    "data_source_type": "sql",
+                    "contains_pii": True,
+                    "gdpr_applicable": True,
+                    "connector_id": self._connector_id,
+                }
+        """
+        return {}  # Default: not a data source

ciris_engine/protocols/telemetry/__init__.py

@@ -0,0 +1 @@
+"""Package initialization."""

ciris_engine/protocols/utils/__init__.py

@@ -0,0 +1 @@
+"""Package initialization."""

ciris_engine/schemas/__init__.py

@@ -0,0 +1,112 @@
+"""
+Contract-driven architecture schemas.
+
+This module provides typed replacements for all Dict[str, Any] usage
+in the CIRIS codebase, ensuring type safety and validation throughout.
+"""
+
+# Re-export all schemas for convenience
+
+from .actions import DeferParams as DeferParameters
+from .actions import ForgetParams as ForgetParameters
+from .actions import MemorizeParams as MemorizeParameters
+from .actions import ObserveParams as ObserveParameters
+from .actions import PonderParams as PonderParameters
+from .actions import RecallParams as RecallParameters
+from .actions import RejectParams as RejectParameters
+from .actions import SpeakParams as SpeakParameters
+from .actions import TaskCompleteParams as TaskCompleteParameters
+from .actions import ToolParams as ToolParameters
+from .conscience.results import ConscienceResult
+from .handlers.contexts import (
+    BaseActionContext,
+    DeferContext,
+    ForgetContext,
+    MemorizeContext,
+    ObserveContext,
+    PonderContext,
+    RecallContext,
+    RejectContext,
+    SpeakContext,
+    TaskCompleteContext,
+    ToolContext,
+)
+from .handlers.schemas import ActionContext, ActionParameters, HandlerContext, HandlerResult
+from .platform import PlatformCapabilities, PlatformRequirement, PlatformRequirementSet
+from .processors.cognitive import DreamState, PlayState, ShutdownState, SolitudeState, WakeupState, WorkState
+from .services.metadata import ServiceMetadata
+from .services.requests import (
+    AuditRequest,
+    AuditResponse,
+    LLMRequest,
+    LLMResponse,
+    MemorizeRequest,
+    MemorizeResponse,
+    RecallRequest,
+    RecallResponse,
+    ServiceRequest,
+    ServiceResponse,
+    ToolExecutionRequest,
+    ToolExecutionResponse,
+)
+
+# Faculty assessments removed - merged into consciences
+
+
+__all__ = [
+    # Service schemas
+    "ServiceMetadata",
+    "ServiceRequest",
+    "ServiceResponse",
+    "MemorizeRequest",
+    "MemorizeResponse",
+    "RecallRequest",
+    "RecallResponse",
+    "ToolExecutionRequest",
+    "ToolExecutionResponse",
+    "LLMRequest",
+    "LLMResponse",
+    "AuditRequest",
+    "AuditResponse",
+    # Action contexts
+    "BaseActionContext",
+    "SpeakContext",
+    "ToolContext",
+    "ObserveContext",
+    "MemorizeContext",
+    "RecallContext",
+    "ForgetContext",
+    "RejectContext",
+    "PonderContext",
+    "DeferContext",
+    "TaskCompleteContext",
+    # Action parameters
+    "SpeakParameters",
+    "ToolParameters",
+    "ObserveParameters",
+    "MemorizeParameters",
+    "RecallParameters",
+    "ForgetParameters",
+    "RejectParameters",
+    "PonderParameters",
+    "DeferParameters",
+    "TaskCompleteParameters",
+    # Cognitive states
+    "WakeupState",
+    "WorkState",
+    "PlayState",
+    "SolitudeState",
+    "DreamState",
+    "ShutdownState",
+    # Handler schemas
+    "HandlerContext",
+    "HandlerResult",
+    "ActionContext",
+    "ActionParameters",
+    # conscience results
+    "ConscienceResult",
+    # Platform requirements
+    "PlatformRequirement",
+    "PlatformCapabilities",
+    "PlatformRequirementSet",
+]

ciris_engine/schemas/actions/__init__.py

@@ -0,0 +1,37 @@
+"""
+Action schemas - shared across handlers, DMAs, and services.
+
+These schemas define the parameters and results for all agent actions.
+"""
+
+# Import all action parameters
+from .parameters import (  # External actions; Control actions; Memory actions; Terminal action
+    DeferParams,
+    ForgetParams,
+    MemorizeParams,
+    ObserveParams,
+    PonderParams,
+    RecallParams,
+    RejectParams,
+    SpeakParams,
+    TaskCompleteParams,
+    ToolParams,
+)
+
+# Make them available at package level
+__all__ = [
+    # External
+    "ObserveParams",
+    "SpeakParams",
+    "ToolParams",
+    # Control
+    "PonderParams",
+    "RejectParams",
+    "DeferParams",
+    # Memory
+    "MemorizeParams",
+    "RecallParams",
+    "ForgetParams",
+    # Terminal
+    "TaskCompleteParams",
+]