ciris-agent 1.7.7__py3-none-any.whl

ciris_engine/schemas/telemetry/core.py

@@ -0,0 +1,252 @@
+"""
+Correlation schemas for service tracking and TSDB capabilities.
+
+Provides type-safe correlation tracking without Dict[str, Any].
+"""
+
+from datetime import datetime
+from enum import Enum
+from typing import Dict, List, Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ServiceCorrelationStatus(str, Enum):
+    """Status values for service correlations."""
+
+    PENDING = "pending"
+    COMPLETED = "completed"
+    FAILED = "failed"
+
+
+class CorrelationType(str, Enum):
+    """Types of correlations supported by the TSDB system."""
+
+    SERVICE_INTERACTION = "service_interaction"
+
+    METRIC_DATAPOINT = "metric_datapoint"
+    LOG_ENTRY = "log_entry"
+    TRACE_SPAN = "trace_span"
+    AUDIT_EVENT = "audit_event"
+
+    METRIC_HOURLY_SUMMARY = "metric_hourly_summary"
+    METRIC_DAILY_SUMMARY = "metric_daily_summary"
+    LOG_HOURLY_SUMMARY = "log_hourly_summary"
+
+
+class ServiceRequestData(BaseModel):
+    """Structured request data for service correlations."""
+
+    service_type: str = Field(..., description="Type of service called")
+    method_name: str = Field(..., description="Method that was called")
+
+    # Common request fields
+    thought_id: Optional[str] = Field(None, description="Associated thought ID")
+    task_id: Optional[str] = Field(None, description="Associated task ID")
+    channel_id: Optional[str] = Field(None, description="Channel where request originated")
+
+    # Parameters passed
+    parameters: Dict[str, str] = Field(default_factory=dict, description="String representation of parameters")
+
+    # Timing
+    request_timestamp: datetime = Field(..., description="When request was made")
+    timeout_seconds: Optional[float] = Field(None, description="Request timeout")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class ServiceResponseData(BaseModel):
+    """Structured response data for service correlations."""
+
+    success: bool = Field(..., description="Whether service call succeeded")
+
+    # Result data
+    result_summary: Optional[str] = Field(None, description="Summary of result")
+    result_type: Optional[str] = Field(None, description="Type of result returned")
+    result_size: Optional[int] = Field(None, description="Size of result in bytes")
+
+    # Error information
+    error_type: Optional[str] = Field(None, description="Type of error if failed")
+    error_message: Optional[str] = Field(None, description="Error message if failed")
+    error_traceback: Optional[str] = Field(None, description="Stack trace if available")
+
+    # Performance metrics
+    execution_time_ms: float = Field(..., description="Execution time in milliseconds")
+    response_timestamp: datetime = Field(..., description="When response was received")
+
+    # Resource usage
+    tokens_used: Optional[int] = Field(None, description="LLM tokens used")
+    memory_bytes: Optional[int] = Field(None, description="Memory consumed")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class TraceContext(BaseModel):
+    """Distributed tracing context."""
+
+    trace_id: str = Field(..., description="Trace identifier")
+    span_id: str = Field(..., description="Span identifier")
+    parent_span_id: Optional[str] = Field(None, description="Parent span for hierarchy")
+
+    # Span details
+    span_name: str = Field(..., description="Name of the span")
+    span_kind: str = Field("internal", description="Span kind: internal, client, server")
+
+    # Baggage
+    baggage: Dict[str, str] = Field(default_factory=dict, description="Propagated context values")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class MetricData(BaseModel):
+    """Metric data for correlations."""
+
+    metric_name: str = Field(..., description="Name of the metric")
+    metric_value: float = Field(..., description="Numeric value")
+    metric_unit: str = Field(..., description="Unit of measurement")
+
+    # Metric type
+    metric_type: str = Field("gauge", description="gauge, counter, histogram, summary")
+
+    # Labels/dimensions
+    labels: Dict[str, str] = Field(default_factory=dict, description="Metric labels/dimensions")
+
+    # Statistical data (for histograms/summaries)
+    min_value: Optional[float] = Field(None, description="Minimum observed")
+    max_value: Optional[float] = Field(None, description="Maximum observed")
+    mean_value: Optional[float] = Field(None, description="Mean value")
+    percentiles: Dict[str, float] = Field(default_factory=dict, description="Percentile values (e.g., p50, p95, p99)")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class LogData(BaseModel):
+    """Log data for correlations."""
+
+    log_level: str = Field(..., description="Log level: DEBUG, INFO, WARNING, ERROR, CRITICAL")
+    log_message: str = Field(..., description="Log message")
+
+    # Source information
+    logger_name: str = Field(..., description="Name of the logger")
+    module_name: str = Field(..., description="Module that logged")
+    function_name: str = Field(..., description="Function that logged")
+    line_number: int = Field(..., description="Line number")
+
+    # Structured data
+    extra_fields: Dict[str, str] = Field(default_factory=dict, description="Additional structured log fields")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class ServiceCorrelation(BaseModel):
+    """Record correlating service requests and responses with TSDB capabilities."""
+
+    # Identity
+    correlation_id: str = Field(..., description="Unique correlation identifier")
+    correlation_type: CorrelationType = Field(CorrelationType.SERVICE_INTERACTION, description="Type of correlation")
+
+    # Service information
+    service_type: str = Field(..., description="Type of service")
+    handler_name: str = Field(..., description="Handler that processed")
+    action_type: str = Field(..., description="Action type performed")
+
+    # Structured data (no Dict[str, Any]!)
+    request_data: Optional[ServiceRequestData] = Field(None, description="Request details")
+    response_data: Optional[ServiceResponseData] = Field(None, description="Response details")
+
+    # Status tracking
+    status: ServiceCorrelationStatus = Field(ServiceCorrelationStatus.PENDING, description="Current status")
+
+    # Timestamps
+    created_at: datetime = Field(..., description="When correlation was created")
+    updated_at: datetime = Field(..., description="Last update time")
+    timestamp: datetime = Field(..., description="Primary timestamp for TSDB indexing")
+
+    # TSDB-specific data based on correlation type
+    metric_data: Optional[MetricData] = Field(None, description="For metric correlations")
+    log_data: Optional[LogData] = Field(None, description="For log correlations")
+    trace_context: Optional[TraceContext] = Field(None, description="For distributed tracing")
+
+    # Flexible tagging for queries
+    tags: Dict[str, str] = Field(default_factory=dict, description="Tags for filtering/grouping")
+
+    # Retention and storage
+    retention_policy: str = Field("raw", description="raw, hourly_summary, daily_summary")
+    ttl_seconds: Optional[int] = Field(None, description="Time to live in seconds")
+
+    # Relationships
+    parent_correlation_id: Optional[str] = Field(None, description="Parent correlation if nested")
+    child_correlation_ids: List[str] = Field(default_factory=list, description="Child correlations")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class CorrelationQuery(BaseModel):
+    """Query for finding correlations."""
+
+    # Time range
+    start_time: Optional[datetime] = Field(None, description="Start of time range")
+    end_time: Optional[datetime] = Field(None, description="End of time range")
+
+    # Filters
+    correlation_types: Optional[List[CorrelationType]] = Field(None, description="Types to include")
+    service_types: Optional[List[str]] = Field(None, description="Service types to include")
+    statuses: Optional[List[ServiceCorrelationStatus]] = Field(None, description="Statuses to include")
+
+    # Tag filters
+    required_tags: Dict[str, str] = Field(default_factory=dict, description="Tags that must match")
+    excluded_tags: List[str] = Field(default_factory=list, description="Tag keys to exclude")
+
+    # Trace context
+    trace_id: Optional[str] = Field(None, description="Find by trace ID")
+
+    # Pagination
+    limit: int = Field(100, description="Maximum results")
+    offset: int = Field(0, description="Skip this many results")
+
+    # Ordering
+    order_by: str = Field("timestamp", description="Field to order by")
+    order_desc: bool = Field(True, description="Descending order")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class CorrelationSummary(BaseModel):
+    """Summary of correlations for a time period."""
+
+    period_start: datetime = Field(..., description="Start of period")
+    period_end: datetime = Field(..., description="End of period")
+
+    # Counts by type
+    total_correlations: int = Field(..., description="Total correlations")
+    correlations_by_type: Dict[str, int] = Field(..., description="Count by type")
+    correlations_by_status: Dict[str, int] = Field(..., description="Count by status")
+
+    # Service metrics
+    service_calls: Dict[str, int] = Field(..., description="Calls by service type")
+    failed_calls: Dict[str, int] = Field(..., description="Failed calls by service")
+
+    # Performance metrics
+    avg_execution_time_ms: float = Field(..., description="Average execution time")
+    p95_execution_time_ms: float = Field(..., description="95th percentile execution time")
+    p99_execution_time_ms: float = Field(..., description="99th percentile execution time")
+
+    # Resource usage
+    total_tokens_used: int = Field(0, description="Total LLM tokens")
+    total_memory_bytes: int = Field(0, description="Total memory used")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+__all__ = [
+    "ServiceCorrelationStatus",
+    "CorrelationType",
+    "ServiceRequestData",
+    "ServiceResponseData",
+    "TraceContext",
+    "MetricData",
+    "LogData",
+    "ServiceCorrelation",
+    "CorrelationQuery",
+    "CorrelationSummary",
+]

