crca 1.4.0__py3-none-any.whl → 1.5.0__py3-none-any.whl

examples/general_agent_example.py

@@ -0,0 +1,277 @@
+"""
+Example usage of GeneralAgent.
+
+Demonstrates:
+- Basic conversation
+- Tool usage
+- Agent routing (auto-discovered)
+- Code execution
+- Multimodal inputs
+- Async operations
+- Batch processing
+- Custom personality configuration
+"""
+
+import asyncio
+from loguru import logger
+
+try:
+    from branches.general_agent import GeneralAgent, get_personality, create_custom_personality
+    GENERAL_AGENT_AVAILABLE = True
+except ImportError:
+    logger.error("GeneralAgent not available. Please ensure all dependencies are installed.")
+    GENERAL_AGENT_AVAILABLE = False
+
+
+def example_basic_conversation():
+    """Example: Basic conversation with GeneralAgent."""
+    print("\n=== Example 1: Basic Conversation ===\n")
+    
+    if not GENERAL_AGENT_AVAILABLE:
+        print("GeneralAgent not available")
+        return
+    
+    # Create agent with default settings
+    agent = GeneralAgent(
+        agent_name="example-agent",
+        model_name="gpt-4o-mini",
+        personality="neutral",
+    )
+    
+    # Simple conversation
+    response = agent.run("Hello! Can you explain what you can do?")
+    print(f"Agent: {response}\n")
+    
+    # Continue conversation
+    response = agent.run("What's the weather like?")
+    print(f"Agent: {response}\n")
+
+
+def example_custom_personality():
+    """Example: Using custom personality."""
+    print("\n=== Example 2: Custom Personality ===\n")
+    
+    if not GENERAL_AGENT_AVAILABLE:
+        print("GeneralAgent not available")
+        return
+    
+    # Create agent with friendly personality
+    agent = GeneralAgent(
+        agent_name="friendly-agent",
+        personality="friendly",
+    )
+    
+    response = agent.run("Tell me a joke!")
+    print(f"Friendly Agent: {response}\n")
+    
+    # Create agent with technical personality
+    agent = GeneralAgent(
+        agent_name="technical-agent",
+        personality="technical",
+    )
+    
+    response = agent.run("Explain how neural networks work")
+    print(f"Technical Agent: {response}\n")
+
+
+def example_async_operations():
+    """Example: Async operations."""
+    print("\n=== Example 3: Async Operations ===\n")
+    
+    if not GENERAL_AGENT_AVAILABLE:
+        print("GeneralAgent not available")
+        return
+    
+    async def run_async_example():
+        agent = GeneralAgent(
+            agent_name="async-agent",
+        )
+        
+        # Run async
+        response = await agent.run_async("What is 2+2?")
+        print(f"Async Response: {response}\n")
+        
+        # Run multiple async tasks
+        tasks = [
+            "What is Python?",
+            "What is machine learning?",
+            "What is AI?",
+        ]
+        
+        responses = await asyncio.gather(*[agent.run_async(task) for task in tasks])
+        for task, response in zip(tasks, responses):
+            print(f"Task: {task}")
+            print(f"Response: {response}\n")
+    
+    asyncio.run(run_async_example())
+
+
+def example_batch_processing():
+    """Example: Batch processing."""
+    print("\n=== Example 4: Batch Processing ===\n")
+    
+    if not GENERAL_AGENT_AVAILABLE:
+        print("GeneralAgent not available")
+        return
+    
+    agent = GeneralAgent(
+        agent_name="batch-agent",
+    )
+    
+    # Process batch of tasks
+    tasks = [
+        "Explain quantum computing",
+        "What is blockchain?",
+        "Describe machine learning",
+    ]
+    
+    results, stats = agent.run_batch(tasks)
+    
+    print(f"Processed {len(results)} tasks")
+    if stats:
+        print(f"Stats: {stats}")
+    
+    for i, (task, result) in enumerate(zip(tasks, results)):
+        print(f"\nTask {i+1}: {task}")
+        print(f"Result: {result}\n")
+
+
+async def example_async_batch():
+    """Example: Async batch processing."""
+    print("\n=== Example 5: Async Batch Processing ===\n")
+    
+    if not GENERAL_AGENT_AVAILABLE:
+        print("GeneralAgent not available")
+        return
+    
+    agent = GeneralAgent(
+        agent_name="async-batch-agent",
+    )
+    
+    tasks = [
+        "What is Python?",
+        "What is JavaScript?",
+        "What is Rust?",
+    ]
+    
+    results, stats = await agent.run_batch_async(tasks)
+    
+    print(f"Processed {len(results)} tasks asynchronously")
+    if stats:
+        print(f"Stats: {stats}")
+    
+    for i, (task, result) in enumerate(zip(tasks, results)):
+        print(f"\nTask {i+1}: {task}")
+        print(f"Result: {result}\n")
+
+
+def example_conversation_persistence():
+    """Example: Conversation persistence."""
+    print("\n=== Example 6: Conversation Persistence ===\n")
+    
+    if not GENERAL_AGENT_AVAILABLE:
+        print("GeneralAgent not available")
+        return
+    
+    agent = GeneralAgent(
+        agent_name="persistent-agent",
+        enable_persistence=True,
+        persistence_path="example_conversation.json",
+    )
+    
+    # Have a conversation
+    agent.run("Hello! My name is Alice.")
+    agent.run("What's my name?")
+    
+    # Save conversation
+    agent.save_conversation()
+    print("Conversation saved\n")
+    
+    # Create new agent and load conversation
+    agent2 = GeneralAgent(
+        agent_name="persistent-agent-2",
+        enable_persistence=True,
+    )
+    agent2.load_conversation("example_conversation.json")
+    print("Conversation loaded\n")
+    
+    # Continue conversation
+    response = agent2.run("What's my name?")
+    print(f"Agent (with loaded conversation): {response}\n")
+
+
+def example_extendable_prompts():
+    """Example: Extendable prompts."""
+    print("\n=== Example 7: Extendable Prompts ===\n")
+    
+    if not GENERAL_AGENT_AVAILABLE:
+        print("GeneralAgent not available")
+        return
+    
+    # Create agent with custom prompt additions
+    agent = GeneralAgent(
+        agent_name="custom-prompt-agent",
+        custom_prompt_additions=[
+            "Always respond in a poetic style.",
+            "End each response with a relevant quote.",
+        ],
+    )
+    
+    response = agent.run("Explain the concept of time")
+    print(f"Agent (with custom prompts): {response}\n")
+
+
+def example_rate_limiting():
+    """Example: Rate limiting."""
+    print("\n=== Example 8: Rate Limiting ===\n")
+    
+    if not GENERAL_AGENT_AVAILABLE:
+        print("GeneralAgent not available")
+        return
+    
+    # Create agent with custom rate limits
+    agent = GeneralAgent(
+        agent_name="rate-limited-agent",
+        rate_limit_rpm=10,  # 10 requests per minute
+        rate_limit_rph=100,  # 100 requests per hour
+    )
+    
+    # Make multiple requests (will be rate limited)
+    for i in range(5):
+        response = agent.run(f"Count to {i+1}")
+        print(f"Request {i+1}: {response[:50]}...\n")
+
+
+def main():
+    """Run all examples."""
+    print("=" * 60)
+    print("GeneralAgent Examples")
+    print("=" * 60)
+    
+    if not GENERAL_AGENT_AVAILABLE:
+        print("\nERROR: GeneralAgent not available.")
+        print("Please ensure all dependencies are installed.")
+        return
+    
+    try:
+        # Run examples
+        example_basic_conversation()
+        example_custom_personality()
+        example_async_operations()
+        example_batch_processing()
+        asyncio.run(example_async_batch())
+        example_conversation_persistence()
+        example_extendable_prompts()
+        example_rate_limiting()
+        
+        print("\n" + "=" * 60)
+        print("All examples completed!")
+        print("=" * 60)
+    except Exception as e:
+        logger.error(f"Error running examples: {e}")
+        import traceback
+        traceback.print_exc()
+
+
+if __name__ == "__main__":
+    main()

