ciris-agent 1.7.7__py3-none-any.whl

ciris_engine/schemas/services/graph/incident.py

@@ -0,0 +1,312 @@
+"""
+Incident management schemas for graph-based incident tracking.
+
+These schemas support ITIL-aligned incident processing for self-improvement.
+"""
+
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Any, Dict, List, Optional
+
+from pydantic import Field
+
+from ciris_engine.schemas.services.graph_core import GraphNode, GraphScope, NodeType
+from ciris_engine.schemas.services.graph_typed_nodes import TypedGraphNode, register_node_type
+from ciris_engine.schemas.types import JSONDict
+
+
+class IncidentSeverity(str, Enum):
+    """Incident severity levels aligned with ITIL."""
+
+    CRITICAL = "CRITICAL"  # Service down, major impact
+    HIGH = "HIGH"  # Significant degradation
+    MEDIUM = "MEDIUM"  # Minor degradation
+    LOW = "LOW"  # Informational
+
+
+class IncidentStatus(str, Enum):
+    """Incident lifecycle status."""
+
+    OPEN = "OPEN"
+    INVESTIGATING = "INVESTIGATING"
+    RESOLVED = "RESOLVED"
+    CLOSED = "CLOSED"
+    RECURRING = "RECURRING"  # Linked to a problem
+
+
+@register_node_type("INCIDENT")
+class IncidentNode(TypedGraphNode):
+    """Represents an incident captured from WARNING/ERROR logs."""
+
+    # Base fields (inherited from GraphNode)
+    type: NodeType = Field(default=NodeType.AUDIT_ENTRY, description="Node type")
+    scope: GraphScope = Field(default=GraphScope.LOCAL, description="Node scope")
+
+    # Incident specific fields (stored in attributes)
+    incident_type: str = Field(..., description="Type of incident (ERROR, WARNING, EXCEPTION)")
+    severity: IncidentSeverity = Field(..., description="Incident severity")
+    status: IncidentStatus = Field(IncidentStatus.OPEN, description="Current incident status")
+
+    # Incident details
+    description: str = Field(..., description="Incident description from log message")
+    source_component: str = Field(..., description="Component that generated the incident")
+    detection_method: str = Field("AUTOMATED_LOG_MONITORING", description="How incident was detected")
+
+    # Timing
+    detected_at: datetime = Field(..., description="When incident was detected")
+    resolved_at: Optional[datetime] = Field(None, description="When incident was resolved")
+
+    # Impact assessment
+    impact: Optional[str] = Field(None, description="Business/operational impact")
+    urgency: Optional[str] = Field(None, description="How quickly this needs attention")
+
+    # Tracing data (correlation with other system components)
+    correlation_id: Optional[str] = Field(None, description="Correlation ID for distributed tracing")
+    task_id: Optional[str] = Field(None, description="Related task ID if applicable")
+    thought_id: Optional[str] = Field(None, description="Related thought ID if applicable")
+    handler_name: Optional[str] = Field(None, description="Handler that was executing")
+
+    # Technical details
+    exception_type: Optional[str] = Field(None, description="Exception class name if applicable")
+    stack_trace: Optional[str] = Field(None, description="Stack trace if available")
+    filename: str = Field(..., description="Source file")
+    line_number: int = Field(..., description="Line number")
+    function_name: Optional[str] = Field(None, description="Function name")
+
+    # Relationships
+    problem_id: Optional[str] = Field(None, description="Linked problem if this is recurring")
+    related_incidents: List[str] = Field(default_factory=list, description="Related incident IDs")
+
+    def to_graph_node(self) -> GraphNode:
+        """Convert to generic GraphNode for storage."""
+        # Serialize extra fields only
+        extra_data = self._serialize_extra_fields()
+
+        # Handle datetime fields
+        if self.detected_at:
+            extra_data["detected_at"] = self.detected_at.isoformat()
+        if self.resolved_at:
+            extra_data["resolved_at"] = self.resolved_at.isoformat()
+
+        # Handle enums
+        extra_data["severity"] = self.severity.value
+        extra_data["status"] = self.status.value
+
+        return GraphNode(
+            id=self.id,
+            type=self.type,
+            scope=self.scope,
+            attributes=extra_data,
+            version=self.version,
+            updated_by=self.updated_by,
+            updated_at=self.updated_at,
+        )
+
+    @classmethod
+    def from_graph_node(cls, node: GraphNode) -> "IncidentNode":
+        """Reconstruct from GraphNode."""
+        attrs = node.attributes if isinstance(node.attributes, dict) else node.attributes.model_dump()
+        attrs.pop("node_class", None)
+
+        # Handle datetime deserialization - extract and convert, don't modify attrs
+        detected_at = cls._deserialize_datetime(attrs.get("detected_at")) if "detected_at" in attrs else None
+        resolved_at = cls._deserialize_datetime(attrs.get("resolved_at")) if "resolved_at" in attrs else None
+
+        # Handle enum deserialization - extract and convert, don't modify attrs
+        severity = IncidentSeverity(attrs["severity"]) if "severity" in attrs else IncidentSeverity.LOW
+        status = IncidentStatus(attrs["status"]) if "status" in attrs else IncidentStatus.OPEN
+
+        # Remove these from attrs so they don't conflict with kwargs
+        attrs.pop("detected_at", None)
+        attrs.pop("resolved_at", None)
+        attrs.pop("severity", None)
+        attrs.pop("status", None)
+
+        # Fall back to values from attributes if the GraphNode fields are None
+        updated_by = node.updated_by or attrs.get("created_by", "unknown")
+        updated_at = node.updated_at or cls._deserialize_datetime(attrs.get("updated_at", attrs.get("created_at")))
+
+        return cls(
+            # Base fields from GraphNode
+            id=node.id,
+            type=node.type,
+            scope=node.scope,
+            attributes=node.attributes,  # Must pass this for GraphNode base class
+            version=node.version,
+            updated_by=updated_by,
+            updated_at=updated_at or datetime.now(timezone.utc),
+            # Datetime fields
+            detected_at=detected_at or datetime.now(timezone.utc),
+            resolved_at=resolved_at,
+            # Enum fields
+            severity=severity,
+            status=status,
+            # Extra fields from attributes
+            **attrs
+        )
+
+
+@register_node_type("PROBLEM")
+class ProblemNode(TypedGraphNode):
+    """Represents a problem (root cause) identified from incident patterns."""
+
+    # Base fields
+    type: NodeType = Field(default=NodeType.CONCEPT, description="Node type")
+    scope: GraphScope = Field(default=GraphScope.IDENTITY, description="Node scope")
+
+    problem_statement: str = Field(..., description="Description of the problem")
+    affected_incidents: List[str] = Field(..., description="Incident IDs linked to this problem")
+    status: str = Field("UNDER_INVESTIGATION", description="Problem status")
+
+    # Analysis
+    potential_root_causes: List[str] = Field(default_factory=list, description="Possible root causes")
+    recommended_actions: List[str] = Field(default_factory=list, description="Suggested fixes")
+
+    # Metrics
+    incident_count: int = Field(..., description="Number of related incidents")
+    first_occurrence: datetime = Field(..., description="When first incident occurred")
+    last_occurrence: datetime = Field(..., description="Most recent incident")
+
+    # Resolution
+    resolution: Optional[str] = Field(None, description="How the problem was resolved")
+    resolved_at: Optional[datetime] = Field(None, description="When problem was resolved")
+
+    def to_graph_node(self) -> GraphNode:
+        """Convert to generic GraphNode for storage."""
+        extra_data = self._serialize_extra_fields()
+
+        # Handle datetime fields
+        if self.first_occurrence:
+            extra_data["first_occurrence"] = self.first_occurrence.isoformat()
+        if self.last_occurrence:
+            extra_data["last_occurrence"] = self.last_occurrence.isoformat()
+        if self.resolved_at:
+            extra_data["resolved_at"] = self.resolved_at.isoformat()
+
+        return GraphNode(
+            id=self.id,
+            type=self.type,
+            scope=self.scope,
+            attributes=extra_data,
+            version=self.version,
+            updated_by=self.updated_by,
+            updated_at=self.updated_at,
+        )
+
+    @classmethod
+    def from_graph_node(cls, node: GraphNode) -> "ProblemNode":
+        """Reconstruct from GraphNode."""
+        attrs = node.attributes if isinstance(node.attributes, dict) else node.attributes.model_dump()
+        attrs.pop("node_class", None)
+
+        # Handle datetime deserialization - extract and convert, don't modify attrs
+        first_occurrence = (
+            cls._deserialize_datetime(attrs.get("first_occurrence")) if "first_occurrence" in attrs else None
+        )
+        last_occurrence = (
+            cls._deserialize_datetime(attrs.get("last_occurrence")) if "last_occurrence" in attrs else None
+        )
+        resolved_at = cls._deserialize_datetime(attrs.get("resolved_at")) if "resolved_at" in attrs else None
+
+        # Remove these from attrs so they don't conflict with kwargs
+        attrs.pop("first_occurrence", None)
+        attrs.pop("last_occurrence", None)
+        attrs.pop("resolved_at", None)
+
+        # Fall back to values from attributes if the GraphNode fields are None
+        updated_by = node.updated_by or attrs.get("created_by", "unknown")
+        updated_at = node.updated_at or cls._deserialize_datetime(attrs.get("updated_at", attrs.get("created_at")))
+
+        return cls(
+            # Base fields from GraphNode
+            id=node.id,
+            type=node.type,
+            scope=node.scope,
+            attributes=node.attributes,
+            version=node.version,
+            updated_by=updated_by,
+            updated_at=updated_at or datetime.now(timezone.utc),
+            # Datetime fields
+            first_occurrence=first_occurrence or datetime.now(timezone.utc),
+            last_occurrence=last_occurrence or datetime.now(timezone.utc),
+            resolved_at=resolved_at,
+            # Extra fields from attributes
+            **attrs
+        )
+
+
+@register_node_type("INCIDENT_INSIGHT")
+class IncidentInsightNode(TypedGraphNode):
+    """Represents insights derived from incident analysis during dream cycles."""
+
+    # Base fields
+    type: NodeType = Field(default=NodeType.CONCEPT, description="Node type")
+    scope: GraphScope = Field(default=GraphScope.LOCAL, description="Node scope")
+
+    insight_type: str = Field(..., description="Type of insight (PERIODIC_ANALYSIS, PATTERN_DETECTED, etc.)")
+    summary: str = Field(..., description="High-level summary of the insight")
+    details: JSONDict = Field(default_factory=dict, description="Detailed analysis results")
+
+    # Recommendations
+    behavioral_adjustments: List[str] = Field(default_factory=list, description="Suggested behavioral changes")
+    configuration_changes: List[str] = Field(default_factory=list, description="Suggested config changes")
+
+    # Traceability
+    source_incidents: List[str] = Field(default_factory=list, description="Incident IDs analyzed")
+    source_problems: List[str] = Field(default_factory=list, description="Problem IDs referenced")
+    analysis_timestamp: datetime = Field(..., description="When analysis was performed")
+
+    # Effectiveness tracking
+    applied: bool = Field(False, description="Whether recommendations were applied")
+    effectiveness_score: Optional[float] = Field(None, description="How effective the changes were (0-1)")
+
+    def to_graph_node(self) -> GraphNode:
+        """Convert to generic GraphNode for storage."""
+        extra_data = self._serialize_extra_fields()
+
+        # Handle datetime fields
+        if self.analysis_timestamp:
+            extra_data["analysis_timestamp"] = self.analysis_timestamp.isoformat()
+
+        return GraphNode(
+            id=self.id,
+            type=self.type,
+            scope=self.scope,
+            attributes=extra_data,
+            version=self.version,
+            updated_by=self.updated_by,
+            updated_at=self.updated_at,
+        )
+
+    @classmethod
+    def from_graph_node(cls, node: GraphNode) -> "IncidentInsightNode":
+        """Reconstruct from GraphNode."""
+        attrs = node.attributes if isinstance(node.attributes, dict) else node.attributes.model_dump()
+        attrs.pop("node_class", None)
+
+        # Handle datetime deserialization - extract and convert, don't modify attrs
+        analysis_timestamp = (
+            cls._deserialize_datetime(attrs.get("analysis_timestamp")) if "analysis_timestamp" in attrs else None
+        )
+
+        # Remove from attrs so it doesn't conflict with kwargs
+        attrs.pop("analysis_timestamp", None)
+
+        # Fall back to values from attributes if the GraphNode fields are None
+        updated_by = node.updated_by or attrs.get("created_by", "unknown")
+        updated_at = node.updated_at or cls._deserialize_datetime(attrs.get("updated_at", attrs.get("created_at")))
+
+        return cls(
+            # Base fields from GraphNode
+            id=node.id,
+            type=node.type,
+            scope=node.scope,
+            attributes=node.attributes,
+            version=node.version,
+            updated_by=updated_by,
+            updated_at=updated_at or datetime.now(timezone.utc),
+            # Datetime field
+            analysis_timestamp=analysis_timestamp or datetime.now(timezone.utc),
+            # Extra fields from attributes
+            **attrs
+        )

