Merge pull request #745 from MervinPraison/claude/issue-744-20250707_174818

feat: Add examples for documented features

Author: MervinPraison

examples/python/agents/code-agent.py

@@ -0,0 +1,133 @@
+"""
+Code Agent Example
+
+This example demonstrates a comprehensive code agent that can write, analyze, debug, and execute code.
+It includes self-reflection for improving code quality and multiple specialized tools.
+"""
+
+from praisonaiagents import Agent, Task, PraisonAIAgents
+from praisonaiagents.tools import CodeInterpreter
+
+# Initialize code execution tool
+code_interpreter = CodeInterpreter()
+
+# Custom code analysis tool
+def analyze_code_complexity(code: str) -> str:
+    """Analyze code complexity and provide feedback."""
+    lines = code.strip().split('\n')
+    num_lines = len(lines)
+    num_functions = sum(1 for line in lines if line.strip().startswith('def '))
+    num_classes = sum(1 for line in lines if line.strip().startswith('class '))
+    
+    return f"""Code Analysis:
+- Lines of code: {num_lines}
+- Functions: {num_functions}
+- Classes: {num_classes}
+- Complexity: {'Simple' if num_lines < 50 else 'Moderate' if num_lines < 200 else 'Complex'}"""
+
+# Create specialized code agents
+code_writer = Agent(
+    name="CodeWriter",
+    role="Expert Python developer",
+    goal="Write clean, efficient, and well-documented Python code",
+    backstory="You are a senior Python developer with 10+ years of experience in writing production-quality code.",
+    instructions="Write Python code that follows PEP 8 standards, includes proper error handling, and has clear documentation.",
+    self_reflect=True,
+    min_reflect=2,
+    max_reflect=5
+)
+
+code_reviewer = Agent(
+    name="CodeReviewer",
+    role="Code quality expert",
+    goal="Review code for bugs, security issues, and best practices",
+    backstory="You are a code review specialist who ensures code quality and maintainability.",
+    instructions="Review the provided code for potential issues, suggest improvements, and ensure it follows best practices.",
+    tools=[analyze_code_complexity]
+)
+
+code_executor = Agent(
+    name="CodeExecutor",
+    role="Code execution specialist",
+    goal="Safely execute and test Python code",
+    backstory="You are responsible for running code and reporting results or errors.",
+    instructions="Execute the provided code safely and report the output or any errors encountered.",
+    tools=[code_interpreter]
+)
+
+# Example tasks
+def demonstrate_code_agent():
+    # Task 1: Write a function
+    write_task = Task(
+        name="write_function",
+        description="Write a Python function that calculates the Fibonacci sequence up to n terms",
+        expected_output="A well-documented Python function with error handling",
+        agent=code_writer
+    )
+    
+    # Task 2: Review the code
+    review_task = Task(
+        name="review_code",
+        description="Review the Fibonacci function for quality and suggest improvements",
+        expected_output="Detailed code review with suggestions",
+        agent=code_reviewer,
+        context=[write_task]
+    )
+    
+    # Task 3: Execute and test
+    execute_task = Task(
+        name="execute_code",
+        description="Execute the Fibonacci function with n=10 and verify it works correctly",
+        expected_output="Execution results showing the first 10 Fibonacci numbers",
+        agent=code_executor,
+        context=[write_task]
+    )
+    
+    # Create workflow
+    workflow = PraisonAIAgents(
+        agents=[code_writer, code_reviewer, code_executor],
+        tasks=[write_task, review_task, execute_task],
+        process="sequential",
+        verbose=True
+    )
+    
+    # Run the workflow
+    result = workflow.start()
+    return result
+
+# Standalone code agent for general programming tasks
+general_code_agent = Agent(
+    name="GeneralCodeAgent",
+    role="Full-stack programming assistant",
+    goal="Help with any programming task including writing, debugging, and explaining code",
+    backstory="You are an AI programming assistant with expertise in multiple languages and frameworks.",
+    instructions="""You can:
+1. Write code in any programming language
+2. Debug and fix code issues
+3. Explain code concepts
+4. Refactor code for better performance
+5. Add tests and documentation""",
+    tools=[code_interpreter, analyze_code_complexity],
+    self_reflect=True,
+    min_reflect=1,
+    max_reflect=3
+)
+
+if __name__ == "__main__":
+    # Example 1: Run the multi-agent workflow
+    print("=== Multi-Agent Code Workflow ===")
+    result = demonstrate_code_agent()
+    print(f"Workflow Result: {result}")
+    
+    # Example 2: Use the general code agent
+    print("\n=== General Code Agent ===")
+    response = general_code_agent.start("""
+    Write a Python class for a simple Calculator with methods for:
+    - Addition
+    - Subtraction
+    - Multiplication
+    - Division (with error handling for division by zero)
+    
+    Then create a simple test to verify it works.
+    """)
+    print(response)

