ciris-agent 1.7.7__py3-none-any.whl

ciris_engine/logic/services/base_graph_service.py

@@ -0,0 +1,142 @@
+"""
+Enhanced Base Graph Service - Extends BaseService for graph-backed services.
+"""
+
+from typing import TYPE_CHECKING, Any, Dict, List, Optional, Protocol, Union
+
+from ciris_engine.logic.services.base_service import BaseService
+from ciris_engine.schemas.services.graph_core import GraphNode
+from ciris_engine.schemas.services.operations import MemoryOpStatus, MemoryQuery
+
+if TYPE_CHECKING:
+    from ciris_engine.logic.buses import MemoryBus
+
+
+class GraphNodeConvertible(Protocol):
+    """Protocol for objects that can be converted to GraphNode."""
+
+    def to_graph_node(self) -> GraphNode: ...
+
+
+class BaseGraphService(BaseService):
+    """
+    Base class for graph services with memory bus integration.
+
+    Provides:
+    - Memory bus dependency management
+    - Graph storage and querying methods
+    - Automatic metrics for memory bus availability
+
+    Subclasses MUST still implement:
+    - get_service_type() -> ServiceType
+    - _get_actions() -> List[str]
+    - get_node_type() -> str (specific to graph services)
+    """
+
+    def __init__(self, *, memory_bus: Optional["MemoryBus"] = None, **kwargs: Any) -> None:
+        """
+        Initialize base graph service.
+
+        Args:
+            memory_bus: MemoryBus for graph persistence operations
+            **kwargs: Additional arguments passed to BaseService
+        """
+        super().__init__(**kwargs)
+        self._memory_bus = memory_bus
+
+    def _set_memory_bus(self, memory_bus: "MemoryBus") -> None:
+        """Set the memory bus for graph operations."""
+        self._memory_bus = memory_bus
+        self._logger.info(f"{self.service_name}: Memory bus updated")
+
+    def _register_dependencies(self) -> None:
+        """Register graph service dependencies."""
+        super()._register_dependencies()
+        self._dependencies.add("MemoryBus")
+
+    def _check_dependencies(self) -> bool:
+        """Check if memory bus is available."""
+        return self._memory_bus is not None
+
+    def _collect_custom_metrics(self) -> Dict[str, float]:
+        """Collect graph service metrics."""
+        metrics = super()._collect_custom_metrics()
+        metrics.update({"memory_bus_available": 1.0 if self._memory_bus else 0.0})
+        return metrics
+
+    # Graph-specific abstract method
+
+    def get_node_type(self) -> str:
+        """
+        Get the type of nodes this service manages.
+
+        Default implementation returns service type, but can be overridden
+        for more specific node types.
+        """
+        return self.get_service_type().value
+
+    # Graph operations
+
+    async def store_in_graph(self, node: Union[GraphNode, GraphNodeConvertible]) -> str:
+        """
+        Store a node in the graph using MemoryBus.
+
+        Args:
+            node: GraphNode to store (or any object with to_graph_node method)
+
+        Returns:
+            Node ID if successful, empty string if failed
+
+        Raises:
+            RuntimeError: If memory bus is not available
+        """
+        if not self._memory_bus:
+            raise RuntimeError(f"{self.service_name}: Memory bus not available")
+
+        self._track_request()
+
+        try:
+            # Convert to GraphNode if it has a to_graph_node method
+            graph_node: GraphNode
+            if isinstance(node, GraphNode):
+                graph_node = node
+            else:
+                graph_node = node.to_graph_node()
+
+            result = await self._memory_bus.memorize(graph_node)
+
+            if result.status == MemoryOpStatus.OK:
+                self._logger.debug(f"{self.service_name}: Stored node {graph_node.id}")
+                return graph_node.id
+            else:
+                self._logger.warning(f"{self.service_name}: Failed to store node {graph_node.id}")
+                return ""
+
+        except Exception as e:
+            self._track_error(e)
+            raise
+
+    async def query_graph(self, query: MemoryQuery) -> List[GraphNode]:
+        """
+        Query the graph using MemoryBus.
+
+        Args:
+            query: MemoryQuery with filters and options
+
+        Returns:
+            List of matching GraphNodes (empty list on error or no results)
+        """
+        if not self._memory_bus:
+            self._logger.warning(f"{self.service_name}: Memory bus not available for query")
+            return []
+
+        self._track_request()
+
+        try:
+            # MemoryBus.recall now returns List[GraphNode] directly
+            nodes = await self._memory_bus.recall(query)
+            return nodes if nodes else []
+
+        except Exception as e:
+            self._track_error(e)
+            return []

