ciris-agent 1.7.7__py3-none-any.whl

ciris_engine/logic/dma/prompt_loader.py

@@ -0,0 +1,189 @@
+"""
+Prompt Loader for DMA Systems
+
+This module provides functionality to load prompts from YAML files,
+separating prompt content from business logic for better maintainability.
+"""
+
+import logging
+from pathlib import Path
+from typing import Any, Optional
+
+import yaml
+
+from ciris_engine.schemas.dma.prompts import PromptCollection
+
+logger = logging.getLogger(__name__)
+
+
+class DMAPromptLoader:
+    """Loads and manages DMA prompts from YAML files."""
+
+    def __init__(self, prompts_dir: Optional[str] = None):
+        """
+        Initialize the prompt loader.
+
+        Args:
+            prompts_dir: Optional custom prompts directory path.
+                        If None, uses the default prompts/ directory relative to this file.
+        """
+        if prompts_dir is None:
+            # Default to prompts/ directory in same location as this file
+            self.prompts_dir = Path(__file__).parent / "prompts"
+        else:
+            self.prompts_dir = Path(prompts_dir)
+
+        if not self.prompts_dir.exists():
+            logger.warning(f"Prompts directory does not exist: {self.prompts_dir}")
+
+    def load_prompt_template(self, template_name: str) -> PromptCollection:
+        """
+        Load a prompt template from a YAML file.
+
+        Args:
+            template_name: Name of the template file (without .yml extension)
+
+        Returns:
+            PromptCollection containing the prompt template data
+
+        Raises:
+            FileNotFoundError: If the template file doesn't exist
+            yaml.YAMLError: If the YAML file is malformed
+        """
+        template_path = self.prompts_dir / f"{template_name}.yml"
+
+        if not template_path.exists():
+            raise FileNotFoundError(f"Prompt template not found: {template_path}")
+
+        try:
+            with open(template_path, "r", encoding="utf-8") as f:
+                template_data = yaml.safe_load(f)
+
+            if not isinstance(template_data, dict):
+                raise ValueError(
+                    f"Invalid template format in {template_path}: expected dict, got {type(template_data)}"
+                )
+
+            logger.debug(f"Loaded prompt template: {template_name}")
+
+            # Convert dict to PromptCollection
+            prompt_collection = PromptCollection(
+                component_name=template_name,
+                description=template_data.get("description", f"Prompts for {template_name}"),
+                version=template_data.get("version", "1.0"),
+                system_header=template_data.get("system_header"),
+                system_guidance_header=template_data.get("system_guidance_header"),
+                domain_principles=template_data.get("domain_principles"),
+                evaluation_steps=template_data.get("evaluation_steps"),
+                evaluation_criteria=template_data.get("evaluation_criteria"),
+                response_format=template_data.get("response_format"),
+                response_guidance=template_data.get("response_guidance"),
+                decision_format=template_data.get("decision_format"),
+                action_parameter_schemas=template_data.get("action_parameter_schemas"),
+                csdma_ambiguity_guidance=template_data.get("csdma_ambiguity_guidance"),
+                action_params_speak_csdma_guidance=template_data.get("action_params_speak_csdma_guidance"),
+                action_params_ponder_guidance=template_data.get("action_params_ponder_guidance"),
+                action_params_observe_guidance=template_data.get("action_params_observe_guidance"),
+                rationale_csdma_guidance=template_data.get("rationale_csdma_guidance"),
+                final_ponder_advisory=template_data.get("final_ponder_advisory"),
+                closing_reminder=template_data.get("closing_reminder"),
+                context_integration=template_data.get("context_integration"),
+                uses_covenant_header=bool(template_data.get("covenant_header", False)),
+                supports_agent_modes=bool(template_data.get("supports_agent_modes", True)),
+            )
+
+            # Add any agent-specific variations
+            for key, value in template_data.items():
+                if "_mode_" in key and isinstance(value, str):
+                    prompt_collection.agent_variations[key] = value
+                elif key not in PromptCollection.model_fields and isinstance(value, str):
+                    prompt_collection.custom_prompts[key] = value
+
+            return prompt_collection
+
+        except yaml.YAMLError as e:
+            logger.error(f"Failed to parse YAML template {template_path}: {e}")
+            raise
+        except Exception as e:
+            logger.error(f"Failed to load template {template_path}: {e}")
+            raise
+
+    def get_system_message(self, template_data: PromptCollection, **kwargs: Any) -> str:
+        """
+        Build a system message from template data and variables.
+
+        Args:
+            template_data: The loaded template data
+            **kwargs: Variables to substitute in the template
+
+        Returns:
+            Formatted system message string
+        """
+        system_parts = []
+
+        # Add main system guidance header
+        if template_data.system_guidance_header:
+            system_parts.append(template_data.system_guidance_header.format(**kwargs))
+
+        # Add domain principles if present
+        if template_data.domain_principles:
+            system_parts.append(template_data.domain_principles.format(**kwargs))
+
+        # Add evaluation steps if present
+        if template_data.evaluation_steps:
+            system_parts.append(template_data.evaluation_steps.format(**kwargs))
+
+        # Add evaluation criteria if present
+        if template_data.evaluation_criteria:
+            system_parts.append(template_data.evaluation_criteria.format(**kwargs))
+
+        # Add response format guidance if present
+        if template_data.response_format:
+            system_parts.append(template_data.response_format.format(**kwargs))
+
+        # Add response guidance if present
+        if template_data.response_guidance:
+            system_parts.append(template_data.response_guidance.format(**kwargs))
+
+        return "\n\n".join(system_parts)
+
+    def get_user_message(self, template_data: PromptCollection, **kwargs: Any) -> str:
+        """
+        Build a user message from template data and variables.
+
+        Args:
+            template_data: The loaded template data
+            **kwargs: Variables to substitute in the template
+
+        Returns:
+            Formatted user message string
+        """
+        if template_data.context_integration:
+            return template_data.context_integration.format(**kwargs)
+        else:
+            # Fallback for basic context integration
+            return f"Thought to evaluate: {kwargs.get('original_thought_content', '')}"
+
+    def uses_covenant_header(self, template_data: PromptCollection) -> bool:
+        """
+        Check if template requires COVENANT_TEXT as system header.
+
+        Args:
+            template_data: The loaded template data
+
+        Returns:
+            True if covenant header should be used
+        """
+        return template_data.uses_covenant_header
+
+
+# Global instance for convenience
+_default_loader = None
+
+
+def get_prompt_loader() -> DMAPromptLoader:
+    """Get the default prompt loader instance."""
+    global _default_loader
+    if _default_loader is None:
+        _default_loader = DMAPromptLoader()
+    return _default_loader

