ciris-agent 1.7.7__py3-none-any.whl

ciris_engine/schemas/services/graph_typed_nodes.py

@@ -0,0 +1,194 @@
+"""
+Base class and utilities for typed graph nodes.
+
+This module provides the foundation for type-safe graph nodes that can be
+stored generically while maintaining full type information.
+"""
+
+from abc import ABC, abstractmethod
+from datetime import datetime
+from typing import TYPE_CHECKING, Any, Callable, Dict, List, Optional, Type, TypeVar, Union
+
+from pydantic import BaseModel
+
+from ciris_engine.schemas.services.graph_core import GraphNode
+from ciris_engine.schemas.types import JSONDict
+
+if TYPE_CHECKING:
+    from ciris_engine.schemas.services.graph_core import NodeType
+
+T = TypeVar("T", bound="TypedGraphNode")
+
+
+class TypedGraphNode(GraphNode, ABC):
+    """
+    Abstract base class for all typed graph nodes.
+
+    Subclasses must implement to_graph_node() and from_graph_node()
+    to handle serialization to/from generic GraphNode storage.
+    """
+
+    @abstractmethod
+    def to_graph_node(self) -> GraphNode:
+        """
+        Convert this typed node to a generic GraphNode for storage.
+
+        Should only include extra fields (beyond GraphNode base fields)
+        in the attributes dict.
+        """
+
+    @classmethod
+    @abstractmethod
+    def from_graph_node(cls: Type[T], node: GraphNode) -> T:
+        """
+        Reconstruct a typed node from a generic GraphNode.
+
+        Should handle deserialization of extra fields from attributes.
+        """
+
+    def _serialize_extra_fields(self, exclude_fields: Optional[List[str]] = None) -> JSONDict:
+        """
+        Helper to serialize only the extra fields (not in GraphNode base).
+
+        Args:
+            exclude_fields: Additional fields to exclude beyond base fields
+
+        Returns:
+            Dict of extra fields suitable for GraphNode attributes
+        """
+        # Base GraphNode fields to always exclude
+        base_fields = {"id", "type", "scope", "attributes", "version", "updated_by", "updated_at"}
+
+        # Add any additional exclusions
+        if exclude_fields:
+            base_fields.update(exclude_fields)
+
+        # Get all fields from this model
+        extra_data: JSONDict = {}
+        for field_name, field_value in self.model_dump().items():
+            if field_name not in base_fields and field_value is not None:
+                # Handle special types
+                if isinstance(field_value, datetime):
+                    extra_data[field_name] = field_value.isoformat()
+                elif isinstance(field_value, BaseModel):
+                    extra_data[field_name] = field_value.model_dump()
+                else:
+                    extra_data[field_name] = field_value
+
+        # Add type hint for deserialization
+        extra_data["node_class"] = self.__class__.__name__
+
+        return extra_data
+
+    @classmethod
+    def _deserialize_datetime(cls, value: Any) -> Optional[datetime]:
+        """Helper to deserialize datetime from string."""
+        if value is None:
+            return None
+        if isinstance(value, datetime):
+            return value
+        if isinstance(value, str):
+            return datetime.fromisoformat(value)
+        raise ValueError(f"Cannot deserialize datetime from {type(value)}")
+
+
+class NodeTypeRegistry:
+    """
+    Registry for typed node classes.
+
+    Allows looking up node classes by type string for deserialization.
+    """
+
+    _registry: Dict[str, Type[TypedGraphNode]] = {}
+
+    @classmethod
+    def register(cls, node_type: str, node_class: Type[TypedGraphNode]) -> None:
+        """Register a node class for a type string."""
+        # Allow re-registration with the same class (for multiple keys pointing to same class)
+        if node_type in cls._registry and cls._registry[node_type] != node_class:
+            raise ValueError(f"Node type {node_type} already registered with a different class")
+
+        # Validate the class has required methods
+        if not hasattr(node_class, "to_graph_node"):
+            raise ValueError(f"{node_class.__name__} must implement to_graph_node()")
+        if not hasattr(node_class, "from_graph_node"):
+            raise ValueError(f"{node_class.__name__} must implement from_graph_node()")
+
+        cls._registry[node_type] = node_class
+
+    @classmethod
+    def get(cls, node_type: str) -> Optional[Type[TypedGraphNode]]:
+        """Get a node class by type string."""
+        return cls._registry.get(node_type)
+
+    @classmethod
+    def deserialize(cls, node: GraphNode) -> Union[TypedGraphNode, GraphNode]:
+        """
+        Deserialize a GraphNode to its typed variant if registered.
+
+        Falls back to returning the GraphNode if type not registered.
+        """
+        # node.type is a NodeType enum, so we need to check both the enum value
+        # and the enum name for backward compatibility
+        node_type_key = node.type if isinstance(node.type, str) else node.type.value
+        node_class = cls._registry.get(node_type_key)
+
+        # Also check by enum name (e.g., "USER" for NodeType.USER)
+        if not node_class and hasattr(node.type, "name"):
+            node_class = cls._registry.get(node.type.name)
+
+        # Also check by uppercase version of the enum value
+        if not node_class:
+            node_class = cls._registry.get(node_type_key.upper())
+
+        if node_class:
+            # Check if attributes is a dict or has a get method
+            if isinstance(node.attributes, dict) or hasattr(node.attributes, "get"):
+                # Check if this was serialized from a typed node
+                attrs = (
+                    node.attributes
+                    if isinstance(node.attributes, dict)
+                    else node.attributes.model_dump() if hasattr(node.attributes, "model_dump") else {}
+                )
+                class_name = attrs.get("node_class") if isinstance(attrs, dict) else None
+                if class_name:
+                    # Try to deserialize to typed node
+                    try:
+                        return node_class.from_graph_node(node)
+                    except Exception:
+                        # Fall back to generic if deserialization fails
+                        pass
+
+        return node
+
+
+def register_node_type(node_type: Union[str, "NodeType"]) -> Callable[[Type[TypedGraphNode]], Type[TypedGraphNode]]:
+    """
+    Decorator to automatically register a node type.
+
+    Usage:
+        @register_node_type("CONFIG")
+        class ConfigNode(TypedGraphNode):
+            ...
+
+        # Or using enum:
+        @register_node_type(NodeType.CONFIG)
+        class ConfigNode(TypedGraphNode):
+            ...
+    """
+
+    def decorator(cls: Type[TypedGraphNode]) -> Type[TypedGraphNode]:
+        # Handle both string and enum inputs
+        if hasattr(node_type, "value") and hasattr(node_type, "name"):
+            # It's an enum, register by multiple keys for flexibility
+            NodeTypeRegistry.register(node_type.value, cls)  # e.g., "config"
+            NodeTypeRegistry.register(node_type.name, cls)  # e.g., "CONFIG"
+            NodeTypeRegistry.register(node_type.value.upper(), cls)  # e.g., "CONFIG"
+        else:
+            # It's a string, register as-is and also lowercase version
+            NodeTypeRegistry.register(node_type, cls)
+            if isinstance(node_type, str) and node_type.lower() != node_type:
+                NodeTypeRegistry.register(node_type.lower(), cls)
+        return cls
+
+    return decorator

