crca 1.4.0__py3-none-any.whl

templates/examples/drag_drop_example.py

@@ -0,0 +1,213 @@
+"""
+Drag-and-Drop Feature Composition Examples
+
+Demonstrates how to use the template framework modules as "drag-and-drop" features
+to quickly compose specialized agents.
+"""
+
+from typing import Dict, Any, List, Optional
+from templates.base_specialized_agent import BaseSpecializedAgent
+from templates.feature_mixins import (
+    GraphFeatureMixin,
+    PredictionFeatureMixin,
+    StatisticsFeatureMixin,
+    LLMFeatureMixin,
+    FullFeatureMixin
+)
+from templates.module_registry import compose_agent, ModuleRegistry
+from templates.llm_integration import create_default_schema
+
+
+# ============================================================================
+# Example 1: Minimal Agent (LLM only)
+# ============================================================================
+
+class MinimalAgent(BaseSpecializedAgent, LLMFeatureMixin):
+    """Minimal agent with just LLM capabilities."""
+    
+    def __init__(self, **kwargs):
+        super().__init__(**kwargs)
+        self.init_llm_feature()
+    
+    def _get_domain_schema(self):
+        return create_default_schema(
+            function_name="minimal_analysis",
+            description="Minimal analysis",
+            properties={"result": {"type": "string"}}
+        )
+    
+    def _build_domain_prompt(self, task: str) -> str:
+        return f"Analyze: {task}"
+    
+    def _domain_specific_setup(self):
+        pass
+
+
+# ============================================================================
+# Example 2: Graph + LLM Agent
+# ============================================================================
+
+class GraphLLMAgent(BaseSpecializedAgent, GraphFeatureMixin, LLMFeatureMixin):
+    """Agent with graph management and LLM capabilities."""
+    
+    def __init__(self, variables=None, edges=None, **kwargs):
+        super().__init__(**kwargs)
+        self.init_graph_feature(variables=variables, edges=edges)
+        self.init_llm_feature()
+    
+    def _get_domain_schema(self):
+        return create_default_schema(
+            function_name="graph_analysis",
+            description="Graph-based analysis",
+            properties={
+                "analysis": {"type": "string"},
+                "graph_info": {"type": "object"}
+            }
+        )
+    
+    def _build_domain_prompt(self, task: str) -> str:
+        return f"Task: {task}\nGraph has {len(self.get_nodes())} nodes."
+    
+    def _domain_specific_setup(self):
+        pass
+
+
+# ============================================================================
+# Example 3: Full-Featured Agent (All Features)
+# ============================================================================
+
+class FullFeaturedAgent(BaseSpecializedAgent, FullFeatureMixin):
+    """Agent with all features - graph, prediction, statistics, LLM."""
+    
+    def __init__(self, variables=None, edges=None, **kwargs):
+        super().__init__(**kwargs)
+        self.init_all_features(
+            variables=variables,
+            edges=edges,
+            use_nonlinear=True
+        )
+    
+    def _get_domain_schema(self):
+        return create_default_schema(
+            function_name="full_analysis",
+            description="Full-featured analysis",
+            properties={
+                "analysis": {"type": "string"},
+                "predictions": {"type": "object"},
+                "statistics": {"type": "object"}
+            }
+        )
+    
+    def _build_domain_prompt(self, task: str) -> str:
+        return f"Full analysis: {task}"
+    
+    def _domain_specific_setup(self):
+        pass
+
+
+# ============================================================================
+# Example 4: Custom Composition (Pick and Choose)
+# ============================================================================
+
+class CustomAgent(BaseSpecializedAgent, GraphFeatureMixin, PredictionFeatureMixin):
+    """Custom agent with only graph and prediction (no statistics, no LLM)."""
+    
+    def __init__(self, variables=None, edges=None, **kwargs):
+        super().__init__(**kwargs)
+        self.init_graph_feature(variables=variables, edges=edges)
+        self.init_prediction_feature(use_nonlinear=False)  # Linear only
+    
+    def _get_domain_schema(self):
+        return None  # No LLM schema needed
+    
+    def _build_domain_prompt(self, task: str) -> str:
+        return ""  # Not used without LLM
+    
+    def _domain_specific_setup(self):
+        pass
+    
+    def run(self, initial_state: Dict[str, float], interventions: Optional[Dict[str, float]] = None):
+        """Run predictions without LLM."""
+        return self.predict(initial_state, interventions or {})
+
+
+# ============================================================================
+# Example 5: Using Module Registry (Programmatic Composition)
+# ============================================================================
+
+def create_agent_with_features(features: List[str], **configs):
+    """
+    Create an agent with specified features using the registry.
+    
+    Args:
+        features: List of feature names ('graph', 'prediction', 'statistics', 'llm')
+        **configs: Configuration for each feature
+        
+    Returns:
+        Agent class
+    """
+    # Define a base agent
+    class DynamicAgent(BaseSpecializedAgent):
+        def _get_domain_schema(self):
+            return create_default_schema(
+                function_name="dynamic_analysis",
+                description="Dynamic analysis",
+                properties={"result": {"type": "string"}}
+            )
+        
+        def _build_domain_prompt(self, task: str) -> str:
+            return f"Task: {task}"
+        
+        def _domain_specific_setup(self):
+            pass
+    
+    # Compose with features
+    return compose_agent(
+        DynamicAgent,
+        features=features,
+        feature_configs=configs
+    )
+
+
+# ============================================================================
+# Usage Examples
+# ============================================================================
+
+if __name__ == "__main__":
+    # Example 1: Minimal agent
+    minimal = MinimalAgent(agent_name="minimal")
+    # result = minimal.analyze_with_llm("Analyze this problem")
+    
+    # Example 2: Graph + LLM
+    graph_llm = GraphLLMAgent(
+        agent_name="graph-llm",
+        variables=["A", "B", "C"],
+        edges=[("A", "B"), ("B", "C")]
+    )
+    # result = graph_llm.analyze_with_llm("Analyze the graph")
+    
+    # Example 3: Full featured
+    full = FullFeaturedAgent(
+        agent_name="full",
+        variables=["X", "Y", "Z"],
+        edges=[("X", "Y"), ("Y", "Z")]
+    )
+    # predictions = full.predict({"X": 1.0}, {"X": 1.5})
+    
+    # Example 4: Custom composition
+    custom = CustomAgent(
+        variables=["A", "B"],
+        edges=[("A", "B")]
+    )
+    # predictions = custom.run({"A": 1.0}, {"A": 2.0})
+    
+    # Example 5: Programmatic composition
+    AgentClass = create_agent_with_features(
+        features=['graph', 'prediction'],
+        graph={'graph_type': 'causal'},
+        prediction={'use_nonlinear': True}
+    )
+    # agent = AgentClass(agent_name="dynamic")
+    
+    print("All examples created successfully!")
+

