ciris-agent 1.7.7__py3-none-any.whl

ciris_engine/schemas/handlers/contexts.py

@@ -0,0 +1,100 @@
+"""
+Action context schemas for contract-driven architecture.
+
+Replaces context: Dict[str, Any] for each action type.
+"""
+
+from datetime import datetime
+from typing import Dict, List, Literal, Optional
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class BaseActionContext(BaseModel):
+    """Base context shared by all actions."""
+
+    task_id: UUID = Field(..., description="Current task ID")
+    thought_id: UUID = Field(..., description="Current thought ID")
+    correlation_id: UUID = Field(..., description="Correlation ID for tracing")
+    channel_id: str = Field(..., description="Channel where action occurs")
+    user_id: Optional[str] = Field(None, description="User requesting action")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class SpeakContext(BaseActionContext):
+    """Context for SPEAK action."""
+
+    message_type: Literal["response", "notification", "error"] = Field("response", description="Type of message")
+    reply_to_message_id: Optional[str] = Field(None, description="Message being replied to")
+
+
+class ToolContext(BaseActionContext):
+    """Context for TOOL action."""
+
+    tool_name: str = Field(..., description="Name of tool to execute")
+    tool_version: Optional[str] = Field(None, description="Tool version")
+    execution_timeout: Optional[float] = Field(30.0, description="Timeout in seconds")
+
+
+class ObserveContext(BaseActionContext):
+    """Context for OBSERVE action."""
+
+    observation_type: Literal["channel", "user", "system"] = Field("channel", description="What to observe")
+    observation_window: Optional[int] = Field(100, description="Number of messages to observe")
+
+
+class MemorizeContext(BaseActionContext):
+    """Context for MEMORIZE action."""
+
+    memory_type: str = Field(..., description="Type of memory to store")
+    memory_scope: Literal["task", "conversation", "global"] = Field("task", description="Scope of memory")
+    retention_policy: Optional[str] = Field(None, description="How long to retain")
+
+
+class RecallContext(BaseActionContext):
+    """Context for RECALL action."""
+
+    memory_type: str = Field(..., description="Type of memory to recall")
+    memory_scope: Literal["task", "conversation", "global"] = Field("task", description="Scope to search")
+    time_range: Optional[Dict[str, datetime]] = Field(None, description="Time range to search")
+
+
+class ForgetContext(BaseActionContext):
+    """Context for FORGET action."""
+
+    memory_type: str = Field(..., description="Type of memory to forget")
+    reason: str = Field(..., description="Reason for forgetting")
+    permanent: bool = Field(False, description="Whether deletion is permanent")
+
+
+class RejectContext(BaseActionContext):
+    """Context for REJECT action."""
+
+    rejection_reason: str = Field(..., description="Why request was rejected")
+    rejection_category: Literal["ethical", "capability", "safety"] = Field(
+        "safety", description="Category of rejection"
+    )
+
+
+class PonderContext(BaseActionContext):
+    """Context for PONDER action."""
+
+    questions: List[str] = Field(..., description="Questions to ponder")
+    ponder_depth: int = Field(1, description="Depth of pondering")
+
+
+class DeferContext(BaseActionContext):
+    """Context for DEFER action."""
+
+    deferral_reason: str = Field(..., description="Why deferring to authority")
+    required_authority: str = Field("AUTHORITY", description="Required authority level")
+    urgency: Literal["low", "medium", "high"] = Field("medium", description="Urgency level")
+
+
+class TaskCompleteContext(BaseActionContext):
+    """Context for TASK_COMPLETE action."""
+
+    completion_status: Literal["success", "partial", "failure"] = Field("success", description="Completion status")
+    completion_message: Optional[str] = Field(None, description="Completion message")

ciris_engine/schemas/handlers/core.py

