mbxai 1.5.0__py3-none-any.whl → 2.0.0__py3-none-any.whl

mbxai/examples/agent_iterations_example.py

@@ -0,0 +1,173 @@
+"""
+Example demonstrating AgentClient max_iterations configuration.
+"""
+
+import os
+from pydantic import BaseModel, Field
+from mbxai import AgentClient, OpenRouterClient
+
+
+class DetailedAnalysis(BaseModel):
+    """A detailed analysis response."""
+    topic: str = Field(description="The topic being analyzed")
+    key_points: list[str] = Field(description="Key points of the analysis")
+    depth_score: int = Field(description="Depth score from 1-10")
+    recommendations: list[str] = Field(description="Recommendations based on analysis")
+    conclusion: str = Field(description="Overall conclusion")
+
+
+def demo_different_iteration_settings():
+    """Demonstrate how max_iterations affects response quality."""
+    
+    print("=== AgentClient max_iterations Configuration Demo ===\n")
+    
+    # Complex prompt that benefits from iteration
+    complex_prompt = """
+    Analyze the impact of artificial intelligence on modern education systems. 
+    Consider both positive and negative aspects, provide specific examples, 
+    and suggest practical implementation strategies for educational institutions.
+    """
+    
+    # Test with different iteration settings
+    iteration_configs = [
+        {"iterations": 0, "description": "No quality iterations (fastest)"},
+        {"iterations": 1, "description": "Single quality check"},
+        {"iterations": 2, "description": "Default - two quality iterations"},
+        {"iterations": 3, "description": "Enhanced quality with three iterations"},
+    ]
+    
+    for config in iteration_configs:
+        print(f"🔄 Testing with {config['iterations']} iterations - {config['description']}")
+        print("-" * 60)
+        
+        try:
+            # Initialize client with specific iteration count
+            openrouter_client = OpenRouterClient(token=os.getenv("OPENROUTER_API_KEY", "test-token"))
+            agent = AgentClient(openrouter_client, max_iterations=config['iterations'])
+            
+            print(f"Agent configured with max_iterations={config['iterations']}")
+            
+            # Mock the response since we can't actually call the API
+            print("📝 Example response would be generated with this configuration:")
+            print(f"   - Quality improvement cycles: {config['iterations']}")
+            print(f"   - Expected processing time: {'Low' if config['iterations'] <= 1 else 'Medium' if config['iterations'] <= 2 else 'High'}")
+            print(f"   - Expected response quality: {'Basic' if config['iterations'] == 0 else 'Good' if config['iterations'] <= 2 else 'Excellent'}")
+            
+            # In real usage, you would call:
+            # response = agent.agent(complex_prompt, DetailedAnalysis, ask_questions=False)
+            
+        except Exception as e:
+            print(f"❌ Error with {config['iterations']} iterations: {e}")
+        
+        print()
+
+
+def demo_iteration_validation():
+    """Demonstrate validation of max_iterations parameter."""
+    
+    print("=== max_iterations Validation ===\n")
+    
+    test_cases = [
+        {"value": -1, "should_pass": False, "description": "Negative value"},
+        {"value": 0, "should_pass": True, "description": "Zero (no iterations)"},
+        {"value": 1, "should_pass": True, "description": "Single iteration"},
+        {"value": 5, "should_pass": True, "description": "High iteration count"},
+    ]
+    
+    openrouter_client = OpenRouterClient(token="test-token")
+    
+    for test in test_cases:
+        try:
+            agent = AgentClient(openrouter_client, max_iterations=test["value"])
+            if test["should_pass"]:
+                print(f"✅ {test['description']}: max_iterations={test['value']} accepted")
+            else:
+                print(f"❌ {test['description']}: Should have failed but didn't")
+        except ValueError as e:
+            if not test["should_pass"]:
+                print(f"✅ {test['description']}: Correctly rejected - {e}")
+            else:
+                print(f"❌ {test['description']}: Unexpectedly rejected - {e}")
+        except Exception as e:
+            print(f"❌ {test['description']}: Unexpected error - {e}")
+
+
+def demo_performance_considerations():
+    """Show performance implications of different iteration settings."""
+    
+    print("\n=== Performance Considerations ===\n")
+    
+    print("max_iterations Impact Analysis:")
+    print("┌─────────────┬─────────────────┬─────────────────┬─────────────────┐")
+    print("│ Iterations  │ API Calls       │ Processing Time │ Quality Level   │")
+    print("├─────────────┼─────────────────┼─────────────────┼─────────────────┤")
+    print("│ 0           │ 2 calls         │ Fastest         │ Basic           │")
+    print("│ 1           │ 4 calls         │ Fast            │ Good            │")
+    print("│ 2 (default) │ 6 calls         │ Moderate        │ Very Good       │")
+    print("│ 3           │ 8 calls         │ Slower          │ Excellent       │")
+    print("│ 4+          │ 10+ calls       │ Slowest         │ Diminishing     │")
+    print("└─────────────┴─────────────────┴─────────────────┴─────────────────┘")
+    
+    print("\nRecommendations:")
+    print("• Use max_iterations=0 for: Quick responses, simple queries, real-time applications")
+    print("• Use max_iterations=1 for: Balanced performance and quality")
+    print("• Use max_iterations=2 for: Default - good balance (recommended)")
+    print("• Use max_iterations=3+ for: Complex analysis, critical applications, maximum quality")
+    
+    print("\nAPI Call Breakdown per agent() call:")
+    print("• Question generation: 1 call")
+    print("• Initial processing: 1 call")  
+    print("• Quality check + improvement: 2 calls per iteration")
+    print("• Final formatting: 1 call")
+    print("• Total = 3 + (2 × max_iterations) calls")
+
+
+def demo_use_cases():
+    """Show appropriate use cases for different iteration settings."""
+    
+    print("\n=== Use Case Examples ===\n")
+    
+    use_cases = [
+        {
+            "scenario": "Chatbot Quick Responses",
+            "iterations": 0,
+            "reasoning": "Speed is critical, basic quality acceptable"
+        },
+        {
+            "scenario": "Content Summarization",
+            "iterations": 1,
+            "reasoning": "Some quality improvement needed, moderate speed"
+        },
+        {
+            "scenario": "Business Report Generation",
+            "iterations": 2,
+            "reasoning": "Default balanced approach for professional content"
+        },
+        {
+            "scenario": "Academic Research Analysis",
+            "iterations": 3,
+            "reasoning": "High quality required, processing time less critical"
+        },
+        {
+            "scenario": "Legal Document Review",
+            "iterations": 4,
+            "reasoning": "Maximum accuracy needed, time not a constraint"
+        }
+    ]
+    
+    for case in use_cases:
+        print(f"📋 {case['scenario']}")
+        print(f"   Recommended max_iterations: {case['iterations']}")
+        print(f"   Reasoning: {case['reasoning']}")
+        print(f"   Example: agent = AgentClient(client, max_iterations={case['iterations']})")
+        print()
+
+
+if __name__ == "__main__":
+    demo_different_iteration_settings()
+    demo_iteration_validation()
+    demo_performance_considerations()
+    demo_use_cases()
+    
+    print("=" * 60)
+    print("max_iterations configuration demo completed! 🎉")

