ciris-agent 1.7.7__py3-none-any.whl

ciris_engine/protocols/processors/agent.py

@@ -0,0 +1,299 @@
+"""
+Agent Processor Protocol - Main coordinator for all processing states.
+
+This protocol defines the interface for the main agent processor that:
+- Manages state transitions between WAKEUP, WORK, PLAY, SOLITUDE, DREAM, SHUTDOWN
+- Provides runtime control (pause, resume, stop, single-step)
+- Coordinates all sub-processors
+- Respects RuntimeControl commands
+"""
+
+from abc import abstractmethod
+from datetime import datetime
+from typing import TYPE_CHECKING, Any, Dict, List, Optional, Protocol
+
+if TYPE_CHECKING:
+    from ciris_engine.schemas.processors.state import StateTransitionRecord
+else:
+    StateTransitionRecord = Any
+
+
+class ProcessingSchedule(Protocol):
+    """Schedule for state transitions."""
+
+    next_dream_time: Optional[datetime]
+    dream_interval_hours: float
+    work_play_ratio: float
+    solitude_triggers: List[str]
+
+
+class AgentProcessorMetrics(Protocol):
+    """Detailed processor metrics."""
+
+    thoughts_processed: int
+    tasks_completed: int
+    errors_encountered: int
+    current_round: int
+    state_transitions: Dict[str, int]
+    average_thought_time_ms: float
+    queue_depth: int
+    memory_usage_mb: float
+
+
+class QueueStatus(Protocol):
+    """Processing queue status."""
+
+    pending_thoughts: int
+    pending_tasks: int
+    active_thoughts: int
+    active_tasks: int
+    blocked_items: int
+    priority_distribution: Dict[str, int]
+
+
+class StepResult(Protocol):
+    """Result of a single-step processing operation."""
+
+    success: bool
+    item_processed: Optional[str]  # thought_id or task_id
+    processing_time_ms: float
+    next_state: Optional[str]  # AgentState
+    error: Optional[str]
+
+
+class AgentProcessorProtocol(Protocol):
+    """
+    Protocol for the main agent processor that coordinates all states.
+
+    This is the central coordinator that:
+    - Manages the state machine (WAKEUP → WORK → PLAY → etc.)
+    - Handles runtime control commands (pause, resume, stop)
+    - Coordinates all sub-processors
+    - Provides fine-grained control for debugging and safety
+
+    Note: AgentProcessor IS a service (implements ServiceProtocol separately).
+    This protocol defines the processor-specific behavior, not service behavior.
+    The implementation should be: class AgentProcessor(AgentProcessorProtocol, ServiceProtocol)
+    """
+
+    # ========================================================================
+    # STATE MANAGEMENT
+    # ========================================================================
+
+    @abstractmethod
+    async def enter_state(self, state: str) -> bool:  # state: AgentState
+        """
+        Transition to a specific state.
+
+        Args:
+            state: Target AgentState to transition to
+
+        Returns:
+            True if transition successful, False otherwise
+        """
+        ...
+
+    @abstractmethod
+    def get_current_state(self) -> str:  # -> AgentState
+        """
+        Get current processing state.
+
+        Returns:
+            Current AgentState
+        """
+        ...
+
+    @abstractmethod
+    def get_processing_schedule(self) -> ProcessingSchedule:
+        """
+        Get schedule for state transitions.
+
+        This includes:
+        - When to enter DREAM state for memory consolidation
+        - Work/Play balance ratios
+        - Solitude triggers
+
+        Returns:
+            Processing schedule configuration
+        """
+        ...
+
+    @abstractmethod
+    async def force_state_transition(self, target_state: str, reason: str) -> bool:
+        """
+        Force transition to a state, bypassing normal checks.
+
+        Args:
+            target_state: Target AgentState
+            reason: Reason for forced transition
+
+        Returns:
+            True if transition successful
+        """
+        ...
+
+    # ========================================================================
+    # RUNTIME CONTROL
+    # ========================================================================
+
+    @abstractmethod
+    async def pause_processing(self) -> bool:
+        """
+        Pause all processing.
+
+        Processing can be resumed with resume_processing().
+        Current thought/task will complete before pausing.
+
+        Returns:
+            True if successfully paused
+        """
+        ...
+
+    @abstractmethod
+    async def resume_processing(self) -> bool:
+        """
+        Resume paused processing.
+
+        Returns:
+            True if successfully resumed
+        """
+        ...
+
+    @abstractmethod
+    async def single_step(self) -> StepResult:
+        """
+        Process one item and pause.
+
+        Useful for debugging and step-through analysis.
+
+        Returns:
+            Result of processing the single item
+        """
+        ...
+
+    @abstractmethod
+    async def stop_processing(self, _: bool = True) -> None:
+        """
+        Stop processing.
+
+        Args:
+            graceful: If True, complete current item and cleanup.
+                     If False, stop immediately.
+        """
+        ...
+
+    @abstractmethod
+    async def emergency_stop(self) -> None:
+        """
+        Emergency stop - immediate halt with no cleanup.
+
+        Use only in critical situations. May leave system in
+        inconsistent state requiring manual cleanup.
+        """
+        ...
+
+    # ========================================================================
+    # STATUS AND MONITORING
+    # ========================================================================
+
+    @abstractmethod
+    def get_processor_metrics(self) -> AgentProcessorMetrics:
+        """
+        Get detailed processor metrics.
+
+        Returns:
+            Comprehensive metrics about processing
+        """
+        ...
+
+    @abstractmethod
+    def get_queue_status(self) -> QueueStatus:
+        """
+        Get processing queue status.
+
+        Returns:
+            Current queue depths and distribution
+        """
+        ...
+
+    @abstractmethod
+    def is_paused(self) -> bool:
+        """
+        Check if processing is paused.
+
+        Returns:
+            True if paused
+        """
+        ...
+
+    @abstractmethod
+    def is_single_stepping(self) -> bool:
+        """
+        Check if in single-step mode.
+
+        Returns:
+            True if single-stepping
+        """
+        ...
+
+    @abstractmethod
+    def is_processing(self) -> bool:
+        """
+        Check if actively processing.
+
+        Returns:
+            True if processing loop is active
+        """
+        ...
+
+    # ========================================================================
+    # ADVANCED CONTROL
+    # ========================================================================
+
+    @abstractmethod
+    async def set_processing_speed(self, _: float) -> None:
+        """
+        Set processing speed multiplier.
+
+        Args:
+            multiplier: 1.0 = normal, 0.5 = half speed, 2.0 = double speed
+        """
+        ...
+
+    @abstractmethod
+    async def skip_current_item(self, reason: str) -> bool:
+        """
+        Skip the currently processing item.
+
+        Args:
+            reason: Why the item is being skipped
+
+        Returns:
+            True if successfully skipped
+        """
+        ...
+
+    @abstractmethod
+    async def replay_last_item(self) -> StepResult:
+        """
+        Replay the last processed item.
+
+        Useful for debugging processing issues.
+
+        Returns:
+            Result of reprocessing
+        """
+        ...
+
+    @abstractmethod
+    def get_state_history(self, limit: int = 10) -> List[StateTransitionRecord]:
+        """
+        Get recent state transition history.
+
+        Args:
+            limit: Maximum number of transitions to return
+
+        Returns:
+            List of state transitions with timestamps and reasons
+        """
+        ...

