# tomefy5/scout-agent architecture

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

- Interactive diagram: https://gitdiagram.com/tomefy5/scout-agent
- Repository: https://github.com/tomefy5/scout-agent

## Overview

1. **What this repo is**
   SCOUT is a Python 3.11+ autonomous sourcing/enrichment agent. The architecture is centered on a **stateful orchestration loop** rather than a traditional request/response app.

2. **Primary runtime entry point**
   `main.py` is the user-facing CLI entry point. It collects the target sourcing request and hands control to the agent workflow defined under `src/`.

3. **Core orchestration layer**
   `src/graph.py` is the main coordination boundary. It defines the LangGraph workflow: planner/search/analysis steps, transitions between them, and the looping behavior that lets the agent refine its search over multiple iterations.

4. **Shared agent state**
   `src/state.py` holds the evolving `AgentState` passed between nodes. This is the main in-memory data structure for the workflow and likely contains the request, ICP, search results, scraped content, lead candidates, and run status.

5. **LLM-driven planning**
   `src/agents/planner.py` is the reasoning layer that turns a vague user prompt into a structured search strategy. This is where the agent decides what to look for, how to search, and how to refine criteria during the graph cycle.

6. **Typed domain models**
   `src/models/schemas.py` defines the Pydantic schemas for the project’s key business objects, especially ICP and lead/enrichment outputs. These schemas act as the contract between LLM output, tools, and the rest of the workflow.

7. **External tool integrations**
   `src/tools/search.py` wraps Tavily search, providing candidate discovery from web search.
   `src/tools/scraper.py` wraps Firecrawl, providing page-level content extraction/verification from real company websites.  
   These are the two main external data acquisition boundaries.

8. **End-to-end data flow**
   The flow is: **user prompt → planner → search → scrape/verify → qualification/enrichment → structured output**. The graph is intended to revisit earlier steps when results are weak or incomplete, which is why state and orchestration are central.

9. **Quality and validation boundary**
   Pydantic schemas plus the test file `test_icp.py` suggest the repo emphasizes validating structured extraction, especially the ICP conversion step. This reduces dependence on free-form LLM output.

10. **Storage and persistence**
   `data/` exists but is mostly empty, indicating persistence/export is not yet a primary subsystem. The current architecture is still agent-execution-first; storage appears planned for later phases.

11. **Documentation and design intent**
   `docs/ARCHITECTURE.md` and `docs/SETUP.md` indicate the repo is organized around explicit architecture and operational setup guidance. The README roadmap also shows that orchestration is still evolving, with production export/UI not yet implemented.

12. **Key external dependencies that shape the architecture**
   The system depends on **LangGraph** for workflow control, **LangChain** for LLM interfacing, **Gemini** for reasoning/extraction, **Tavily** for search, **Firecrawl** for scraping, and **Pydantic** for typed I/O. These are not incidental libraries; they define the boundaries between planning, retrieval, scraping, and validation.

13. **How to diagram it**
   The cleanest diagram would show:
   - a CLI entry point,
   - a central LangGraph orchestration loop,
   - a shared typed state object,
   - a planning node,
   - external search and scraping services,
   - schema validation around outputs,
   - and a final qualified lead/result stream back to the user.

