# traversaal-ai/agentpro architecture

> Architecture diagram of the GitHub repository traversaal-ai/agentpro, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/traversaal-ai/agentpro
- Repository: https://github.com/traversaal-ai/agentpro

## Overview

##### Project type and purpose
- AgentPro is a Python-based ReAct-style “agentic” framework. It isn’t a web app or microservice but a local library + CLI/Notebook entrypoint that orchestrates reasoning loops (Thought → Action → Observation → …) via an LLM and a pluggable tool set.

##### File structure
- Top level:
- agentpro/ → the core library
– react_agent.py: orchestration of ReAct loop
– agent.py & model.py: data classes and LLM-provider abstraction
– tools/: base_tool.py plus DuckDuckGo, calculator, SlideGen, YFinance, RAG, user-input, Ares API tools
- main.py → CLI entrypoint for interactive sessions
- cookbook/ → examples & demos (Jupyter notebooks / hackathon projects)
- setup.py, pyproject.toml, requirements.txt → packaging & dependencies
- No frontend/backend split – it’s a single Python process calling external APIs (LLM, internet search, financial data, etc.)

##### README insights
- Describes the ReAct pattern, LLM-agnostic model factory (create_model), and modular tool system.
- Usage: user writes `agent = ReactAgent(model, tools)` then `agent.run(query)`.

##### Core components
a. User Interface (main.py / Notebook)
b. ReactAgent Core
c. Model Adapter Layer
d. Tool Plugins
e. External Services & APIs
f. Data Flow / Agent History Store (Thought/Action/Observation)

##### Relationships & interactions
- User → ReactAgent.run(query)
- ReactAgent invokes Model Adapter → HTTP call to LLM provider (OpenAI/Anthropic/HuggingFace)
- Model returns “Thought” → ReactAgent decides on Action
- If Action is “use tool X”, ReactAgent calls Tool plugin → Tool may call external API (e.g., DuckDuckGo search, YFinance, slide-gen service)
- Tool returns Observation → fed back to ReactAgent → new Thought → … → Final Answer returned to User
- All steps appended to an in-memory history log

##### Architectural patterns & principles
- Modular plugin architecture (Tool base class, easy to drop in/out)
- Single orchestrator (ReactAgent) enforcing the ReAct pattern
- Clear separation of concerns: orchestration vs. LLM integration vs. tool logic vs. user I/O
- Dependency Injection: model & tools passed to ReactAgent at instantiation

##### Relevant technologies
- Python 3.8+
- HTTP APIs: OpenAI/Anthropic or any LLM endpoint
- External services: web search (Traversaal Ares), DuckDuckGo, Yahoo Finance, slide generation
- Packaging: setuptools / pyproject.toml
- Demo environment: Jupyter notebooks in cookbook/