ciris_engine/protocols/processors/base.py

@@ -0,0 +1,130 @@
+"""
+Base Processor Protocol - Interface for all state processors.
+
+This protocol defines the interface that all state processors
+(WorkProcessor, PlayProcessor, DreamProcessor, etc.) must implement.
+"""
+
+from abc import abstractmethod
+from typing import TYPE_CHECKING, List, Optional, Protocol
+
+if TYPE_CHECKING:
+    from ciris_engine.schemas.processors.base import ProcessorMetrics
+    from ciris_engine.schemas.processors.error import ErrorContext, ErrorHandlingResult, ProcessorConfig
+    from ciris_engine.schemas.processors.results import ProcessingResult
+
+
+class ProcessorProtocol(Protocol):
+    """
+    Protocol for individual state processors.
+
+    Each processor handles a specific AgentState and must implement
+    these methods for the AgentProcessor to coordinate them.
+
+    Note: Processors are NOT services - they don't implement ServiceProtocol.
+    They are components managed by the AgentProcessor.
+    """
+
+    @abstractmethod
+    def get_supported_states(self) -> List[str]:  # List[AgentState]
+        """
+        Get the states this processor handles.
+
+        Most processors handle one state, but some may handle multiple.
+
+        Returns:
+            List of AgentState values this processor supports
+        """
+        ...
+
+    @abstractmethod
+    async def process(self, round_number: int) -> "ProcessingResult":
+        """
+        Main processing method for the state.
+
+        Args:
+            round_number: Current processing round
+
+        Returns:
+            ProcessingResult - A state-specific result (WakeupResult, WorkResult, etc.)
+        """
+        ...
+
+    @abstractmethod
+    async def can_process(self) -> bool:
+        """
+        Check if processor can currently process items.
+
+        This checks preconditions like:
+        - Required services available
+        - No blocking errors
+        - State-specific requirements met
+
+        Returns:
+            True if ready to process
+        """
+        ...
+
+    @abstractmethod
+    async def initialize(self) -> None:
+        """
+        Initialize processor for its state.
+
+        Called when entering the processor's state.
+        Used for setup like loading state-specific data.
+        """
+        ...
+
+    @abstractmethod
+    async def cleanup(self) -> None:
+        """
+        Cleanup when leaving the processor's state.
+
+        Called before transitioning to another state.
+        Used for saving state, releasing resources, etc.
+        """
+        ...
+
+    @abstractmethod
+    def get_metrics(self) -> "ProcessorMetrics":
+        """
+        Get processor-specific metrics.
+
+        Returns:
+            ProcessorMetrics with state-specific metrics
+        """
+        ...
+
+    @abstractmethod
+    def should_transition(self) -> Optional[str]:  # Optional[AgentState]
+        """
+        Check if processor thinks it's time to transition states.
+
+        Returns:
+            Target state if transition recommended, None otherwise
+        """
+        ...
+
+    @abstractmethod
+    async def handle_error(self, error: Exception, context: "ErrorContext") -> "ErrorHandlingResult":
+        """
+        Handle processing errors.
+
+        Args:
+            error: The exception that occurred
+            context: Context about what was being processed
+
+        Returns:
+            ErrorHandlingResult indicating how the error was handled
+        """
+        ...
+
+    @abstractmethod
+    def get_processor_config(self) -> "ProcessorConfig":
+        """
+        Get processor configuration.
+
+        Returns:
+            ProcessorConfig with processor-specific settings
+        """
+        ...