examples/python/agents/math-agent.py

@@ -0,0 +1,188 @@
+"""
+Math Agent Example
+
+This example demonstrates a mathematical problem-solving agent that can handle various math tasks
+including calculations, equation solving, and step-by-step explanations.
+"""
+
+from praisonaiagents import Agent, Task, PraisonAIAgents
+from typing import Dict, Any
+import math
+import re
+
+# Custom math tools
+def basic_calculator(expression: str) -> str:
+    """Evaluate basic mathematical expressions safely."""
+    try:
+        # Remove any non-mathematical characters for safety
+        safe_expr = re.sub(r'[^0-9+\-*/().,\s]', '', expression)
+        result = eval(safe_expr)
+        return f"Result: {result}"
+    except Exception as e:
+        return f"Error in calculation: {str(e)}"
+
+def solve_quadratic(a: float, b: float, c: float) -> str:
+    """Solve quadratic equation ax² + bx + c = 0."""
+    discriminant = b**2 - 4*a*c
+    
+    if discriminant > 0:
+        x1 = (-b + math.sqrt(discriminant)) / (2*a)
+        x2 = (-b - math.sqrt(discriminant)) / (2*a)
+        return f"Two real solutions: x₁ = {x1:.4f}, x₂ = {x2:.4f}"
+    elif discriminant == 0:
+        x = -b / (2*a)
+        return f"One real solution: x = {x:.4f}"
+    else:
+        real_part = -b / (2*a)
+        imag_part = math.sqrt(-discriminant) / (2*a)
+        return f"Two complex solutions: x₁ = {real_part:.4f} + {imag_part:.4f}i, x₂ = {real_part:.4f} - {imag_part:.4f}i"
+
+def calculate_statistics(numbers: list) -> str:
+    """Calculate basic statistics for a list of numbers."""
+    if not numbers:
+        return "No numbers provided"
+    
+    n = len(numbers)
+    mean = sum(numbers) / n
+    sorted_nums = sorted(numbers)
+    median = sorted_nums[n//2] if n % 2 else (sorted_nums[n//2-1] + sorted_nums[n//2]) / 2
+    variance = sum((x - mean)**2 for x in numbers) / n
+    std_dev = math.sqrt(variance)
+    
+    return f"""Statistics:
+- Count: {n}
+- Mean: {mean:.4f}
+- Median: {median:.4f}
+- Standard Deviation: {std_dev:.4f}
+- Min: {min(numbers)}
+- Max: {max(numbers)}"""
+
+# Create specialized math agents
+calculation_agent = Agent(
+    name="CalculationAgent",
+    role="Mathematical calculation specialist",
+    goal="Perform accurate mathematical calculations and computations",
+    backstory="You are an expert mathematician who can handle complex calculations with precision.",
+    instructions="Perform the requested calculations step by step, showing your work clearly.",
+    tools=[basic_calculator, solve_quadratic, calculate_statistics],
+    self_reflect=True,
+    min_reflect=1,
+    max_reflect=2
+)
+
+problem_solver_agent = Agent(
+    name="ProblemSolver",
+    role="Mathematical problem solver",
+    goal="Solve complex math problems with detailed explanations",
+    backstory="You are a math teacher who excels at breaking down complex problems into understandable steps.",
+    instructions="""When solving math problems:
+1. Identify the type of problem
+2. List the given information
+3. Determine what needs to be found
+4. Show each step of the solution
+5. Verify the answer makes sense""",
+    self_reflect=True,
+    min_reflect=2,
+    max_reflect=4
+)
+
+math_tutor_agent = Agent(
+    name="MathTutor",
+    role="Mathematics tutor and explainer",
+    goal="Explain mathematical concepts clearly and help users understand math",
+    backstory="You are a patient math tutor who can explain concepts at any level from elementary to advanced.",
+    instructions="Explain mathematical concepts using simple language, provide examples, and check for understanding."
+)
+
+# Example workflow for solving complex problems
+def solve_math_problem_workflow():
+    # Task 1: Understand the problem
+    understand_task = Task(
+        name="understand_problem",
+        description="""A farmer has a rectangular field. The length is 3 meters more than twice the width. 
+        If the perimeter is 96 meters, what are the dimensions of the field?""",
+        expected_output="Clear problem statement with identified variables and equations",
+        agent=problem_solver_agent
+    )
+    
+    # Task 2: Solve the problem
+    solve_task = Task(
+        name="solve_problem",
+        description="Solve for the dimensions using the equations identified",
+        expected_output="The width and length of the field with calculations shown",
+        agent=calculation_agent,
+        context=[understand_task]
+    )
+    
+    # Task 3: Verify and explain
+    verify_task = Task(
+        name="verify_solution",
+        description="Verify the solution is correct and explain why it makes sense",
+        expected_output="Verification that the solution satisfies all conditions",
+        agent=math_tutor_agent,
+        context=[solve_task]
+    )
+    
+    workflow = PraisonAIAgents(
+        agents=[problem_solver_agent, calculation_agent, math_tutor_agent],
+        tasks=[understand_task, solve_task, verify_task],
+        process="sequential",
+        verbose=True
+    )
+    
+    return workflow.start()
+
+# General math assistant combining all capabilities
+math_assistant = Agent(
+    name="MathAssistant",
+    role="Comprehensive mathematics assistant",
+    goal="Help with any mathematical task from basic arithmetic to complex problem solving",
+    backstory="You are an AI math assistant with expertise in all areas of mathematics.",
+    instructions="""You can help with:
+1. Basic arithmetic and calculations
+2. Algebra and equation solving
+3. Geometry and trigonometry
+4. Calculus and advanced mathematics
+5. Statistics and probability
+6. Math tutoring and explanations
+
+Always show your work step by step.""",
+    tools=[basic_calculator, solve_quadratic, calculate_statistics],
+    self_reflect=True,
+    min_reflect=1,
+    max_reflect=3
+)
+
+if __name__ == "__main__":
+    # Example 1: Basic calculation
+    print("=== Basic Calculation ===")
+    result = calculation_agent.start("Calculate: (15 + 23) * 4 - 18 / 3")
+    print(result)
+    
+    # Example 2: Quadratic equation
+    print("\n=== Quadratic Equation ===")
+    result = calculation_agent.start("Solve the equation: 2x² - 5x + 3 = 0")
+    print(result)
+    
+    # Example 3: Statistics
+    print("\n=== Statistics ===")
+    result = calculation_agent.start("Calculate statistics for: [12, 15, 18, 20, 22, 25, 28, 30]")
+    print(result)
+    
+    # Example 4: Complex problem workflow
+    print("\n=== Complex Problem Workflow ===")
+    result = solve_math_problem_workflow()
+    print(f"Workflow Result: {result}")
+    
+    # Example 5: General math assistance
+    print("\n=== General Math Assistance ===")
+    result = math_assistant.start("""
+    I need help with this problem:
+    A ball is thrown upward with an initial velocity of 20 m/s. 
+    The height h(t) = 20t - 5t² where t is time in seconds.
+    
+    1. When does the ball reach maximum height?
+    2. What is the maximum height?
+    3. When does the ball hit the ground?
+    """)
+    print(result)

examples/python/concepts/chat-with-pdf.py

@@ -0,0 +1,49 @@
+"""
+Chat with PDF Example
+
+This example demonstrates how to create an agent that can read and answer questions about PDF documents.
+It uses the knowledge parameter to load PDF files and provides interactive Q&A capabilities.
+"""
+
+from praisonaiagents import Agent
+
+# Configure vector store for PDF storage
+config = {
+    "vector_store": {
+        "provider": "chroma",
+        "config": {
+            "collection_name": "pdf_chat",
+            "path": ".praison_pdf_chat",
+        }
+    }
+}
+
+# Create a PDF chat agent
+pdf_agent = Agent(
+    name="PDF Assistant",
+    role="PDF document expert",
+    goal="Help users understand and extract information from PDF documents",
+    backstory="You are an expert at reading, analyzing, and answering questions about PDF documents. You provide accurate, detailed answers based on the document content.",
+    instructions="Read the provided PDF document and answer questions about its content. Be specific and cite relevant sections when possible.",
+    knowledge=["document.pdf"],  # Replace with your PDF file path
+    knowledge_config=config,
+    self_reflect=True,
+    min_reflect=1,
+    max_reflect=3
+)
+
+# Example usage
+if __name__ == "__main__":
+    # Single question
+    response = pdf_agent.start("What are the main topics covered in this document?")
+    print(response)
+    
+    # Interactive chat
+    print("\nPDF Chat Assistant Ready! Type 'quit' to exit.")
+    while True:
+        question = input("\nYour question: ")
+        if question.lower() == 'quit':
+            break
+        
+        response = pdf_agent.start(question)
+        print(f"\nAnswer: {response}")