ciris_engine/schemas/services/graph/memory.py

@@ -0,0 +1,84 @@
+"""
+Graph memory service schemas.
+
+Provides typed schemas in memory service operations.
+"""
+
+from datetime import datetime
+from typing import Any, Dict, List, Optional, Union
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from ciris_engine.schemas.types import JSONDict
+
+
+class MemoryNodeData(BaseModel):
+    """Attributes for a graph node."""
+
+    # Core attributes
+    created_at: Optional[datetime] = Field(None, description="Creation timestamp")
+    updated_at: Optional[datetime] = Field(None, description="Last update timestamp")
+    created_by: Optional[str] = Field(None, description="Creator identifier")
+
+    # Secret references
+    secret_refs: List[str] = Field(default_factory=list, description="Secret reference UUIDs")
+
+    # Dynamic attributes - we use a constrained dict here since node attributes are truly dynamic
+    # but we ensure they're JSON-serializable types
+    data: JSONDict = Field(default_factory=dict, description="Node data attributes")
+
+    model_config = ConfigDict(extra="allow")  # Allow additional fields for flexibility
+
+
+class MemorySearchFilter(BaseModel):
+    """Filters for memory search operations."""
+
+    node_type: Optional[str] = Field(None, description="Filter by node type")
+    scope: Optional[str] = Field(None, description="Filter by scope")
+    created_after: Optional[datetime] = Field(None, description="Filter by creation date")
+    created_before: Optional[datetime] = Field(None, description="Filter by creation date")
+    created_by: Optional[str] = Field(None, description="Filter by creator")
+    has_attributes: Optional[List[str]] = Field(None, description="Must have these attributes")
+    attribute_values: Optional[Dict[str, Union[str, int, float, bool]]] = Field(
+        None, description="Attribute value filters"
+    )
+    limit: Optional[int] = Field(None, description="Maximum results")
+    offset: Optional[int] = Field(None, description="Results offset")
+
+
+class GraphQuery(BaseModel):
+    """Query parameters for graph operations."""
+
+    # Query type
+    query_type: str = Field(..., description="Type of query: match, traverse, aggregate")
+
+    # Node filters
+    node_filters: Optional[MemorySearchFilter] = Field(None, description="Node filters")
+
+    # Relationship filters
+    relationship_type: Optional[str] = Field(None, description="Filter by relationship type")
+    relationship_direction: Optional[str] = Field("any", description="in, out, any")
+
+    # Traversal options
+    max_depth: Optional[int] = Field(None, description="Maximum traversal depth")
+    include_relationships: bool = Field(False, description="Include relationships in results")
+
+    # Aggregation options
+    group_by: Optional[str] = Field(None, description="Attribute to group by")
+    aggregations: Optional[List[str]] = Field(None, description="Aggregation functions")
+
+    # Result options
+    order_by: Optional[str] = Field(None, description="Attribute to order by")
+    order_desc: bool = Field(False, description="Order descending")
+    limit: Optional[int] = Field(None, description="Result limit")
+
+
+class MemoryOperationContext(BaseModel):
+    """Context for memory operations."""
+
+    operation: str = Field(..., description="Operation being performed")
+    action_type: Optional[str] = Field(None, description="Associated action type")
+    auto_decrypt: bool = Field(False, description="Whether to auto-decrypt secrets")
+    channel_id: Optional[str] = Field(None, description="Channel context")
+    user_id: Optional[str] = Field(None, description="User context")
+    metadata: Dict[str, str] = Field(default_factory=dict, description="Additional metadata")