templates/examples/logistics_agent_template.py

@@ -0,0 +1,207 @@
+"""
+Example: Logistics Agent Template
+
+This demonstrates how to create a logistics/supply chain agent using the template framework.
+"""
+
+from typing import Dict, Any, List, Tuple, Optional, Union
+from templates.base_specialized_agent import BaseSpecializedAgent
+from templates.graph_management import GraphManager
+from templates.prediction_framework import PredictionFramework
+from templates.statistical_methods import StatisticalMethods
+from templates.llm_integration import LLMIntegration, create_default_schema
+
+
+class LogisticsAgentTemplate(BaseSpecializedAgent):
+    """
+    Example logistics agent using the template framework.
+    
+    This agent can reason about supply chain relationships, predict delivery times,
+    optimize routes, and generate logistics strategies.
+    """
+
+    def __init__(
+        self,
+        supply_chain_nodes: Optional[List[str]] = None,
+        supply_chain_edges: Optional[List[Tuple[str, str]]] = None,
+        max_loops: Optional[Union[int, str]] = 3,
+        agent_name: str = "logistics-agent",
+        model_name: str = "gpt-4o",
+        **kwargs,
+    ):
+        """
+        Initialize the logistics agent.
+        
+        Args:
+            supply_chain_nodes: List of supply chain node names (e.g., ['warehouse', 'transport', 'delivery'])
+            supply_chain_edges: List of (source, target) relationship tuples
+            max_loops: Maximum reasoning loops
+            agent_name: Agent identifier
+            model_name: LLM model name
+            **kwargs: Additional arguments
+        """
+        super().__init__(
+            max_loops=max_loops,
+            agent_name=agent_name,
+            agent_description="Logistics and Supply Chain Analysis Agent",
+            model_name=model_name,
+            **kwargs,
+        )
+
+        # Initialize graph manager for supply chain
+        self.graph_manager = GraphManager(graph_type="supply_chain")
+        
+        # Initialize prediction framework
+        self.prediction_framework = PredictionFramework(
+            graph_manager=self.graph_manager,
+            use_nonlinear=False,  # Logistics often linear
+        )
+        
+        # Initialize statistical methods
+        self.statistical_methods = StatisticalMethods(
+            graph_manager=self.graph_manager,
+            prediction_framework=self.prediction_framework,
+            standardization_stats=self.prediction_framework.standardization_stats,
+        )
+        
+        # Initialize LLM integration
+        self.llm_integration = LLMIntegration(
+            agent=self,
+            max_loops=self.domain_max_loops if isinstance(self.domain_max_loops, int) else 3,
+        )
+        
+        # Add supply chain nodes and edges
+        if supply_chain_nodes:
+            self.graph_manager.add_nodes_from(supply_chain_nodes)
+        
+        if supply_chain_edges:
+            for source, target in supply_chain_edges:
+                self.add_supply_chain_relationship(source, target)
+
+    def _get_domain_schema(self) -> Optional[Dict[str, Any]]:
+        """Return the logistics analysis schema."""
+        return create_default_schema(
+            function_name="generate_logistics_analysis",
+            description="Generates logistics analysis and optimization recommendations",
+            properties={
+                "supply_chain_analysis": {
+                    "type": "string",
+                    "description": "Analysis of supply chain efficiency and bottlenecks"
+                },
+                "route_optimization": {
+                    "type": "string",
+                    "description": "Route optimization recommendations"
+                },
+                "delivery_scenarios": {
+                    "type": "array",
+                    "items": {
+                        "type": "object",
+                        "properties": {
+                            "scenario_name": {"type": "string"},
+                            "interventions": {"type": "object"},
+                            "expected_delivery_times": {"type": "object"},
+                            "cost_impact": {"type": "object"}
+                        }
+                    },
+                    "description": "Different delivery scenarios and their impacts"
+                },
+                "optimization_recommendations": {
+                    "type": "string",
+                    "description": "Recommendations for supply chain optimization"
+                }
+            },
+            required=[
+                "supply_chain_analysis",
+                "route_optimization",
+                "delivery_scenarios",
+                "optimization_recommendations"
+            ]
+        )
+
+    def _build_domain_prompt(self, task: str) -> str:
+        """Build a logistics analysis prompt."""
+        return (
+            f"You are a Logistics and Supply Chain Analysis Agent.\n"
+            f"Task: {task}\n"
+            f"Current supply chain model has {len(self.graph_manager.get_nodes())} nodes and "
+            f"{len(self.graph_manager.get_edges())} relationships.\n"
+            f"Analyze the supply chain and provide optimization recommendations.\n"
+        )
+
+    def _domain_specific_setup(self) -> None:
+        """Set up logistics-specific attributes."""
+        # Logistics-specific setup (e.g., capacity constraints, service levels)
+        self.capacity_constraints: Dict[str, float] = {}
+        self.service_level_targets: Dict[str, float] = {}
+
+    def add_supply_chain_relationship(
+        self,
+        source: str,
+        target: str,
+        lead_time: float = 0.0,
+        capacity: float = 1.0,
+        confidence: float = 1.0
+    ) -> None:
+        """Add a supply chain relationship."""
+        self.graph_manager.add_relationship(
+            source=source,
+            target=target,
+            strength=lead_time,
+            confidence=confidence,
+            capacity=capacity,
+        )
+
+    def predict_delivery_outcomes(
+        self,
+        current_state: Dict[str, float],
+        interventions: Dict[str, float]
+    ) -> Dict[str, float]:
+        """Predict delivery outcomes given current state and interventions."""
+        return self.prediction_framework.predict_outcomes(
+            current_state, interventions
+        )
+
+    def generate_delivery_scenarios(
+        self,
+        current_state: Dict[str, float],
+        target_nodes: List[str],
+        max_scenarios: int = 5
+    ) -> List:
+        """Generate delivery scenarios."""
+        return self.prediction_framework.generate_counterfactual_scenarios(
+            current_state, target_nodes, max_scenarios
+        )
+
+    def run(
+        self,
+        task: Optional[Union[str, Any]] = None,
+        supply_chain_state: Optional[Dict[str, float]] = None,
+        **kwargs,
+    ) -> Dict[str, Any]:
+        """
+        Run logistics analysis.
+        
+        Args:
+            task: Logistics task or question
+            supply_chain_state: Current supply chain state dictionary
+            **kwargs: Additional arguments
+            
+        Returns:
+            Dictionary with logistics analysis results
+        """
+        if task and isinstance(task, str) and supply_chain_state is None:
+            return self.llm_integration.run_llm_domain_analysis(
+                task,
+                build_prompt_fn=self._build_domain_prompt,
+            )
+        
+        # Supply chain state analysis
+        if supply_chain_state:
+            return {
+                "supply_chain_state": supply_chain_state,
+                "predictions": self.prediction_framework.predict_outcomes(supply_chain_state, {}),
+                "scenarios": self.generate_delivery_scenarios(supply_chain_state, list(supply_chain_state.keys())),
+            }
+        
+        return {"error": "Either task or supply_chain_state must be provided"}
+