ciris_engine/schemas/telemetry/unified.py

@@ -0,0 +1,59 @@
+"""
+Unified telemetry response schemas for v1.4.3.
+
+This provides typed response models for all telemetry endpoints,
+replacing Dict[str, Any] returns with proper Pydantic models.
+"""
+
+from datetime import datetime
+from typing import Any, Dict, List, Optional, Union
+
+from pydantic import BaseModel, Field, field_serializer
+
+# ============================================================================
+# RESOURCE METRICS - Fixes the duplicate ResourceMetricData issue
+# ============================================================================
+
+
+class MetricDataPoint(BaseModel):
+    """Single metric data point for time series."""
+
+    timestamp: datetime = Field(..., description="When metric was recorded")
+    value: float = Field(..., description="Metric value")
+    tags: Optional[Dict[str, str]] = Field(default=None, description="Metric tags")
+
+    @field_serializer("timestamp")
+    def serialize_timestamp(self, timestamp: datetime, _info: Any) -> str:
+        return timestamp.isoformat()
+
+
+class ResourceMetricWithStats(BaseModel):
+    """Resource metric with statistics - replaces dict format."""
+
+    data: List[MetricDataPoint] = Field(..., description="Time series data points")
+    stats: Dict[str, float] = Field(..., description="Statistical summary")
+    unit: str = Field(..., description="Metric unit")
+
+
+class ResourceTimeSeriesData(BaseModel):
+    """Time series data for resource metrics - unified model."""
+
+    metric_name: str = Field(..., description="Name of the metric")
+    data_points: List[MetricDataPoint] = Field(..., description="Time series data")
+    unit: str = Field(..., description="Metric unit")
+
+    # Statistics
+    current: float = Field(..., description="Current/latest value")
+    average: float = Field(..., description="Average over period")
+    min: float = Field(..., description="Minimum value in period")
+    max: float = Field(..., description="Maximum value in period")
+    percentile_95: float = Field(..., description="95th percentile")
+    trend: str = Field(..., description="Trend: up, down, or stable")
+
+
+# Export the specific models needed by telemetry.py
+__all__ = [
+    "MetricDataPoint",
+    "ResourceMetricWithStats",
+    "ResourceTimeSeriesData",
+]