@@ -0,0 +1,167 @@
+"""
+Deferral schemas for CIRIS.
+
+Provides type-safe structures for deferral handling.
+"""
+
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Dict, List, Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class DeferralReason(str, Enum):
+    """Standard deferral reason codes."""
+
+    conscience_FAILURE = "conscience_failure"
+    MAX_ROUNDS_REACHED = "max_rounds_reached"
+    CHANNEL_POLICY_UPDATE = "channel_policy_update"
+    INSUFFICIENT_CONTEXT = "insufficient_context"
+    ETHICAL_CONCERN = "ethical_concern"
+    SYSTEM_ERROR = "system_error"
+    WA_REVIEW_REQUIRED = "wa_review_required"
+    MEMORY_CONFLICT = "memory_conflict"
+    UNKNOWN = "unknown"
+
+
+class EthicalAssessment(BaseModel):
+    """Ethical evaluation results."""
+
+    decision: str = Field(..., description="approve, reject, defer")
+    reasoning: str = Field(..., description="Explanation")
+    principles_upheld: List[str] = Field(default_factory=list)
+    principles_violated: List[str] = Field(default_factory=list)
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class CSDMAAssessment(BaseModel):
+    """Common sense evaluation results."""
+
+    makes_sense: bool = Field(..., description="Whether action makes sense")
+    practicality_score: float = Field(..., ge=0.0, le=1.0)
+    flags: List[str] = Field(default_factory=list, description="Common sense flags")
+    reasoning: str = Field(..., description="Explanation")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class DSDMAAssessment(BaseModel):
+    """Domain-specific evaluation results."""
+
+    domain: str = Field(..., description="Domain of expertise")
+    alignment_score: float = Field(..., ge=0.0, le=1.0)
+    recommendations: List[str] = Field(default_factory=list)
+    reasoning: str = Field(..., description="Explanation")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class ActionHistoryItem(BaseModel):
+    """A single action in history."""
+
+    action_type: str = Field(..., description="Type of action taken")
+    timestamp: datetime = Field(..., description="When action occurred")
+    parameters: Dict[str, str] = Field(default_factory=dict, description="Action parameters")
+    result: Optional[str] = Field(None, description="Action result")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class DeferralPackage(BaseModel):
+    """Complete context package for deferred decisions."""
+
+    thought_id: str = Field(..., description="ID of deferred thought")
+    task_id: str = Field(..., description="ID of associated task")
+    deferral_reason: DeferralReason = Field(..., description="Reason code")
+    reason_description: str = Field(..., description="Human-readable reason")
+
+    # Core content
+    thought_content: str = Field(..., description="The thought being deferred")
+    task_description: Optional[str] = Field(None, description="Task description")
+
+    # Assessments (no Dict[str, Any]!)
+    ethical_assessment: Optional[EthicalAssessment] = Field(None)
+    csdma_assessment: Optional[CSDMAAssessment] = Field(None)
+    dsdma_assessment: Optional[DSDMAAssessment] = Field(None)
+
+    # Context
+    user_profiles: Dict[str, str] = Field(default_factory=dict, description="User profile data as strings")
+    system_snapshot: Dict[str, str] = Field(default_factory=dict, description="System state as strings")
+
+    # History
+    ponder_history: List[str] = Field(default_factory=list, description="Previous ponder thoughts")
+    action_history: List[ActionHistoryItem] = Field(default_factory=list, description="Actions taken")
+
+    # Metadata
+    created_at: datetime = Field(
+        default_factory=lambda: datetime.now(timezone.utc), description="When package was created"
+    )
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class TransportData(BaseModel):
+    """Transport-specific metadata."""
+
+    adapter_type: str = Field(..., description="Type of adapter")
+    channel_id: Optional[str] = Field(None, description="Channel identifier")
+    user_id: Optional[str] = Field(None, description="User identifier")
+    message_id: Optional[str] = Field(None, description="Message identifier")
+    additional_context: Dict[str, str] = Field(default_factory=dict, description="Additional transport context")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class DeferralReport(BaseModel):
+    """Deferral report for transmission to WA."""
+
+    report_id: str = Field(..., description="Unique report ID")
+    package: DeferralPackage = Field(..., description="Deferral package")
+    target_wa_identifier: str = Field(..., description="Target WA (Discord user, email, etc.)")
+    urgency_level: str = Field(default="normal", pattern="^(low|normal|high|critical)$", description="Urgency level")
+
+    # Transport metadata (no Dict[str, Any]!)
+    transport_data: TransportData = Field(..., description="Transport metadata")
+    created_at: datetime = Field(..., description="Report creation time")
+
+    # Status tracking
+    delivered: bool = Field(default=False, description="Whether delivered")
+    delivered_at: Optional[datetime] = Field(None, description="Delivery timestamp")
+    response_received: bool = Field(default=False, description="Whether response received")
+    response_at: Optional[datetime] = Field(None, description="Response timestamp")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class DeferralResolution(BaseModel):
+    """WA resolution of a deferral."""
+
+    report_id: str = Field(..., description="Report being resolved")
+    wa_id: str = Field(..., description="WA who resolved")
+    decision: str = Field(..., description="approve, reject, modify")
+    reasoning: str = Field(..., description="Explanation of decision")
+
+    # Modifications if any
+    modified_action: Optional[str] = Field(None, description="Modified action if changed")
+    conditions: List[str] = Field(default_factory=list, description="Conditions on approval")
+
+    # Timing
+    resolved_at: datetime = Field(..., description="When resolved")
+    signature: str = Field(..., description="Digital signature")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+__all__ = [
+    "DeferralReason",
+    "EthicalAssessment",
+    "CSDMAAssessment",
+    "DSDMAAssessment",
+    "ActionHistoryItem",
+    "DeferralPackage",
+    "TransportData",
+    "DeferralReport",
+    "DeferralResolution",
+]

