haive.agents.react
==================

.. py:module:: haive.agents.react

.. autoapi-nested-parse::

   ReactAgent Package - Reasoning and Acting AI Agents with Tool Integration.

   This package provides the ReactAgent, an advanced AI agent that implements the ReAct
   (Reasoning and Acting) pattern for tool-based problem solving, complex reasoning,
   and iterative task execution with real-time decision making.

   The ReactAgent extends beyond simple conversation to provide:
   - **Tool Integration**: Seamless integration with external tools and APIs
   - **Reasoning Loops**: Iterative thought-action-observation cycles
   - **Planning Capabilities**: Multi-step reasoning and task decomposition
   - **Error Handling**: Robust error recovery and alternative strategy execution
   - **Structured Output**: Type-safe result generation with validation

   Core Architecture:
       ReactAgent implements the ReAct pattern through several key components:

       **Reasoning Engine**:
           - Iterative thought-action-observation loops for complex problem solving
           - Multi-step reasoning with intermediate result validation
           - Dynamic strategy adaptation based on tool execution results
           - Reflection and self-correction capabilities for improved accuracy

       **Tool Management System**:
           - Dynamic tool registration and execution
           - Tool routing and selection based on task requirements
           - Error handling and fallback strategies for tool failures
           - Tool result parsing and integration into reasoning flow

       **Planning and Coordination**:
           - Task decomposition into manageable sub-tasks
           - Multi-step plan generation and execution monitoring
           - Dynamic plan adaptation based on intermediate results
           - Goal-oriented execution with success criteria validation

       **State Management**:
           - Comprehensive execution state tracking and persistence
           - Conversation history with tool execution context
           - Iterative reasoning state with thought progression
           - Error state management and recovery mechanisms

   Agent Capabilities:
       **Advanced Reasoning**:
           - Multi-step logical reasoning with tool integration
           - Complex problem decomposition and solution synthesis
           - Iterative refinement of solutions based on tool feedback
           - Meta-reasoning about tool selection and execution strategies

       **Tool-Based Problem Solving**:
           - Dynamic tool selection based on problem requirements
           - Parallel and sequential tool execution patterns
           - Tool result integration and synthesis
           - Error handling and alternative tool strategies

       **Research and Analysis**:
           - Multi-source information gathering and synthesis
           - Fact verification and cross-referencing
           - Evidence-based reasoning and conclusion formation
           - Structured report generation with citations

       **Interactive Planning**:
           - Real-time plan generation and adaptation
           - User feedback integration into reasoning loops
           - Progress monitoring and milestone tracking
           - Dynamic goal adjustment based on execution results

   .. rubric:: Examples

   Basic ReactAgent with mathematical tools::

       from haive.agents.react import ReactAgent
       from haive.core.engine.aug_llm import AugLLMConfig
       from langchain_core.tools import tool

       @tool
       def calculator(expression: str) -> str:
           """Calculate mathematical expressions."""
           try:
               result = eval(expression)
               return f"Result: {result}"
           except Exception as e:
               return f"Error: {e}"

       @tool
       def plot_generator(data: str) -> str:
           """Generate statistical plots from data."""
           return f"Generated plot for data: {data}"

       # Create ReactAgent with mathematical capabilities
       math_agent = ReactAgent(
           name="math_assistant",
           engine=AugLLMConfig(
               tools=[calculator, plot_generator],
               temperature=0.3,  # Lower for consistent reasoning
               system_message="You are a mathematical reasoning assistant."
           ),
           max_iterations=5
       )

       # Execute complex mathematical task
       result = await math_agent.arun(
           "Calculate the compound interest on $10,000 at 5% annually for 3 years, "
           "then create a visualization showing the growth"
       )
       # Agent will:
       # 1. Reason about compound interest formula
       # 2. Use calculator tool for computation
       # 3. Generate visualization with plot_generator
       # 4. Provide comprehensive analysis

   Research agent with web search and analysis tools::

       from haive.agents.react import ReactAgent, create_research_agent
       from langchain_core.tools import tool
       import requests

       @tool
       def web_search(query: str) -> str:
           """Search the web for current information."""
           # Implementation would use real search API
           return f"Search results for: {query}"

       @tool
       def fact_checker(claim: str) -> str:
           """Verify facts using reliable sources."""
           # Implementation would check against fact databases
           return f"Fact check result for: {claim}"

       @tool
       def citation_formatter(source: str, format_type: str = "APA") -> str:
           """Format citations in academic style."""
           return f"Formatted citation ({format_type}): {source}"

       # Create research agent using factory function
       researcher = create_research_agent(
           name="academic_researcher",
           tools=[web_search, fact_checker, citation_formatter],
           max_iterations=8,
           enable_reflection=True
       )

       # Execute research task
       result = await researcher.arun(
           "Research the latest developments in quantum computing and provide "
           "a comprehensive analysis with verified facts and proper citations"
       )
       # Agent will:
       # 1. Break down research into subtopics
       # 2. Search for current information on each topic
       # 3. Fact-check important claims
       # 4. Synthesize findings into coherent analysis
       # 5. Add proper academic citations

   ReactAgent with structured output for data analysis::

       from haive.agents.react import ReactAgent
       from haive.core.engine.aug_llm import AugLLMConfig
       from pydantic import BaseModel, Field
       from typing import List, Dict
       from langchain_core.tools import tool

       # Define structured output format
       class DataAnalysisResult(BaseModel):
           summary: str = Field(description="Executive summary of analysis")
           key_findings: List[str] = Field(description="Main insights discovered")
           methodology: str = Field(description="Analysis approach used")
           data_quality: str = Field(description="Assessment of data quality")
           recommendations: List[str] = Field(description="Actionable recommendations")
           visualizations: List[str] = Field(description="Charts and graphs created")
           confidence_score: float = Field(ge=0.0, le=1.0, description="Confidence in analysis")

       @tool
       def data_loader(source: str) -> str:
           """Load data from various sources."""
           return f"Loaded data from {source}"

       @tool
       def statistical_analyzer(data: str, method: str) -> str:
           """Perform statistical analysis on data."""
           return f"Analysis using {method}: {data}"

       @tool
       def visualization_creator(data: str, chart_type: str) -> str:
           """Create data visualizations."""
           return f"Created {chart_type} chart for: {data}"

       # Create data analysis agent with structured output
       analyst = ReactAgent(
           name="data_analyst",
           engine=AugLLMConfig(
               tools=[data_loader, statistical_analyzer, visualization_creator],
               structured_output_model=DataAnalysisResult,
               temperature=0.2,  # Very low for analytical consistency
               system_message="You are an expert data analyst who provides thorough, evidence-based insights."
           ),
           max_iterations=10
       )

       # Execute comprehensive data analysis
       analysis = await analyst.arun({
           "task": "Analyze customer satisfaction survey data",
           "data_source": "customer_survey_2024.csv",
           "requirements": ["identify trends", "segment analysis", "predictive insights"]
       })

       # Access structured results
       print(f"Summary: {analysis.summary}")
       print(f"Key Findings: {analysis.key_findings}")
       print(f"Confidence: {analysis.confidence_score}")

   Multi-agent workflow with ReactAgent coordination::

       from haive.agents.react import ReactAgent
       from haive.agents.simple import SimpleAgent
       from haive.agents.multi import MultiAgent
       from haive.core.engine.aug_llm import AugLLMConfig

       # Create specialized agents for different aspects
       planning_agent = ReactAgent(
           name="planner",
           engine=AugLLMConfig(
               tools=[task_decomposer, resource_planner],
               system_message="You are a strategic planner who breaks down complex projects."
           ),
           max_iterations=6
       )

       execution_agent = ReactAgent(
           name="executor",
           engine=AugLLMConfig(
               tools=[code_generator, tester, deployer],
               system_message="You are a technical executor who implements plans."
           ),
           max_iterations=8
       )

       review_agent = SimpleAgent(
           name="reviewer",
           engine=AugLLMConfig(
               system_message="You are a quality reviewer who ensures excellence."
           )
       )

       # Compose into project workflow
       project_team = MultiAgent(
           name="software_project",
           agents=[planning_agent, execution_agent, review_agent],
           execution_mode="sequential"
       )

       # Execute complex project
       result = await project_team.arun(
           "Build a web application for inventory management with real-time updates"
       )

   ReactAgent as tool for hierarchical reasoning::

       from haive.agents.react import ReactAgent
       from haive.core.engine.aug_llm import AugLLMConfig

       # Create specialized ReactAgents
       math_expert = ReactAgent(
           name="mathematician",
           engine=AugLLMConfig(
               tools=[calculator, equation_solver, graph_plotter],
               system_message="You are a mathematics expert specializing in computational problems."
           )
       )

       research_expert = ReactAgent(
           name="researcher",
           engine=AugLLMConfig(
               tools=[web_search, database_query, citation_tool],
               system_message="You are a research expert who gathers and verifies information."
           )
       )

       # Convert ReactAgents to tools
       math_tool = math_expert.as_tool(
           name="mathematical_reasoning",
           description="Solve complex mathematical problems with step-by-step reasoning"
       )

       research_tool = research_expert.as_tool(
           name="information_research",
           description="Research and verify information using multiple sources"
       )

       # Use in meta-coordinator agent
       coordinator = ReactAgent(
           name="project_coordinator",
           engine=AugLLMConfig(
               tools=[math_tool, research_tool],
               system_message="You coordinate expert agents to solve complex problems."
           ),
           max_iterations=15
       )

       # Coordinator uses other ReactAgents as reasoning tools
       result = await coordinator.arun(
           "Research the mathematical foundations of machine learning and provide "
           "detailed analysis with calculations and verified sources"
       )

   Performance Characteristics:
       **Reasoning Performance**:
           - Simple reasoning tasks: 500ms-2s depending on tool complexity
           - Multi-step reasoning: 2-10s for iterative problems
           - Tool execution overhead: 50-200ms per tool call
           - State management: <20ms per reasoning iteration

       **Scalability Metrics**:
           - Maximum iterations: Configurable up to 50+ steps
           - Concurrent tool execution: 10+ parallel tool calls
           - Memory efficiency: Optimized state serialization
           - Tool management: 100+ tools per agent supported

       **Error Recovery**:
           - Tool failure recovery: Automatic fallback strategies
           - Reasoning loop termination: Intelligent stopping criteria
           - State corruption recovery: Checkpoint and rollback mechanisms
           - Performance degradation handling: Adaptive iteration limits

   Integration Patterns:
       **Standalone Reasoning**:
           - Complex problem-solving applications
           - Research and analysis systems
           - Decision support tools
           - Interactive consultation systems

       **Tool Ecosystem Integration**:
           - API service orchestration
           - External system coordination
           - Data processing pipelines
           - Workflow automation engines

       **Multi-Agent Orchestration**:
           - Specialized expert agent coordination
           - Hierarchical reasoning systems
           - Collaborative problem-solving teams
           - Complex workflow management

   Advanced Features:
       **Reflection and Self-Correction**:
           - Automatic result validation and improvement
           - Meta-reasoning about reasoning quality
           - Alternative strategy generation
           - Learning from execution patterns

       **Dynamic Tool Management**:
           - Runtime tool addition and removal
           - Tool capability discovery and matching
           - Tool performance monitoring and optimization
           - Tool composition and chaining strategies

       **Adaptive Reasoning**:
           - Dynamic iteration limit adjustment
           - Strategy switching based on progress
           - Resource-aware execution planning
           - Performance-based optimization

   Best Practices:
       **Tool Design**:
           - Create focused, single-purpose tools
           - Implement proper error handling in tools
           - Provide clear, descriptive tool documentation
           - Design tools for composability and reuse

       **Reasoning Optimization**:
           - Set appropriate iteration limits for task complexity
           - Use structured output for complex analysis tasks
           - Implement proper stopping criteria
           - Monitor and optimize tool execution performance

       **Agent Configuration**:
           - Tune temperature based on reasoning vs creativity needs
           - Provide clear, specific system messages
           - Configure appropriate tool sets for problem domains
           - Enable reflection for high-stakes reasoning tasks

   Factory Functions:
       **create_react_agent()**:
           - Convenient factory for common ReactAgent configurations
           - Built-in tool integration and validation
           - Performance optimization defaults
           - Enhanced debugging and observability

       **create_research_agent()**:
           - Specialized factory for research-oriented agents
           - Pre-configured for information gathering and analysis
           - Built-in fact-checking and citation capabilities
           - Research workflow optimization

   Version History:
       **v3.0** (Current):
           - Enhanced reasoning loops with reflection capabilities
           - Improved tool management and error handling
           - Structured output integration with validation
           - Performance optimizations and debugging tools

       **v2.0**:
           - Multi-step reasoning improvements
           - Enhanced tool integration patterns
           - State management and persistence enhancements

       **v1.0**:
           - Initial ReAct pattern implementation
           - Basic tool integration and reasoning loops
           - Foundation reasoning agent patterns

   .. seealso::

      :mod:`haive.agents.react.agent`: Core ReactAgent implementation
      :mod:`haive.agents.simple`: SimpleAgent for basic conversation
      :mod:`haive.agents.multi`: MultiAgent for coordination patterns
      :mod:`haive.core.engine.aug_llm`: Engine configuration and tool management



Submodules
----------

.. toctree::
   :maxdepth: 1

   /autoapi/haive/agents/react/agent/index
   /autoapi/haive/agents/react/state/index