Main entry points: [`src/graph.py`](https://github.com/tomefy5/scout-agent/blob/main/src/graph.py) (Orchestrator), [`src/state.py`](https://github.com/tomefy5/scout-agent/blob/main/src/state.py) (Agent state), [`src/agents/planner.py`](https://github.com/tomefy5/scout-agent/blob/main/src/agents/planner.py) (Planner), [`src/models/schemas.py`](https://github.com/tomefy5/scout-agent/blob/main/src/models/schemas.py) (Schemas)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_user_request(("User request<br/>input"))
  node_cli["CLI<br/>entrypoint<br/>[main.py]"]
  node_result["Qualified output<br/>final output"]
end

subgraph group_core["Core workflow"]
  node_graph{{"Orchestrator<br/>langgraph workflow<br/>[graph.py]"}}
  node_state[("Agent state<br/>shared state<br/>[state.py]")]
  node_planner["Planner<br/>[planner.py]"]
  node_qualifier["Qualify lead<br/>analysis step"]
end

subgraph group_integrations["Integrations"]
  node_search["Search<br/>[search.py]"]
  node_scraper["Scraper<br/>site extraction tool<br/>[scraper.py]"]
end

subgraph group_contracts["Contracts"]
  node_schemas["Schemas<br/>pydantic models<br/>[schemas.py]"]
  node_tests["ICP test<br/>validation test<br/>[test_icp.py]"]
end

node_user_request -->|"submit"| node_cli
node_cli -->|"start run"| node_graph
node_graph -->|"read/write"| node_state
node_graph -->|"plan"| node_planner
node_planner -->|"shape intent"| node_schemas
node_planner -->|"store plan"| node_state
node_graph -->|"retrieve candidates"| node_search
node_search -->|"add results"| node_state
node_graph -->|"verify pages"| node_scraper
node_scraper -->|"add evidence"| node_state
node_state -->|"provide context"| node_qualifier
node_qualifier -->|"validate output"| node_schemas
node_qualifier -->|"update status"| node_state
node_graph -.->|"refine loop"| node_planner
node_qualifier -->|"emit"| node_result
node_tests -.->|"exercise"| node_schemas

click node_cli "https://github.com/tomefy5/scout-agent/blob/main/main.py"
click node_graph "https://github.com/tomefy5/scout-agent/blob/main/src/graph.py"
click node_state "https://github.com/tomefy5/scout-agent/blob/main/src/state.py"
click node_planner "https://github.com/tomefy5/scout-agent/blob/main/src/agents/planner.py"
click node_search "https://github.com/tomefy5/scout-agent/blob/main/src/tools/search.py"
click node_scraper "https://github.com/tomefy5/scout-agent/blob/main/src/tools/scraper.py"
click node_schemas "https://github.com/tomefy5/scout-agent/blob/main/src/models/schemas.py"
click node_tests "https://github.com/tomefy5/scout-agent/blob/main/test_icp.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_user_request,node_cli,node_result toneBlue
class node_graph,node_state,node_planner,node_qualifier toneAmber
class node_search,node_scraper toneMint
class node_schemas,node_tests toneRose
```

## Components

### Runtime

User-facing entry and final result flow.

- **User request**: input · Sourcing prompt and target criteria provided by the user.
- [CLI](https://github.com/tomefy5/scout-agent/blob/main/main.py): entrypoint · Command-line entry point that starts the agent run. · `main.py`
- **Qualified output**: final output · Structured sourcing result returned to the user.

### Core workflow

Stateful orchestration and planning loop.

- [Orchestrator](https://github.com/tomefy5/scout-agent/blob/main/src/graph.py): langgraph workflow · Central coordination loop for planning, retrieval, analysis, and refinement. · `src/graph.py`
- [Agent state](https://github.com/tomefy5/scout-agent/blob/main/src/state.py): shared state · Mutable run state passed between workflow nodes. · `src/state.py`
- [Planner](https://github.com/tomefy5/scout-agent/blob/main/src/agents/planner.py): llm planner · Turns the prompt into a structured search and refinement strategy. · `src/agents/planner.py`
- **Qualify lead**: analysis step · Evaluates retrieved evidence and produces structured lead/enrichment output.

### Integrations

External acquisition services used by the agent.

- [Search](https://github.com/tomefy5/scout-agent/blob/main/src/tools/search.py): web search tool · Tavily-backed candidate discovery from the web. · `src/tools/search.py`
- [Scraper](https://github.com/tomefy5/scout-agent/blob/main/src/tools/scraper.py): site extraction tool · Firecrawl-backed page fetching and verification from company websites. · `src/tools/scraper.py`

### Contracts

Typed schemas and validation boundary.

- [Schemas](https://github.com/tomefy5/scout-agent/blob/main/src/models/schemas.py): pydantic models · Typed ICP and lead/enrichment contracts used across the workflow. · `src/models/schemas.py`
- [ICP test](https://github.com/tomefy5/scout-agent/blob/main/test_icp.py): validation test · Checks structured ICP extraction and schema behavior. · `test_icp.py`

## Connections

- User request → CLI: submit · The user supplies a sourcing request to the CLI.
- CLI → Orchestrator: start run · CLI hands control to the orchestration workflow.
- Orchestrator → Agent state: read/write · Workflow nodes share and update run state.
- Orchestrator → Planner: plan · Orchestrator invokes the LLM planning step.
- Planner → Schemas: shape intent · Planner uses typed structures for ICP and search strategy output.
- Planner → Agent state: store plan · Structured plan is persisted into agent state.
- Orchestrator → Search: retrieve candidates · Workflow sends search queries to external discovery tooling.
- Search → Agent state: add results · Search results are accumulated in state for downstream steps.
- Orchestrator → Scraper: verify pages · Workflow fetches and extracts website content for candidates.
- Scraper → Agent state: add evidence · Scraped content is stored for qualification and refinement.
- Agent state → Qualify lead: provide context · Qualification step consumes request, evidence, and prior iterations.
- Qualify lead → Schemas: validate output · Lead and enrichment objects are constrained by typed schemas.
- Qualify lead → Agent state: update status · Qualification updates confidence, completeness, and next actions.
- Orchestrator → Planner: refine loop · Weak or incomplete results can send the workflow back to planning.
- Qualify lead → Qualified output: emit · Structured output is returned once the run is complete.
- ICP test → Schemas: exercise · Tests verify schema-driven ICP extraction and structured validation.