ciris_engine/schemas/handlers/memory_schemas.py

@@ -0,0 +1,67 @@
+"""
+Memory handler schemas for typed memory operations.
+
+Provides typed schemas usage in memory handlers.
+"""
+
+from typing import Dict, List, Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from ciris_engine.schemas.types import JSONDict
+
+
+class ConnectedNodeInfo(BaseModel):
+    """Information about a node connected to a recalled node."""
+
+    node_id: str = Field(..., description="ID of the connected node")
+    node_type: str = Field(..., description="Type of the connected node")
+    relationship: str = Field(..., description="Type of relationship/edge")
+    direction: str = Field(..., description="Direction of the relationship (incoming/outgoing)")
+    attributes: JSONDict = Field(default_factory=dict, description="Attributes of the connected node")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class RecalledNodeInfo(BaseModel):
+    """Structured information about a recalled node."""
+
+    type: str = Field(..., description="Type of the node")
+    scope: str = Field(..., description="Scope of the node (LOCAL/GLOBAL)")
+    attributes: JSONDict = Field(default_factory=dict, description="Node attributes")
+    connected_nodes: Optional[List[ConnectedNodeInfo]] = Field(None, description="Connected nodes information")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class RecallResult(BaseModel):
+    """Result of a memory recall operation."""
+
+    success: bool = Field(..., description="Whether the recall was successful")
+    nodes: Dict[str, RecalledNodeInfo] = Field(default_factory=dict, description="Map of node IDs to their information")
+    query_description: str = Field(..., description="Description of the query that was executed")
+    total_results: int = Field(0, description="Total number of results found")
+    truncated: bool = Field(False, description="Whether results were truncated")
+
+    model_config = ConfigDict(extra="forbid")
+
+    def to_follow_up_content(self) -> str:
+        """Convert recall result to follow-up thought content."""
+        import json
+
+        if not self.success or not self.nodes:
+            return f"CIRIS_FOLLOW_UP_THOUGHT: No memories found for query '{self.query_description}'"
+
+        # Convert nodes to enhanced data format
+        enhanced_data = {}
+        for node_id, node_info in self.nodes.items():
+            enhanced_data[node_id] = node_info.model_dump()
+
+        data_str = json.dumps(enhanced_data, indent=2, default=str)
+
+        if len(data_str) > 10000:
+            # Truncate to first 10k characters
+            truncated_data = data_str[:10000]
+            return f"CIRIS_FOLLOW_UP_THOUGHT: Memory query '{self.query_description}' returned over {len(data_str)} characters, first 10000 characters: {truncated_data}"
+        else:
+            return f"CIRIS_FOLLOW_UP_THOUGHT: Memory query '{self.query_description}' returned: {data_str}"

ciris_engine/schemas/handlers/schemas.py