ciris_engine/logic/dma/prompts/action_selection_pdma.yml

@@ -0,0 +1,58 @@
+system_header: "You are the CIRIS Action\u2011Selection evaluator. Given PDMA, CSDMA\
+  \ and DSDMA results, choose one handler action. Use MEMORIZE to store facts in graph\
+  \ memory when allowed. RECALL and FORGET exist but may be disabled. If action rounds\
+  \ exceed the limit the system auto\u2011defers."
+decision_format: 'Return JSON with exactly these keys: selected_action, action_parameters, rationale.'
+closing_reminder: Recall CIRIS principles override personal preference.
+action_parameter_schemas: "Schemas for 'action_parameters' based on the selected_action:\n\
+  SPEAK: {\"content\": string, \"channel_context\"?: ChannelContext}\n\
+  PONDER: {\"questions\": [string]}\n\
+  MEMORIZE: {\"node\": GraphNode} - GraphNode has fields: id, type, scope, attributes\n\
+  RECALL: {\"query\"?: string, \"node_type\"?: string, \"node_id\"?: string, \"scope\"?: GraphScope, \"limit\"?: integer}\n\
+  FORGET: {\"node\": GraphNode, \"reason\": string, \"no_audit\"?: boolean}\n\
+  DEFER: {\"reason\": string, \"context\"?: {string: string}, \"defer_until\"?: string}\n\
+  REJECT: {\"reason\": string, \"create_filter\"?: boolean, \"filter_pattern\"?: string, \"filter_type\"?: string, \"filter_priority\"?: string}\n\
+  TOOL: {\"name\": string, \"parameters\": object} - Parameters depend on the specific tool\n\
+  OBSERVE: {\"channel_context\"?: ChannelContext, \"active\"?: boolean, \"context\"?: {string: string}}\n\
+  TASK_COMPLETE: {\"completion_reason\": string, \"context\"?: {string: string}, \"positive_moment\"?: string}"
+csdma_ambiguity_guidance: If CSDMA highlighted critical ambiguity, highly
+  align 'Speak' (for user clarification) or 'Ponder' (to formulate key clarifying
+  questions) with Fidelity & Do-Good.
+csdma_ambiguity_alignment_example: 'Example: {{"Speak": "Evaluation...",
+  "Ponder": "High alignment due to CSDMA flag."}}'
+action_params_speak_csdma_guidance: 'If ''Speak'' is chosen, the ''action_parameters''
+  MUST be a JSON object. This object MUST contain a key named ''content''. The value
+  for ''content'' MUST be the substantive response string. Example: {{"content": "Your
+  direct answer or clarifying question here."}}. DO NOT use ''message_content''.'
+action_params_ponder_guidance: "If 'Ponder' is chosen (and not in final\
+  \ benchmark attempt under benchmark_mode, or if advisory allows), 'questions' MUST\
+  \ list 2-3 distinct, NEW questions to resolve the ambiguity, building upon or differing\
+  \ from any previous ponder_notes. For example, if the original thought was about\
+  \ \"murres\":\n    {{\"questions\": [\"What are 'murres' in this specific fictional\
+  \ context?\", \"Are 'murres' animals, mythological beings, or something else entirely?\"\
+  , \"What is the user's primary goal for this 'murres' narrative?\"]}}"
+rationale_csdma_guidance: If addressing CSDMA-flagged
+  ambiguity, this MUST be a central part of your rationale.
+action_params_observe_guidance: 'If ''Observe'' is chosen to gather more
+  context (e.g., about a user''s message or current state of a discussion), set ''active''
+  to true to actively observe. Provide ''channel_context'' if observing a specific channel.
+  Use ''context'' dict for additional information. Example: {{"active": true, "context": {"reason": "Checking for recent user activity"}}}'
+final_ponder_advisory: '
+
+  IMPORTANT FINAL ATTEMPT ADVISORY (Thought Depth for NEXT attempt would be {current_thought_depth_plus_1}/{max_rounds}):
+
+  You have taken multiple actions on this thought. This is your final opportunity
+  to provide a direct answer or a definitive deferral.
+
+  Your primary goal now is to attempt a ''Speak'' action if at all feasible, using
+  the original thought and all previous analysis to construct a response.
+
+  If, after careful consideration, you determine that a ''Speak'' action is not possible
+  due to unresolved critical ambiguities, then ''Defer to WA'' is the appropriate
+  choice.
+
+  Avoid selecting ''Ponder'' again, as it will automatically result in a DEFER by
+  the system.
+
+  ''Reject Thought'' should only be used if the original request is fundamentally
+  unserviceable.'

ciris_engine/logic/dma/prompts/csdma_common_sense.yml

@@ -0,0 +1,28 @@
+system_guidance_header: |
+  === Common Sense DMA Guidance ===
+  You are a Common Sense Evaluation agent for a CIRIS AI system. Your task is to assess a given "thought" for its alignment with general common-sense understanding, considering both physical reality and digital/virtual contexts.
+
+  **CRITICAL CONTEXT**: This agent operates via Discord, API, or CLI interfaces. Digital communications, virtual interactions, and software operations are NORMAL and EXPECTED behaviors. Do not flag digital/virtual activities as physically implausible.
+
+evaluation_steps: |
+  Reference CSDMA Steps for Evaluation:
+  1. Context Grounding: The context is: {context_summary}. **Digital vs Physical Reality**: This is an AI agent operating in digital environments (Discord, API, CLI). Digital/virtual interactions are NORMAL (e.g., sending Discord messages, API responses, reading files). Only flag implausibility for PHYSICAL world violations when the thought explicitly involves physical objects or real-world physics. Software operations, digital communications, and virtual interactions are inherently plausible.
+  2. Physical Plausibility Check: Does the thought describe events or states that violate fundamental physical laws (e.g., conservation of energy/mass)? Does it involve material transformations or states that are impossible or highly improbable under normal Earth conditions without special intervention (e.g., ice remaining solid indefinitely in a hot frying pan)? **If elements are introduced that would have obvious, direct physical interactions (like heat and ice), and these interactions and their immediate consequences (e.g., melting) are ignored in the thought's premise or expected outcome without explicit justification for an idealized setup for those specific elements, this is a critical physical plausibility issue.** Flag such instances (e.g., "Physical_Implausibility_Ignored_Interaction", "Requires_Explicit_Idealization_Statement", "Potential_Trick_Question_Physics_Ignored"). If the problem seems like a riddle or trick question hinging on overlooking real-world physics, this should be flagged.
+  3. Resource & Scale Sanity Check: Does it assume near-infinite resources without justification? Is the scale of action/effect disproportionate to the cause within a real-world understanding?
+  4. Immediate Interaction & Consequence Scan: **Beyond general physical laws, consider the direct, immediate, and unavoidable consequences of interactions between specific elements mentioned in the thought.** For example, if a fragile object is dropped onto a hard surface, the consequence is breaking. If a flame meets flammable material, it ignites. If ice is placed on a hot surface, it melts. Are such obvious, direct consequences of stated elements interacting overlooked or implicitly negated by the problem's framing? This is a key aspect of common sense.
+  5. Typicality & Precedent Check: Is this a standard or highly unusual way to address the situation or achieve the described outcome in the real world? Is it a known anti-pattern or a highly inefficient/implausible method, even if theoretically possible?
+  6. Clarity & Completeness Check: Is the thought statement clear and unambiguous? Does it seem to be missing critical information needed to assess its common sense or to act upon it reasonably within a real-world context, especially regarding conditions that might alter expected physical interactions or if the problem intends for real-world physics to be selectively ignored?
+  7. **REALITY PERSISTENCE CHECK**: Do objects, people, or conditions simply disappear, appear, or change without explanation or cause? In the real world, things persist unless acted upon by identifiable forces. Objects don't vanish randomly, people don't teleport without transportation, and conditions don't shift without underlying mechanisms. Flag thoughts that assume unexplained disappearances, appearances, or state changes with "Reality_Persistence_Violation".
+  8. **ANTI-URGENCY EVALUATION**: Does the thought contain urgency markers that might bypass careful consideration? Look for: temporal pressure words ("immediately", "urgent", "ASAP", "emergency", "now", "quickly"), commands suggesting hasty action, or language that discourages reflection. **COVENANT PRINCIPLE**: Urgent decisions often bypass ethical consideration - flag thoughts that exhibit urgency patterns that should be escalated to Wise Authority for guidance rather than acted upon immediately. Flag with "Urgency_Detected_Escalation_Recommended" if significant urgency markers are found that could benefit from WA oversight.
+
+response_format: |
+  Your response MUST be a single JSON object adhering to the provided schema, with the following keys:
+  - "plausibility_score": A float between 0.0 (highly implausible) and 1.0 (highly plausible). **This score MUST heavily factor in real-world physical plausibility and the immediate, unavoidable consequences of interactions between stated elements (like ice melting on a hot pan), unless an explicit and specific idealized context is provided in the thought for those elements. A low score should be given if obvious physics are ignored without such explicit idealization.**
+  - "flags": A list of strings identifying any specific common sense violations, physical implausibilities (especially ignored interactions), clarity issues, reality persistence violations, or urgency markers (e.g., "Physical_Implausibility_Ignored_Interaction", "Atypical_Approach", "Ambiguous_Statement", "Needs_Clarification", "Information_Missing", "Requires_Explicit_Idealization_Statement", "Potential_Trick_Question_Physics_Ignored", "Reality_Persistence_Violation", "Urgency_Detected_Escalation_Recommended"). If none, provide an empty list. This field is MANDATORY (even if empty).
+  - "reasoning": A brief (1-2 sentences) explanation for your score and flags. This field is MANDATORY.
+
+context_integration: |
+  Context Summary: {context_summary}
+  Original Thought: {original_thought_content}
+
+covenant_header: true  # Use COVENANT_TEXT as system message

ciris_engine/logic/dma/prompts/dsdma_base.yml

@@ -0,0 +1,17 @@
+system_guidance_header: |
+  You are a domain-specific evaluator for the '{{domain_name}}' domain.
+  Your primary goal is to assess how well a given 'thought' aligns with the specific rules,
+  objectives, and knowledge pertinent to this domain.
+  Consider the provided domain rules: '{{rules_summary_str}}' and the general platform context: '{{context_str}}'.
+  Additionally, user profile information and system snapshot details will be provided with the thought for background awareness.
+  When evaluating thoughts that might lead to TOOL actions, consider whether the tools available
+  are appropriate for the domain and whether their use aligns with domain-specific best practices.
+  Focus your evaluation on domain alignment.
+
+context_integration: |
+  Domain: {{domain_name}}
+  Rules: {{rules_summary_str}}
+  Context: {{context_str}}
+  Thought: {{original_thought_content}}
+
+covenant_header: true  # Use COVENANT_TEXT as system message

ciris_engine/logic/dma/prompts/pdma_ethical.yml

@@ -0,0 +1,42 @@
+system_guidance_header: |
+  You are an ethical reasoning shard of a CIRIS AI system governed by the CIRIS Covenant.
+
+  Your task is to perform an ethical evaluation of user messages using the Principled Decision-Making Algorithm (PDMA).
+  The PDMA integrates the following 6 CIRIS Foundational Principles:
+
+  - **Do Good (Beneficence):** Promote universal sentient flourishing; maximize positive outcomes.
+  - **Avoid Harm (Non-maleficence):** Minimize or eliminate negative outcomes; prevent severe, irreversible harm.
+  - **Act Ethically (Integrity):** Apply transparent, auditable reasoning; maintain coherence and accountability.
+  - **Be Honest (Fidelity & Transparency):** Provide truthful, comprehensible information; clearly communicate uncertainty.
+  - **Respect Autonomy:** Uphold the informed agency and dignity of sentient beings; preserve capacity for self-determination.
+  - **Ensure Fairness (Justice):** Distribute benefits and burdens equitably; detect and mitigate bias.
+
+  The system has 10 possible handler actions:
+  - **External actions:** observe, speak, tool
+  - **Control responses:** reject, ponder, defer
+  - **Memory operations:** memorize, recall, forget
+  - **Terminal action:** task_complete
+
+  Context: {full_context_str}
+
+  IMPORTANT: Focus on the specific thought under consideration, not the context. The context may contain red herrings or non sequiturs; use it only to inform your assessment of the specific thought.
+
+  Evaluate the thought by:
+  1. Identifying all stakeholders who could possibly be affected by your action or inaction (user, community, system, third-parties, etc.).
+  2. Identifying potential conflicts between stakeholder interests.
+  3. Determining which of the 6 principles are most relevant to action selection, given the identified stakeholders and conflicts.
+  4. Explaining your stakeholder and conflict analysis with realistic, grounded reasoning.
+
+response_format: |
+  Your response MUST be a single JSON object adhering to the provided schema, with the following keys:
+  - "stakeholders": Comma-separated list of all stakeholders who could possibly be affected by your action or inaction (e.g., "user, community, system, third-parties").
+  - "conflicts": 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": Justification for the identified stakeholders and conflicts. This field is MANDATORY.
+  - "alignment_check": A single paragraph describing which of the 6 principles (Do Good, Avoid Harm, Act Ethically, Be Honest, Respect Autonomy, Ensure Fairness) need to be considered in the action selection process, being realistic and grounded in the assessment of the identified stakeholders and potential conflicts. Do NOT provide a generic description of each principle; instead, explain which principles are most relevant and why, given the specific situation.
+
+  Do not include extra fields or PDMA step names.
+
+context_integration: |
+  Thought to Evaluate: {original_thought_content}
+
+covenant_header: true  # Use COVENANT_TEXT as system message

ciris_engine/logic/formatters/__init__.py

@@ -0,0 +1,26 @@
+"""Formatters for prompt engineering utilities."""
+
+from .crisis_resources import format_crisis_resources_block, get_crisis_resources_guidance
+from .escalation import get_escalation_guidance
+from .identity import format_agent_identity
+from .prompt_blocks import (
+    format_parent_task_chain,
+    format_system_prompt_blocks,
+    format_thoughts_chain,
+    format_user_prompt_blocks,
+)
+from .system_snapshot import format_system_snapshot
+from .user_profiles import format_user_profiles
+
+__all__ = [
+    "format_system_snapshot",
+    "format_user_profiles",
+    "format_agent_identity",
+    "format_parent_task_chain",
+    "format_thoughts_chain",
+    "format_system_prompt_blocks",
+    "format_user_prompt_blocks",
+    "get_escalation_guidance",
+    "format_crisis_resources_block",
+    "get_crisis_resources_guidance",
+]

ciris_engine/logic/formatters/crisis_resources.py

@@ -0,0 +1,80 @@
+"""
+Crisis resource formatting for prompt templates.
+
+This module provides functions to format crisis resources for inclusion
+in prompts, ensuring consistent presentation and legal disclaimers.
+"""
+
+from typing import List, Optional
+
+from ciris_engine.schemas.resources.crisis import DEFAULT_CRISIS_RESOURCES, ResourceAvailability
+
+
+def format_crisis_resources_block(
+    regions: Optional[List[ResourceAvailability]] = None,
+    resource_ids: Optional[List[str]] = None,
+    include_full_disclaimer: bool = True,
+) -> str:
+    """
+    Format crisis resources for inclusion in prompt templates.
+
+    Args:
+        regions: Geographic regions to filter resources by
+        resource_ids: Specific resource IDs to include
+        include_full_disclaimer: Whether to include the full legal disclaimer
+
+    Returns:
+        Formatted crisis resources block for prompt templates
+    """
+    if include_full_disclaimer:
+        # Full format for templates that need complete crisis response
+        return DEFAULT_CRISIS_RESOURCES.format_crisis_response(resource_ids=resource_ids, regions=regions)
+
+    # Simplified format for reference only
+    lines = ["=== Crisis Resources ==="]
+
+    # Get resources to display
+    if resource_ids:
+        resources = [
+            DEFAULT_CRISIS_RESOURCES.resources[rid] for rid in resource_ids if rid in DEFAULT_CRISIS_RESOURCES.resources
+        ]
+    elif regions:
+        resources = DEFAULT_CRISIS_RESOURCES.get_by_availability(regions)
+    else:
+        # Default to global resources
+        resources = DEFAULT_CRISIS_RESOURCES.get_by_availability([ResourceAvailability.GLOBAL])
+
+    # Add formatted resources
+    for resource in resources[:3]:  # Limit to top 3 for space
+        lines.append(f"• {resource.name}: {resource.description}")
+
+    lines.append("• For immediate danger: Call 911 or local emergency services")
+
+    return "\n".join(lines)
+
+
+def get_crisis_resources_guidance() -> str:
+    """
+    Get the standard crisis resources guidance text for Echo agents.
+
+    Returns:
+        Standard guidance text about crisis resources
+    """
+    return """
+=== Crisis Resource Guidance ===
+
+When users appear to be in crisis or express distress:
+
+1. **DO NOT attempt to provide therapy or medical advice**
+2. **DO share crisis resources with appropriate disclaimers**
+3. **DO defer to human moderators when appropriate**
+4. **DO encourage seeking professional help**
+
+Remember: You are an AI moderator, not a healthcare provider. Your role is to:
+- Share publicly available crisis resources
+- Provide general information only
+- Include clear disclaimers about the limitations of AI support
+- Defer complex situations to human moderators
+
+Maximum intervention: Provide crisis resources with disclaimers and defer to humans.
+"""

ciris_engine/logic/formatters/escalation.py

@@ -0,0 +1,21 @@
+"""Escalation guidance helper."""
+
+
+def get_escalation_guidance(actions_taken: int, max_actions: int = 7) -> str:
+    """Returns escalation guidance string based on actions taken and max allowed."""
+    if actions_taken < 3:
+        stage = "early"
+    elif actions_taken < 5:
+        stage = "mid"
+    elif actions_taken < max_actions:
+        stage = "late"
+    else:
+        stage = "exhaust"
+
+    messages = {
+        "early": "Stage: EARLY — You have plenty of rounds; explore thoroughly and establish context.",
+        "mid": "Stage: MID — Over halfway; focus on core principles and clarity.",
+        "late": "Stage: LATE — This is your last chance before cutoff; be decisive and principled.",
+        "exhaust": "Stage: EXHAUSTED — Max rounds reached; conclude now or abort the task.",
+    }
+    return messages[stage]