ciris_engine/schemas/services/infrastructure/__init__.py

@@ -0,0 +1 @@
+"""Infrastructure services schemas."""

ciris_engine/schemas/services/infrastructure/resource_monitor.py

@@ -0,0 +1,20 @@
+"""
+Schemas for Resource Monitor Service.
+
+Re-exports resource monitoring schemas from resources_core for proper
+directory alignment.
+"""
+
+# ResourceUsage is in runtime.resources, not resources_core
+from ciris_engine.schemas.runtime.resources import ResourceUsage
+
+# Re-export from resources_core to maintain clean directory structure
+from ciris_engine.schemas.services.resources_core import ResourceAction, ResourceBudget, ResourceLimit, ResourceSnapshot
+
+__all__ = [
+    "ResourceAction",
+    "ResourceBudget",
+    "ResourceLimit",
+    "ResourceSnapshot",
+    "ResourceUsage",
+]

ciris_engine/schemas/services/lifecycle/__init__.py

@@ -0,0 +1,9 @@
+"""Lifecycle service schemas."""
+
+from .time import TimeServiceConfig, TimeServiceStatus, TimeSnapshot
+
+__all__ = [
+    "TimeServiceConfig",
+    "TimeSnapshot",
+    "TimeServiceStatus",
+]

ciris_engine/schemas/services/lifecycle/initialization.py

