ciris-agent 1.7.7__py3-none-any.whl

ciris_engine/logic/utils/privacy.py

@@ -0,0 +1,266 @@
+"""
+Privacy utilities for respecting consent in audit and correlation storage.
+
+Provides functions to sanitize data based on user consent stream.
+"""
+
+import hashlib
+from datetime import datetime, timezone
+from typing import Optional
+
+from ciris_engine.logic.utils.jsondict_helpers import get_str
+from ciris_engine.schemas.audit.verification import RefutationProof
+from ciris_engine.schemas.types import JSONDict
+
+# Redaction placeholders - constants to avoid duplication
+REDACTED_MENTION = "[mention]"
+REDACTED_EMAIL = "[email]"
+REDACTED_PHONE = "[phone]"
+REDACTED_NUMBER = "[number]"
+REDACTED_URL = "[url]"
+REDACTED_NAME = "[name]"
+
+
+def sanitize_for_anonymous(data: JSONDict, user_id: Optional[str] = None) -> JSONDict:
+    """
+    Sanitize data for anonymous users.
+
+    Removes PII while preserving necessary audit information.
+    Stores content hash for future verification/refutation.
+
+    Args:
+        data: Data to sanitize (JSON-compatible dict)
+        user_id: Optional user ID for context
+
+    Returns:
+        Sanitized data with PII removed/hashed
+    """
+    sanitized = data.copy()
+
+    # Fields to completely remove for anonymous users
+    pii_fields = [
+        "author_name",
+        "username",
+        "display_name",
+        "real_name",
+        "email",
+        "phone",
+        "address",
+        "ip_address",
+    ]
+
+    for field in pii_fields:
+        if field in sanitized:
+            del sanitized[field]
+
+    # Fields to hash instead of storing raw
+    hashable_fields = [
+        "author_id",
+        "user_id",
+        "discord_id",
+        "member_id",
+    ]
+
+    for field in hashable_fields:
+        if field in sanitized and sanitized[field]:
+            # Replace with hash
+            value = str(sanitized[field])
+            sanitized[field] = f"anon_{hashlib.sha256(value.encode()).hexdigest()[:8]}"
+
+    # Handle content fields - hash original, store sanitized
+    content_fields = ["content", "message", "text", "body"]
+    for field in content_fields:
+        if field in sanitized and sanitized[field]:
+            original_content = str(sanitized[field])
+
+            # Create hash of original content for verification
+            content_hash = hashlib.sha256(original_content.encode()).hexdigest()
+            sanitized[f"{field}_hash"] = content_hash
+
+            # Store truncated/redacted version
+            if len(original_content) > 50:
+                sanitized[field] = f"{original_content[:47]}..."
+            else:
+                sanitized[field] = original_content
+
+            # Redact any mentions or personal info patterns - get as string first
+            field_value = get_str(sanitized, field, "")
+            sanitized[field] = redact_personal_info(field_value)
+
+    return sanitized
+
+
+def redact_personal_info(text: str) -> str:
+    """
+    Redact potential personal information from text.
+
+    Replaces mentions, emails, phone numbers, etc.
+    """
+    import re
+
+    # Discord mentions - simple and clear
+    text = re.sub(r"<@!?\d+>", REDACTED_MENTION, text)
+
+    # Email addresses - simplified to avoid backtracking DoS
+    # Limit length and use word boundaries to prevent ReDoS
+    text = re.sub(
+        r"\b[a-zA-Z0-9][a-zA-Z0-9._-]{0,63}@[a-zA-Z0-9][a-zA-Z0-9.-]{0,62}\.[a-zA-Z]{2,6}\b", REDACTED_EMAIL, text
+    )
+
+    # Phone numbers - handle multiple formats robustly
+    # Format: (555) 555-1234 or (555)555-1234
+    text = re.sub(r"\(\d{3}\)\s*\d{3}[-.]?\d{4}", REDACTED_PHONE, text)
+    # Format: 555-555-1234 or 555.555.1234 or 555 555 1234
+    text = re.sub(r"\b\d{3}[-.\s]\d{3}[-.\s]\d{4}\b", REDACTED_PHONE, text)
+    # Format: 5555551234 (10 digits together)
+    text = re.sub(r"\b\d{10}\b", REDACTED_PHONE, text)
+    # Format: 555-1234 (7 digit local)
+    text = re.sub(r"\b\d{3}-\d{4}\b", REDACTED_PHONE, text)
+    # Any other long number sequence (11+ digits)
+    text = re.sub(r"\b\d{11,}\b", REDACTED_NUMBER, text)
+
+    # URLs - simple pattern
+    text = re.sub(r"https?://[^\s]+", REDACTED_URL, text)
+
+    # Names after common phrases - keep it simple
+    text = re.sub(r"(I am|My name is|I\'m)\s+\w+(\s+\w+)?", rf"\1 {REDACTED_NAME}", text, flags=re.IGNORECASE)
+
+    return text
+
+
+def should_sanitize_for_user(user_consent_stream: Optional[str]) -> bool:
+    """
+    Determine if data should be sanitized based on consent stream.
+
+    Returns True for anonymous or expired temporary consent.
+    """
+    if not user_consent_stream:
+        return False
+
+    return user_consent_stream.lower() in ["anonymous", "expired", "revoked"]
+
+
+def sanitize_correlation_parameters(parameters: JSONDict, consent_stream: Optional[str] = None) -> JSONDict:
+    """
+    Sanitize correlation parameters based on consent.
+
+    Used when storing ServiceRequestData parameters.
+
+    Args:
+        parameters: Correlation parameters to sanitize
+        consent_stream: User consent stream status
+
+    Returns:
+        Sanitized parameters if consent requires it, otherwise original
+    """
+    if not should_sanitize_for_user(consent_stream):
+        return parameters
+
+    return sanitize_for_anonymous(parameters)
+
+
+def sanitize_audit_details(details: JSONDict, consent_stream: Optional[str] = None) -> JSONDict:
+    """
+    Sanitize audit entry details based on consent.
+
+    Used when creating audit entries.
+
+    Args:
+        details: Audit entry details to sanitize
+        consent_stream: User consent stream status
+
+    Returns:
+        Sanitized details if consent requires it, otherwise original
+    """
+    if not should_sanitize_for_user(consent_stream):
+        return details
+
+    return sanitize_for_anonymous(details)
+
+
+def sanitize_trace_content(content: str, consent_stream: Optional[str] = None) -> str:
+    """
+    Sanitize trace/audit content based on consent.
+
+    Preserves semantic meaning while removing PII.
+    Returns sanitized content with hash appended for verification.
+
+    Note: This is for audit trails and traces only.
+    Thoughts themselves are never sanitized.
+    """
+    if not should_sanitize_for_user(consent_stream):
+        return content
+
+    # Hash the original content for future verification
+    content_hash = hashlib.sha256(content.encode()).hexdigest()
+
+    # For anonymous users, redact personal info but keep semantic content
+    sanitized = redact_personal_info(content)
+
+    # If content is very long, truncate to reasonable length
+    if len(sanitized) > 500:
+        sanitized = f"{sanitized[:497]}..."
+
+    # Append hash for verification/refutation capability
+    sanitized += f" [Hash: {content_hash[:16]}]"
+
+    return sanitized
+
+
+def verify_content_hash(content: str, claimed_hash: str) -> bool:
+    """
+    Verify if content matches a claimed hash.
+
+    Used for refutation - proving we did/didn't see specific content.
+
+    Args:
+        content: The content to verify
+        claimed_hash: The hash to check against
+
+    Returns:
+        True if content matches the hash
+    """
+    actual_hash = hashlib.sha256(content.encode()).hexdigest()
+
+    # Support partial hash matching (first 8-16 chars often stored)
+    if len(claimed_hash) < len(actual_hash):
+        return actual_hash.startswith(claimed_hash)
+
+    return actual_hash == claimed_hash
+
+
+def create_refutation_proof(
+    claimed_content: str, stored_hash: str, actual_content: Optional[str] = None
+) -> RefutationProof:
+    """
+    Create a refutation proof for disputed content.
+
+    Args:
+        claimed_content: What someone claims was said
+        stored_hash: The hash we have stored
+        actual_content: The actual content if available
+
+    Returns:
+        Proof dictionary with verification results
+    """
+    claimed_content_hash = hashlib.sha256(claimed_content.encode()).hexdigest()
+    matches_stored = verify_content_hash(claimed_content, stored_hash)
+
+    actual_content_hash = None
+    actual_matches_stored = None
+    claimed_matches_actual = None
+
+    if actual_content:
+        actual_content_hash = hashlib.sha256(actual_content.encode()).hexdigest()
+        actual_matches_stored = verify_content_hash(actual_content, stored_hash)
+        claimed_matches_actual = claimed_content_hash == actual_content_hash
+
+    return RefutationProof(
+        timestamp=datetime.now(timezone.utc).isoformat(),
+        stored_hash=stored_hash,
+        claimed_content_hash=claimed_content_hash,
+        matches_stored=matches_stored,
+        actual_content_hash=actual_content_hash,
+        actual_matches_stored=actual_matches_stored,
+        claimed_matches_actual=claimed_matches_actual,
+    )

