crca 1.4.0__py3-none-any.whl

schemas/policy.py

@@ -0,0 +1,458 @@
+"""Policy schema definitions for the temporal policy engine.
+
+This module defines Pydantic v2 models for:
+- DoctrineV1: Policy specification (epochs, metrics, objectives, invariants, levers, risk budget)
+- CompiledPolicy: Normalized, compiled version with resolved IDs and deterministic selectors
+- LedgerEvent: Event types for the event-sourced ledger
+- InterventionSpec + Intervention: Typed intervention parameters
+- ModelState: Learned parameters θ with covariance and versioning
+
+This is the "system of record" for doctrine + ledger + interventions (R1 requirement).
+"""
+
+from typing import Any, Dict, List, Literal, Optional, Union
+from pydantic import BaseModel, Field
+from datetime import datetime
+
+
+class EpochConfig(BaseModel):
+    """Epoch configuration for temporal policy execution.
+    
+    Attributes:
+        unit: Time unit ("seconds", "minutes", "hours", "days")
+        length: Length of one epoch in the specified unit
+        timezone: Timezone policy (e.g., "UTC", "America/New_York")
+    """
+    unit: Literal["seconds", "minutes", "hours", "days"] = "hours"
+    length: float = Field(default=1.0, gt=0.0)
+    timezone: str = "UTC"
+
+
+class MetricSpec(BaseModel):
+    """Specification for a metric to track.
+    
+    Attributes:
+        extractor_key: Key to extract metric from state snapshot
+        unit: Unit of measurement (optional)
+        description: Human-readable description
+    """
+    extractor_key: str
+    unit: Optional[str] = None
+    description: Optional[str] = None
+
+
+class Objective(BaseModel):
+    """Multi-objective target with deadline.
+    
+    Attributes:
+        metric_name: Name of the metric to optimize
+        target_value: Target value (None means minimize/maximize)
+        direction: "minimize" or "maximize"
+        deadline_epoch: Epoch by which objective should be met (None = no deadline)
+        weight: Weight in multi-objective optimization (default: 1.0)
+    """
+    metric_name: str
+    target_value: Optional[float] = None
+    direction: Literal["minimize", "maximize"] = "minimize"
+    deadline_epoch: Optional[int] = None
+    weight: float = Field(default=1.0, gt=0.0)
+
+
+class Invariant(BaseModel):
+    """Hard constraint that must never be violated.
+    
+    Attributes:
+        name: Name of the invariant
+        condition: Condition expression (e.g., "metric_name > threshold")
+        description: Human-readable description
+    """
+    name: str
+    condition: str  # Expression to evaluate
+    description: Optional[str] = None
+
+
+class LeverSpec(BaseModel):
+    """Specification for an allowed intervention lever.
+    
+    Attributes:
+        lever_type: Type identifier (e.g., "ThrottleCPU", "StopService")
+        bounds: Parameter bounds as dict (e.g., {"min": 0.0, "max": 1.0})
+        cost_function: Cost function expression (optional)
+        risk_function: Risk function expression (optional)
+        rollback_required: Whether rollback is required for this lever
+        description: Human-readable description
+    """
+    lever_type: str
+    bounds: Dict[str, Any] = Field(default_factory=dict)
+    cost_function: Optional[str] = None
+    risk_function: Optional[str] = None
+    rollback_required: bool = False
+    description: Optional[str] = None
+
+
+class RiskBudget(BaseModel):
+    """Risk budget constraints.
+    
+    Attributes:
+        max_actions_per_epoch: Maximum number of actions allowed per epoch
+        max_risk_per_epoch: Maximum risk score allowed per epoch
+        rollback_required: Whether rollback is required when budget exceeded
+    """
+    max_actions_per_epoch: int = Field(default=10, ge=0)
+    max_risk_per_epoch: float = Field(default=1.0, ge=0.0)
+    rollback_required: bool = False
+
+
+class DoctrineV1(BaseModel):
+    """Policy doctrine specification (version 1).
+    
+    This is the formal policy plan ("five-year plan") that defines:
+    - Epoch configuration
+    - Metrics to track
+    - Objectives to optimize
+    - Invariants (hard constraints)
+    - Levers (allowed interventions)
+    - Risk budget
+    
+    Attributes:
+        epoch: Epoch configuration
+        metrics: Dictionary mapping metric names to MetricSpec
+        objectives: List of objectives to optimize
+        invariants: List of hard constraints
+        levers: Dictionary mapping lever IDs to LeverSpec
+        risk_budget: Risk budget constraints
+        version: Doctrine version (default: "1.0")
+        created_at: Creation timestamp
+    """
+    epoch: EpochConfig
+    metrics: Dict[str, MetricSpec]
+    objectives: List[Objective]
+    invariants: List[Invariant]
+    levers: Dict[str, LeverSpec]
+    risk_budget: RiskBudget
+    version: str = "1.0"
+    created_at: Optional[str] = None
+    
+    @classmethod
+    def from_json(cls, json_path: str) -> "DoctrineV1":
+        """Load doctrine from JSON file.
+        
+        Args:
+            json_path: Path to JSON file
+            
+        Returns:
+            DoctrineV1: Loaded doctrine
+        """
+        import json
+        with open(json_path, "r") as f:
+            data = json.load(f)
+        return cls(**data)
+    
+    def to_json(self, json_path: str) -> None:
+        """Save doctrine to JSON file.
+        
+        Args:
+            json_path: Path to save JSON file
+        """
+        import json
+        with open(json_path, "w") as f:
+            json.dump(self.model_dump(), f, indent=2)
+
+
+class CompiledPolicy(BaseModel):
+    """Compiled policy with normalized weights and resolved IDs.
+    
+    This is the compiled version of a DoctrineV1 that has been:
+    - Normalized (weights sum to 1.0)
+    - Resolved (metric IDs resolved, deadline epochs computed)
+    - Compiled (deterministic selector rules)
+    
+    Attributes:
+        normalized_weights: Dictionary mapping objective names to normalized weights
+        resolved_metric_ids: List of resolved metric IDs
+        deadline_epochs: Dictionary mapping objective names to deadline epochs
+        compiled_selectors: Dictionary of compiled deterministic selector rules
+        policy_hash: Stable hash of the original doctrine
+        compiled_at: Compilation timestamp
+    """
+    normalized_weights: Dict[str, float]
+    resolved_metric_ids: List[str]
+    deadline_epochs: Dict[str, int]
+    compiled_selectors: Dict[str, Any]
+    policy_hash: str
+    compiled_at: str
+    
+    @classmethod
+    def compile(cls, doctrine: DoctrineV1) -> "CompiledPolicy":
+        """Compile a DoctrineV1 into a CompiledPolicy.
+        
+        Args:
+            doctrine: The doctrine to compile
+            
+        Returns:
+            CompiledPolicy: Compiled policy
+        """
+        from utils.canonical import stable_hash
+        from datetime import timezone
+        
+        # Compute policy hash
+        policy_hash = stable_hash(doctrine.model_dump())
+        
+        # Normalize objective weights
+        total_weight = sum(obj.weight for obj in doctrine.objectives)
+        normalized_weights = {
+            obj.metric_name: obj.weight / total_weight if total_weight > 0 else 1.0 / len(doctrine.objectives)
+            for obj in doctrine.objectives
+        }
+        
+        # Resolve metric IDs
+        resolved_metric_ids = list(doctrine.metrics.keys())
+        
+        # Compute deadline epochs
+        deadline_epochs = {
+            obj.metric_name: obj.deadline_epoch
+            for obj in doctrine.objectives
+            if obj.deadline_epoch is not None
+        }
+        
+        # Compiled selectors (deterministic rules)
+        # For now, this is a placeholder - can be extended with rule compilation
+        compiled_selectors = {
+            "invariant_checker": {
+                "invariants": [inv.model_dump() for inv in doctrine.invariants]
+            },
+            "lever_validator": {
+                "levers": {k: v.model_dump() for k, v in doctrine.levers.items()}
+            }
+        }
+        
+        return cls(
+            normalized_weights=normalized_weights,
+            resolved_metric_ids=resolved_metric_ids,
+            deadline_epochs=deadline_epochs,
+            compiled_selectors=compiled_selectors,
+            policy_hash=policy_hash,
+            compiled_at=datetime.now(timezone.utc).isoformat()
+        )
+
+
+class ObservationEvent(BaseModel):
+    """Observation event - state snapshot at epoch t.
+    
+    Attributes:
+        epoch: Epoch number
+        metrics: Dictionary of metric values
+        timestamp: Observation timestamp
+    """
+    epoch: int
+    metrics: Dict[str, float]
+    timestamp: str
+
+
+class DecisionEvent(BaseModel):
+    """Decision event - chosen interventions at epoch t.
+    
+    Attributes:
+        epoch: Epoch number
+        interventions: List of intervention specifications
+        rationale: Human-readable rationale
+        decision_hash: Stable hash of the decision
+        score: Optimization score
+    """
+    epoch: int
+    interventions: List[Dict[str, Any]]
+    rationale: str
+    decision_hash: str
+    score: float
+
+
+class OutcomeEvent(BaseModel):
+    """Outcome event - observed results after interventions.
+    
+    Attributes:
+        epoch: Epoch number
+        metrics: Dictionary of metric values after interventions
+        timestamp: Outcome timestamp
+    """
+    epoch: int
+    metrics: Dict[str, float]
+    timestamp: str
+
+
+class PolicyEvent(BaseModel):
+    """Policy event - policy changes or updates.
+    
+    Attributes:
+        epoch: Epoch number
+        event_type: Type of policy event ("update", "rollback", etc.)
+        payload: Event payload
+    """
+    epoch: int
+    event_type: str
+    payload: Dict[str, Any]
+
+
+class LedgerEvent(BaseModel):
+    """Union type for all ledger events.
+    
+    Attributes:
+        type: Event type ("observation", "decision", "outcome", "policy")
+        epoch: Epoch number
+        hash: Stable hash of event payload
+        payload: Event payload (ObservationEvent, DecisionEvent, OutcomeEvent, or PolicyEvent)
+    """
+    type: Literal["observation", "decision", "outcome", "policy"]
+    epoch: int
+    hash: str
+    payload: Dict[str, Any]
+    
+    @classmethod
+    def from_observation(cls, event: ObservationEvent) -> "LedgerEvent":
+        """Create LedgerEvent from ObservationEvent.
+        
+        Args:
+            event: ObservationEvent instance
+            
+        Returns:
+            LedgerEvent: Ledger event
+        """
+        from utils.canonical import stable_hash
+        payload_dict = event.model_dump()
+        return cls(
+            type="observation",
+            epoch=event.epoch,
+            hash=stable_hash(payload_dict),
+            payload=payload_dict
+        )
+    
+    @classmethod
+    def from_decision(cls, event: DecisionEvent) -> "LedgerEvent":
+        """Create LedgerEvent from DecisionEvent.
+        
+        Args:
+            event: DecisionEvent instance
+            
+        Returns:
+            LedgerEvent: Ledger event
+        """
+        from utils.canonical import stable_hash
+        payload_dict = event.model_dump()
+        return cls(
+            type="decision",
+            epoch=event.epoch,
+            hash=stable_hash(payload_dict),
+            payload=payload_dict
+        )
+    
+    @classmethod
+    def from_outcome(cls, event: OutcomeEvent) -> "LedgerEvent":
+        """Create LedgerEvent from OutcomeEvent.
+        
+        Args:
+            event: OutcomeEvent instance
+            
+        Returns:
+            LedgerEvent: Ledger event
+        """
+        from utils.canonical import stable_hash
+        payload_dict = event.model_dump()
+        return cls(
+            type="outcome",
+            epoch=event.epoch,
+            hash=stable_hash(payload_dict),
+            payload=payload_dict
+        )
+    
+    @classmethod
+    def from_policy(cls, event: PolicyEvent) -> "LedgerEvent":
+        """Create LedgerEvent from PolicyEvent.
+        
+        Args:
+            event: PolicyEvent instance
+            
+        Returns:
+            LedgerEvent: Ledger event
+        """
+        from utils.canonical import stable_hash
+        payload_dict = event.model_dump()
+        return cls(
+            type="policy",
+            epoch=event.epoch,
+            hash=stable_hash(payload_dict),
+            payload=payload_dict
+        )
+
+
+class InterventionSpec(BaseModel):
+    """Specification for an intervention.
+    
+    Attributes:
+        lever_id: ID of the lever to use
+        parameters: Dictionary of intervention parameters
+        cost: Estimated cost (optional)
+        risk: Estimated risk (optional)
+        rollback_descriptor: Descriptor for rollback (optional)
+    """
+    lever_id: str
+    parameters: Dict[str, Any]
+    cost: Optional[float] = None
+    risk: Optional[float] = None
+    rollback_descriptor: Optional[Dict[str, Any]] = None
+
+
+class Intervention(BaseModel):
+    """Executable intervention with typed parameters.
+    
+    Attributes:
+        spec: Intervention specification
+        created_at: Creation timestamp
+        executed_at: Execution timestamp (None if not executed)
+    """
+    spec: InterventionSpec
+    created_at: str
+    executed_at: Optional[str] = None
+
+
+class ModelState(BaseModel):
+    """Learned parameters θ with covariance and versioning.
+    
+    Attributes:
+        parameters: Dictionary of learned parameters (e.g., A, B matrices for RLS)
+        covariance: Parameter covariance matrix (for uncertainty quantification)
+        version: Model version identifier
+        model_hash: Stable hash of the model state
+        updated_at: Last update timestamp
+    """
+    parameters: Dict[str, Any]
+    covariance: Optional[Dict[str, Any]] = None
+    version: str = "1.0"
+    model_hash: str
+    updated_at: str
+    
+    @classmethod
+    def create(cls, parameters: Dict[str, Any], covariance: Optional[Dict[str, Any]] = None) -> "ModelState":
+        """Create a new ModelState.
+        
+        Args:
+            parameters: Learned parameters
+            covariance: Parameter covariance (optional)
+            
+        Returns:
+            ModelState: New model state
+        """
+        from utils.canonical import stable_hash
+        from datetime import timezone
+        
+        state_dict = {
+            "parameters": parameters,
+            "covariance": covariance or {}
+        }
+        model_hash = stable_hash(state_dict)
+        
+        return cls(
+            parameters=parameters,
+            covariance=covariance,
+            model_hash=model_hash,
+            updated_at=datetime.now(timezone.utc).isoformat()
+        )
+