ciris_engine/schemas/tools.py

@@ -0,0 +1,72 @@
+"""
+Tool schemas for CLI tools testing.
+
+These schemas are used by the CLI tools test suite.
+"""
+
+from datetime import datetime
+from enum import Enum
+from typing import Dict, List, Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from ciris_engine.schemas.types import ConfigValue, JSONDict
+
+
+class ParameterType(str, Enum):
+    """Parameter types for tools."""
+
+    STRING = "string"
+    NUMBER = "number"
+    BOOLEAN = "boolean"
+    OBJECT = "object"
+    ARRAY = "array"
+
+
+class ToolStatus(str, Enum):
+    """Status of tool execution."""
+
+    SUCCESS = "success"
+    ERROR = "error"
+    TIMEOUT = "timeout"
+    NOT_FOUND = "not_found"
+    UNAUTHORIZED = "unauthorized"
+
+
+class ToolParameter(BaseModel):
+    """Definition of a tool parameter."""
+
+    name: str = Field(..., description="Parameter name")
+    type: ParameterType = Field(..., description="Parameter type")
+    description: str = Field(..., description="Parameter description")
+    required: bool = Field(True, description="Whether parameter is required")
+    default: Optional[ConfigValue] = Field(None, description="Default value if not provided")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class Tool(BaseModel):
+    """Tool definition."""
+
+    name: str = Field(..., description="Tool name")
+    display_name: str = Field(..., description="Display name for the tool")
+    description: str = Field(..., description="What the tool does")
+    category: str = Field("general", description="Tool category")
+    parameters: List[ToolParameter] = Field(default_factory=list, description="Tool parameters")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class ToolResult(BaseModel):
+    """Result from tool execution."""
+
+    status: ToolStatus = Field(..., description="Execution status")
+    output: Optional[JSONDict] = Field(None, description="Tool output data")
+    error: Optional[str] = Field(None, description="Error message if failed")
+    execution_time: Optional[float] = Field(None, description="Execution time in seconds")
+    timestamp: Optional[datetime] = Field(None, description="When the tool was executed")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+__all__ = ["ParameterType", "ToolStatus", "ToolParameter", "Tool", "ToolResult"]

