# faraway1nspace/pedantic-research-assistant-multi-agent architecture

> Architecture diagram of the GitHub repository faraway1nspace/pedantic-research-assistant-multi-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/faraway1nspace/pedantic-research-assistant-multi-agent
- Repository: https://github.com/faraway1nspace/pedantic-research-assistant-multi-agent

## Overview

##### Project type and purpose
- This is a Python-based multi-agent research assistant built on the Pydantic-AI framework.
- It orchestrates a workflow of specialized LLM agents to perform web searches, document summarization, critique, and report writing for deep research tasks (e.g., company due diligence).

##### File structure
- Top level
- README.md, requirements.txt, dot_env – project metadata, dependencies, and API key config
- scratch.py, docs/ – demo scripts and documentation
- src/ – application code
- Under src/
- config.py, models.py – shared configuration and Pydantic data models
- utils/webtools.py – helper functions for web fetching, PDF downloads, etc.
- usecase/company_research/
– agents.py – definitions of the five agents (research_assistant_agent, search_intent_agent, summarizer_agent, critic_agent, report_writer_agent)
– config.py, prompts.py, utils.py, models.py – per–use-case configuration, prompt templates, utilities, and data schemas
– main.py – the entry point tying agents together

##### Key insights from the README
- Agents: each has specialized system prompts and tools
- Tools: deterministic Python functions registered via `@agent.tool`
- Dependencies: a shared “knowledge base” object passed to each agent for inter-agent communication
- Data validation: using Pydantic models for predictable outputs (e.g., Footnote, ResearchReport)
- External services: OpenAI/Anthropic API for LLM calls, DuckDuckGo (duckduckgo_search) for web search