ciris_engine/protocols/processors/orchestration.py

@@ -0,0 +1,62 @@
+"""Protocol definitions for thought processor dependencies."""
+
+from typing import Any, Optional, Protocol
+
+from ciris_engine.schemas.conscience.core import ConscienceCheckResult
+from ciris_engine.schemas.dma.results import ActionSelectionDMAResult
+from ciris_engine.schemas.processors.context import ProcessorContext
+from ciris_engine.schemas.processors.core import ConscienceApplicationResult, DMAResults
+from ciris_engine.schemas.runtime.models import Thought
+
+
+class DMAOrchestratorProtocol(Protocol):
+    """Protocol for DMA orchestration services."""
+
+    async def run_dmas(self, thought_item: Any, processing_context: ProcessorContext) -> DMAResults:
+        """Run all DMAs for a thought."""
+        ...
+
+    async def run_action_selection(
+        self,
+        thought_item: Any,
+        actual_thought: Thought,
+        processing_context: ProcessorContext,
+        dma_results: DMAResults,
+        profile_name: str,
+    ) -> ActionSelectionDMAResult:
+        """Run action selection DMA."""
+        ...
+
+
+class ContextBuilderProtocol(Protocol):
+    """Protocol for context building services."""
+
+    async def build_context(
+        self, thought_id: str, additional_context: Optional[dict[str, Any]] = None
+    ) -> ProcessorContext:
+        """Build processing context for a thought."""
+        ...
+
+
+class ConscienceEntry:
+    """Entry in conscience registry."""
+
+    name: str
+    conscience: "ConscienceProtocol"
+    circuit_breaker: Optional[Any]
+
+
+class ConscienceProtocol(Protocol):
+    """Protocol for individual conscience implementations."""
+
+    async def check(self, action_result: ActionSelectionDMAResult, context: Any) -> ConscienceCheckResult:
+        """Check an action against conscience rules."""
+        ...
+
+
+class ConscienceRegistryProtocol(Protocol):
+    """Protocol for conscience registry."""
+
+    def get_consciences(self) -> list[ConscienceEntry]:
+        """Get all registered consciences."""
+        ...

ciris_engine/protocols/registries/__init__.py

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

ciris_engine/protocols/runtime/__init__.py

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

ciris_engine/protocols/runtime/base.py