ciris_engine/schemas/types.py

@@ -0,0 +1,47 @@
+"""
+Common type aliases for CIRIS schemas.
+
+MIGRATION NOTE: This file is being phased out in favor of concrete Pydantic models.
+Only JSON serialization and configuration types remain as type aliases.
+For all other use cases, import the concrete model from its specific schema module.
+
+Type Alias Replacements:
+- EventData → Use ciris_engine.schemas.audit.core.AuditEventData
+- OAuthData → Use ciris_engine.schemas.infrastructure.oauth.OAuthTokenResponse or related models
+- ToolParameters → Use ciris_engine.schemas.tools.Tool.parameters (dict[str, ToolParameter])
+- ActionParameters → Use specific action param models from ciris_engine.schemas.actions.parameters
+- FilterConfig → Use ciris_engine.schemas.services.filters_core.FilterConfig
+- JSONDict → Use ciris_engine.schemas.services.graph/attributes.JSONDict
+- IdentityData → Use ciris_engine.schemas.infrastructure.identity_variance.IdentitySnapshot
+- StepData → Use ciris_engine.schemas.processors.state.StepContext or ProcessingContext
+"""
+
+from typing import Any, Dict, List, Union
+
+# JSON-compatible types - for serialization/deserialization ONLY
+# These are intentionally flexible for JSON I/O boundaries
+JSONValue = Union[str, int, float, bool, None, List[Any], Dict[str, Any]]
+JSONDict = Dict[str, JSONValue]
+JSONList = List[JSONValue]
+
+# Configuration values - for flexible configuration loading ONLY
+# These are intentionally flexible for config file parsing
+ConfigValue = Union[str, int, float, bool, List[Any], Dict[str, Any]]
+ConfigDict = Dict[str, ConfigValue]
+
+# DEPRECATED ALIASES - Do not use in new code, use concrete models instead
+# These exist temporarily for backwards compatibility during migration
+
+# SerializedModel represents Pydantic model.model_dump() output
+# Prefer: Use the actual Pydantic model type instead of dict
+SerializedModel = Dict[str, Any]
+
+# Export only the core type aliases still in use
+__all__ = [
+    "ConfigValue",
+    "ConfigDict",
+    "JSONValue",
+    "JSONDict",
+    "JSONList",
+    "SerializedModel",  # Deprecated, for backwards compat only
+]