ciris_engine/logic/services/base_infrastructure_service.py

@@ -0,0 +1,69 @@
+"""
+Base Infrastructure Service - Extends BaseService for system-level services.
+"""
+
+from typing import Dict
+
+from ciris_engine.logic.services.base_service import BaseService
+from ciris_engine.schemas.runtime.enums import ServiceType
+from ciris_engine.schemas.services.core import ServiceCapabilities
+from ciris_engine.schemas.services.metadata import ServiceMetadata
+
+
+class BaseInfrastructureService(BaseService):
+    """
+    Base class for infrastructure services.
+
+    Infrastructure services are critical system-level services that:
+    - Provide core functionality (time, auth, resource monitoring)
+    - Have high availability requirements
+    - Are marked as critical in metadata
+
+    Subclasses should override get_service_type() to return the
+    appropriate ServiceType enum value.
+    """
+
+    def get_service_type(self) -> ServiceType:
+        """Infrastructure services can be various types.
+
+        Subclasses should override to return specific type like:
+        - ServiceType.TIME for time services
+        - ServiceType.SHUTDOWN for shutdown services
+        - ServiceType.INITIALIZATION for init services
+        - ServiceType.VISIBILITY for visibility services
+
+        Default returns TIME as a common infrastructure type.
+        """
+        return ServiceType.TIME
+
+    def _get_metadata(self) -> ServiceMetadata:
+        """
+        Get infrastructure service metadata.
+
+        Returns ServiceMetadata for type safety, with infrastructure-specific
+        attributes added.
+        """
+        base_metadata = super()._get_metadata()
+        # Use model_copy to create a mutable copy and update it
+        updated_metadata = base_metadata.model_copy(update={"category": "infrastructure", "critical": True})
+        return updated_metadata
+
+    def _collect_custom_metrics(self) -> Dict[str, float]:
+        """
+        Collect infrastructure-specific metrics.
+
+        Adds availability metric based on uptime.
+        """
+        metrics = super()._collect_custom_metrics()
+
+        # Calculate availability (simplified - just based on uptime)
+        uptime = self._calculate_uptime()
+        if uptime > 0:
+            # Simple availability: 1.0 if up for more than 60 seconds
+            availability = min(1.0, uptime / 60.0)
+        else:
+            availability = 0.0
+
+        metrics.update({"availability": availability})
+
+        return metrics

ciris_engine/logic/services/base_scheduled_service.py