- Blue: core library modules (ReactAgent, model.py, agent.py)
- Green: tool plugins (each concrete tool extends base_tool.py)
- Orange: user-facing entrypoints (main.py, quick_start.ipynb)
- Red: external services/APIs
- “query” from User → ReactAgent
- “LLM call” from Model Adapter → LLM API
- “tool invocation” from ReactAgent → Tool → External Service
- “observation” back into ReactAgent loop

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "User Interface"
        UI1["CLI: main.py"]:::entrypoint
        UI2["Notebook: quick_start.ipynb"]:::entrypoint
    end

    subgraph "Core Library"
        RA["ReactAgent\nreact_agent.py"]:::core
        AgentA["Agent Adapter\nagent.py"]:::core
        ModelM["Model Adapter\nmodel.py"]:::core
    end

    subgraph "Tool Plugins\n(agentpro/tools)"
        base["BaseTool\nbase_tool.py"]:::tool
        duck["DuckDuckGo Tool\nduckduckgo_tool.py"]:::tool
        calc["Calculator Tool\ncalculator_tool.py"]:::tool
        slide["SlideGen Tool\nslide_generation_tool.py"]:::tool
        yfin["YFinance Tool\nyfinance_tool.py"]:::tool
        ares["Ares API Tool\nares_tool.py"]:::tool
        rag["RAG Tool\ntraversaalpro_rag_tool.py"]:::tool
        usert["UserInput Tool\nuserinput_tool.py"]:::tool
    end

    subgraph "External Services & APIs"
        LLM["LLM Providers\n(OpenAI/Anthropic/...)\nHTTP"]:::external
        extSearch["Web Search\n(DuckDuckGo API)"]:::external
        extFin["Financial Data\n(Yahoo Finance API)"]:::external
        extSlide["SlideGen Service\n(HTTP)"]:::external
    end

    subgraph "Packaging & Dependencies"
        setup["setup.py"]:::package
        pyproject["pyproject.toml"]:::package
        req["requirements.txt"]:::package
    end

    %% Data Flows
    UI1 -->|"query"| RA
    UI2 -->|"query"| RA
    RA -->|"instantiate"| AgentA
    RA -->|"instantiate"| ModelM
    RA -->|"use model"| ModelM
    ModelM -->|"LLM call"| LLM
    LLM -->|"response Thought"| RA
    RA -->|"tool invocation"| base
    base -->|"extends"| duck
    base -->|"extends"| calc
    base -->|"extends"| slide
    base -->|"extends"| yfin
    base -->|"extends"| ares
    base -->|"extends"| rag
    base -->|"extends"| usert
    duck -->|"calls"| extSearch
    calc -->|"calculates"| RA
    slide -->|"calls"| extSlide
    yfin -->|"calls"| extFin
    ares -->|"calls"| extSearch
    rag -->|"calls"| LLM
    usert -->|"user input"| UI1
    RA -->|"final answer"| UI1
    RA -->|"final answer"| UI2
    RA -.->|"Thought→Action→Observation loop"| RA

    %% Click Events
    click UI1 "https://github.com/traversaal-ai/agentpro/blob/main/main.py"
    click UI2 "https://github.com/traversaal-ai/agentpro/blob/main/cookbook/quick_start.ipynb"
    click RA "https://github.com/traversaal-ai/agentpro/blob/main/agentpro/react_agent.py"
    click AgentA "https://github.com/traversaal-ai/agentpro/blob/main/agentpro/agent.py"
    click ModelM "https://github.com/traversaal-ai/agentpro/blob/main/agentpro/model.py"
    click base "https://github.com/traversaal-ai/agentpro/blob/main/agentpro/tools/base_tool.py"
    click duck "https://github.com/traversaal-ai/agentpro/blob/main/agentpro/tools/duckduckgo_tool.py"
    click calc "https://github.com/traversaal-ai/agentpro/blob/main/agentpro/tools/calculator_tool.py"
    click slide "https://github.com/traversaal-ai/agentpro/blob/main/agentpro/tools/slide_generation_tool.py"
    click yfin "https://github.com/traversaal-ai/agentpro/blob/main/agentpro/tools/yfinance_tool.py"
    click ares "https://github.com/traversaal-ai/agentpro/blob/main/agentpro/tools/ares_tool.py"
    click rag "https://github.com/traversaal-ai/agentpro/blob/main/agentpro/tools/traversaalpro_rag_tool.py"
    click usert "https://github.com/traversaal-ai/agentpro/blob/main/agentpro/tools/userinput_tool.py"
    click setup "https://github.com/traversaal-ai/agentpro/blob/main/setup.py"
    click pyproject "https://github.com/traversaal-ai/agentpro/blob/main/pyproject.toml"
    click req "https://github.com/traversaal-ai/agentpro/blob/main/requirements.txt"

    %% Styles
    classDef core fill:#ADD8E6,stroke:#000,color:#000
    classDef tool fill:#98FB98,stroke:#000,color:#000
    classDef entrypoint fill:#FFA500,stroke:#000,color:#000
    classDef external fill:#FF6347,stroke:#000,color:#000
    classDef package fill:#D3D3D3,stroke:#000,color:#000
```