examples/general_agent_quickstart.py

@@ -0,0 +1,202 @@
+"""
+Quick Start Guide: Spawning GeneralAgent for Immediate Use
+
+This file demonstrates the simplest ways to create and use the GeneralAgent.
+"""
+
+from branches.general_agent import GeneralAgent
+
+# ============================================================================
+# METHOD 1: Simplest - Default Settings
+# ============================================================================
+
+def quick_start_minimal():
+    """Minimal setup - just create and use."""
+    agent = GeneralAgent()
+    response = agent.run("Hello! What can you do?")
+    print(response)
+    return agent
+
+
+# ============================================================================
+# METHOD 2: With Custom Model
+# ============================================================================
+
+def quick_start_custom_model():
+    """Create with custom model."""
+    agent = GeneralAgent(
+        model_name="gpt-4o",  # or "gpt-4o-mini", "claude-3-5-sonnet", etc.
+    )
+    response = agent.run("Analyze the causal factors affecting product pricing.")
+    print(response)
+    return agent
+
+
+# ============================================================================
+# METHOD 3: With Personality
+# ============================================================================
+
+def quick_start_with_personality():
+    """Create with personality."""
+    agent = GeneralAgent(
+        personality="friendly",  # or "neutral", "technical"
+    )
+    response = agent.run("Explain quantum computing in simple terms.")
+    print(response)
+    return agent
+
+
+# ============================================================================
+# METHOD 4: Production-Ready Setup
+# ============================================================================
+
+def quick_start_production():
+    """Production-ready setup with all features enabled."""
+    agent = GeneralAgent(
+        agent_name="production-agent",
+        model_name="gpt-4o-mini",
+        temperature=0.4,
+        personality="neutral",
+        enable_agent_routing="auto",
+        enable_code_execution=True,
+        enable_multimodal=True,
+        enable_streaming=True,
+        enable_persistence=True,
+        enable_causal_reasoning=True,
+        enable_file_operations=True,
+        persistence_path="./conversations/",
+        rate_limit_rpm=60,
+        rate_limit_rph=1000,
+    )
+    response = agent.run("Help me understand the causal relationships in my business model.")
+    print(response)
+    return agent
+
+
+# ============================================================================
+# METHOD 5: Using Helper Function
+# ============================================================================
+
+def quick_start_helper():
+    """Using the get_general_agent helper function."""
+    from branches.general_agent import get_general_agent
+    
+    agent = get_general_agent(
+        model_name="gpt-4o-mini",
+        personality="neutral",
+    )
+    
+    if agent:
+        response = agent.run("What is causal reasoning?")
+        print(response)
+        return agent
+    else:
+        print("Failed to create agent")
+
+
+# ============================================================================
+# METHOD 6: Async Usage
+# ============================================================================
+
+async def quick_start_async():
+    """Async usage for concurrent operations."""
+    agent = GeneralAgent()
+    
+    # Run async
+    response = await agent.run_async("Analyze this task using causal reasoning.")
+    print(response)
+    
+    # Batch processing
+    tasks = [
+        "What factors affect sales?",
+        "Explain supply and demand relationships.",
+        "How does marketing impact revenue?",
+    ]
+    results = await agent.run_batch_async(tasks)
+    for task, result in zip(tasks, results):
+        print(f"\nTask: {task}\nResult: {result}\n")
+    
+    return agent
+
+
+# ============================================================================
+# METHOD 7: With Causal Reasoning Focus
+# ============================================================================
+
+def quick_start_causal_focus():
+    """Create agent focused on causal reasoning tasks."""
+    agent = GeneralAgent(
+        model_name="gpt-4o",
+        personality="technical",
+        enable_causal_reasoning=True,
+        enable_agent_routing="auto",  # Will route to CRCAAgent if needed
+    )
+    
+    # The agent will automatically use causal reasoning tools
+    response = agent.run(
+        "I want to understand what factors influence customer satisfaction. "
+        "Extract the causal variables and relationships."
+    )
+    print(response)
+    return agent
+
+
+# ============================================================================
+# METHOD 8: Minimal with Environment Variables
+# ============================================================================
+
+def quick_start_env_vars():
+    """Create agent using environment variables for API keys."""
+    import os
+    
+    # Set your API keys in environment (or use .env file)
+    # os.environ["OPENAI_API_KEY"] = "your-key-here"
+    # os.environ["ANTHROPIC_API_KEY"] = "your-key-here"
+    
+    agent = GeneralAgent(
+        model_name="gpt-4o-mini",
+    )
+    response = agent.run("Hello!")
+    print(response)
+    return agent
+
+
+# ============================================================================
+# MAIN: Run Examples
+# ============================================================================
+
+if __name__ == "__main__":
+    print("=" * 70)
+    print("GeneralAgent Quick Start Examples")
+    print("=" * 70)
+    
+    # Uncomment the example you want to run:
+    
+    # Example 1: Minimal
+    # quick_start_minimal()
+    
+    # Example 2: Custom Model
+    # quick_start_custom_model()
+    
+    # Example 3: With Personality
+    # quick_start_with_personality()
+    
+    # Example 4: Production Setup
+    # quick_start_production()
+    
+    # Example 5: Helper Function
+    # quick_start_helper()
+    
+    # Example 6: Async (requires asyncio.run())
+    # import asyncio
+    # asyncio.run(quick_start_async())
+    
+    # Example 7: Causal Reasoning Focus
+    # quick_start_causal_focus()
+    
+    # Example 8: Environment Variables
+    # quick_start_env_vars()
+    
+    print("\n" + "=" * 70)
+    print("Choose an example and uncomment it to run!")
+    print("=" * 70)