@@ -0,0 +1,163 @@
+"""
+Base protocols that all CIRIS components inherit from.
+
+These form the foundation of the Protocol-Module-Schema architecture.
+Every component in CIRIS must implement one of these base protocols.
+"""
+
+from abc import abstractmethod
+from typing import TYPE_CHECKING, Any, Dict, List, Protocol
+
+if TYPE_CHECKING:
+    from ciris_engine.schemas.dma.core import DMAContext, DMADecision
+    from ciris_engine.schemas.handlers.schemas import HandlerContext, HandlerResult
+    from ciris_engine.schemas.runtime.adapter_management import AdapterConfig, RuntimeAdapterStatus
+    from ciris_engine.schemas.runtime.enums import ServiceType
+    from ciris_engine.schemas.runtime.models import Task, Thought
+    from ciris_engine.schemas.services.core import ServiceCapabilities, ServiceStatus
+    from ciris_engine.schemas.services.graph_core import GraphNode
+    from ciris_engine.schemas.services.operations import MemoryQuery
+    from ciris_engine.schemas.services.visibility import VisibilitySnapshot
+
+
+class ServiceProtocol(Protocol):
+    """Root protocol for ALL services in CIRIS."""
+
+    @abstractmethod
+    async def start(self) -> None:
+        """Start the service."""
+        ...
+
+    @abstractmethod
+    async def stop(self) -> None:
+        """Stop the service."""
+        ...
+
+    @abstractmethod
+    def get_capabilities(self) -> "ServiceCapabilities":
+        """Get service capabilities."""
+        ...
+
+    @abstractmethod
+    def get_status(self) -> "ServiceStatus":
+        """Get current service status."""
+        ...
+
+    @abstractmethod
+    async def is_healthy(self) -> bool:
+        """Check if service is healthy.
+
+        Used by buses and registries for quick health checks.
+
+        Returns:
+            True if service is healthy and available
+        """
+        ...
+
+    @abstractmethod
+    def get_service_type(self) -> "ServiceType":
+        """Get the type of this service.
+
+        Returns:
+            ServiceType enum indicating the service category
+        """
+        ...
+
+
+class GraphServiceProtocol(ServiceProtocol, Protocol):
+    """Base for services that store everything in the graph."""
+
+    @abstractmethod
+    async def store_in_graph(self, node: "GraphNode") -> str:
+        """Store a node in the graph."""
+        ...
+
+    @abstractmethod
+    async def query_graph(self, query: "MemoryQuery") -> List["GraphNode"]:
+        """Query the graph."""
+        ...
+
+    @abstractmethod
+    def get_node_type(self) -> str:
+        """Get the type of nodes this service manages."""
+        ...
+
+
+class CoreServiceProtocol(ServiceProtocol, Protocol):
+    """Base for services that cannot be stored in the graph."""
+
+    @abstractmethod
+    def get_resource_limits(self) -> Dict[str, int]:
+        """Get resource limits for this service."""
+        ...
+
+
+class VisibilityServiceProtocol(ServiceProtocol, Protocol):
+    """Base for services that provide transparency and compliance."""
+
+    @abstractmethod
+    async def get_visibility_data(self) -> "VisibilitySnapshot":  # Service-specific visibility data
+        """Get visibility/transparency data."""
+        ...
+
+
+class BaseHandlerProtocol(Protocol):
+    """Root protocol for all action handlers."""
+
+    @abstractmethod
+    async def handle(self, task: "Task", thought: "Thought", context: "HandlerContext") -> "HandlerResult":
+        """Handle an action."""
+        ...
+
+    @abstractmethod
+    def get_action_type(self) -> str:
+        """Get the action type this handler processes."""
+        ...
+
+
+class BaseAdapterProtocol(Protocol):
+    """Root protocol for all platform adapters."""
+
+    @abstractmethod
+    async def start(self) -> None:
+        """Start the adapter."""
+        ...
+
+    @abstractmethod
+    async def stop(self) -> None:
+        """Stop the adapter."""
+        ...
+
+    @abstractmethod
+    def get_config(self) -> "AdapterConfig":
+        """Get adapter configuration."""
+        ...
+
+    @abstractmethod
+    def get_status(self) -> "RuntimeAdapterStatus":
+        """Get adapter status."""
+        ...
+
+    @abstractmethod
+    def get_services_to_register(self) -> List[Any]:
+        """Get list of services this adapter provides."""
+        ...
+
+    @abstractmethod
+    async def run_lifecycle(self, agent_task: Any) -> None:
+        """Run the adapter lifecycle."""
+        ...
+
+
+class BaseDMAProtocol(Protocol):
+    """Root protocol for Decision Making Algorithms."""
+
+    @abstractmethod
+    async def evaluate(self, context: "DMAContext") -> "DMADecision":
+        """Evaluate a decision context."""
+        ...
+
+    @abstractmethod
+    def get_algorithm_type(self) -> str:
+        """Get the type of decision making algorithm."""
+        ...

ciris_engine/protocols/secrets/__init__.py

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