@@ -0,0 +1,33 @@
+"""Initialization service schemas."""
+
+from datetime import datetime
+from typing import Dict, List, Optional
+
+from pydantic import BaseModel, ConfigDict, Field, field_serializer
+
+
+class InitializationStatus(BaseModel):
+    """Status of system initialization."""
+
+    complete: bool = Field(..., description="Whether initialization is complete")
+    start_time: Optional[datetime] = Field(None, description="When initialization started")
+    duration_seconds: Optional[float] = Field(None, description="How long initialization took")
+    completed_steps: List[str] = Field(default_factory=list, description="Steps that completed successfully")
+    phase_status: Dict[str, str] = Field(default_factory=dict, description="Status of each phase")
+    error: Optional[str] = Field(None, description="Error message if initialization failed")
+    total_steps: int = Field(0, description="Total number of steps registered")
+
+    model_config = ConfigDict()
+
+    @field_serializer("start_time")
+    def serialize_datetime(self, dt: Optional[datetime]) -> Optional[str]:
+        return dt.isoformat() if dt else None
+
+
+class InitializationVerification(BaseModel):
+    """Results of initialization verification."""
+
+    system_initialized: bool = Field(..., description="Whether system is fully initialized")
+    no_errors: bool = Field(..., description="Whether there were no errors")
+    all_steps_completed: bool = Field(..., description="Whether all steps completed")
+    phase_results: Dict[str, bool] = Field(default_factory=dict, description="Results for each phase")

ciris_engine/schemas/services/lifecycle/time.py

@@ -0,0 +1,50 @@
+"""
+Schemas for Time Service.
+
+Provides configuration and data structures for time operations.
+"""
+
+from datetime import datetime, timezone
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+
+class TimeServiceConfig(BaseModel):
+    """Configuration for Time Service."""
+
+    enable_mocking: bool = Field(default=True, description="Whether to allow time mocking for tests")
+    default_timezone: str = Field(default="UTC", description="Default timezone (always UTC for CIRIS)")
+
+
+class TimeSnapshot(BaseModel):
+    """A snapshot of time information."""
+
+    current_time: datetime = Field(..., description="Current time in UTC")
+    current_iso: str = Field(..., description="Current time as ISO string")
+    current_timestamp: float = Field(..., description="Current Unix timestamp")
+    is_mocked: bool = Field(..., description="Whether time is mocked")
+    mock_time: Optional[datetime] = Field(None, description="Mock time if set")
+
+
+class LocalizedTimeData(BaseModel):
+    """Localized time information for multiple timezones - flexible for future time sources."""
+
+    utc: str = Field(..., description="UTC time in ISO format")
+    london: str = Field(..., description="London time in ISO format")
+    chicago: str = Field(..., description="Chicago time in ISO format")
+    tokyo: str = Field(..., description="Tokyo time in ISO format")
+    source_service: str = Field(default="TimeService", description="Time service that provided this data")
+    generated_at: datetime = Field(
+        default_factory=lambda: datetime.now(timezone.utc), description="When this data was generated"
+    )
+
+
+class TimeServiceStatus(BaseModel):
+    """Extended status for Time Service."""
+
+    service_name: str = Field(default="TimeService")
+    is_healthy: bool = Field(..., description="Service health")
+    uptime_seconds: float = Field(..., description="Service uptime")
+    is_mocked: bool = Field(..., description="Whether time is mocked")
+    calls_served: int = Field(default=0, description="Total time requests served")

ciris_engine/schemas/services/llm.py

