ciris-agent 1.7.7__py3-none-any.whl

ciris_engine/protocols/services/__init__.py

@@ -0,0 +1,80 @@
+"""Service protocols package - organized by functional area."""
+
+# Re-export base protocols from runtime
+from ..runtime.base import CoreServiceProtocol, GraphServiceProtocol, ServiceProtocol
+from ..runtime.base import VisibilityServiceProtocol as BaseVisibilityServiceProtocol
+
+# Backward compatibility alias
+Service = ServiceProtocol
+
+# Adaptation service protocols - self-improvement
+from .adaptation import SelfObservationServiceProtocol
+
+# Governance service protocols - security and oversight
+from .governance import AdaptiveFilterServiceProtocol
+from .governance import CommunicationServiceProtocol as CommunicationService
+from .governance import VisibilityServiceProtocol
+from .governance import WiseAuthorityServiceProtocol as WiseAuthorityService
+
+# Graph service protocols - data persistence layer
+from .graph import AuditServiceProtocol as AuditService
+from .graph import GraphConfigServiceProtocol as ConfigService
+from .graph import MemoryServiceProtocol as MemoryService
+from .graph import TelemetryServiceProtocol as TelemetryService
+
+# Infrastructure service protocols
+from .infrastructure import AuthenticationServiceProtocol
+
+# Lifecycle service protocols - system state management
+from .lifecycle import (
+    InitializationServiceProtocol,
+    ShutdownServiceProtocol,
+    TaskSchedulerServiceProtocol,
+    TimeServiceProtocol,
+)
+
+# Runtime service protocols - core operations
+from .runtime import LLMServiceProtocol as LLMService
+from .runtime import RuntimeControlServiceProtocol as RuntimeControlService
+from .runtime import SecretsServiceProtocol as SecretsService
+from .runtime import ToolServiceProtocol as ToolService
+
+
+# Legacy protocol for compatibility
+class GraphMemoryServiceProtocol(ServiceProtocol):
+    """Legacy protocol for graph memory service operations."""
+
+
+__all__ = [
+    # Base protocols
+    "Service",
+    "ServiceProtocol",
+    "GraphServiceProtocol",
+    "CoreServiceProtocol",
+    "BaseVisibilityServiceProtocol",
+    # Graph services (5)
+    "MemoryService",
+    "AuditService",
+    "TelemetryService",
+    "ConfigService",
+    # Runtime services (4)
+    "LLMService",
+    "ToolService",
+    "SecretsService",
+    "RuntimeControlService",
+    # Lifecycle services (4)
+    "TimeServiceProtocol",
+    "ShutdownServiceProtocol",
+    "InitializationServiceProtocol",
+    "TaskSchedulerServiceProtocol",
+    # Governance services (5)
+    "AuthenticationServiceProtocol",
+    "WiseAuthorityService",
+    "VisibilityServiceProtocol",
+    "AdaptiveFilterServiceProtocol",
+    "CommunicationService",
+    # Adaptation services (1)
+    "SelfObservationServiceProtocol",
+    # Legacy
+    "GraphMemoryServiceProtocol",
+]

ciris_engine/protocols/services/adaptation/__init__.py

@@ -0,0 +1,7 @@
+"""Special service protocols."""
+
+from .self_observation import SelfObservationServiceProtocol
+
+__all__ = [
+    "SelfObservationServiceProtocol",
+]

ciris_engine/protocols/services/adaptation/self_observation.py

