ciris-agent 1.7.7__py3-none-any.whl

ciris_engine/schemas/dma/faculty.py

@@ -0,0 +1,192 @@
+"""
+Faculty-related schemas for DMA system.
+
+Provides typed schemas with properly typed structures for faculty integration.
+"""
+
+from typing import TYPE_CHECKING, Any, Dict, List, Optional, Union
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from ciris_engine.schemas.infrastructure.identity_variance import IdentityData
+from ciris_engine.schemas.runtime.enums import HandlerActionType
+from ciris_engine.schemas.runtime.models import ImageContent
+
+
+class ThoughtMetadata(BaseModel):
+    """Metadata about a thought being analyzed by faculties."""
+
+    thought_id: Optional[str] = Field(None, description="Unique thought identifier")
+    thought_type: Optional[str] = Field(None, description="Type of thought")
+    processing_depth: Optional[int] = Field(None, description="Current processing depth")
+    round_number: Optional[int] = Field(None, description="Processing round number")
+    task_id: Optional[str] = Field(None, description="Associated task ID")
+    created_at: Optional[str] = Field(None, description="When thought was created (ISO format)")
+    content_length: Optional[int] = Field(None, description="Length of thought content")
+    previous_actions: Optional[List[str]] = Field(None, description="Previous actions taken")
+    priority: Optional[int] = Field(None, description="Thought priority level")
+    tags: Optional[List[str]] = Field(None, description="Thought classification tags")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class FacultyContext(BaseModel):
+    """Context passed to faculties for analysis."""
+
+    # Evaluation context type
+    evaluation_context: str = Field(..., description="Type of evaluation (e.g., 'faculty_enhanced_action_selection')")
+
+    # Thought metadata
+    thought_metadata: ThoughtMetadata = Field(
+        default_factory=ThoughtMetadata, description="Metadata about the thought being analyzed"
+    )
+
+    # Identity context for decision faculties
+    agent_identity: Optional[IdentityData] = Field(None, description="Agent identity information")
+    identity_purpose: Optional[str] = Field(None, description="Agent's purpose statement")
+    identity_capabilities: Optional[List[str]] = Field(None, description="Agent capabilities")
+    identity_restrictions: Optional[List[str]] = Field(None, description="Agent restrictions")
+    identity_context_string: Optional[str] = Field(None, description="Formatted identity context")
+
+    # Conscience failure context if applicable
+    conscience_failure_reason: Optional[str] = Field(None, description="Reason for conscience failure")
+    conscience_guidance: Optional[str] = Field(None, description="Guidance from conscience")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class FacultyResult(BaseModel):
+    """Result from a single faculty analysis."""
+
+    faculty_name: str = Field(..., description="Name of the faculty")
+    analysis_type: str = Field(..., description="Type of analysis performed")
+
+    # Core result data
+    score: Optional[float] = Field(None, ge=0.0, le=1.0, description="Numeric score if applicable")
+    assessment: str = Field(..., description="Text assessment/summary")
+    confidence: float = Field(0.8, ge=0.0, le=1.0, description="Confidence in the assessment")
+
+    # Detailed findings
+    findings: List[str] = Field(default_factory=list, description="Key findings from analysis")
+    concerns: List[str] = Field(default_factory=list, description="Identified concerns")
+    recommendations: List[str] = Field(default_factory=list, description="Recommended actions")
+
+    # Metadata
+    processing_time_ms: Optional[float] = Field(None, description="Time taken for analysis")
+    error: Optional[str] = Field(None, description="Error message if analysis failed")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class FacultyEvaluationSet(BaseModel):
+    """Complete set of faculty evaluations for a thought."""
+
+    # Results by faculty name
+    evaluations: Dict[str, FacultyResult] = Field(
+        default_factory=dict, description="Faculty evaluation results keyed by faculty name"
+    )
+
+    # Aggregate metadata
+    total_faculties_run: int = Field(0, description="Number of faculties that ran")
+    successful_evaluations: int = Field(0, description="Number of successful evaluations")
+    failed_evaluations: int = Field(0, description="Number of failed evaluations")
+
+    # Flags based on evaluations
+    has_ethical_concerns: bool = Field(False, description="Any faculty raised ethical concerns")
+    has_optimization_veto: bool = Field(False, description="Optimization veto was triggered")
+    requires_humility: bool = Field(False, description="Epistemic humility is advised")
+
+    def add_result(self, faculty_name: str, result: FacultyResult) -> None:
+        """Add a faculty result to the evaluation set."""
+        # Ensure faculty name matches
+        result.faculty_name = faculty_name
+
+        self.evaluations[faculty_name] = result
+        self.total_faculties_run += 1
+
+        if result.error:
+            self.failed_evaluations += 1
+        else:
+            self.successful_evaluations += 1
+
+        # Update flags based on faculty type and results
+        if faculty_name == "optimization_veto" and result.score and result.score > 0.7:
+            self.has_optimization_veto = True
+        elif faculty_name == "epistemic_humility" and result.score and result.score > 0.6:
+            self.requires_humility = True
+        elif faculty_name in ["entropy", "coherence"] and result.concerns:
+            self.has_ethical_concerns = True
+
+    def to_dict(self) -> Dict[str, Dict[str, Union[str, float, List[str], None]]]:
+        """Convert to dictionary format with proper typing."""
+        return {
+            name: {
+                "analysis_type": result.analysis_type,
+                "score": result.score,
+                "assessment": result.assessment,
+                "confidence": result.confidence,
+                "findings": result.findings,
+                "concerns": result.concerns,
+                "recommendations": result.recommendations,
+                "processing_time_ms": result.processing_time_ms,
+                "error": result.error,
+            }
+            for name, result in self.evaluations.items()
+        }
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class ConscienceFailureContext(BaseModel):
+    """Context from conscience failures requiring faculty intervention."""
+
+    failure_reason: str = Field(..., description="Why conscience check failed")
+    retry_guidance: str = Field(..., description="Guidance for retry with faculties")
+
+    # Specific conscience concerns
+    ethical_violations: List[str] = Field(default_factory=list, description="Ethical issues identified")
+    safety_concerns: List[str] = Field(default_factory=list, description="Safety issues identified")
+    alignment_issues: List[str] = Field(default_factory=list, description="Alignment problems")
+
+    # Recommended faculty focus
+    recommended_faculties: List[str] = Field(
+        default_factory=list, description="Specific faculties recommended for evaluation"
+    )
+
+    # Severity assessment
+    severity: str = Field("medium", description="Severity level: low, medium, high, critical")
+    requires_escalation: bool = Field(False, description="Whether to escalate to human")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class EnhancedDMAInputs(BaseModel):
+    """Enhanced DMA inputs with faculty evaluations."""
+
+    # All fields from original inputs (using inheritance or composition)
+    original_thought: Any = Field(..., description="Original thought being processed")
+    ethical_pdma_result: Any = Field(..., description="Ethical PDMA result")
+    csdma_result: Any = Field(..., description="Common sense DMA result")
+    dsdma_result: Optional[Any] = Field(None, description="Domain-specific DMA result")
+
+    current_thought_depth: int = Field(0, description="Ponder depth")
+    max_rounds: int = Field(5, description="Maximum rounds")
+    processing_context: Any = Field(..., description="Processing context")
+
+    # Native multimodal support - images from source task for vision processing
+    images: List[ImageContent] = Field(
+        default_factory=list, description="Images from source task for multimodal processing"
+    )
+
+    # Action selection fields
+    agent_identity: Optional[IdentityData] = Field(None, description="Agent identity information")
+    permitted_actions: Optional[List[HandlerActionType]] = Field(None, description="List of permitted actions")
+    conscience_feedback: Optional[Any] = Field(None, description="Conscience evaluation feedback")
+
+    # Faculty enhancements
+    faculty_evaluations: Optional[FacultyEvaluationSet] = Field(None, description="Faculty evaluation results")
+    faculty_enhanced: bool = Field(False, description="Whether faculty enhancement was applied")
+    recursive_evaluation: bool = Field(False, description="Whether this is a recursive evaluation")
+    conscience_context: Optional[ConscienceFailureContext] = Field(None, description="Conscience failure context")
+
+    model_config = ConfigDict(extra="allow")  # Allow pass-through of other fields