##### Main components and interactions
a. Components
- User (CLI or script)
- research_assistant_agent (orchestrator)
- Sub-agents:
- search_intent_agent
- summarizer_agent
- critic_agent
- report_writer_agent
- Tools layer (webtools, PDF downloader, search wrapper)
- Knowledge Base (in-memory store of downloaded docs; a Dependency)
- External services:
- LLM API (OpenAI or Anthropic)
- Web Search API (DuckDuckGo)
- Web / PDF hosts
b. Relationships / Data flow
1. User sends research query → research_assistant_agent
2. research_assistant_agent delegates to search_intent_agent → refines query
3. research_assistant_agent calls webtools → DuckDuckGo API → downloads pages/PDFs → stores them in Knowledge Base
4. research_assistant_agent invokes summarizer_agent on raw docs → summaries returned to KB
5. research_assistant_agent invokes critic_agent → filtered/improved docs in KB
6. research_assistant_agent invokes report_writer_agent → final ResearchReport (with Footnotes) → returned to User
7. All agent→LLM calls go through Pydantic-AI, which wraps OpenAI/Anthropic API
c. Architectural patterns and design principles
- Multi-agent orchestration (modular, specialized workflows)
- Dependency injection (shared Knowledge Base passed via Pydantic-AI Deps)
- Tool registration (functions exposed to agents via decorators)
- Strong typing and validation (Pydantic models for inputs/outputs)
d. Relevant technologies/frameworks
- Python 3.11
- Pydantic-AI (agent framework)
- Pydantic (data models)
- openai / anthropic SDKs
- duckduckgo_search
- dotenv (API key management)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% UI Layer
    subgraph "UI Layer"
        User["User (CLI)"]:::external
        Demo["Blog Demo Script"]:::external
    end

    %% Config & Metadata
    subgraph "Config & Metadata"
        Env[".env (API Keys)"]:::config
        Metadata["README.md / requirements.txt"]:::config
    end

    %% Agent Layer
    subgraph "Agent Layer"
        Orchestrator["Research Assistant Agent"]:::agent
        subgraph "Sub-Agents"
            SearchIntent["Search Intent Agent"]:::agent
            Summarizer["Summarizer Agent"]:::agent
            Critic["Critic Agent"]:::agent
            Reporter["Report Writer Agent"]:::agent
        end
    end

    %% Pydantic-AI Glue
    subgraph "Pydantic-AI Glue"
        SharedConfig["Shared Config"]:::config
        SharedModels["Shared Pydantic Models"]:::config
    end

    %% Usecase Layer
    subgraph "Usecase Layer"
        UCConfig["KB Config"]:::dependency
        UCModels["Usecase Pydantic Models"]:::config
        Prompts["Prompt Templates"]:::config
        UCUtils["Usecase Utilities"]:::tools
        Entry["Main (workflow)"]:::agent
    end

    %% Tools Layer
    subgraph "Tools Layer"
        Webtools["Webtools (search, PDF)"]:::tools
    end

    %% Knowledge Base
    subgraph "Knowledge Base"
        KB["Knowledge Base"]:::dependency
    end

    %% External Services
    subgraph "External Services"
        LLM["LLM API"]:::external
        SearchAPI["DuckDuckGo API"]:::external
        WebPDF["Web/PDF Hosts"]:::external
    end

    %% Connections
    User -->|runs| Entry
    Demo -->|runs| Entry
    Entry -->|orchestrates| Orchestrator
    Orchestrator -->|delegate| SearchIntent
    SearchIntent -->|refined query| Orchestrator
    Orchestrator -->|call tools| Webtools
    Webtools -->|search calls| SearchAPI
    Webtools -->|downloads| WebPDF
    Webtools -->|raw docs| KB
    Orchestrator -->|summarize| Summarizer
    Summarizer -->|summary| KB
    Orchestrator -->|critique| Critic
    Critic -->|improved docs| KB
    Orchestrator -->|write report| Reporter
    Reporter -->|ResearchReport| User

    %% Agent to LLM calls
    Orchestrator -.->|LLM call| LLM
    SearchIntent -.->|LLM call| LLM
    Summarizer -.->|LLM call| LLM
    Critic -.->|LLM call| LLM
    Reporter -.->|LLM call| LLM

    %% Dependencies and Glue
    Orchestrator --> SharedConfig
    Orchestrator --> SharedModels
    Entry --> UCConfig
    Entry --> UCModels
    Entry --> Prompts
    Entry --> UCUtils

    %% Click Events
    click User "https://github.com/faraway1nspace/pedantic-research-assistant-multi-agent/blob/main/scratch.py"
    click Demo "https://github.com/faraway1nspace/pedantic-research-assistant-multi-agent/blob/main/docs/blog/blog_demo.py"
    click Env "https://github.com/faraway1nspace/pedantic-research-assistant-multi-agent/tree/main/dot_env"
    click Metadata "https://github.com/faraway1nspace/pedantic-research-assistant-multi-agent/blob/main/README.md"
    click SharedConfig "https://github.com/faraway1nspace/pedantic-research-assistant-multi-agent/blob/main/src/config.py"
    click SharedModels "https://github.com/faraway1nspace/pedantic-research-assistant-multi-agent/blob/main/src/models.py"
    click UCConfig "https://github.com/faraway1nspace/pedantic-research-assistant-multi-agent/blob/main/src/usecase/company_research/config.py"
    click Orchestrator "https://github.com/faraway1nspace/pedantic-research-assistant-multi-agent/blob/main/src/usecase/company_research/agents.py"
    click SearchIntent "https://github.com/faraway1nspace/pedantic-research-assistant-multi-agent/blob/main/src/usecase/company_research/agents.py"
    click Summarizer "https://github.com/faraway1nspace/pedantic-research-assistant-multi-agent/blob/main/src/usecase/company_research/agents.py"
    click Critic "https://github.com/faraway1nspace/pedantic-research-assistant-multi-agent/blob/main/src/usecase/company_research/agents.py"
    click Reporter "https://github.com/faraway1nspace/pedantic-research-assistant-multi-agent/blob/main/src/usecase/company_research/agents.py"
    click Entry "https://github.com/faraway1nspace/pedantic-research-assistant-multi-agent/blob/main/src/usecase/company_research/main.py"
    click UCModels "https://github.com/faraway1nspace/pedantic-research-assistant-multi-agent/blob/main/src/usecase/company_research/models.py"
    click Prompts "https://github.com/faraway1nspace/pedantic-research-assistant-multi-agent/blob/main/src/usecase/company_research/prompts.py"
    click UCUtils "https://github.com/faraway1nspace/pedantic-research-assistant-multi-agent/blob/main/src/usecase/company_research/utils.py"
    click Webtools "https://github.com/faraway1nspace/pedantic-research-assistant-multi-agent/blob/main/src/utils/webtools.py"

    %% Styles
    classDef agent fill:#B3CDE0,stroke:#333,stroke-width:1px
    classDef tools fill:#C7E9B4,stroke:#333,stroke-width:1px
    classDef dependency fill:#FBE99A,stroke:#333,stroke-width:1px
    classDef config fill:#FBE99A,stroke:#333,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px
```