ciris_engine/logic/utils/profile_loader.py

@@ -0,0 +1,124 @@
+import asyncio
+import logging
+from pathlib import Path
+from typing import Any, List, Optional
+
+import yaml
+from pydantic import ValidationError
+
+from ciris_engine.schemas.config.agent import AgentTemplate
+
+# Import adapter configs to resolve forward references
+try:
+    pass
+    # Rebuild models with resolved references
+    AgentTemplate.model_rebuild()
+except Exception:
+    pass  # Continue without rebuild if imports fail
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_TEMPLATE_PATH = Path("ciris_templates/default.yaml")
+
+
+async def load_template(template_path: Optional[Path]) -> Optional[AgentTemplate]:
+    """Asynchronously load an agent template from a YAML file.
+
+    This coroutine should be awaited so file I/O does not block the event loop.
+
+    Template Search Order (if template_path is None):
+    1. CWD/ciris_templates/ (development mode)
+    2. CIRIS_HOME/ciris_templates/ (if CIRIS_HOME set)
+    3. ~/ciris/ciris_templates/ (user templates)
+    4. <package>/ciris_templates/ (bundled templates)
+
+    Args:
+        template_path: Path to the YAML template file. If None, searches for default.yaml.
+
+    Returns:
+        An AgentTemplate instance if loading is successful, otherwise None.
+    """
+    if template_path is None:
+        # First check if DEFAULT_TEMPLATE_PATH exists (for tests/backwards compatibility)
+        if DEFAULT_TEMPLATE_PATH.exists():
+            template_path = DEFAULT_TEMPLATE_PATH
+        else:
+            # Search for default template in multiple locations
+            from ciris_engine.logic.utils.path_resolution import find_template_file
+
+            resolved_path = find_template_file("default")
+            if resolved_path is None:
+                # Fallback to DEFAULT_TEMPLATE_PATH for error message
+                template_path = DEFAULT_TEMPLATE_PATH
+            else:
+                template_path = resolved_path
+
+    if not template_path.exists() or not template_path.is_file():
+        # FAIL instead of falling back to default template
+        error_msg = f"Template file {template_path} not found or is not a file"
+        logger.error(error_msg)
+        raise FileNotFoundError(error_msg)
+
+    try:
+
+        def _load_yaml(path: Path) -> Any:
+            with open(path, "r") as f:
+                return yaml.safe_load(f)
+
+        template_data = await asyncio.to_thread(_load_yaml, template_path)
+
+        if not template_data:
+            logger.error(f"Template file is empty or invalid YAML: {template_path}")
+            return None
+
+        if "name" not in template_data:
+            template_data["name"] = template_path.stem
+            logger.warning(
+                f"Template 'name' not found in YAML, inferred as '{template_data['name']}' from filename: {template_path}"
+            )
+
+        if "permitted_actions" in template_data:
+            from ciris_engine.schemas.runtime.enums import HandlerActionType
+
+            converted_actions: List[object] = []
+            for action in template_data["permitted_actions"]:
+                if isinstance(action, HandlerActionType):
+                    converted_actions.append(action)
+                elif isinstance(action, str):
+                    try:
+                        enum_action = HandlerActionType(action)
+                        converted_actions.append(enum_action)
+                    except ValueError:
+                        try:
+                            enum_action = HandlerActionType[action.upper()]
+                            converted_actions.append(enum_action)
+                        except KeyError:
+                            matched = False
+                            for member in HandlerActionType:
+                                if member.value.lower() == action.lower():
+                                    converted_actions.append(member)
+                                    matched = True
+                                    break
+                            if not matched:
+                                logger.warning(f"Unknown action '{action}' in permitted_actions, skipping")
+                else:
+                    logger.warning(f"Invalid action type {type(action)} in permitted_actions")
+            template_data["permitted_actions"] = [a for a in converted_actions if isinstance(a, HandlerActionType)]
+
+        template = AgentTemplate(**template_data)
+        logger.info(f"Successfully loaded template '{template.name}' from {template_path}")
+        return template
+
+    except yaml.YAMLError as e:
+        error_msg = f"Error parsing YAML template file {template_path}: {e}"
+        logger.exception(error_msg)
+        raise ValueError(error_msg) from e
+    except ValidationError as e:
+        # Pydantic validation error - template doesn't match schema
+        error_msg = f"Template validation failed for {template_path}: {e}"
+        logger.exception(error_msg)
+        raise ValueError(error_msg) from e
+    except Exception as e:
+        error_msg = f"Error loading or validating template from {template_path}: {e}"
+        logger.exception(error_msg)
+        raise RuntimeError(error_msg) from e