mbxai/examples/agent_tool_registration_example.py

@@ -0,0 +1,247 @@
+"""
+Example demonstrating AgentClient tool registration proxy methods.
+"""
+
+import os
+from pydantic import BaseModel, Field
+from mbxai import AgentClient, OpenRouterClient, ToolClient
+from mbxai.mcp import MCPClient
+
+
+class WeatherResponse(BaseModel):
+    """Response for weather queries."""
+    location: str = Field(description="The location")
+    temperature: str = Field(description="Current temperature")
+    conditions: str = Field(description="Weather conditions")
+    recommendations: list[str] = Field(description="Recommendations based on weather")
+
+
+class CalculationResponse(BaseModel):
+    """Response for calculations."""
+    operation: str = Field(description="The operation performed")
+    result: float = Field(description="The calculation result")
+    explanation: str = Field(description="Step-by-step explanation")
+
+
+def get_weather(location: str) -> dict:
+    """Get weather information for a location."""
+    # Mock weather service
+    weather_data = {
+        "New York": {"temp": "72°F", "conditions": "Sunny"},
+        "London": {"temp": "15°C", "conditions": "Cloudy"},
+        "Tokyo": {"temp": "25°C", "conditions": "Rainy"},
+    }
+    
+    data = weather_data.get(location, {"temp": "20°C", "conditions": "Unknown"})
+    return {
+        "location": location,
+        "temperature": data["temp"],
+        "conditions": data["conditions"]
+    }
+
+
+def calculate(operation: str, a: float, b: float) -> dict:
+    """Perform mathematical calculations."""
+    operations = {
+        "add": a + b,
+        "subtract": a - b,
+        "multiply": a * b,
+        "divide": a / b if b != 0 else None
+    }
+    
+    result = operations.get(operation.lower())
+    if result is None:
+        return {"error": "Invalid operation or division by zero"}
+    
+    return {
+        "operation": f"{a} {operation} {b}",
+        "result": result,
+        "explanation": f"Calculated {a} {operation} {b} = {result}"
+    }
+
+
+def demo_tool_registration_with_tool_client():
+    """Demonstrate tool registration with ToolClient via AgentClient."""
+    print("=== Tool Registration with ToolClient ===")
+    
+    # Initialize clients
+    openrouter_client = OpenRouterClient(token=os.getenv("OPENROUTER_API_KEY", "test-token"))
+    tool_client = ToolClient(openrouter_client)
+    agent = AgentClient(tool_client)
+    
+    # Register tools through the agent proxy
+    try:
+        agent.register_tool(
+            name="get_weather",
+            description="Get current weather for a location",
+            function=get_weather,
+            schema={
+                "type": "object",
+                "properties": {
+                    "location": {
+                        "type": "string",
+                        "description": "The location to get weather for"
+                    }
+                },
+                "required": ["location"]
+            }
+        )
+        print("✅ Successfully registered weather tool via AgentClient")
+        
+        agent.register_tool(
+            name="calculate",
+            description="Perform mathematical calculations",
+            function=calculate,
+            schema={
+                "type": "object",
+                "properties": {
+                    "operation": {
+                        "type": "string",
+                        "enum": ["add", "subtract", "multiply", "divide"],
+                        "description": "The mathematical operation to perform"
+                    },
+                    "a": {
+                        "type": "number",
+                        "description": "First number"
+                    },
+                    "b": {
+                        "type": "number", 
+                        "description": "Second number"
+                    }
+                },
+                "required": ["operation", "a", "b"]
+            }
+        )
+        print("✅ Successfully registered calculator tool via AgentClient")
+        
+    except Exception as e:
+        print(f"❌ Tool registration failed: {e}")
+    
+    # Test agent with tools (mock example)
+    print("\n📝 Example usage:")
+    print('agent.agent("What\'s the weather in New York?", WeatherResponse)')
+    print('agent.agent("Calculate 15 + 25", CalculationResponse)')
+
+
+def demo_tool_registration_with_mcp_client():
+    """Demonstrate tool registration with MCPClient via AgentClient."""
+    print("\n=== Tool Registration with MCPClient ===")
+    
+    # Initialize clients
+    openrouter_client = OpenRouterClient(token=os.getenv("OPENROUTER_API_KEY", "test-token"))
+    mcp_client = MCPClient(openrouter_client)
+    agent = AgentClient(mcp_client)
+    
+    # Register individual tools
+    try:
+        agent.register_tool(
+            name="get_weather",
+            description="Get current weather for a location",
+            function=get_weather,
+            schema={
+                "type": "object",
+                "properties": {
+                    "location": {
+                        "type": "string",
+                        "description": "The location to get weather for"
+                    }
+                },
+                "required": ["location"]
+            }
+        )
+        print("✅ Successfully registered tool with MCPClient via AgentClient")
+        
+    except Exception as e:
+        print(f"❌ Tool registration failed: {e}")
+    
+    # Register MCP server (mock - would normally connect to real server)
+    try:
+        # Note: This would fail in real usage without a running MCP server
+        # agent.register_mcp_server("example_server", "http://localhost:8000")
+        print("📝 MCP server registration available via: agent.register_mcp_server(name, url)")
+        
+    except Exception as e:
+        print(f"⚠️  MCP server registration example: {e}")
+
+
+def demo_tool_registration_errors():
+    """Demonstrate error handling when trying to register tools with unsupported clients."""
+    print("\n=== Error Handling for Unsupported Clients ===")
+    
+    # Try with OpenRouterClient (doesn't support tool registration)
+    try:
+        openrouter_client = OpenRouterClient(token="test-token")
+        agent = AgentClient(openrouter_client)
+        
+        agent.register_tool(
+            name="test_tool",
+            description="A test tool",
+            function=lambda x: x,
+            schema={"type": "object", "properties": {}}
+        )
+        print("❌ This should not be reached - OpenRouterClient doesn't support tools")
+        
+    except AttributeError as e:
+        print(f"✅ Correctly handled unsupported client: {e}")
+    except Exception as e:
+        print(f"❌ Unexpected error: {e}")
+    
+    # Try MCP server registration with non-MCP client
+    try:
+        openrouter_client = OpenRouterClient(token="test-token")
+        tool_client = ToolClient(openrouter_client)
+        agent = AgentClient(tool_client)
+        
+        agent.register_mcp_server("test_server", "http://localhost:8000")
+        print("❌ This should not be reached - ToolClient doesn't support MCP servers")
+        
+    except AttributeError as e:
+        print(f"✅ Correctly handled unsupported MCP registration: {e}")
+    except Exception as e:
+        print(f"❌ Unexpected error: {e}")
+
+
+def demo_client_capabilities():
+    """Show which clients support which registration methods."""
+    print("\n=== Client Capabilities Summary ===")
+    
+    capabilities = {
+        "OpenRouterClient": {
+            "parse": "✅",
+            "register_tool": "❌",
+            "register_mcp_server": "❌"
+        },
+        "ToolClient": {
+            "parse": "✅", 
+            "register_tool": "✅",
+            "register_mcp_server": "❌"
+        },
+        "MCPClient": {
+            "parse": "✅",
+            "register_tool": "✅", 
+            "register_mcp_server": "✅"
+        }
+    }
+    
+    print("Client capabilities for AgentClient:")
+    print("┌─────────────────┬───────┬──────────────┬─────────────────────┐")
+    print("│ Client          │ parse │ register_tool│ register_mcp_server │")
+    print("├─────────────────┼───────┼──────────────┼─────────────────────┤")
+    
+    for client, caps in capabilities.items():
+        print(f"│ {client:<15} │ {caps['parse']:>5} │ {caps['register_tool']:>12} │ {caps['register_mcp_server']:>19} │")
+    
+    print("└─────────────────┴───────┴──────────────┴─────────────────────┘")
+
+
+if __name__ == "__main__":
+    print("AgentClient Tool Registration Examples\n")
+    print("=" * 60)
+    
+    demo_tool_registration_with_tool_client()
+    demo_tool_registration_with_mcp_client()
+    demo_tool_registration_errors()
+    demo_client_capabilities()
+    
+    print("\n" + "=" * 60)
+    print("All examples completed! 🎉")

