# skyworkai/deepresearchagent architecture

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

- Interactive diagram: https://gitdiagram.com/skyworkai/deepresearchagent
- Repository: https://github.com/skyworkai/deepresearchagent

## Overview

1. **What this repository is**
   - A Python runtime for “self-evolving” LLM agent systems.
   - The core idea is to treat prompts, agents, tools, environments, and memory as composable, versioned resources that can be observed and improved over time.

2. **Top-level architecture**
   - The repository is organized around a small set of runtime primitives in `src/` and a large config layer in `configs/`.
   - `examples/` contains runnable entrypoints that wire these primitives together for specific demos, benchmarks, and domain tasks.
   - `tests/` mirrors the same surfaces and acts like an executable architecture spec for the system.

3. **Composition and configuration boundary**
   - `src/config/` and `configs/` are the main assembly layer.
   - Configs define how to combine a model backend, agent policy, tools, environment, memory system, and optimizer into a runnable workflow.
   - This repo uses a strongly configuration-driven style rather than hard-coded application wiring.

4. **Agent runtime**
   - `src/agent/` contains the decision-making layer: simple chat, tool-calling, planning, debate, mobile, browser/operator, ESG, and trading agents.
   - Agents are the orchestration boundary between the LLM and the rest of the system.
   - They choose actions, invoke tools, consume environment feedback, and may hand off to optimizers or memory.

5. **Tool layer**
   - `src/tool/` exposes capabilities to agents.
   - It includes default utilities like bash, file editing/reading, Python execution, web search/fetch, markdown conversion, and LeetCode helpers.
   - There are also workflow tools for research, reporting, todo generation, browser operations, and skill generation.
   - This is the main “action surface” an agent uses to affect the outside world.

6. **Environment layer**
   - `src/environment/` is the stateful execution boundary.
   - It includes browser, mobile, filesystem, GitHub, database, FAISS, Alpaca, Binance, Hyperliquid, quick backtest, signal research, and QLib-related environments.
   - Many environments have subpackages like `alpacaentry`, `binanceentry`, and `browser/` that implement service, producer/consumer, and event handling internals.
   - Environments encapsulate external systems and expose structured state, actions, and feedback.

7. **Memory and long-lived state**
   - `src/memory/` stores session-level and long-term artifacts, including general memory and trading-specific memory systems.
   - Memory is where summaries, insights, records, and optimization traces accumulate across steps or runs.
   - This is one of the key “evolution” boundaries: the system can remember what happened and reuse it later.

8. **Optimization / self-improvement loop**
   - `src/optimizer/` contains the improvement algorithms: reflection, GRPO, Reinforce++, and a larger TextGrad-based optimizer stack.
   - These optimizers transform feedback into updated prompts, variables, or solution artifacts.
   - They are the “Optimize” phase in the repo’s Act → Observe → Optimize → Remember loop.

9. **Model/provider abstraction**
   - `src/model/` centralizes LLM access and backend-specific serializers/clients.
   - Provider support includes OpenAI, Anthropic, Google, and OpenRouter.
   - This layer isolates the agent/runtime from vendor-specific APIs and response formats.

10. **Prompt management and versioned templates**
   - `src/prompt/` contains prompt templates and a prompt server/manager.
   - Templates are specialized by agent type: trading, debate, planning, mobile, browser, tool-calling, optimization, and chat.
   - This layer is important because prompts are treated as first-class resources rather than ad hoc strings.

11. **Tracing, versioning, and runtime services**
   - `src/tracer/` records trajectories and execution artifacts.
   - `src/version/` manages version metadata for evolving resources.
   - `src/interaction/`, `src/message/`, `src/session/`, and `src/task/` provide supporting types and event/message boundaries for runtime coordination.
   - Together these modules make the system inspectable and auditable.

12. **Domain-specific data and evaluation pipelines**
   - `src/benchmark/`, `src/data/`, `src/download/`, `src/process/`, `src/metric/`, and `src/indicator/` support datasets, downloaders, preprocessing, scoring, and evaluation.
   - The repo covers math/code benchmarks, ESG, financial time series, and trading/backtesting workflows.
   - This makes the architecture not just an inference system, but also a research/evaluation platform.

13. **Specialized external integration: LightRAG / ESG tooling**
   - `src/tool/esg_tools/lightrag/` vendors a substantial retrieval/graph/RAG subsystem with its own API, web UI assets, LLM backends, and graph/vector store adapters.
   - This is effectively a nested platform inside the repo, used for ESG-oriented retrieval and graph reasoning.
   - If drawing architecture, treat it as a separate integrated service boundary rather than a small utility.