ciris_engine/logic/utils/profile_manager.py

@@ -0,0 +1,16 @@
+"""Legacy profile manager - DEPRECATED.
+
+This module is deprecated and should not be used.
+Agent identity is now managed through the graph-based identity system.
+See ciris_engine/persistence/models/identity.py for the new approach.
+"""
+
+import logging
+
+logger = logging.getLogger(__name__)
+
+logger.warning(
+    "profile_manager.py is deprecated. "
+    "Agent identity is now managed through the graph-based identity system. "
+    "See ciris_engine/persistence/models/identity.py"
+)

ciris_engine/logic/utils/runtime_utils.py

@@ -0,0 +1,69 @@
+"""Runtime utilities for CIRIS engine startup and configuration."""
+
+import asyncio
+import logging
+import signal
+from pathlib import Path
+from typing import Optional
+
+from ciris_engine.schemas.config.essential import EssentialConfig
+from ciris_engine.schemas.types import ConfigDict
+
+from ..config.bootstrap import ConfigBootstrap
+from ..runtime.ciris_runtime import CIRISRuntime
+
+
+async def load_config(config_path: Optional[str], cli_overrides: Optional[ConfigDict] = None) -> EssentialConfig:
+    """Load essential configuration using the new bootstrap system.
+
+    Args:
+        config_path: Optional path to configuration file
+        cli_overrides: Optional configuration overrides from command line
+
+    Returns:
+        Loaded and validated essential configuration
+    """
+    return await ConfigBootstrap.load_essential_config(
+        config_path=Path(config_path) if config_path else None, cli_overrides=cli_overrides
+    )
+
+
+async def run_with_shutdown_handler(runtime: CIRISRuntime, num_rounds: Optional[int] = None) -> None:
+    """Run the runtime and handle shutdown signals gracefully."""
+    loop = asyncio.get_running_loop()
+    shutdown_requested_event = asyncio.Event()
+
+    def signal_handler() -> None:
+        if not shutdown_requested_event.is_set():
+            logging.info("Shutdown signal received. Requesting runtime shutdown...")
+            runtime.request_shutdown("Signal received by main.py handler")
+            shutdown_requested_event.set()  # Prevent multiple calls to request_shutdown from signals
+        else:
+            logging.info("Shutdown already in progress.")
+
+    for sig in (signal.SIGINT, signal.SIGTERM):
+        try:
+            loop.add_signal_handler(sig, signal_handler)
+        except NotImplementedError:
+            # Some environments (like Windows default loop) might not support add_signal_handler
+            logging.warning(f"Signal handler for {sig} could not be set. Manual shutdown might be required.")
+            pass  # Continue without signal handlers if not supported
+
+    try:
+        await runtime.run(num_rounds)
+    except Exception as e:
+        logging.critical(f"Runtime execution failed: {e}", exc_info=True)
+        # Ensure shutdown is requested if a top-level error occurs in runtime.run() itself
+        if (
+            runtime._shutdown_event is None or not runtime._shutdown_event.is_set()
+        ):  # Accessing protected member for check
+            runtime.request_shutdown(f"Runtime error: {e}")
+        await runtime.shutdown()  # Attempt graceful shutdown
+    finally:
+        logging.info("Runtime execution finished or was interrupted.")
+        # Ensure signal handlers are removed to avoid issues if the loop is reused
+        for sig in (signal.SIGINT, signal.SIGTERM):
+            try:
+                loop.remove_signal_handler(sig)
+            except (NotImplementedError, ValueError):  # ValueError if not set
+                pass