@@ -0,0 +1,187 @@
+"""
+LLM Service specific schemas.
+
+Provides typed schemas for LLM service operations.
+"""
+
+from datetime import datetime, timezone
+from typing import Dict, List, Literal, Optional, Union
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class TokenUsageStats(BaseModel):
+    """Token usage statistics from LLM API."""
+
+    prompt_tokens: int = Field(0, description="Number of tokens in the prompt")
+    completion_tokens: int = Field(0, description="Number of tokens in the completion")
+    total_tokens: int = Field(0, description="Total tokens used")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class CircuitBreakerStats(BaseModel):
+    """Circuit breaker statistics."""
+
+    state: str = Field(..., description="Current state: closed, open, or half-open")
+    failure_count: int = Field(..., description="Number of consecutive failures")
+    success_count: int = Field(..., description="Number of consecutive successes")
+    last_failure: Optional[datetime] = Field(None, description="Timestamp of last failure")
+    last_success: Optional[datetime] = Field(None, description="Timestamp of last success")
+    call_count: int = Field(0, description="Total number of calls")
+    success_rate: float = Field(1.0, description="Success rate (0-1)")
+
+
+class LLMHealthResponse(BaseModel):
+    """Health check response for LLM service."""
+
+    healthy: bool = Field(..., description="Whether service is healthy")
+    service_name: str = Field(..., description="Name of the service")
+    model_name: str = Field(..., description="Model being used")
+    service_type: str = Field(..., description="Type of service (real/mock)")
+    status: str = Field(..., description="Status: healthy, degraded, or unhealthy")
+    circuit_breaker: Optional[CircuitBreakerStats] = Field(None, description="Circuit breaker stats")
+    error_message: Optional[str] = Field(None, description="Error message if unhealthy")
+    last_check: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+
+    model_config = ConfigDict(protected_namespaces=())
+
+
+class LLMResponse(BaseModel):
+    """Standard LLM response structure."""
+
+    content: str = Field(..., description="Response content")
+    model: str = Field(..., description="Model that generated response")
+    usage: TokenUsageStats = Field(default_factory=TokenUsageStats, description="Token usage stats")
+    finish_reason: Optional[str] = Field(None, description="Why generation stopped")
+
+    model_config = ConfigDict(protected_namespaces=())
+
+
+class ExtractedJSONData(BaseModel):
+    """Structured data extracted from LLM JSON response."""
+
+    # Common fields that appear in LLM JSON responses
+    message: Optional[str] = Field(None, description="Message content")
+    content: Optional[str] = Field(None, description="Content text")
+    result: Optional[str] = Field(None, description="Result value")
+    status: Optional[str] = Field(None, description="Status indicator")
+
+    model_config = ConfigDict(extra="allow")
+
+
+class JSONExtractionResult(BaseModel):
+    """Result of JSON extraction from LLM response."""
+
+    success: bool = Field(..., description="Whether extraction succeeded")
+    data: Optional[ExtractedJSONData] = Field(None, description="Extracted JSON data")
+    error: Optional[str] = Field(None, description="Error message if extraction failed")
+    raw_content: Optional[str] = Field(None, description="Raw content that failed to parse")
+
+
+class LLMCallMetadata(BaseModel):
+    """Metadata for an LLM call."""
+
+    prompt_tokens: int = Field(0, description="Number of tokens in prompt")
+    completion_tokens: int = Field(0, description="Number of tokens in completion")
+    total_tokens: int = Field(0, description="Total tokens used")
+    model: str = Field(..., description="Model used")
+    temperature: float = Field(..., description="Temperature setting")
+    max_tokens: int = Field(..., description="Max tokens setting")
+    duration_ms: Optional[float] = Field(None, description="Call duration in milliseconds")
+    cached: bool = Field(False, description="Whether response was cached")
+
+
+class TextContentBlock(BaseModel):
+    """Text content block for multimodal messages."""
+
+    type: Literal["text"] = "text"
+    text: str = Field(..., description="Text content")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class ImageURLDetail(BaseModel):
+    """Image URL details for multimodal messages."""
+
+    url: str = Field(..., description="Image URL or data URL (data:image/jpeg;base64,...)")
+    detail: Optional[Literal["auto", "low", "high"]] = Field(
+        default="auto", description="Image detail level for vision processing"
+    )
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class ImageContentBlock(BaseModel):
+    """Image content block for multimodal messages."""
+
+    type: Literal["image_url"] = "image_url"
+    image_url: ImageURLDetail = Field(..., description="Image URL details")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+# Union type for content blocks in multimodal messages
+ContentBlock = Union[TextContentBlock, ImageContentBlock]
+
+
+class LLMMessage(BaseModel):
+    """
+    Message for LLM conversations.
+
+    Supports both simple text content (str) and multimodal content (List[ContentBlock]).
+    For text-only messages, use content="text".
+    For multimodal messages with images, use content=[TextContentBlock(...), ImageContentBlock(...)].
+    """
+
+    role: Literal["system", "user", "assistant"] = Field(..., description="Message role")
+    content: str | List[ContentBlock] = Field(
+        ..., description="Message content - string for text, list of blocks for multimodal"
+    )
+    name: Optional[str] = Field(None, description="Optional name for the message sender")
+
+    def is_multimodal(self) -> bool:
+        """Check if this message contains multimodal content."""
+        return isinstance(self.content, list)
+
+    def get_text_content(self) -> str:
+        """Extract text content from the message."""
+        if isinstance(self.content, str):
+            return self.content
+        # Extract text from content blocks
+        texts = []
+        for block in self.content:
+            if isinstance(block, TextContentBlock):
+                texts.append(block.text)
+        return "\n".join(texts)
+
+
+class LLMCallParams(BaseModel):
+    """Additional parameters for LLM calls."""
+
+    top_p: Optional[float] = Field(None, description="Nucleus sampling parameter")
+    frequency_penalty: Optional[float] = Field(None, description="Frequency penalty")
+    presence_penalty: Optional[float] = Field(None, description="Presence penalty")
+    stop: Optional[List[str]] = Field(None, description="Stop sequences")
+    seed: Optional[int] = Field(None, description="Random seed for deterministic output")
+
+
+class CachedResponseData(BaseModel):
+    """Serialized response data for cached LLM responses."""
+
+    content: str = Field(..., description="Response content")
+    model: str = Field(..., description="Model used")
+    finish_reason: Optional[str] = Field(None, description="Finish reason")
+
+    model_config = ConfigDict(extra="allow")
+
+
+class CachedLLMResponse(BaseModel):
+    """Cached response from LLM service."""
+
+    response_model_name: str = Field(..., description="Name of the response model type")
+    response_data: CachedResponseData = Field(..., description="Serialized response data")
+    cache_key: str = Field(..., description="Cache key used")
+    cached_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+    metadata: LLMCallMetadata = Field(..., description="Call metadata")
+    expires_at: Optional[datetime] = Field(None, description="When cache entry expires")