examples/general_agent_simple.py

@@ -0,0 +1,92 @@
+"""
+Ultra-Simple GeneralAgent Usage Examples
+
+All examples are under 10 lines of code (LOC).
+"""
+
+# ============================================================================
+# EXAMPLE 1: Simplest Possible (1 LOC)
+# ============================================================================
+
+from branches.general_agent import GeneralAgent
+agent = GeneralAgent()
+response = agent.run("Hello!")
+print(response)
+
+# ============================================================================
+# EXAMPLE 2: With Model (2 LOC)
+# ============================================================================
+
+agent = GeneralAgent(model_name="gpt-4o")
+response = agent.run("Explain causal reasoning.")
+print(response)
+
+# ============================================================================
+# EXAMPLE 3: With Personality (2 LOC)
+# ============================================================================
+
+agent = GeneralAgent(personality="friendly")
+response = agent.run("Tell me a joke.")
+print(response)
+
+# ============================================================================
+# EXAMPLE 4: Using Factory Function (2 LOC)
+# ============================================================================
+
+from branches.general_agent import create_agent
+agent = create_agent()
+response = agent.run("What can you do?")
+print(response)
+
+# ============================================================================
+# EXAMPLE 5: Using Class Method (2 LOC)
+# ============================================================================
+
+agent = GeneralAgent.create(model_name="gpt-4o", personality="technical")
+response = agent.run("Analyze this business problem.")
+print(response)
+
+# ============================================================================
+# EXAMPLE 6: Full Conversation (5 LOC)
+# ============================================================================
+
+agent = GeneralAgent()
+agent.run("My name is Alice.")
+response = agent.run("What's my name?")
+print(response)
+
+# ============================================================================
+# EXAMPLE 7: Causal Reasoning Task (3 LOC)
+# ============================================================================
+
+agent = GeneralAgent()
+response = agent.run("Extract causal variables for: product price depends on demand and supply")
+print(response)
+
+# ============================================================================
+# EXAMPLE 8: Async Usage (4 LOC)
+# ============================================================================
+
+import asyncio
+agent = GeneralAgent()
+response = asyncio.run(agent.run_async("Hello!"))
+print(response)
+
+# ============================================================================
+# EXAMPLE 9: Batch Processing (4 LOC)
+# ============================================================================
+
+agent = GeneralAgent()
+tasks = ["What is AI?", "What is ML?", "What is causal reasoning?"]
+results = agent.run_batch(tasks)
+for r in results:
+    print(r)
+
+# ============================================================================
+# EXAMPLE 10: Complete Workflow (8 LOC)
+# ============================================================================
+
+agent = GeneralAgent(model_name="gpt-4o-mini", personality="neutral")
+task = "Help me understand what factors influence customer satisfaction"
+response = agent.run(task)
+print(f"Task: {task}\nResponse: {response}")