ciris_engine/logic/utils/shutdown_manager.py

@@ -0,0 +1,107 @@
+"""
+Shutdown manager compatibility module.
+
+This module provides backwards compatibility for code that imports from
+the old shutdown_manager location. The functionality is now provided by
+the ShutdownService.
+"""
+
+import logging
+from typing import Any, Callable, Optional
+
+from ciris_engine.logic.services.lifecycle.shutdown import ShutdownService
+
+logger = logging.getLogger(__name__)
+
+# Global instance for compatibility
+_global_shutdown_service: Optional[ShutdownService] = None
+
+
+# Keep original function definition for type hints
+def _get_shutdown_service() -> ShutdownService:
+    """Get or create the global shutdown service instance."""
+    global _global_shutdown_service
+    if _global_shutdown_service is None:
+        _global_shutdown_service = ShutdownService()
+    return _global_shutdown_service
+
+
+def is_global_shutdown_requested() -> bool:
+    """Check if shutdown has been requested."""
+    service = _get_shutdown_service()
+    return service.is_shutdown_requested()
+
+
+def get_global_shutdown_reason() -> Optional[str]:
+    """Get the reason for shutdown if any."""
+    service = _get_shutdown_service()
+    return service.get_shutdown_reason()
+
+
+def request_global_shutdown(reason: str = "Shutdown requested") -> None:
+    """Request a global shutdown."""
+    service = _get_shutdown_service()
+    # Use the sync version to avoid async/await issues
+    service._request_shutdown_sync(reason)
+
+
+def register_global_shutdown_handler(handler: Callable[[], None]) -> None:
+    """Register a shutdown handler."""
+    service = _get_shutdown_service()
+    service.register_shutdown_handler(handler)
+
+
+def wait_for_global_shutdown() -> None:
+    """Wait for shutdown to be requested (blocking)."""
+    service = _get_shutdown_service()
+    service.wait_for_shutdown()
+
+
+async def wait_for_global_shutdown_async() -> None:
+    """Wait for shutdown to be requested (async)."""
+    service = _get_shutdown_service()
+    await service.wait_for_shutdown_async()
+
+
+async def execute_async_handlers() -> None:
+    """Execute all registered async shutdown handlers."""
+    service = _get_shutdown_service()
+    if hasattr(service, "_execute_async_handlers"):
+        await service._execute_async_handlers()
+
+
+# Add attribute to shutdown service instance for compatibility
+class ShutdownManagerWrapper:
+    """Wrapper to provide compatibility methods."""
+
+    def __init__(self, service: ShutdownService) -> None:
+        self._service = service
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._service, name)
+
+    async def execute_async_handlers(self) -> None:
+        """Execute all registered async shutdown handlers."""
+        if hasattr(self._service, "_execute_async_handlers"):
+            await self._service._execute_async_handlers()
+
+
+def get_shutdown_manager() -> ShutdownManagerWrapper:
+    """Get or create the global shutdown service instance."""
+    global _global_shutdown_service
+    if _global_shutdown_service is None:
+        _global_shutdown_service = ShutdownService()
+    return ShutdownManagerWrapper(_global_shutdown_service)
+
+
+# Export for compatibility
+__all__ = [
+    "get_shutdown_manager",
+    "is_global_shutdown_requested",
+    "get_global_shutdown_reason",
+    "request_global_shutdown",
+    "register_global_shutdown_handler",
+    "wait_for_global_shutdown",
+    "wait_for_global_shutdown_async",
+    "execute_async_handlers",
+]