ciris_engine/schemas/services/metadata.py

@@ -0,0 +1,43 @@
+"""
+Service metadata schemas for service capabilities.
+
+Provides typed metadata fields for describing service capabilities.
+"""
+
+from typing import Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ServiceMetadata(BaseModel):
+    """Metadata for service capabilities - describes service characteristics and configuration."""
+
+    # Infrastructure-specific fields
+    category: Optional[str] = Field(None, description="Service category (e.g., 'infrastructure')")
+    critical: Optional[bool] = Field(None, description="Whether the service is critical for system operation")
+
+    # LLM service fields
+    model: Optional[str] = Field(None, description="LLM model name")
+    instructor_mode: Optional[str] = Field(None, description="Instructor mode (JSON, TOOLS, etc.)")
+    timeout_seconds: Optional[int] = Field(None, description="Operation timeout in seconds")
+    max_retries: Optional[int] = Field(None, description="Maximum retry attempts")
+    circuit_breaker_state: Optional[str] = Field(None, description="Circuit breaker state")
+
+    # Tool service fields
+    adapter: Optional[str] = Field(None, description="Adapter name providing tools")
+    tool_count: Optional[int] = Field(None, description="Number of tools available")
+
+    # Scheduler service fields
+    active_tasks: Optional[int] = Field(None, description="Number of active scheduled tasks")
+    total_tasks: Optional[int] = Field(None, description="Total tasks scheduled")
+    features: Optional[list[str]] = Field(None, description="List of supported features")
+    cron_support: Optional[bool] = Field(None, description="Whether cron scheduling is available")
+    description: Optional[str] = Field(None, description="Service description")
+
+    # Runtime control service fields
+    processors_active: Optional[int] = Field(None, description="Number of active processors")
+    adapters_loaded: Optional[int] = Field(None, description="Number of loaded adapters")
+    stepping_enabled: Optional[bool] = Field(None, description="Whether pipeline stepping is enabled")
+    queue_depth: Optional[int] = Field(None, description="Current processor queue depth")
+
+    model_config = ConfigDict(extra="forbid")  # No arbitrary fields allowed