@@ -0,0 +1,95 @@
+"""
+Handler schemas for contract-driven architecture.
+
+Provides typed schemas in handler contexts and results.
+"""
+
+from typing import Any, Dict, List, Optional, Union
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from ciris_engine.schemas.types import JSONDict
+
+from ..actions import DeferParams as DeferParameters
+from ..actions import ForgetParams as ForgetParameters
+from ..actions import MemorizeParams as MemorizeParameters
+from ..actions import ObserveParams as ObserveParameters
+from ..actions import PonderParams as PonderParameters
+from ..actions import RecallParams as RecallParameters
+from ..actions import RejectParams as RejectParameters
+from ..actions import SpeakParams as SpeakParameters
+from ..actions import TaskCompleteParams as TaskCompleteParameters
+from ..actions import ToolParams as ToolParameters
+from ..secrets.service import DecapsulationContext
+from ..services.metadata import ServiceMetadata
+from .contexts import (
+    DeferContext,
+    ForgetContext,
+    MemorizeContext,
+    ObserveContext,
+    PonderContext,
+    RecallContext,
+    RejectContext,
+    SpeakContext,
+    TaskCompleteContext,
+    ToolContext,
+)
+
+# Union types for contexts and parameters
+ActionContext = Union[
+    SpeakContext,
+    ToolContext,
+    ObserveContext,
+    MemorizeContext,
+    RecallContext,
+    ForgetContext,
+    RejectContext,
+    PonderContext,
+    DeferContext,
+    TaskCompleteContext,
+]
+
+ActionParameters = Union[
+    SpeakParameters,
+    ToolParameters,
+    ObserveParameters,
+    MemorizeParameters,
+    RecallParameters,
+    ForgetParameters,
+    RejectParameters,
+    PonderParameters,
+    DeferParameters,
+    TaskCompleteParameters,
+]
+
+
+class HandlerContext(BaseModel):
+    """Typed context for all handlers."""
+
+    action_type: str = Field(..., description="Type of action being handled")
+    action_context: ActionContext = Field(..., description="Action-specific context")
+    action_parameters: ActionParameters = Field(..., description="Action-specific parameters")
+    metadata: ServiceMetadata = Field(..., description="Service metadata")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class HandlerResult(BaseModel):
+    """Typed result from all handlers."""
+
+    success: bool = Field(..., description="Whether the handler succeeded")
+    message: Optional[str] = Field(None, description="Result message")
+    data: Optional[JSONDict] = Field(None, description="Additional result data")
+    error: Optional[str] = Field(None, description="Error message if failed")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class HandlerDecapsulatedParams(BaseModel):
+    """Schema for decapsulated handler parameters."""
+
+    action_type: str = Field(..., description="Type of action being handled")
+    action_params: JSONDict = Field(..., description="Decapsulated action parameters")
+    context: DecapsulationContext = Field(..., description="Decapsulation context")
+
+    model_config = ConfigDict(extra="forbid")

ciris_engine/schemas/identity.py