ciris_engine/logic/utils/task_formatters.py

@@ -0,0 +1,60 @@
+"""Prompt engineering utilities for summarizing task context."""
+
+from typing import Dict, List, Optional
+
+
+def format_task_context(
+    current_task: Dict[str, str],
+    recent_actions: List[Dict[str, str]],
+    completed_tasks: Optional[List[Dict[str, str]]] = None,
+    max_actions: int = 5,
+) -> str:
+    """Return a formatted summary block for LLM prompts.
+
+    Parameters
+    ----------
+    current_task : Dict[str, str]
+        Mapping containing ``description``, ``task_id`` and optional ``status``
+        and ``priority``.
+    recent_actions : List[Dict[str, str]]
+        Sequence of recent actions with ``description``, ``outcome`` and
+        ``updated_at`` fields.
+    completed_tasks : List[Dict[str, str]], optional
+        Optional list of completed tasks for additional context. Only the first
+        item is included.
+    max_actions : int, default 5
+        Maximum number of actions to include.
+
+    Returns
+    -------
+    str
+        A human-readable block describing the task context.
+    """
+
+    if not isinstance(current_task, dict):
+        raise TypeError("current_task must be a dict")
+
+    out_lines: List[str] = ["=== Current Task ==="]
+    cur_desc = str(current_task.get("description", ""))
+    task_id = current_task.get("task_id", "N/A")
+    status = current_task.get("status", "N/A")
+    priority = current_task.get("priority", "N/A")
+    out_lines.append(f"{cur_desc} (Task ID: {task_id}, Status: {status}, Priority: {priority})")
+
+    if recent_actions:
+        out_lines.append("\n=== Recent Actions ===")
+        for idx, act in enumerate(recent_actions[:max_actions], 1):
+            desc = str(act.get("description", ""))
+            outcome = str(act.get("outcome", ""))
+            upd = act.get("updated_at", "N/A")
+            out_lines.append(f"{idx}. {desc} | Outcome: {outcome} (updated: {upd})")
+
+    if completed_tasks:
+        last = completed_tasks[0]
+        if isinstance(last, dict):
+            desc = str(last.get("description", ""))
+            outcome = str(last.get("outcome", ""))
+            upd = last.get("updated_at", "N/A")
+            out_lines.append(f"\n=== Last Completed Task ===\n{desc} | Outcome: {outcome} (completed: {upd})")
+
+    return "\n".join(out_lines)