@@ -0,0 +1,136 @@
+"""
+Base Scheduled Service - Extends BaseService for services with background tasks.
+"""
+
+import asyncio
+from abc import abstractmethod
+from typing import Any, Dict, Optional
+
+from ciris_engine.logic.services.base_service import BaseService
+from ciris_engine.schemas.services.metadata import ServiceMetadata
+
+
+class BaseScheduledService(BaseService):
+    """
+    Base class for services with scheduled background tasks.
+
+    Provides:
+    - Automatic task lifecycle management
+    - Configurable run intervals
+    - Error handling for scheduled tasks
+    - Metrics for task execution
+
+    Subclasses MUST implement:
+    - _run_scheduled_task() -> None
+    - (plus all BaseService abstract methods)
+    """
+
+    def __init__(self, *, run_interval_seconds: float = 60.0, **kwargs: Any) -> None:
+        """
+        Initialize scheduled service.
+
+        Args:
+            run_interval_seconds: How often to run the scheduled task
+            **kwargs: Additional arguments passed to BaseService
+        """
+        super().__init__(**kwargs)
+        self._run_interval = run_interval_seconds
+        self._task: Optional[asyncio.Task[Any]] = None
+        self._task_run_count = 0
+        self._task_error_count = 0
+        self._last_task_run: Optional[float] = None
+
+    async def _on_start(self) -> None:
+        """Start the scheduled task."""
+        await super()._on_start()
+        self._task = asyncio.create_task(self._run_loop())
+        self._logger.info(f"{self.service_name}: Started scheduled task with interval {self._run_interval}s")
+
+    async def _on_stop(self) -> None:
+        """Stop the scheduled task."""
+        if self._task:
+            self._task.cancel()
+            try:
+                await self._task
+            except asyncio.CancelledError:
+                pass  # NOSONAR - Expected when stopping the service in _on_stop()
+            self._task = None
+            self._logger.info(f"{self.service_name}: Stopped scheduled task")
+
+        await super()._on_stop()
+
+    async def _run_loop(self) -> None:
+        """Main scheduled task loop."""
+        while self._started:
+            try:
+                # Track task execution
+                self._task_run_count += 1
+                start_time = self._now()
+
+                # Run the scheduled task
+                await self._run_scheduled_task()
+
+                # Update last run time
+                self._last_task_run = start_time.timestamp()
+
+                self._logger.debug(f"{self.service_name}: Completed scheduled task run #{self._task_run_count}")
+
+            except asyncio.CancelledError:
+                # Task was cancelled, exit cleanly
+                self._logger.debug(f"{self.service_name}: Scheduled task cancelled")
+                raise  # Re-raise to properly exit the task
+            except Exception as e:
+                # Track errors but continue running
+                self._task_error_count += 1
+                self._track_error(e)
+                self._logger.error(f"{self.service_name}: Error in scheduled task: {e}", exc_info=True)
+
+            # Wait for next interval
+            try:
+                await asyncio.sleep(self._run_interval)
+            except asyncio.CancelledError:
+                self._logger.debug(f"{self.service_name}: Sleep cancelled, exiting loop")
+                raise  # Re-raise to properly exit the task
+
+    @abstractmethod
+    async def _run_scheduled_task(self) -> None:
+        """
+        Execute the scheduled task.
+
+        This method is called periodically based on run_interval_seconds.
+        Subclasses must implement this to define what the task does.
+
+        Exceptions raised here are caught and logged but don't stop the loop.
+        """
+        ...
+
+    def _collect_custom_metrics(self) -> Dict[str, float]:
+        """Collect scheduled task metrics."""
+        metrics = super()._collect_custom_metrics()
+
+        # Calculate time since last run
+        time_since_last_run = 0.0
+        if self._last_task_run:
+            time_since_last_run = self._now().timestamp() - self._last_task_run
+
+        metrics.update(
+            {
+                "task_run_count": float(self._task_run_count),
+                "task_error_count": float(self._task_error_count),
+                "task_error_rate": float(self._task_error_count) / max(1, self._task_run_count),
+                "task_interval_seconds": self._run_interval,
+                "time_since_last_task_run": time_since_last_run,
+                "task_running": 1.0 if self._task and not self._task.done() else 0.0,
+            }
+        )
+
+        return metrics
+
+    def _get_metadata(self) -> ServiceMetadata:
+        """Add scheduled task metadata."""
+        # Get base metadata from parent
+        base_metadata = super()._get_metadata()
+
+        # For now, we'll return the base metadata as-is
+        # In a future refactor, we could extend ServiceMetadata to include additional fields
+        return base_metadata

ciris_engine/logic/services/base_service.py