ciris_engine/schemas/utils/__init__.py

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

ciris_engine/schemas/utils/config_validator.py

@@ -0,0 +1,54 @@
+"""
+Schemas for config validator operations.
+
+These replace all Dict[str, Any] usage in logic/utils/config_validator.py.
+"""
+
+from typing import List, Optional
+
+from pydantic import BaseModel, Field
+
+from ciris_engine.schemas.types import ConfigDict, ConfigValue
+
+
+class ConfigData(BaseModel):
+    """Configuration data for validation."""
+
+    llm_services: ConfigDict = Field(default_factory=dict, description="LLM services config")
+    database: ConfigDict = Field(default_factory=dict, description="Database config")
+    secrets: ConfigDict = Field(default_factory=dict, description="Secrets config")
+    additional_config: ConfigDict = Field(default_factory=dict, description="Other configuration")
+
+
+class LLMConfig(BaseModel):
+    """LLM configuration."""
+
+    openai: ConfigDict = Field(default_factory=dict, description="OpenAI config")
+    additional_providers: ConfigDict = Field(default_factory=dict, description="Other LLM providers")
+
+
+# OpenAIConfig moved to schemas/config/core.py to avoid duplication
+
+
+class DatabaseValidationConfig(BaseModel):
+    """Database configuration for validation."""
+
+    db_filename: Optional[str] = Field(None, description="Database filename")
+    additional_settings: ConfigDict = Field(default_factory=dict, description="Other database settings")
+
+
+class MaskedConfigResult(BaseModel):
+    """Result of masking sensitive configuration values."""
+
+    masked_config: ConfigDict = Field(..., description="Configuration with masked sensitive values")
+    masked_count: int = Field(0, description="Number of values masked")
+    masked_paths: List[str] = Field(default_factory=list, description="Paths that were masked")
+
+
+class NestedValueUpdate(BaseModel):
+    """Represents a nested value update operation."""
+
+    target_object: ConfigDict = Field(..., description="Object to update")
+    path: str = Field(..., description="Dot-separated path")
+    value: ConfigValue = Field(..., description="Value to set")
+    original_value: Optional[ConfigValue] = Field(None, description="Original value before update")

ciris_engine/utils/__init__.py

@@ -0,0 +1 @@
+"""Utilities module."""

ciris_engine/utils/serialization.py

@@ -0,0 +1,35 @@
+"""Serialization utilities for CIRIS."""
+
+from datetime import datetime
+from typing import Any, Optional
+
+
+def serialize_timestamp(timestamp: datetime, _info: Any = None) -> Optional[str]:
+    """
+    Standard timestamp serialization for Pydantic models.
+
+    Converts datetime to ISO format string for JSON serialization.
+
+    Args:
+        timestamp: The datetime to serialize
+        _info: Pydantic serialization info (unused but required for field_serializer)
+
+    Returns:
+        ISO format string or None if timestamp is None
+    """
+    return timestamp.isoformat() if timestamp else None
+
+
+def serialize_datetime(dt: datetime) -> Optional[str]:
+    """
+    Serialize datetime to ISO format.
+
+    Simple version without the _info parameter for non-Pydantic use.
+
+    Args:
+        dt: The datetime to serialize
+
+    Returns:
+        ISO format string or None if dt is None
+    """
+    return dt.isoformat() if dt else None