mbxai/examples/agent_validation_example.py

@@ -0,0 +1,123 @@
+"""
+Example demonstrating AgentClient validation and error handling.
+"""
+
+import os
+from pydantic import BaseModel, Field
+from mbxai import AgentClient, OpenRouterClient, ToolClient
+from mbxai.mcp import MCPClient
+
+
+class SimpleResponse(BaseModel):
+    """A simple response for testing."""
+    message: str = Field(description="The response message")
+
+
+class MockClientWithoutParse:
+    """Mock client that doesn't have a parse method."""
+    def create(self, messages, **kwargs):
+        return "This client doesn't support structured responses"
+
+
+def demo_client_validation():
+    """Demonstrate AgentClient validation of client capabilities."""
+    
+    print("=== AgentClient Validation Examples ===\n")
+    
+    # Example 1: Valid clients
+    print("1. Testing valid clients with parse method:")
+    
+    try:
+        # OpenRouterClient - has parse method
+        openrouter_client = OpenRouterClient(token="test-token")
+        agent1 = AgentClient(openrouter_client)
+        print("✅ OpenRouterClient: Successfully created AgentClient")
+    except Exception as e:
+        print(f"❌ OpenRouterClient: {e}")
+    
+    try:
+        # ToolClient - has parse method (inherits from OpenRouterClient functionality)
+        openrouter_client = OpenRouterClient(token="test-token")
+        tool_client = ToolClient(openrouter_client)
+        agent2 = AgentClient(tool_client)
+        print("✅ ToolClient: Successfully created AgentClient")
+    except Exception as e:
+        print(f"❌ ToolClient: {e}")
+    
+    try:
+        # MCPClient - has parse method (inherits from ToolClient)
+        openrouter_client = OpenRouterClient(token="test-token")
+        mcp_client = MCPClient(openrouter_client)
+        agent3 = AgentClient(mcp_client)
+        print("✅ MCPClient: Successfully created AgentClient")
+    except Exception as e:
+        print(f"❌ MCPClient: {e}")
+    
+    print("\n" + "="*50 + "\n")
+    
+    # Example 2: Invalid client
+    print("2. Testing invalid client without parse method:")
+    
+    try:
+        mock_client = MockClientWithoutParse()
+        agent_invalid = AgentClient(mock_client)
+        print("❌ This should not be reached - validation failed!")
+    except ValueError as e:
+        print(f"✅ Correctly rejected invalid client: {e}")
+    except Exception as e:
+        print(f"❌ Unexpected error: {e}")
+    
+    print("\n" + "="*50 + "\n")
+    
+    # Example 3: Demonstrate why parse method is required
+    print("3. Why structured responses are essential for AgentClient:")
+    print("""
+The AgentClient requires structured responses because it:
+- Generates questions as QuestionList objects
+- Performs quality checks as QualityCheck objects  
+- Processes intermediate results as Result objects
+- Returns final responses as user-defined Pydantic models
+
+Without structured parsing, the agent cannot reliably:
+- Extract questions to ask users
+- Determine if results need improvement
+- Format final responses correctly
+- Handle the multi-step thinking process
+    """)
+
+
+def demo_agent_workflow():
+    """Demonstrate the complete agent workflow."""
+    print("4. Complete AgentClient workflow example:")
+    
+    # Note: This would require a real API token to run
+    api_key = os.getenv("OPENROUTER_API_KEY")
+    if not api_key:
+        print("⚠️  Set OPENROUTER_API_KEY environment variable to run live examples")
+        return
+    
+    try:
+        # Initialize with real client
+        openrouter_client = OpenRouterClient(token=api_key)
+        agent = AgentClient(openrouter_client)
+        
+        # Test without questions
+        response = agent.agent(
+            prompt="Explain the benefits of structured AI responses", 
+            final_response_structure=SimpleResponse,
+            ask_questions=False
+        )
+        
+        if response.is_complete():
+            print(f"✅ Agent response: {response.final_response.message}")
+        else:
+            print("❌ Expected complete response but got questions")
+            
+    except Exception as e:
+        print(f"❌ Agent workflow error: {e}")
+
+
+if __name__ == "__main__":
+    demo_client_validation()
+    print("\n" + "="*70 + "\n")
+    demo_agent_workflow()