@@ -0,0 +1,247 @@
+"""
+Base Service Class for CIRIS - Maximum clarity and simplicity.
+
+Design Principles:
+1. No Untyped Dicts, No Bypass Patterns, No Exceptions - All typed with Pydantic
+2. Clear separation between required and optional functionality
+3. Dependency injection for all external services
+4. Comprehensive lifecycle management
+5. Built-in observability (metrics, health, status)
+"""
+
+import logging
+from abc import ABC, abstractmethod
+from datetime import datetime, timezone
+from typing import Dict, List, Optional, Set
+
+from ciris_engine.protocols.runtime.base import ServiceProtocol
+from ciris_engine.protocols.services.lifecycle.time import TimeServiceProtocol
+from ciris_engine.schemas.runtime.enums import ServiceType
+from ciris_engine.schemas.services.core import ServiceCapabilities, ServiceStatus
+from ciris_engine.schemas.services.metadata import ServiceMetadata
+
+
+class BaseService(ABC, ServiceProtocol):
+    """
+    Base class for all CIRIS services.
+
+    Provides:
+    - Lifecycle management (start/stop)
+    - Health checking
+    - Status reporting
+    - Metrics collection
+    - Dependency tracking
+    - Error tracking
+
+    Subclasses MUST implement:
+    - get_service_type() -> ServiceType
+    - _get_actions() -> List[str]
+    - _check_dependencies() -> bool
+
+    Subclasses MAY override:
+    - _on_start() -> None (for custom startup logic)
+    - _on_stop() -> None (for custom cleanup)
+    - _collect_custom_metrics() -> Dict[str, float]
+    - _get_metadata() -> ServiceMetadata
+    """
+
+    def __init__(
+        self,
+        *,  # Force keyword-only arguments for clarity
+        time_service: Optional[TimeServiceProtocol] = None,
+        service_name: Optional[str] = None,
+        version: str = "1.0.0",
+    ) -> None:
+        """
+        Initialize base service.
+
+        Args:
+            time_service: Time service for consistent timestamps (optional)
+            service_name: Override service name (defaults to class name)
+            version: Service version string
+        """
+        # Core state
+        self._started = False
+        self._start_time: Optional[datetime] = None
+        self.service_name = service_name or self.__class__.__name__
+        self._version = version
+
+        # Dependencies
+        self._time_service = time_service
+        self._logger = logging.getLogger(f"ciris_engine.services.{self.service_name}")
+
+        # Metrics and observability
+        self._metrics: Dict[str, float] = {}
+        self._last_error: Optional[str] = None
+        self._last_health_check: Optional[datetime] = None
+        self._request_count = 0
+        self._error_count = 0
+
+        # Dependency tracking
+        self._dependencies: Set[str] = set()
+        self._register_dependencies()
+
+    # Required abstract methods
+
+    @abstractmethod
+    def get_service_type(self) -> ServiceType:
+        """Get the service type enum value."""
+        ...
+
+    @abstractmethod
+    def _get_actions(self) -> List[str]:
+        """Get list of actions this service provides."""
+        ...
+
+    @abstractmethod
+    def _check_dependencies(self) -> bool:
+        """Check if all required dependencies are available."""
+        ...
+
+    # Optional override points
+
+    async def _on_start(self) -> None:
+        """Custom startup logic - override in subclass if needed."""
+        pass
+
+    async def _on_stop(self) -> None:
+        """Custom cleanup logic - override in subclass if needed."""
+        pass
+
+    def _collect_custom_metrics(self) -> Dict[str, float]:
+        """Collect service-specific metrics - override in subclass."""
+        return {}
+
+    def _get_metadata(self) -> ServiceMetadata:
+        """Get service-specific metadata - override in subclass."""
+        return ServiceMetadata()
+
+    def _register_dependencies(self) -> None:
+        """Register service dependencies - override in subclass."""
+        if self._time_service:
+            self._dependencies.add("TimeService")
+
+    # ServiceProtocol implementation
+
+    async def start(self) -> None:
+        """Start the service."""
+        if self._started:
+            self._logger.warning(f"{self.service_name} already started")
+            return
+
+        try:
+            # Check dependencies first
+            if not self._check_dependencies():
+                raise RuntimeError(f"{self.service_name}: Required dependencies not available")
+
+            # Set start time
+            self._start_time = self._now()
+
+            # Call custom startup logic
+            await self._on_start()
+
+            # Mark as started
+            self._started = True
+            self._logger.info(f"{self.service_name} started successfully")
+
+        except Exception as e:
+            self._last_error = str(e)
+            self._logger.error(f"{self.service_name} failed to start: {e}")
+            raise
+
+    async def stop(self) -> None:
+        """Stop the service."""
+        if not self._started:
+            self._logger.warning(f"{self.service_name} not started")
+            return
+
+        try:
+            # Call custom cleanup logic
+            await self._on_stop()
+
+            # Mark as stopped
+            self._started = False
+            self._logger.info(f"{self.service_name} stopped successfully")
+
+        except Exception as e:
+            self._last_error = str(e)
+            self._logger.error(f"{self.service_name} error during stop: {e}")
+            raise
+
+    async def is_healthy(self) -> bool:
+        """Check if service is healthy."""
+        self._last_health_check = self._now()
+        return self._started and self._check_dependencies()
+
+    def get_capabilities(self) -> ServiceCapabilities:
+        """Get service capabilities."""
+        return ServiceCapabilities(
+            service_name=self.service_name,
+            actions=self._get_actions(),
+            version=self._version,
+            dependencies=list(self._dependencies),
+            metadata=self._get_metadata(),
+        )
+
+    def get_status(self) -> ServiceStatus:
+        """Get current service status."""
+        return ServiceStatus(
+            service_name=self.service_name,
+            service_type=self.get_service_type().value,
+            is_healthy=self._started and self._check_dependencies(),
+            uptime_seconds=self._calculate_uptime(),
+            metrics=self._collect_metrics(),
+            last_error=self._last_error,
+            last_health_check=self._last_health_check,
+        )
+
+    # Helper methods
+
+    def _now(self) -> datetime:
+        """Get current time using time service if available."""
+        if self._time_service:
+            return self._time_service.now()
+        return datetime.now(timezone.utc)
+
+    def _calculate_uptime(self) -> float:
+        """Calculate service uptime in seconds."""
+        if not self._started or not self._start_time:
+            return 0.0
+        return (self._now() - self._start_time).total_seconds()
+
+    def _collect_metrics(self) -> Dict[str, float]:
+        """Collect all metrics including custom ones."""
+        base_metrics = {
+            "uptime_seconds": self._calculate_uptime(),
+            "request_count": float(self._request_count),
+            "error_count": float(self._error_count),
+            "error_rate": float(self._error_count) / max(1, self._request_count),
+            "healthy": 1.0 if self._started else 0.0,
+        }
+
+        # Add custom metrics
+        custom_metrics = self._collect_custom_metrics()
+        base_metrics.update(custom_metrics)
+
+        return base_metrics
+
+    async def get_metrics(self) -> Dict[str, float]:
+        """
+        Public async method to get all service metrics.
+
+        Returns combined base metrics and custom metrics.
+        This is the standard interface for metric collection.
+        """
+        return self._collect_metrics()
+
+    # Request tracking helpers (for services that handle requests)
+
+    def _track_request(self) -> None:
+        """Track a request for metrics."""
+        self._request_count += 1
+
+    def _track_error(self, error: Exception) -> None:
+        """Track an error for metrics."""
+        self._error_count += 1
+        self._last_error = str(error)
+        self._logger.error(f"{self.service_name} error: {error}")

ciris_engine/logic/services/governance/__init__.py

@@ -0,0 +1,3 @@
+"""Governance services - security and oversight."""
+
+# Note: Imports will be added as needed to avoid circular dependencies

ciris_engine/logic/services/governance/adaptive_filter/__init__.py

@@ -0,0 +1,14 @@
+"""
+CIRIS Adaptive Filter Service Module
+
+Provides intelligent message filtering with graph memory persistence,
+user trust tracking, self-configuration capabilities, and privacy-preserving
+moderation for anonymous users.
+
+This module implements universal message filtering across all CIRIS adapters
+(Discord, CLI, API) with attention economy management and ethical AI principles.
+"""
+
+from .service import AdaptiveFilterService
+
+__all__ = ["AdaptiveFilterService"]