@@ -0,0 +1,265 @@
+"""
+Protocol for Self-Observation Service - Pattern detection and learning.
+
+This service observes system behavior, detects patterns, and stores insights
+for the agent's autonomous adaptation within its identity bounds.
+"""
+
+from abc import abstractmethod
+from datetime import timedelta
+from typing import TYPE_CHECKING, List, Optional, Protocol
+
+from ...runtime.base import ServiceProtocol
+
+# Import forward references for schemas
+if TYPE_CHECKING:
+    from ciris_engine.schemas.infrastructure.behavioral_patterns import ActionFrequency, TemporalPattern
+    from ciris_engine.schemas.infrastructure.feedback_loop import AnalysisResult, DetectedPattern, PatternType
+    from ciris_engine.schemas.runtime.core import AgentIdentityRoot
+    from ciris_engine.schemas.services.special.self_observation import (
+        AnalysisStatus,
+        LearningSummary,
+        ObservabilityAnalysis,
+        ObservationCycleResult,
+        ObservationEffectiveness,
+        ObservationStatus,
+        PatternEffectiveness,
+        PatternInsight,
+        PatternLibrarySummary,
+        ReviewOutcome,
+        ServiceImprovementReport,
+    )
+
+
+class SelfObservationServiceProtocol(ServiceProtocol, Protocol):
+    """
+    Protocol for self-observation service.
+
+    Implements continuous observation and pattern detection to enable
+    autonomous adaptation through stored insights.
+    """
+
+    # ========== Pattern Detection ==========
+
+    @abstractmethod
+    async def analyze_patterns(self, force: bool = False) -> "AnalysisResult":
+        """
+        Analyze recent system behavior and detect patterns.
+
+        This is the main entry point that:
+        1. Detects patterns from metrics and telemetry
+        2. Stores pattern insights for agent introspection
+        3. Updates learning state
+
+        Args:
+            force: Force analysis even if not due
+
+        Returns:
+            AnalysisResult with patterns detected and insights stored
+        """
+        ...
+
+    @abstractmethod
+    async def get_detected_patterns(
+        self, pattern_type: Optional["PatternType"] = None, hours: int = 24
+    ) -> List["DetectedPattern"]:
+        """
+        Get recently detected patterns.
+
+        Args:
+            pattern_type: Filter by pattern type (temporal, frequency, etc.)
+            hours: Look back period
+
+        Returns:
+            List of detected patterns
+        """
+        ...
+
+    @abstractmethod
+    async def get_action_frequency(self, hours: int = 24) -> dict[str, "ActionFrequency"]:
+        """
+        Get frequency analysis of agent actions.
+
+        Args:
+            hours: Analysis window
+
+        Returns:
+            Map of action -> frequency data
+        """
+        ...
+
+    # ========== Pattern Insights ==========
+
+    @abstractmethod
+    async def get_pattern_insights(self, limit: int = 50) -> List["PatternInsight"]:
+        """
+        Get stored pattern insights.
+
+        These are the insights stored in graph memory for the agent
+        to use during its reasoning process.
+
+        Args:
+            limit: Maximum insights to return
+
+        Returns:
+            List of PatternInsight objects from graph memory
+        """
+        ...
+
+    @abstractmethod
+    async def get_learning_summary(self) -> "LearningSummary":
+        """
+        Get summary of what the system has learned.
+
+        Returns:
+            LearningSummary object with patterns, frequencies, and adaptations
+        """
+        ...
+
+    # ========== Temporal Analysis ==========
+
+    @abstractmethod
+    async def get_temporal_patterns(self, hours: int = 168) -> List["TemporalPattern"]:  # 1 week
+        """
+        Get temporal patterns (daily, weekly cycles).
+
+        Args:
+            hours: Analysis window
+
+        Returns:
+            List of temporal patterns detected
+        """
+        ...
+
+    # ========== Effectiveness Tracking ==========
+
+    @abstractmethod
+    async def get_pattern_effectiveness(self, pattern_id: str) -> Optional["PatternEffectiveness"]:
+        """
+        Get effectiveness metrics for a specific pattern.
+
+        Tracks whether acting on this pattern improved outcomes.
+
+        Args:
+            pattern_id: ID of pattern to check
+
+        Returns:
+            PatternEffectiveness object if available
+        """
+        ...
+
+    # ========== Service Status ==========
+
+    @abstractmethod
+    async def get_analysis_status(self) -> "AnalysisStatus":
+        """
+        Get current analysis status.
+
+        Returns:
+            AnalysisStatus object including last analysis time, patterns detected, etc.
+        """
+        ...
+
+    # ========== Adaptation and Identity Management ==========
+
+    @abstractmethod
+    async def initialize_baseline(self, identity: "AgentIdentityRoot") -> str:
+        """
+        Establish identity baseline for variance monitoring.
+
+        Args:
+            identity: The agent's identity root
+
+        Returns:
+            Baseline ID
+        """
+        ...
+
+    @abstractmethod
+    async def get_adaptation_status(self) -> "ObservationStatus":
+        """
+        Get current status of the self-observation system.
+
+        Returns:
+            ObservationStatus with current state and metrics
+        """
+        ...
+
+    @abstractmethod
+    async def analyze_observability_window(self, window: timedelta = timedelta(hours=6)) -> "ObservabilityAnalysis":
+        """
+        Analyze all observability signals for adaptation opportunities.
+
+        Args:
+            window: Time window to analyze
+
+        Returns:
+            ObservabilityAnalysis with signals and opportunities
+        """
+        ...
+
+    @abstractmethod
+    async def trigger_adaptation_cycle(self) -> "ObservationCycleResult":
+        """
+        Manually trigger an adaptation assessment cycle.
+
+        Returns:
+            ObservationCycleResult with cycle outcomes
+        """
+        ...
+
+    @abstractmethod
+    async def get_pattern_library(self) -> "PatternLibrarySummary":
+        """
+        Get summary of learned adaptation patterns.
+
+        Returns:
+            PatternLibrarySummary with pattern statistics
+        """
+        ...
+
+    @abstractmethod
+    async def measure_adaptation_effectiveness(self, adaptation_id: str) -> "ObservationEffectiveness":
+        """
+        Measure if an adaptation actually improved the system.
+
+        Args:
+            adaptation_id: ID of the adaptation to measure
+
+        Returns:
+            ObservationEffectiveness metrics
+        """
+        ...
+
+    @abstractmethod
+    async def get_improvement_report(self, period: timedelta = timedelta(days=30)) -> "ServiceImprovementReport":
+        """
+        Generate service improvement report for period.
+
+        Args:
+            period: Time period to analyze
+
+        Returns:
+            ServiceImprovementReport with metrics and recommendations
+        """
+        ...
+
+    @abstractmethod
+    async def resume_after_review(self, review_outcome: "ReviewOutcome") -> None:
+        """
+        Resume self-configuration after WA review.
+
+        Args:
+            review_outcome: The outcome of the WA review
+        """
+        ...
+
+    @abstractmethod
+    async def emergency_stop(self, reason: str) -> None:
+        """
+        Activate emergency stop for self-configuration.
+
+        Args:
+            reason: Reason for emergency stop
+        """
+        ...