ciris_engine/schemas/dma/prompts.py

@@ -0,0 +1,172 @@
+"""
+Prompt-related schemas for DMA system.
+
+Provides typed schemas with properly typed structures for prompt management.
+"""
+
+from typing import Any, Dict, List, Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from ciris_engine.schemas.types import JSONDict
+
+
+class PromptTemplate(BaseModel):
+    """A single prompt template with metadata."""
+
+    name: str = Field(..., description="Template name/identifier")
+    content: str = Field(..., description="Template content with {variable} placeholders")
+    description: Optional[str] = Field(None, description="What this template is for")
+
+    # Template metadata
+    version: str = Field("1.0", description="Template version")
+    category: str = Field("general", description="Template category")
+    requires_covenant: bool = Field(False, description="Whether COVENANT_TEXT should be prepended")
+
+    # Variable requirements
+    required_variables: List[str] = Field(default_factory=list, description="Required template variables")
+    optional_variables: List[str] = Field(default_factory=list, description="Optional template variables")
+
+    # Usage hints
+    usage_context: Optional[str] = Field(None, description="When to use this template")
+    example_output: Optional[str] = Field(None, description="Example of filled template")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class PromptCollection(BaseModel):
+    """Collection of prompt templates for a DMA component."""
+
+    # Metadata
+    component_name: str = Field(..., description="Name of the DMA component")
+    description: str = Field(..., description="Description of this prompt collection")
+    version: str = Field("1.0", description="Collection version")
+
+    # Core prompt sections
+    system_header: Optional[str] = Field(None, description="System message header")
+    system_guidance_header: Optional[str] = Field(None, description="System guidance header")
+
+    # Domain-specific prompts
+    domain_principles: Optional[str] = Field(None, description="Domain principles template")
+    evaluation_steps: Optional[str] = Field(None, description="Evaluation steps template")
+    evaluation_criteria: Optional[str] = Field(None, description="Evaluation criteria template")
+
+    # Response formatting
+    response_format: Optional[str] = Field(None, description="Response format guidance")
+    response_guidance: Optional[str] = Field(None, description="Response guidance template")
+    decision_format: Optional[str] = Field(None, description="Decision format template")
+
+    # Action-specific prompts
+    action_parameter_schemas: Optional[str] = Field(None, description="Action parameter schemas")
+
+    # Guidance prompts
+    csdma_ambiguity_guidance: Optional[str] = Field(None, description="CSDMA ambiguity guidance")
+    action_params_speak_csdma_guidance: Optional[str] = Field(None, description="SPEAK action guidance")
+    action_params_ponder_guidance: Optional[str] = Field(None, description="PONDER action guidance")
+    action_params_observe_guidance: Optional[str] = Field(None, description="OBSERVE action guidance")
+    rationale_csdma_guidance: Optional[str] = Field(None, description="Rationale guidance")
+
+    # Special case prompts
+    final_ponder_advisory: Optional[str] = Field(None, description="Final ponder advisory template")
+    closing_reminder: Optional[str] = Field(None, description="Closing reminder text")
+
+    # Context integration
+    context_integration: Optional[str] = Field(None, description="Context integration template")
+
+    # Agent-specific variations (e.g., "ciris_mode_<prompt_key>")
+    agent_variations: Dict[str, str] = Field(default_factory=dict, description="Agent-specific prompt variations")
+
+    # Additional custom prompts
+    custom_prompts: Dict[str, str] = Field(default_factory=dict, description="Additional custom prompts")
+
+    # Metadata flags
+    uses_covenant_header: bool = Field(False, description="Whether to use COVENANT_TEXT")
+    supports_agent_modes: bool = Field(True, description="Whether agent-specific prompts are supported")
+
+    def get_prompt(self, key: str, agent_name: Optional[str] = None) -> Optional[str]:
+        """Get a prompt by key, with agent-specific fallback."""
+        # Try agent-specific first
+        if agent_name and self.supports_agent_modes:
+            agent_key = f"{agent_name.lower()}_mode_{key}"
+            if agent_key in self.agent_variations:
+                return self.agent_variations[agent_key]
+
+        # Try direct attribute
+        if hasattr(self, key):
+            return getattr(self, key)  # type: ignore[no-any-return]  # Dynamic attribute lookup
+
+        # Try custom prompts
+        if key in self.custom_prompts:
+            return self.custom_prompts[key]
+
+        return None
+
+    def to_dict(self) -> JSONDict:
+        """Convert to JSON-serializable dictionary for backward compatibility.
+
+        Returns a flattened dictionary containing all prompt strings,
+        agent variations, and custom prompts.
+        """
+        result: JSONDict = {}
+
+        # Add all non-None string fields
+        for field_name in self.model_fields:
+            value = getattr(self, field_name)
+            if isinstance(value, str) and value is not None:
+                result[field_name] = value
+
+        # Add agent variations
+        result.update(self.agent_variations)
+
+        # Add custom prompts
+        result.update(self.custom_prompts)
+
+        return result
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class PromptVariable(BaseModel):
+    """Definition of a template variable."""
+
+    name: str = Field(..., description="Variable name (without braces)")
+    description: str = Field(..., description="What this variable represents")
+    type: str = Field("str", description="Variable type: str, int, float, bool, list, dict")
+    required: bool = Field(True, description="Whether this variable is required")
+    default: Optional[Any] = Field(None, description="Default value if not provided")
+    example: Optional[Any] = Field(None, description="Example value")
+
+    # Validation rules
+    min_length: Optional[int] = Field(None, description="Minimum length for strings")
+    max_length: Optional[int] = Field(None, description="Maximum length for strings")
+    allowed_values: Optional[List[Any]] = Field(None, description="Allowed values (enum)")
+    pattern: Optional[str] = Field(None, description="Regex pattern for validation")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class PromptMetadata(BaseModel):
+    """Metadata about a prompt file or collection."""
+
+    file_path: str = Field(..., description="Path to the prompt file")
+    format: str = Field("yaml", description="File format: yaml, json, txt")
+
+    # Versioning
+    version: str = Field(..., description="Prompt version")
+    last_modified: str = Field(..., description="ISO timestamp of last modification")
+    author: Optional[str] = Field(None, description="Author of the prompts")
+
+    # Content summary
+    description: str = Field(..., description="What these prompts are for")
+    component: str = Field(..., description="Which DMA component uses these")
+    prompt_count: int = Field(0, description="Number of prompts in file")
+
+    # Dependencies
+    requires: List[str] = Field(default_factory=list, description="Required prompt files")
+    imports: List[str] = Field(default_factory=list, description="Imported prompt collections")
+
+    # Usage stats
+    usage_count: int = Field(0, description="How many times loaded")
+    last_used: Optional[str] = Field(None, description="ISO timestamp of last use")
+
+    model_config = ConfigDict(extra="forbid")

