# yuzuponikemi/llmpg architecture

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

- Interactive diagram: https://gitdiagram.com/yuzuponikemi/llmpg
- Repository: https://github.com/yuzuponikemi/llmpg

## Overview

##### Project type and purpose
- From the file tree and minimal README, this is a Python-based “Enhanced Research Agent” framework (llmdev) that orchestrates LLM calls, memory management, planning, tool-based actions (e.g., web browsing, code execution, search), and logging.
- It is not a traditional frontend/backend web app, but a modular agent library/CLI tool that integrates with external LLM APIs and persists data locally.

##### File structure
Top-level:
- .env, .gitignore, .vscode – configuration and environment.
- README.md – high-level title.
- requirements.txt – Python dependencies (e.g., openai, requests).
- “enhanced-research-agent/” – the core Python package.
– data/ – persistent storage (long-term memory JSON, sample/verification data).
– examples/ – usage scripts.
– main.py – CLI or entrypoint to kick off the agent.
– requirements.txt – package-specific deps.
– src/ – code organized into three subpackages:
· agent/ – core logic (core.py, planning.py, memory.py, query_evaluator.py, reflection.py, web.py, utils.py).
· tools/ – concrete tool implementations (browse.py, execution.py, search.py).
· logger/ – logging facilities (agent_logger.py, interaction_logger.py).
Others/: Jupyter notebooks and ad-hoc scripts for experimentation.

##### README for additional insights
- The project title “llmdev” implies an LLM-driven development or research workflow.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Entrypoint
    CLI["CLI Entrypoint"]:::cli
    click CLI "https://github.com/yuzuponikemi/llmpg/blob/main/enhanced-research-agent/main.py"

    %% Agent Core
    subgraph "Agent Core"
        Planning["Planning Module"]:::core
        click Planning "https://github.com/yuzuponikemi/llmpg/blob/main/enhanced-research-agent/src/agent/planning.py"
        QueryEval["Query Evaluator"]:::core
        click QueryEval "https://github.com/yuzuponikemi/llmpg/blob/main/enhanced-research-agent/src/agent/query_evaluator.py"
        Reflection["Reflection Module"]:::core
        click Reflection "https://github.com/yuzuponikemi/llmpg/blob/main/enhanced-research-agent/src/agent/reflection.py"
        MemoryMgr["Memory Manager"]:::core
        click MemoryMgr "https://github.com/yuzuponikemi/llmpg/blob/main/enhanced-research-agent/src/agent/memory.py"
        Utils["Utility Functions"]:::core
        click Utils "https://github.com/yuzuponikemi/llmpg/blob/main/enhanced-research-agent/src/agent/utils.py"
        WebHelper["Web/HTTP Helper"]:::core
        click WebHelper "https://github.com/yuzuponikemi/llmpg/blob/main/enhanced-research-agent/src/agent/web.py"
    end

    %% Tools Layer
    subgraph "Tools Layer"
        Browse["Web Browsing Tool"]:::tools
        click Browse "https://github.com/yuzuponikemi/llmpg/blob/main/enhanced-research-agent/src/tools/browse.py"
        Search["Search Tool"]:::tools
        click Search "https://github.com/yuzuponikemi/llmpg/blob/main/enhanced-research-agent/src/tools/search.py"
        ExecTool["Code Execution Tool"]:::tools
        click ExecTool "https://github.com/yuzuponikemi/llmpg/blob/main/enhanced-research-agent/src/tools/execution.py"
    end

    %% Data Store
    subgraph "Data Store"
        LongTerm["Long-Term Memory JSON"]:::persistence
        click LongTerm "https://github.com/yuzuponikemi/llmpg/blob/main/enhanced-research-agent/data/memory/long_term_memory.json"
        SampleData["Sample Data CSV"]:::persistence
        click SampleData "https://github.com/yuzuponikemi/llmpg/blob/main/enhanced-research-agent/data/sample_data.csv"
        VerifData["Verification Data JSON"]:::persistence
        click VerifData "https://github.com/yuzuponikemi/llmpg/blob/main/enhanced-research-agent/data/verification_data.json"
    end

    %% Logging
    subgraph "Logging"
        AgentLog["Agent Logger"]:::logger
        click AgentLog "https://github.com/yuzuponikemi/llmpg/blob/main/enhanced-research-agent/src/logger/agent_logger.py"
        InteractionLog["Interaction Logger"]:::logger
        click InteractionLog "https://github.com/yuzuponikemi/llmpg/blob/main/enhanced-research-agent/src/logger/interaction_logger.py"
    end

    %% External Services
    subgraph "External Services"
        LLM["LLM API"]:::external
        WebAPI["Web Endpoints"]:::external
    end

    %% Flow
    CLI -->|"start session"| Planning
    Planning -->|"plan actions"| QueryEval
    QueryEval -->|"determine tool"| Browse
    QueryEval -->|"determine tool"| Search
    QueryEval -->|"determine tool"| ExecTool
    Browse -->|"browse results"| MemoryMgr
    Search -->|"search results"| MemoryMgr
    ExecTool -->|"execution output"| MemoryMgr
    MemoryMgr -->|"updated memory"| LongTerm
    MemoryMgr --> Reflection
    Reflection -->|"refined plan"| Planning

    %% Tools to external
    Browse -->|"HTTP request"| WebAPI
    Search -->|"API request"| WebAPI
    ExecTool -->|"shell exec"| LLM

    %% Logging hooks
    CLI -->|"log start"| InteractionLog
    Planning -->|"log event"| AgentLog
    QueryEval -->|"log query"| InteractionLog
    Browse -->|"log tool use"| InteractionLog
    MemoryMgr -->|"log memory"| AgentLog
    Reflection -->|"log reflection"| AgentLog

    %% Styles
    classDef core fill:#e0ffe0,stroke:#2b8a3e;
    classDef tools fill:#e0f0ff,stroke:#1f4e78;
    classDef persistence fill:#fff0b3,stroke:#b38f00;
    classDef external fill:#f0f0f0,stroke:#888,stroke-dasharray:5 5;
    classDef logger fill:#ffe5e0,stroke:#d9480f;
    classDef cli fill:#f3e5ff,stroke:#6f42c1;
```