ciris_engine/protocols/services/governance/__init__.py

@@ -0,0 +1,20 @@
+"""Governance service protocols."""
+
+from .communication import CommunicationServiceProtocol
+from .filter import AdaptiveFilterServiceProtocol
+from .visibility import VisibilityServiceProtocol
+from .wa_auth import JWTService, OAuthService, WAAuthMiddleware, WACrypto, WAStore
+from .wise_authority import WiseAuthorityServiceProtocol
+
+__all__ = [
+    "WiseAuthorityServiceProtocol",
+    "VisibilityServiceProtocol",
+    "AdaptiveFilterServiceProtocol",
+    "CommunicationServiceProtocol",
+    # WA Auth protocols
+    "WAStore",
+    "JWTService",
+    "WACrypto",
+    "WAAuthMiddleware",
+    "OAuthService",
+]

ciris_engine/protocols/services/governance/communication.py

@@ -0,0 +1,58 @@
+"""Communication Service Protocol.
+
+IMPORTANT: This is NOT one of the 22 core services!
+
+This protocol defines the interface for adapter-provided communication services.
+It is used by the CommunicationBus to enable multiple communication providers:
+- CLIAdapter provides CLI-based communication
+- APICommunicationService provides API-based communication
+- DiscordAdapter provides Discord-based communication
+
+There is no core CommunicationService - all communication is handled by adapters
+that implement this protocol and register with the CommunicationBus.
+
+See CLAUDE.md section on "Message Bus Architecture" for more details.
+"""
+
+from abc import abstractmethod
+from datetime import datetime
+from typing import List, Optional, Protocol
+
+from ciris_engine.schemas.runtime.messages import FetchedMessage
+
+from ...runtime.base import ServiceProtocol
+
+
+class CommunicationServiceProtocol(ServiceProtocol, Protocol):
+    """Protocol for adapter-provided communication services.
+
+    This protocol must be implemented by any adapter that wants to provide
+    communication capabilities to the CIRIS system. Adapters register their
+    implementation with the CommunicationBus at runtime.
+    """
+
+    @abstractmethod
+    async def send_message(self, channel_id: str, content: str) -> bool:
+        """Send a message to the specified channel."""
+        ...
+
+    @abstractmethod
+    async def fetch_messages(
+        self,
+        channel_id: str,
+        *,
+        limit: int = 50,
+        before: Optional[datetime] = None,
+    ) -> List[FetchedMessage]:
+        """Retrieve messages from a channel."""
+        ...
+
+    @abstractmethod
+    def get_home_channel_id(self) -> Optional[str]:
+        """Get the home channel ID for this communication adapter.
+
+        Returns:
+            The formatted channel ID (e.g., 'discord_123456', 'cli_user@host', 'api_0.0.0.0_8080')
+            or None if no home channel is configured.
+        """
+        ...