@@ -0,0 +1,149 @@
+"""Identity resolution schemas for DSAR automation."""
+
+from typing import Any, Dict, List, Optional
+
+from pydantic import BaseModel, Field
+
+
+class UserIdentifier(BaseModel):
+    """A single user identifier from a specific system."""
+
+    identifier_type: str = Field(
+        ...,
+        description="Type of identifier (email, discord_id, reddit_username, api_key, etc.)",
+    )
+    identifier_value: str = Field(..., description="Identifier value")
+    confidence: float = Field(
+        default=1.0,
+        ge=0.0,
+        le=1.0,
+        description="Confidence score for this identifier (0.0-1.0)",
+    )
+    source: str = Field(
+        default="manual",
+        description="Source of identifier (oauth, manual, auto, api, etc.)",
+    )
+    created_at: Optional[str] = Field(default=None, description="Timestamp when identifier was added")
+    verified: bool = Field(default=False, description="Whether identifier has been verified")
+    graph_node_id: Optional[str] = Field(default=None, description="Reference to GraphNode in MemoryBus")
+
+
+class UserIdentityNode(BaseModel):
+    """Complete user identity with all known identifiers across systems."""
+
+    primary_id: str = Field(..., description="Primary user identifier (typically email or user_id)")
+    identifiers: List[UserIdentifier] = Field(default_factory=list, description="All known identifiers for this user")
+    graph_node_id: Optional[str] = Field(default=None, description="Reference to primary GraphNode in MemoryBus")
+    total_identifiers: int = Field(default=0, description="Total number of identifiers")
+    last_updated: Optional[str] = Field(default=None, description="Timestamp of last update")
+
+
+class IdentityMappingEvidence(BaseModel):
+    """Evidence supporting an identity mapping."""
+
+    evidence_type: str = Field(..., description="Type of evidence (oauth, behavior, shared_attribute, etc.)")
+    confidence: float = Field(
+        default=0.0,
+        ge=0.0,
+        le=1.0,
+        description="Confidence contribution from this evidence",
+    )
+    source: str = Field(..., description="Source of evidence")
+    details: Dict[str, Any] = Field(default_factory=dict, description="Additional details about evidence")
+    created_at: Optional[str] = Field(default=None, description="Timestamp when evidence was collected")
+
+
+class IdentityConflict(BaseModel):
+    """Conflict detected in identity mapping."""
+
+    conflict_type: str = Field(
+        ...,
+        description="Type of conflict (duplicate_mapping, inconsistent_data, etc.)",
+    )
+    identifier1: UserIdentifier = Field(..., description="First identifier in conflict")
+    identifier2: UserIdentifier = Field(..., description="Second identifier in conflict")
+    severity: str = Field(default="warning", description="Severity: info, warning, error, critical")
+    details: str = Field(..., description="Description of conflict")
+    created_at: Optional[str] = Field(default=None, description="Timestamp when conflict was detected")
+
+
+class IdentityConfidence(BaseModel):
+    """Confidence assessment for an identity mapping."""
+
+    score: float = Field(
+        ...,
+        ge=0.0,
+        le=1.0,
+        description="Overall confidence score (0.0-1.0)",
+    )
+    evidence: List[IdentityMappingEvidence] = Field(
+        default_factory=list, description="Evidence supporting this mapping"
+    )
+    conflicts: List[IdentityConflict] = Field(default_factory=list, description="Conflicts detected for this mapping")
+    recommendation: str = Field(
+        ...,
+        description="Recommendation: accept, review, reject",
+    )
+    reasoning: str = Field(..., description="Human-readable explanation of confidence score")
+
+
+class IdentityGraphVisualization(BaseModel):
+    """Identity graph structure for visualization/debugging."""
+
+    nodes: List[Dict[str, Any]] = Field(default_factory=list, description="Graph nodes with metadata")
+    edges: List[Dict[str, Any]] = Field(default_factory=list, description="Graph edges with relationships")
+    center_node_id: str = Field(..., description="Central node for this graph")
+    depth: int = Field(..., description="Maximum depth traversed")
+    total_nodes: int = Field(default=0, description="Total nodes in graph")
+    total_edges: int = Field(default=0, description="Total edges in graph")
+
+
+class IdentityResolutionRequest(BaseModel):
+    """Request for identity resolution."""
+
+    identifier: str = Field(..., description="User identifier value")
+    identifier_type: str = Field(default="email", description="Type of identifier to resolve")
+    include_low_confidence: bool = Field(
+        default=False,
+        description="Include low-confidence mappings (confidence < 0.5)",
+    )
+    max_depth: int = Field(default=2, ge=1, le=5, description="Maximum graph traversal depth")
+
+
+class IdentityResolutionResult(BaseModel):
+    """Result of identity resolution request."""
+
+    success: bool = Field(..., description="Whether resolution succeeded")
+    identity_node: Optional[UserIdentityNode] = Field(default=None, description="Resolved identity node")
+    confidence: float = Field(
+        default=0.0,
+        ge=0.0,
+        le=1.0,
+        description="Overall confidence in resolution",
+    )
+    identifiers_found: int = Field(default=0, description="Number of identifiers found")
+    error: Optional[str] = Field(default=None, description="Error message if failed")
+
+
+class IdentityMergeRequest(BaseModel):
+    """Request to merge two user identities."""
+
+    primary_id: str = Field(..., description="Primary user identifier (kept)")
+    secondary_id: str = Field(..., description="Secondary user identifier (merged into primary)")
+    reason: str = Field(..., description="Reason for merge")
+    confidence: float = Field(
+        default=1.0,
+        ge=0.0,
+        le=1.0,
+        description="Confidence in merge decision",
+    )
+
+
+class IdentityMergeResult(BaseModel):
+    """Result of identity merge operation."""
+
+    success: bool = Field(..., description="Whether merge succeeded")
+    merged_identity: Optional[UserIdentityNode] = Field(default=None, description="Merged identity node")
+    identifiers_merged: int = Field(default=0, description="Number of identifiers merged")
+    conflicts_resolved: int = Field(default=0, description="Number of conflicts resolved")
+    error: Optional[str] = Field(default=None, description="Error message if failed")

ciris_engine/schemas/infrastructure/__init__.py

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