ciris_engine/schemas/dma/results.py

@@ -0,0 +1,103 @@
+"""
+DMA result schemas for typed decision outputs.
+
+Provides type-safe results from each Decision Making Algorithm.
+"""
+
+from typing import Any, Dict, List, Optional, Union
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from ciris_engine.schemas.types import JSONDict
+
+from ..actions.parameters import (
+    DeferParams,
+    ForgetParams,
+    MemorizeParams,
+    ObserveParams,
+    PonderParams,
+    RecallParams,
+    RejectParams,
+    SpeakParams,
+    TaskCompleteParams,
+    ToolParams,
+)
+from ..runtime.enums import HandlerActionType
+
+
+class EthicalDMAResult(BaseModel):
+    """Result from Principled Decision Making Algorithm (PDMA).
+
+    PDMA identifies stakeholders affected by the thought and potential conflicts
+    between their interests to inform ethical action selection.
+    """
+
+    stakeholders: str = Field(
+        ...,
+        description="Comma-separated list of all stakeholders who could possibly be affected by the agent's action or inaction (e.g., 'user, community, system, third-parties')",
+    )
+    conflicts: str = Field(
+        ...,
+        description="Comma-separated list of potential conflicts between stakeholder interests (e.g., 'user privacy vs system learning, individual benefit vs community harm'). Use 'none' if no conflicts identified.",
+    )
+    reasoning: str = Field(..., description="Ethical reasoning for the identified stakeholders and conflicts")
+    alignment_check: str = Field(..., description="Detailed ethical analysis addressing each CIRIS principle")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class CSDMAResult(BaseModel):
+    """Result from Common Sense Decision Making Algorithm."""
+
+    plausibility_score: float = Field(..., ge=0.0, le=1.0, description="Plausibility rating")
+    flags: List[str] = Field(default_factory=list, description="Common sense flags raised")
+    reasoning: str = Field(..., description="Common sense reasoning")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class DSDMAResult(BaseModel):
+    """Result from Domain Specific Decision Making Algorithm."""
+
+    domain: str = Field(..., description="Primary domain of expertise")
+    domain_alignment: float = Field(..., ge=0.0, le=1.0, description="How well aligned with domain")
+    flags: List[str] = Field(default_factory=list, description="Domain-specific flags")
+    reasoning: str = Field(..., description="Domain-specific reasoning")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class ActionSelectionDMAResult(BaseModel):
+    """Result from Action Selection DMA - the meta-decision maker."""
+
+    # Core fields matching handler expectations
+    selected_action: HandlerActionType = Field(..., description="The chosen handler action")
+    action_parameters: Union[
+        ObserveParams,
+        SpeakParams,
+        ToolParams,
+        PonderParams,
+        RejectParams,
+        DeferParams,
+        MemorizeParams,
+        RecallParams,
+        ForgetParams,
+        TaskCompleteParams,
+    ] = Field(..., description="Parameters for the selected action")
+    rationale: str = Field(..., description="Reasoning for this action selection (REQUIRED)")
+
+    # LLM metadata
+    raw_llm_response: Optional[str] = Field(None, description="Raw LLM response")
+
+    # Processing metadata
+    reasoning: Optional[str] = Field(None, description="Detailed reasoning process")
+    evaluation_time_ms: Optional[float] = Field(None, description="Time taken for evaluation")
+    resource_usage: Optional[JSONDict] = Field(None, description="Resource usage details")
+
+    # User prompt for debugging/transparency (set by evaluator)
+    user_prompt: Optional[str] = Field(None, description="User prompt passed to ASPDMA")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+__all__ = ["EthicalDMAResult", "CSDMAResult", "DSDMAResult", "ActionSelectionDMAResult"]