examples/hybrid_agent_auto_extraction.py

@@ -0,0 +1,84 @@
+"""
+Example demonstrating automatic variable and edge extraction from natural language.
+
+The HybridAgent can automatically extract causal variables and relationships
+from natural language text without any LLM dependency.
+"""
+
+import sys
+import os
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from architecture.hybrid.hybrid_agent import HybridAgent
+
+
+def main():
+    """Demonstrate auto-extraction capabilities."""
+    
+    # Create agent
+    agent = HybridAgent()
+    
+    print("=" * 70)
+    print("Hybrid Agent - Automatic Variable and Edge Extraction")
+    print("=" * 70)
+    print()
+    
+    # Example 1: Simple causal relationship
+    print("Example 1: Simple causal relationship")
+    print("-" * 70)
+    task1 = "product price depends on demand and supply"
+    result1 = agent.extract_causal_variables(task1)
+    print(f"Input: {task1}")
+    print(f"Variables extracted: {result1['variables']}")
+    print(f"Edges extracted: {result1['edges']}")
+    print(f"Relationships found: {result1['metadata']['total_relationships']}")
+    print()
+    
+    # Example 2: Multiple relationships
+    print("Example 2: Multiple causal relationships")
+    print("-" * 70)
+    task2 = "customer satisfaction is influenced by product quality, and product quality depends on manufacturing process"
+    result2 = agent.extract_causal_variables(task2)
+    print(f"Input: {task2}")
+    print(f"Variables extracted: {result2['variables']}")
+    print(f"Edges extracted: {result2['edges']}")
+    print(f"Relationships found: {result2['metadata']['total_relationships']}")
+    print()
+    
+    # Example 3: Complex sentence
+    print("Example 3: Complex sentence with multiple relationships")
+    print("-" * 70)
+    task3 = "sales revenue increases when marketing spend rises, and marketing spend is controlled by budget allocation"
+    result3 = agent.extract_causal_variables(task3)
+    print(f"Input: {task3}")
+    print(f"Variables extracted: {result3['variables']}")
+    print(f"Edges extracted: {result3['edges']}")
+    print(f"Relationships found: {result3['metadata']['total_relationships']}")
+    print()
+    
+    # Example 4: Full analysis
+    print("Example 4: Full causal analysis")
+    print("-" * 70)
+    task4 = "employee productivity affects company revenue, and employee productivity is determined by training quality and work environment"
+    result4 = agent.run(task4)
+    print(f"Input: {task4}")
+    print(f"\nAnalysis Result:\n{result4}")
+    print()
+    
+    # Example 5: Arrow notation
+    print("Example 5: Arrow notation")
+    print("-" * 70)
+    task5 = "temperature -> pressure -> volume"
+    result5 = agent.extract_causal_variables(task5)
+    print(f"Input: {task5}")
+    print(f"Variables extracted: {result5['variables']}")
+    print(f"Edges extracted: {result5['edges']}")
+    print()
+    
+    print("=" * 70)
+    print("Auto-extraction complete!")
+    print("=" * 70)
+
+
+if __name__ == "__main__":
+    main()