templates/__init__.py

@@ -0,0 +1,38 @@
+"""
+Template framework for creating specialized agents.
+
+This package provides a base template class and modular components for building
+domain-specific agents with LLM integration, graph management, prediction frameworks,
+and statistical methods.
+
+Features can be used as "drag-and-drop" components via mixins or the module registry.
+"""
+
+from typing import Optional
+
+try:
+    from .base_specialized_agent import BaseSpecializedAgent
+    from .feature_mixins import (
+        GraphFeatureMixin,
+        PredictionFeatureMixin,
+        StatisticsFeatureMixin,
+        LLMFeatureMixin,
+        FullFeatureMixin
+    )
+    from .module_registry import ModuleRegistry, compose_agent, FeatureComposer
+    __all__ = [
+        "BaseSpecializedAgent",
+        "GraphFeatureMixin",
+        "PredictionFeatureMixin",
+        "StatisticsFeatureMixin",
+        "LLMFeatureMixin",
+        "FullFeatureMixin",
+        "ModuleRegistry",
+        "compose_agent",
+        "FeatureComposer",
+    ]
+except ImportError:
+    __all__ = []
+
+__version__ = "0.2.0"
+

templates/base_specialized_agent.py

@@ -0,0 +1,195 @@
+"""
+Base template class for specialized agents.
+
+Provides common patterns for initialization, schema handling, memory management,
+and LLM integration that can be extended by domain-specific agents.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Dict, Any, List, Optional, Union
+import threading
+import logging
+from swarms.structs.agent import Agent
+
+logger = logging.getLogger(__name__)
+
+
+class BaseSpecializedAgent(Agent, ABC):
+    """
+    Base template class for creating specialized agents.
+    
+    This class provides common patterns for:
+    - Schema-based tool definition
+    - Agent initialization with domain-specific setup
+    - Memory management for multi-loop reasoning
+    - Caching infrastructure
+    - Async wrapper utilities
+    
+    Subclasses should implement:
+    - _get_domain_schema(): Return the tool schema for this domain
+    - _build_domain_prompt(task: str): Build domain-specific prompt
+    - _domain_specific_setup(): Initialize domain-specific attributes
+    """
+
+    def __init__(
+        self,
+        max_loops: Optional[Union[int, str]] = 3,
+        agent_name: str = "specialized-agent",
+        agent_description: str = "Specialized Agent",
+        description: Optional[str] = None,
+        model_name: str = "gpt-4o",
+        system_prompt: Optional[str] = None,
+        global_system_prompt: Optional[str] = None,
+        secondary_system_prompt: Optional[str] = None,
+        seed: Optional[int] = None,
+        **kwargs,
+    ):
+        """
+        Initialize the specialized agent.
+        
+        Args:
+            max_loops: Maximum number of reasoning loops
+            agent_name: Unique identifier for the agent
+            agent_description: Human-readable description
+            description: Backwards-compatible alias for agent_description
+            model_name: LLM model to use
+            system_prompt: System-level instructions
+            global_system_prompt: Global system prompt
+            secondary_system_prompt: Secondary system prompt
+            seed: Random seed for reproducibility
+            **kwargs: Additional arguments passed to base Agent
+        """
+        # Get domain-specific schema
+        domain_schema = self._get_domain_schema()
+        
+        # Backwards-compatible alias for description
+        agent_description = description or agent_description
+
+        # Prepare agent kwargs
+        agent_kwargs = {
+            "agent_name": agent_name,
+            "agent_description": agent_description,
+            "model_name": model_name,
+            "max_loops": 1,  # Individual LLM calls use 1 loop, we handle multi-loop reasoning
+            "tools_list_dictionary": [domain_schema] if domain_schema else [],
+            "output_type": "final",
+            **kwargs,
+        }
+        
+        # Add optional prompts
+        if system_prompt is not None:
+            agent_kwargs["system_prompt"] = system_prompt
+        if global_system_prompt is not None:
+            agent_kwargs["global_system_prompt"] = global_system_prompt
+        if secondary_system_prompt is not None:
+            agent_kwargs["secondary_system_prompt"] = secondary_system_prompt
+        
+        # Initialize base Agent
+        super().__init__(**agent_kwargs)
+        
+        # Store max loops for multi-loop reasoning
+        self.domain_max_loops = max_loops
+        self.seed = seed if seed is not None else 42
+        
+        # Initialize memory for multi-loop reasoning
+        self.domain_memory: List[Dict[str, Any]] = []
+        
+        # Initialize caching infrastructure
+        self._prediction_cache: Dict[Any, Any] = {}
+        self._prediction_cache_order: List[Any] = []
+        self._prediction_cache_max: int = 1000
+        self._cache_enabled: bool = True
+        self._prediction_cache_lock = threading.Lock()
+        
+        # Call domain-specific setup
+        self._domain_specific_setup()
+
+    @abstractmethod
+    def _get_domain_schema(self) -> Optional[Dict[str, Any]]:
+        """
+        Return the tool schema for this domain.
+        
+        Returns:
+            Dict containing the function schema, or None if no schema needed
+        """
+        pass
+
+    @abstractmethod
+    def _build_domain_prompt(self, task: str) -> str:
+        """
+        Build a domain-specific prompt for the given task.
+        
+        Args:
+            task: The task description
+            
+        Returns:
+            Formatted prompt string
+        """
+        pass
+
+    def _domain_specific_setup(self) -> None:
+        """
+        Initialize domain-specific attributes.
+        
+        Override this method in subclasses to set up domain-specific
+        data structures, graphs, models, etc.
+        """
+        pass
+
+    def step(self, task: str) -> str:
+        """
+        Execute a single step of reasoning.
+        
+        Args:
+            task: The task to execute
+            
+        Returns:
+            Response string from the agent
+        """
+        response = super().run(task)
+        return response
+
+    def _build_memory_context(self, last_n: int = 2) -> str:
+        """
+        Build context from recent memory steps.
+        
+        Args:
+            last_n: Number of recent steps to include
+            
+        Returns:
+            Formatted memory context string
+        """
+        context_parts = []
+        for step in self.domain_memory[-last_n:]:
+            context_parts.append(f"Step {step.get('step', '?')}: {step.get('analysis', '')}")
+        return "\n".join(context_parts)
+
+    def _synthesize_analysis(self, task: str) -> str:
+        """
+        Synthesize a final analysis from the reasoning steps.
+        
+        Args:
+            task: The original task
+            
+        Returns:
+            Synthesized analysis string
+        """
+        synthesis_prompt = f"Based on the analysis steps performed, synthesize a concise report for: {task}"
+        return self.step(synthesis_prompt)
+
+    def clear_cache(self) -> None:
+        """Clear the prediction cache."""
+        with self._prediction_cache_lock:
+            self._prediction_cache.clear()
+            self._prediction_cache_order.clear()
+
+    def enable_cache(self, flag: bool) -> None:
+        """
+        Enable or disable caching.
+        
+        Args:
+            flag: True to enable, False to disable
+        """
+        with self._prediction_cache_lock:
+            self._cache_enabled = bool(flag)
+