ciris_engine/protocols/services/governance/filter.py

@@ -0,0 +1,56 @@
+"""Adaptive Filter Service Protocol."""
+
+from abc import abstractmethod
+from typing import Any, Protocol
+
+from ciris_engine.schemas.services.filters_core import FilterHealth, FilterResult, FilterTrigger
+
+from ...runtime.base import ServiceProtocol
+
+
+class AdaptiveFilterServiceProtocol(ServiceProtocol, Protocol):
+    """Protocol for adaptive filter service."""
+
+    @abstractmethod
+    async def filter_message(self, message: Any, adapter_type: str, is_llm_response: bool = False) -> FilterResult:
+        """Apply filters to determine message priority and processing.
+
+        Args:
+            message: The message object to filter
+            adapter_type: The adapter type (discord, cli, api)
+            is_llm_response: Whether this is an LLM-generated response
+
+        Returns:
+            FilterResult with priority, triggered filters, and processing decision
+        """
+        ...
+
+    @abstractmethod
+    async def get_health(self) -> FilterHealth:
+        """Get filter service health and statistics."""
+        ...
+
+    @abstractmethod
+    async def add_filter_trigger(self, trigger: FilterTrigger, trigger_list: str = "review") -> bool:
+        """Add a new filter trigger to the configuration.
+
+        Args:
+            trigger: The filter trigger to add
+            trigger_list: Which list to add to ("attention", "review", or "llm")
+
+        Returns:
+            True if trigger was added successfully
+        """
+        ...
+
+    @abstractmethod
+    async def remove_filter_trigger(self, trigger_id: str) -> bool:
+        """Remove a filter trigger from the configuration.
+
+        Args:
+            trigger_id: The ID of the trigger to remove
+
+        Returns:
+            True if trigger was removed successfully
+        """
+        ...

ciris_engine/protocols/services/governance/visibility.py

@@ -0,0 +1,32 @@
+"""Visibility Service Protocol."""
+
+from abc import abstractmethod
+from typing import Protocol
+
+from ciris_engine.schemas.services.visibility import ReasoningTrace, TaskDecisionHistory, VisibilitySnapshot
+
+from ...runtime.base import ServiceProtocol
+
+
+class VisibilityServiceProtocol(ServiceProtocol, Protocol):
+    """Protocol for visibility service."""
+
+    @abstractmethod
+    async def get_current_state(self) -> VisibilitySnapshot:
+        """Get current agent state snapshot."""
+        ...
+
+    @abstractmethod
+    async def get_reasoning_trace(self, task_id: str) -> ReasoningTrace:
+        """Get reasoning trace for a task."""
+        ...
+
+    @abstractmethod
+    async def get_decision_history(self, task_id: str) -> TaskDecisionHistory:
+        """Get decision history for a task."""
+        ...
+
+    @abstractmethod
+    async def explain_action(self, action_id: str) -> str:
+        """Explain why an action was taken."""
+        ...