templates/examples/trading_agent_template.py

@@ -0,0 +1,206 @@
+"""
+Example: Trading Agent Template
+
+This demonstrates how to create a trading/financial agent using the template framework.
+"""
+
+from typing import Dict, Any, List, Tuple, Optional, Union
+from templates.base_specialized_agent import BaseSpecializedAgent
+from templates.graph_management import GraphManager
+from templates.prediction_framework import PredictionFramework
+from templates.statistical_methods import StatisticalMethods
+from templates.llm_integration import LLMIntegration, create_default_schema
+
+
+class TradingAgentTemplate(BaseSpecializedAgent):
+    """
+    Example trading agent using the template framework.
+    
+    This agent can reason about market relationships, predict price movements,
+    and generate trading strategies.
+    """
+
+    def __init__(
+        self,
+        market_variables: Optional[List[str]] = None,
+        market_relationships: Optional[List[Tuple[str, str]]] = None,
+        max_loops: Optional[Union[int, str]] = 3,
+        agent_name: str = "trading-agent",
+        model_name: str = "gpt-4o",
+        **kwargs,
+    ):
+        """
+        Initialize the trading agent.
+        
+        Args:
+            market_variables: List of market variable names (e.g., ['SPY', 'VIX', 'USD'])
+            market_relationships: List of (source, target) relationship tuples
+            max_loops: Maximum reasoning loops
+            agent_name: Agent identifier
+            model_name: LLM model name
+            **kwargs: Additional arguments
+        """
+        super().__init__(
+            max_loops=max_loops,
+            agent_name=agent_name,
+            agent_description="Trading and Financial Analysis Agent",
+            model_name=model_name,
+            **kwargs,
+        )
+
+        # Initialize graph manager for market relationships
+        self.graph_manager = GraphManager(graph_type="market")
+        
+        # Initialize prediction framework
+        self.prediction_framework = PredictionFramework(
+            graph_manager=self.graph_manager,
+            use_nonlinear=True,  # Markets are nonlinear
+        )
+        
+        # Initialize statistical methods
+        self.statistical_methods = StatisticalMethods(
+            graph_manager=self.graph_manager,
+            prediction_framework=self.prediction_framework,
+            standardization_stats=self.prediction_framework.standardization_stats,
+        )
+        
+        # Initialize LLM integration
+        self.llm_integration = LLMIntegration(
+            agent=self,
+            max_loops=self.domain_max_loops if isinstance(self.domain_max_loops, int) else 3,
+        )
+        
+        # Add market variables and relationships
+        if market_variables:
+            self.graph_manager.add_nodes_from(market_variables)
+        
+        if market_relationships:
+            for source, target in market_relationships:
+                self.add_market_relationship(source, target)
+
+    def _get_domain_schema(self) -> Optional[Dict[str, Any]]:
+        """Return the trading analysis schema."""
+        return create_default_schema(
+            function_name="generate_trading_analysis",
+            description="Generates trading analysis and strategy recommendations",
+            properties={
+                "market_analysis": {
+                    "type": "string",
+                    "description": "Analysis of current market conditions and trends"
+                },
+                "risk_assessment": {
+                    "type": "string",
+                    "description": "Assessment of market risks and volatility"
+                },
+                "trading_strategies": {
+                    "type": "array",
+                    "items": {
+                        "type": "object",
+                        "properties": {
+                            "strategy_name": {"type": "string"},
+                            "entry_signals": {"type": "object"},
+                            "exit_signals": {"type": "object"},
+                            "risk_parameters": {"type": "object"},
+                            "expected_returns": {"type": "object"}
+                        }
+                    },
+                    "description": "Recommended trading strategies"
+                },
+                "portfolio_recommendations": {
+                    "type": "string",
+                    "description": "Portfolio allocation recommendations"
+                }
+            },
+            required=[
+                "market_analysis",
+                "risk_assessment",
+                "trading_strategies",
+                "portfolio_recommendations"
+            ]
+        )
+
+    def _build_domain_prompt(self, task: str) -> str:
+        """Build a trading analysis prompt."""
+        return (
+            f"You are a Trading and Financial Analysis Agent.\n"
+            f"Task: {task}\n"
+            f"Current market model has {len(self.graph_manager.get_nodes())} variables and "
+            f"{len(self.graph_manager.get_edges())} relationships.\n"
+            f"Analyze the market conditions and provide trading recommendations.\n"
+        )
+
+    def _domain_specific_setup(self) -> None:
+        """Set up trading-specific attributes."""
+        # Trading-specific setup (e.g., risk limits, position sizing)
+        self.risk_limits: Dict[str, float] = {}
+        self.position_sizing_rules: Dict[str, Any] = {}
+
+    def add_market_relationship(
+        self,
+        source: str,
+        target: str,
+        correlation: float = 0.0,
+        confidence: float = 1.0
+    ) -> None:
+        """Add a market relationship (e.g., correlation, lead-lag)."""
+        self.graph_manager.add_relationship(
+            source=source,
+            target=target,
+            strength=correlation,
+            confidence=confidence,
+        )
+
+    def predict_market_outcomes(
+        self,
+        current_market_state: Dict[str, float],
+        interventions: Dict[str, float]
+    ) -> Dict[str, float]:
+        """Predict market outcomes given current state and interventions."""
+        return self.prediction_framework.predict_outcomes(
+            current_market_state, interventions
+        )
+
+    def generate_trading_scenarios(
+        self,
+        current_state: Dict[str, float],
+        target_assets: List[str],
+        max_scenarios: int = 5
+    ) -> List:
+        """Generate trading scenarios."""
+        return self.prediction_framework.generate_counterfactual_scenarios(
+            current_state, target_assets, max_scenarios
+        )
+
+    def run(
+        self,
+        task: Optional[Union[str, Any]] = None,
+        market_state: Optional[Dict[str, float]] = None,
+        **kwargs,
+    ) -> Dict[str, Any]:
+        """
+        Run trading analysis.
+        
+        Args:
+            task: Trading task or question
+            market_state: Current market state dictionary
+            **kwargs: Additional arguments
+            
+        Returns:
+            Dictionary with trading analysis results
+        """
+        if task and isinstance(task, str) and market_state is None:
+            return self.llm_integration.run_llm_domain_analysis(
+                task,
+                build_prompt_fn=self._build_domain_prompt,
+            )
+        
+        # Market state analysis
+        if market_state:
+            return {
+                "market_state": market_state,
+                "predictions": self.prediction_framework.predict_outcomes(market_state, {}),
+                "scenarios": self.generate_trading_scenarios(market_state, list(market_state.keys())),
+            }
+        
+        return {"error": "Either task or market_state must be provided"}
+