ciris_sdk/__init__.py

@@ -0,0 +1,124 @@
+"""
+CIRIS SDK for v1 API (Pre-Beta).
+
+**WARNING**: This SDK is for the v1 API which is in pre-beta stage.
+The API and SDK interfaces may change without notice.
+No backwards compatibility is guaranteed.
+"""
+
+from .client import CIRISClient
+from .models import (  # Legacy models; Telemetry models; Other models
+    AdapterInfo,
+    AuditEntriesResponse,
+    AuditEntryResponse,
+    AuditExportResponse,
+    DeferralInfo,
+    MemoryEntry,
+    MemoryOpResult,
+    MemoryScope,
+    Message,
+    MetricRecord,
+    ProcessorControlResponse,
+    ProcessorState,
+    RuntimeStatus,
+    ServiceInfo,
+    SystemHealth,
+    TelemetryDetailedMetric,
+    TelemetryLogEntry,
+    TelemetryMetricData,
+    TelemetryReasoningTrace,
+    TelemetrySystemOverview,
+)
+from .resources.agent import (
+    AgentIdentity,
+    AgentStatus,
+    ConversationHistory,
+    ConversationMessage,
+    InteractResponse,
+    MessageRequest,
+    MessageSubmissionResponse,
+)
+from .resources.consent import (
+    ConsentAction,
+    ConsentRecord,
+    ConsentRequest,
+    ConsentResponse,
+    ConsentScope,
+    ConsentStatus,
+)
+from .resources.emergency import EmergencyCommandType, EmergencyShutdownResponse, WASignedCommand
+from .resources.memory import GraphNode, MemoryQueryResponse, MemoryStoreResponse, TimelineResponse
+from .resources.system import (
+    ResourceUsageResponse,
+    RuntimeControlResponse,
+    ServicesStatusResponse,
+    ShutdownResponse,
+    SystemHealthResponse,
+    SystemTimeResponse,
+)
+from .websocket import EventChannel, WebSocketClient
+
+__all__ = [
+    "CIRISClient",
+    "WebSocketClient",
+    "EventChannel",
+    # Agent interaction types
+    "InteractResponse",
+    "MessageRequest",
+    "MessageSubmissionResponse",
+    "AgentStatus",
+    "AgentIdentity",
+    "ConversationHistory",
+    "ConversationMessage",
+    # Memory types
+    "GraphNode",
+    "MemoryStoreResponse",
+    "MemoryQueryResponse",
+    "TimelineResponse",
+    # System types
+    "SystemHealthResponse",
+    "SystemTimeResponse",
+    "ResourceUsageResponse",
+    "RuntimeControlResponse",
+    "ServicesStatusResponse",
+    "ShutdownResponse",
+    # Consent types
+    "ConsentAction",
+    "ConsentScope",
+    "ConsentStatus",
+    "ConsentRequest",
+    "ConsentResponse",
+    "ConsentRecord",
+    # Emergency types
+    "EmergencyShutdownResponse",
+    "WASignedCommand",
+    "EmergencyCommandType",
+    # Legacy models
+    "MemoryEntry",
+    "MemoryScope",
+    "MemoryOpResult",
+    # Telemetry
+    "TelemetryMetricData",
+    "TelemetryDetailedMetric",
+    "TelemetrySystemOverview",
+    "TelemetryReasoningTrace",
+    "TelemetryLogEntry",
+    # Other models
+    "Message",
+    "ProcessorControlResponse",
+    "AdapterInfo",
+    "RuntimeStatus",
+    "SystemHealth",
+    "ServiceInfo",
+    "ProcessorState",
+    "MetricRecord",
+    "DeferralInfo",
+    "AuditEntryResponse",
+    "AuditEntriesResponse",
+    "AuditExportResponse",
+]
+
+# Version indicator for v1 API
+from ciris_engine.constants import CIRIS_VERSION
+
+__version__ = CIRIS_VERSION