ciris_engine/schemas/formatters/__init__.py

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

ciris_engine/schemas/handlers/__init__.py

@@ -0,0 +1,10 @@
+"""Handler schemas for contract-driven architecture."""
+
+from .schemas import ActionContext, ActionParameters, HandlerContext, HandlerResult
+
+__all__ = [
+    "HandlerContext",
+    "HandlerResult",
+    "ActionContext",
+    "ActionParameters",
+]

ciris_engine/schemas/handlers/context.py

@@ -0,0 +1,119 @@
+"""
+Handler context schemas for CIRIS.
+
+Provides typed contexts for all handler operations.
+"""
+
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional, Union
+
+from pydantic import BaseModel, Field
+
+from ciris_engine.schemas.types import JSONDict
+
+
+class HandlerData(BaseModel):
+    """Base class for handler-specific data."""
+
+    handler_name: str = Field(..., description="Name of the handler")
+
+
+class SpeakHandlerData(HandlerData):
+    """Data specific to SPEAK handler."""
+
+    message_type: str = Field("response", description="Type of message")
+    reply_to_message_id: Optional[str] = Field(None, description="Message being replied to")
+    formatting_hints: Optional[Dict[str, str]] = Field(None, description="Formatting hints")
+
+
+class ToolHandlerData(HandlerData):
+    """Data specific to TOOL handler."""
+
+    tool_timeout: float = Field(30.0, description="Tool execution timeout")
+    requires_confirmation: bool = Field(False, description="Whether user confirmation needed")
+    sandbox_mode: bool = Field(True, description="Whether to run in sandbox")
+
+
+class MemoryHandlerData(HandlerData):
+    """Data specific to memory handlers (MEMORIZE, RECALL, FORGET)."""
+
+    operation_type: str = Field(..., description="memorize, recall, or forget")
+    allow_duplicates: bool = Field(False, description="Whether to allow duplicate memories")
+    cascade_delete: bool = Field(False, description="Whether to cascade delete related memories")
+
+
+class HandlerRequest(BaseModel):
+    """Request passed to all handlers - fully typed."""
+
+    task_id: str = Field(..., description="ID of the task being handled")
+    thought_id: str = Field(..., description="ID of the thought being processed")
+    correlation_id: str = Field(..., description="Correlation ID for tracing")
+    channel_id: Optional[str] = Field(None, description="Channel ID if applicable")
+    user_id: Optional[str] = Field(None, description="User ID if applicable")
+    trace_context: Dict[str, str] = Field(default_factory=dict, description="Distributed tracing context")
+
+    # Handler-specific context - typed based on handler
+    handler_data: Optional[Union[SpeakHandlerData, ToolHandlerData, MemoryHandlerData, HandlerData]] = Field(
+        None, description="Handler-specific typed data"
+    )
+
+
+class ActionContextParams(BaseModel):
+    """Base class for action parameters in audit context."""
+
+    action_type: str = Field(..., description="Type of action")
+
+
+class SpeakActionParams(ActionContextParams):
+    """Parameters for SPEAK action."""
+
+    message: str = Field(..., description="Message content")
+    channel_id: str = Field(..., description="Target channel")
+    message_type: str = Field("response", description="Type of message")
+
+
+class ToolActionParams(ActionContextParams):
+    """Parameters for TOOL action."""
+
+    tool_name: str = Field(..., description="Tool to execute")
+    tool_args: JSONDict = Field(..., description="Tool arguments")
+
+
+class MemoryActionParams(ActionContextParams):
+    """Parameters for memory actions."""
+
+    operation: str = Field(..., description="memorize, recall, or forget")
+    node_id: Optional[str] = Field(None, description="Node ID for recall/forget")
+    query: Optional[str] = Field(None, description="Query for recall")
+    content: Optional[JSONDict] = Field(None, description="Content for memorize")
+
+
+class ActionContext(BaseModel):
+    """Context for an action being audited - fully typed."""
+
+    action_type: str = Field(..., description="Type of action performed")
+    action_params: Union[SpeakActionParams, ToolActionParams, MemoryActionParams, ActionContextParams] = Field(
+        ..., description="Typed action parameters"
+    )
+    initiated_by: str = Field(..., description="Who initiated the action")
+    reason: Optional[str] = Field(None, description="Reason for the action")
+
+    # Audit trail
+    task_id: str = Field(..., description="Associated task ID")
+    thought_id: str = Field(..., description="Associated thought ID")
+    correlation_id: str = Field(..., description="Correlation ID")
+    timestamp: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+
+
+__all__ = [
+    "HandlerData",
+    "SpeakHandlerData",
+    "ToolHandlerData",
+    "MemoryHandlerData",
+    "HandlerRequest",
+    "ActionContextParams",
+    "SpeakActionParams",
+    "ToolActionParams",
+    "MemoryActionParams",
+    "ActionContext",
+]