14. **Execution surfaces**
   - `examples/` provides the main runnable flows for agents, downloads, benchmarks, backtests, debates, and process pipelines.
   - `src/*/server.py` modules indicate some components can run as services rather than only as local libraries.
   - `tests/` includes many end-to-end scenarios, confirming that the repo’s architecture is meant to be assembled and exercised in multiple modes.

15. **Operational/tooling boundaries**
   - `environment.yml`, `requirements.txt`, `.env.template`, and GitHub Actions deployment config define the operational footprint.
   - `libs/` contains vendored or embedded dependencies.
   - The repo is primarily a Python research/runtime system with optional UI/server components and external API integrations, not a single monolithic app.

Main entry points: [`src/agent`](https://github.com/skyworkai/deepresearchagent/tree/main/src/agent) (Agents), [`configs`](https://github.com/skyworkai/deepresearchagent/tree/main/configs) (Configs), [`src`](https://github.com/skyworkai/deepresearchagent/tree/main/src) (Services), [`tests`](https://github.com/skyworkai/deepresearchagent/tree/main/tests) (Tests)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_config["Composition"]
  node_configs["Configs<br/>assembly config"]
  node_src_config["Runtime Config<br/>config helpers"]
end

subgraph group_grp_runtime["Runtime"]
  node_agent_runtime["Agents<br/>orchestration"]
  node_model_layer["Models<br/>provider abstraction"]
end

subgraph group_grp_io["Action & State"]
  node_tool_layer["Tools<br/>action surface"]
  node_env_layer["Environments<br/>execution boundary"]
  node_memory_layer[("Memory<br/>state store")]
end

subgraph group_grp_learning["Learning"]
  node_prompt_layer["Prompts<br/>template manager"]
  node_optimizer_layer{{"Optimizers<br/>self-improvement"}}
  node_tracer_layer["Tracing<br/>audit trail"]
  node_version_layer["Versioning<br/>resource metadata"]
  node_interaction_core["Runtime Types<br/>coordination types"]
  node_support_services["Services<br/>server surfaces"]
end

subgraph group_grp_data["Data & Eval"]
  node_benchmark_layer["Benchmarks<br/>evaluation suite"]
  node_data_layer["Data"]
  node_download_layer["Download<br/>ingestion"]
  node_process_layer["Process"]
  node_metric_layer["Metrics<br/>scoring"]
end

subgraph group_grp_examples["Execution"]
  node_examples_layer["Examples<br/>runnable flows"]
  node_tests_layer["Tests<br/>spec harness"]
end

subgraph group_grp_lightrag["LightRAG"]
  node_lightrag_service["LightRAG<br/>nested retrieval platform"]
end

node_configs -->|"assembles"| node_src_config
node_configs -->|"builds"| node_agent_runtime
node_configs -->|"binds"| node_tool_layer
node_configs -->|"binds"| node_env_layer
node_configs -->|"binds"| node_memory_layer
node_configs -->|"binds"| node_optimizer_layer
node_agent_runtime -->|"queries"| node_model_layer
node_agent_runtime -->|"uses"| node_prompt_layer
node_agent_runtime -->|"invokes"| node_tool_layer
node_agent_runtime -->|"observes"| node_env_layer
node_agent_runtime -->|"reads/writes"| node_memory_layer
node_optimizer_layer -->|"updates"| node_prompt_layer
node_optimizer_layer -->|"stores"| node_memory_layer
node_tracer_layer -->|"records"| node_agent_runtime
node_version_layer -->|"versions"| node_prompt_layer
node_interaction_core -->|"coordinates"| node_agent_runtime
node_benchmark_layer -->|"loads"| node_data_layer
node_download_layer -->|"feeds"| node_data_layer
node_process_layer -->|"transforms"| node_data_layer
node_metric_layer -->|"scores"| node_benchmark_layer
node_examples_layer -->|"runs"| node_configs
node_examples_layer -->|"demonstrates"| node_agent_runtime
node_examples_layer -->|"executes"| node_benchmark_layer
node_examples_layer -->|"executes"| node_process_layer
node_tests_layer -->|"verifies"| node_agent_runtime
node_tests_layer -->|"verifies"| node_env_layer
node_tests_layer -->|"verifies"| node_model_layer
node_tests_layer -->|"verifies"| node_prompt_layer
node_tests_layer -->|"verifies"| node_lightrag_service
node_lightrag_service -->|"exposed via"| node_tool_layer
node_support_services -->|"serves"| node_agent_runtime
node_support_services -->|"serves"| node_env_layer
node_support_services -->|"serves"| node_memory_layer
node_support_services -->|"serves"| node_benchmark_layer
node_support_services -->|"serves"| node_prompt_layer

click node_configs "https://github.com/skyworkai/deepresearchagent/tree/main/configs"
click node_src_config "https://github.com/skyworkai/deepresearchagent/tree/main/src/config"
click node_agent_runtime "https://github.com/skyworkai/deepresearchagent/tree/main/src/agent"
click node_model_layer "https://github.com/skyworkai/deepresearchagent/tree/main/src/model"
click node_prompt_layer "https://github.com/skyworkai/deepresearchagent/tree/main/src/prompt"
click node_tool_layer "https://github.com/skyworkai/deepresearchagent/tree/main/src/tool"
click node_env_layer "https://github.com/skyworkai/deepresearchagent/tree/main/src/environment"
click node_memory_layer "https://github.com/skyworkai/deepresearchagent/tree/main/src/memory"
click node_optimizer_layer "https://github.com/skyworkai/deepresearchagent/tree/main/src/optimizer"
click node_tracer_layer "https://github.com/skyworkai/deepresearchagent/tree/main/src/tracer"
click node_version_layer "https://github.com/skyworkai/deepresearchagent/tree/main/src/version"
click node_interaction_core "https://github.com/skyworkai/deepresearchagent/tree/main/src/interaction"
click node_benchmark_layer "https://github.com/skyworkai/deepresearchagent/tree/main/src/benchmark"
click node_data_layer "https://github.com/skyworkai/deepresearchagent/tree/main/src/data"
click node_download_layer "https://github.com/skyworkai/deepresearchagent/tree/main/src/download"
click node_process_layer "https://github.com/skyworkai/deepresearchagent/tree/main/src/process"
click node_metric_layer "https://github.com/skyworkai/deepresearchagent/tree/main/src/metric"
click node_examples_layer "https://github.com/skyworkai/deepresearchagent/tree/main/examples"
click node_tests_layer "https://github.com/skyworkai/deepresearchagent/tree/main/tests"
click node_lightrag_service "https://github.com/skyworkai/deepresearchagent/tree/main/src/tool/esg_tools/lightrag"
click node_support_services "https://github.com/skyworkai/deepresearchagent/tree/main/src"

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_configs,node_src_config,node_lightrag_service toneBlue
class node_agent_runtime,node_model_layer toneAmber
class node_tool_layer,node_env_layer,node_memory_layer toneMint
class node_prompt_layer,node_optimizer_layer,node_tracer_layer,node_version_layer,node_interaction_core,node_support_services toneRose
class node_benchmark_layer,node_data_layer,node_download_layer,node_process_layer,node_metric_layer toneIndigo
class node_examples_layer,node_tests_layer toneTeal
```

## Components

### Composition

Configuration and assembly layer

- [Configs](https://github.com/skyworkai/deepresearchagent/tree/main/configs): assembly config · Repository-wide configuration layer that wires models, agents, tools, environments, memory, and optimizers. · `configs`
- [Runtime Config](https://github.com/skyworkai/deepresearchagent/tree/main/src/config): config helpers · Core configuration helpers and shared config structures. · `src/config`

### Runtime

Core agent/runtime primitives

- [Agents](https://github.com/skyworkai/deepresearchagent/tree/main/src/agent): orchestration · Decision-making layer for chat, tool use, planning, debate, mobile, browser, ESG, and trading agents. · `src/agent`
- [Models](https://github.com/skyworkai/deepresearchagent/tree/main/src/model): provider abstraction · LLM provider abstraction and backend-specific clients/serializers. · `src/model`

### Action & State

Tools, environments, memory, and external effects

- [Tools](https://github.com/skyworkai/deepresearchagent/tree/main/src/tool): action surface · Default, workflow, MCP, and domain tools exposed to agents. · `src/tool`
- [Environments](https://github.com/skyworkai/deepresearchagent/tree/main/src/environment): execution boundary · Stateful external-system environments for browsers, mobile, trading, filesystem, databases, and research. · `src/environment`
- [Memory](https://github.com/skyworkai/deepresearchagent/tree/main/src/memory): state store · Session and long-term memory systems for general, trading, and optimizer artifacts. · `src/memory`

### Learning

Optimization, prompts, tracing, and versions

- [Prompts](https://github.com/skyworkai/deepresearchagent/tree/main/src/prompt): template manager · Prompt templates and prompt server/manager for versioned agent prompts. · `src/prompt`
- [Optimizers](https://github.com/skyworkai/deepresearchagent/tree/main/src/optimizer): self-improvement · Reflection, GRPO, Reinforce++, and TextGrad-based optimization stacks. · `src/optimizer`
- [Tracing](https://github.com/skyworkai/deepresearchagent/tree/main/src/tracer): audit trail · Trajectory and execution artifact recording for observability. · `src/tracer`
- [Versioning](https://github.com/skyworkai/deepresearchagent/tree/main/src/version): resource metadata · Version metadata for evolving prompts, agents, and other resources. · `src/version`
- [Runtime Types](https://github.com/skyworkai/deepresearchagent/tree/main/src/interaction): coordination types · Messages, interactions, sessions, and task types that connect runtime components. · `src/interaction`
- [Services](https://github.com/skyworkai/deepresearchagent/tree/main/src): server surfaces · Server modules and runtime service entrypoints across major subsystems. · `src`

### Data & Eval

Benchmarks, datasets, download, processing, metrics

- [Benchmarks](https://github.com/skyworkai/deepresearchagent/tree/main/src/benchmark): evaluation suite · Benchmark loaders, contexts, utilities, and server support for math/code evaluation. · `src/benchmark`
- [Data](https://github.com/skyworkai/deepresearchagent/tree/main/src/data): datasets · Dataset loaders, collators, scalers, and task-specific data structures. · `src/data`
- [Download](https://github.com/skyworkai/deepresearchagent/tree/main/src/download): ingestion · Data acquisition adapters for market and benchmark sources. · `src/download`
- [Process](https://github.com/skyworkai/deepresearchagent/tree/main/src/process): preprocessing · Data processing and scoring pipelines for market and benchmark workflows. · `src/process`
- [Metrics](https://github.com/skyworkai/deepresearchagent/tree/main/src/metric): scoring · Evaluation metrics for classification, ranking, and trading performance. · `src/metric`

### Execution

Runnable demos and tests

- [Examples](https://github.com/skyworkai/deepresearchagent/tree/main/examples): runnable flows · Executable entrypoints for agents, benchmarks, downloads, debates, and backtests. · `examples`
- [Tests](https://github.com/skyworkai/deepresearchagent/tree/main/tests): spec harness · End-to-end and subsystem tests that mirror the architecture surfaces. · `tests`

### LightRAG

Nested ESG retrieval and graph subsystem

- [LightRAG](https://github.com/skyworkai/deepresearchagent/tree/main/src/tool/esg_tools/lightrag): nested retrieval platform · Integrated ESG retrieval, knowledge graph, vector store, API, and web UI subsystem. · `src/tool/esg_tools/lightrag`

## Connections

- Configs → Runtime Config: assembles · Configuration definitions are normalized through shared config helpers.
- Configs → Agents: builds · Configs instantiate agent policies and runtime wiring.
- Configs → Tools: binds · Configs select the tool surface for each agent/workflow.
- Configs → Environments: binds · Configs select the environment boundary for each workflow.
- Configs → Memory: binds · Configs choose session and long-term memory systems.
- Configs → Optimizers: binds · Configs attach optimization loops to agent workflows.
- Agents → Models: queries · Agents rely on provider abstraction for LLM calls.
- Agents → Prompts: uses · Agents consume versioned prompt templates.
- Agents → Tools: invokes · Agents execute tools to act on the world.
- Agents → Environments: observes · Agents receive structured environment state and feedback.
- Agents → Memory: reads/writes · Agents store and retrieve summaries and artifacts.
- Optimizers → Prompts: updates · Optimizers refine prompts and related variables.
- Optimizers → Memory: stores · Optimization traces and lessons accumulate in memory.
- Tracing → Agents: records · Tracing captures agent trajectories and execution artifacts.
- Versioning → Prompts: versions · Prompt resources are versioned as first-class artifacts.
- Runtime Types → Agents: coordinates · Messages, sessions, and tasks structure agent execution.
- Benchmarks → Data: loads · Benchmarks consume datasets and task examples.
- Download → Data: feeds · Download adapters populate datasets.
- Process → Data: transforms · Processing pipelines prepare and score data.
- Metrics → Benchmarks: scores · Metrics evaluate benchmark and trading outputs.
- Examples → Configs: runs · Examples are the main executable entrypoints for configured workflows.
- Examples → Agents: demonstrates · Examples exercise the agent runtime in concrete scenarios.
- Examples → Benchmarks: executes · Some examples run benchmark and evaluation flows.
- Examples → Process: executes · Some examples run ingestion and processing pipelines.
- Tests → Agents: verifies · Tests cover agent behavior and integrations.
- Tests → Environments: verifies · Tests exercise environment adapters and services.
- Tests → Models: verifies · Tests cover provider integrations and serialization.
- Tests → Prompts: verifies · Tests cover prompt management and template selection.
- Tests → LightRAG: verifies · Tests touch the integrated LightRAG/ESG subsystem where relevant.
- LightRAG → Tools: exposed via · LightRAG is surfaced as an ESG-oriented tool subsystem.
- Services → Agents: serves · Some components expose server entrypoints for agents.
- Services → Environments: serves · Some environments run as services.
- Services → Memory: serves · Memory has service entrypoints for shared access.
- Services → Benchmarks: serves · Benchmarks include server surfaces.
- Services → Prompts: serves · Prompt resources can be managed through a server.