ciris_engine/schemas/services/graph/node_data.py

@@ -0,0 +1,174 @@
+"""
+Typed node data schemas for graph nodes.
+
+Replaces the generic JSONDict.data: Dict[str, Union[...]] with specific typed schemas.
+"""
+
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional, Union
+
+from pydantic import BaseModel, ConfigDict, Field, field_serializer
+
+from ciris_engine.schemas.types import JSONDict
+
+
+class ValidationRule(BaseModel):
+    """A single validation rule for configuration."""
+
+    rule_type: str = Field(..., description="Type of validation: range, regex, enum, etc.")
+    parameters: Dict[str, Union[str, int, float, bool]] = Field(..., description="Rule parameters")
+    error_message: Optional[str] = Field(None, description="Custom error message")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class BaseNodeData(BaseModel):
+    """Base class for all typed node data."""
+
+    version: int = Field(1, description="Schema version for migration")
+    created_at: datetime = Field(..., description="When this data was created")
+    updated_at: datetime = Field(..., description="Last update time")
+
+    model_config = ConfigDict(extra="forbid")  # No extra fields allowed
+
+    @field_serializer("created_at", "updated_at")
+    def serialize_datetime(self, dt: datetime) -> str:
+        return dt.isoformat()
+
+
+class ConfigNodeData(BaseNodeData):
+    """Data for configuration nodes."""
+
+    key: str = Field(..., description="Configuration key")
+    value: Union[str, int, float, bool, List[str], Dict[str, str]] = Field(..., description="Configuration value")
+    description: Optional[str] = Field(None, description="What this config controls")
+    category: Optional[str] = Field(None, description="Config category: ethical, operational, etc.")
+    is_sensitive: bool = Field(False, description="Whether this is a sensitive config")
+    validation_rules: Optional[List[ValidationRule]] = Field(None, description="Validation rules for this config")
+
+
+class TelemetryNodeData(BaseNodeData):
+    """Data for telemetry/metrics nodes."""
+
+    metric_name: str = Field(..., description="Name of the metric")
+    metric_value: float = Field(..., description="Numeric value")
+    metric_type: str = Field(..., description="Type: counter, gauge, histogram")
+    unit: Optional[str] = Field(None, description="Unit of measurement")
+    labels: Dict[str, str] = Field(default_factory=dict, description="Metric labels")
+    aggregation_type: Optional[str] = Field(None, description="How to aggregate: sum, avg, max, min")
+
+    # For time-series data
+    start_time: Optional[datetime] = Field(None, description="Start of measurement period")
+    end_time: Optional[datetime] = Field(None, description="End of measurement period")
+    sample_count: Optional[int] = Field(None, description="Number of samples in this period")
+
+
+class AuditNodeData(BaseNodeData):
+    """Data for audit event nodes."""
+
+    event_type: str = Field(..., description="Type of audit event")
+    event_category: str = Field(..., description="Category: security, compliance, operational")
+    actor: str = Field(..., description="Who/what triggered this event")
+    target: Optional[str] = Field(None, description="What was affected")
+    action: str = Field(..., description="What action was taken")
+    outcome: str = Field(..., description="Result: success, failure, partial")
+
+    # Additional context
+    ip_address: Optional[str] = Field(None, description="Source IP if applicable")
+    user_agent: Optional[str] = Field(None, description="User agent if applicable")
+    correlation_id: Optional[str] = Field(None, description="For tracing related events")
+    risk_score: Optional[float] = Field(None, description="Risk assessment 0.0-1.0")
+
+    # Evidence/details
+    evidence: Dict[str, str] = Field(default_factory=dict, description="Supporting evidence")
+    error_details: Optional[str] = Field(None, description="Error message if failed")
+
+
+class MemoryNodeData(BaseNodeData):
+    """Data for memory/knowledge nodes."""
+
+    content: str = Field(..., description="The actual memory content")
+    memory_type: str = Field(..., description="Type: fact, experience, learning, insight")
+    source: str = Field(..., description="Where this memory came from")
+
+    # Relationships
+    related_memories: List[str] = Field(default_factory=list, description="Related memory node IDs")
+    derived_from: Optional[str] = Field(None, description="Parent memory if derived")
+
+    # Usage tracking
+    access_count: int = Field(0, description="How often accessed")
+    last_accessed: Optional[datetime] = Field(None, description="Last access time")
+    importance_score: float = Field(0.5, description="Importance 0.0-1.0")
+
+
+class TaskNodeData(BaseNodeData):
+    """Data for task-related nodes."""
+
+    task_id: str = Field(..., description="Associated task ID")
+    task_type: str = Field(..., description="Type of task")
+    status: str = Field(..., description="Current status")
+    priority: int = Field(0, description="Task priority")
+
+    # Task details
+    description: str = Field(..., description="What this task is about")
+    requester: Optional[str] = Field(None, description="Who requested this")
+    deadline: Optional[datetime] = Field(None, description="When it's due")
+
+    # Progress tracking
+    progress_percentage: float = Field(0.0, description="Completion percentage")
+    milestones: List[str] = Field(default_factory=list, description="Completed milestones")
+    blockers: List[str] = Field(default_factory=list, description="Current blockers")
+
+    @field_serializer("deadline")
+    def serialize_optional_datetime(self, dt: Optional[datetime]) -> Optional[str]:
+        return dt.isoformat() if dt else None
+
+
+class EnvironmentNodeData(BaseNodeData):
+    """Data for environment/context nodes."""
+
+    environment_type: str = Field(..., description="Type: channel, user, system")
+    identifier: str = Field(..., description="Unique identifier")
+    display_name: Optional[str] = Field(None, description="Human-readable name")
+
+    # Context details
+    properties: Dict[str, str] = Field(default_factory=dict, description="Environment properties")
+    capabilities: List[str] = Field(default_factory=list, description="What this environment supports")
+    restrictions: List[str] = Field(default_factory=list, description="What's not allowed")
+
+    # State tracking
+    is_active: bool = Field(True, description="Whether currently active")
+    last_interaction: Optional[datetime] = Field(None, description="Last interaction time")
+    interaction_count: int = Field(0, description="Total interactions")
+
+
+# Type alias for all possible node data types
+NodeData = Union[ConfigNodeData, TelemetryNodeData, AuditNodeData, MemoryNodeData, TaskNodeData, EnvironmentNodeData]
+
+
+def create_node_data(
+    node_type: str, data: Dict[str, Any]
+) -> NodeData:  # NOQA: Modifies dict to add datetime objects for model construction
+    """Factory function to create appropriate node data based on type."""
+    type_map = {
+        "config": ConfigNodeData,
+        "telemetry": TelemetryNodeData,
+        "audit": AuditNodeData,
+        "memory": MemoryNodeData,
+        "task": TaskNodeData,
+        "environment": EnvironmentNodeData,
+    }
+
+    data_class = type_map.get(node_type)
+    if not data_class:
+        raise ValueError(f"Unknown node type: {node_type}")
+
+    # Add timestamps if not present
+    now = datetime.now(timezone.utc)
+    if "created_at" not in data:
+        data["created_at"] = now
+    if "updated_at" not in data:
+        data["updated_at"] = now
+
+    # Create instance and cast to appropriate type
+    return data_class(**data)  # type: ignore[no-any-return]

ciris_engine/schemas/services/graph/query_results.py

@@ -0,0 +1,82 @@
+"""
+Query result schemas for TSDB consolidation service.
+
+These schemas provide type-safe alternatives to Dict[str, Any] returns.
+"""
+
+from datetime import datetime
+from typing import Any, Dict, List, Optional, Union
+
+from pydantic import BaseModel, Field
+
+from ciris_engine.schemas.services.graph.consolidation import (
+    MetricCorrelationData,
+    ServiceInteractionData,
+    TaskCorrelationData,
+    TraceSpanData,
+)
+from ciris_engine.schemas.services.graph_core import GraphNode
+
+
+class ServiceCorrelationQueryResult(BaseModel):
+    """Result of querying service correlations."""
+
+    service_interactions: List[ServiceInteractionData] = Field(
+        default_factory=list, description="Service interaction correlations"
+    )
+    metric_correlations: List[MetricCorrelationData] = Field(default_factory=list, description="Metric correlations")
+    trace_spans: List[TraceSpanData] = Field(default_factory=list, description="Trace span correlations")
+    task_correlations: List[TaskCorrelationData] = Field(default_factory=list, description="Task correlations")
+
+    def to_dict_by_type(
+        self,
+    ) -> Dict[
+        str,
+        Union[
+            List[ServiceInteractionData], List[MetricCorrelationData], List[TraceSpanData], List[TaskCorrelationData]
+        ],
+    ]:
+        """Convert to dictionary keyed by correlation type."""
+        return {
+            "service_interactions": self.service_interactions,
+            "metric_correlations": self.metric_correlations,
+            "trace_spans": self.trace_spans,
+            "task_correlations": self.task_correlations,
+        }
+
+
+class TSDBNodeQueryResult(BaseModel):
+    """Result of querying TSDB nodes."""
+
+    nodes: List[GraphNode] = Field(default_factory=list, description="TSDB data nodes")
+    period_start: datetime = Field(..., description="Query period start")
+    period_end: datetime = Field(..., description="Query period end")
+    count: int = Field(0, description="Number of nodes found")
+
+    def __init__(self, **data: Any) -> None:
+        super().__init__(**data)
+        self.count = len(self.nodes)
+
+
+class EdgeQueryResult(BaseModel):
+    """Result of querying edges between nodes."""
+
+    source_id: str = Field(..., description="Source node ID")
+    target_id: str = Field(..., description="Target node ID")
+    edge_type: str = Field(..., description="Type of edge")
+    properties: Dict[str, str] = Field(default_factory=dict, description="Edge properties")
+    created_at: Optional[datetime] = Field(None, description="Edge creation time")
+
+
+class ConsolidationSummary(BaseModel):
+    """Summary of a consolidation operation."""
+
+    consolidation_id: str = Field(..., description="Unique consolidation ID")
+    period_start: datetime = Field(..., description="Consolidation period start")
+    period_end: datetime = Field(..., description="Consolidation period end")
+    nodes_created: int = Field(0, description="Number of nodes created")
+    edges_created: int = Field(0, description="Number of edges created")
+    correlations_processed: int = Field(0, description="Number of correlations processed")
+    success: bool = Field(True, description="Whether consolidation succeeded")
+    error_message: Optional[str] = Field(None, description="Error message if failed")
+    execution_time_ms: float = Field(0.0, description="Execution time in milliseconds")