# bingreeky/opd-evolver architecture

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

- Interactive diagram: https://gitdiagram.com/bingreeky/opd-evolver
- Repository: https://github.com/bingreeky/opd-evolver

## Overview

OPD-Evolver is a slow–fast agent-evolution framework. Its runtime workflow runs benchmark tasks through an agent, retrieves and selects hierarchical experience for execution, then reflects on results to update memory and collect training data. A separate slow loop prepares OPD data and trains policy capabilities. The graph retains the documented benchmark and memory-management branches; several runner and training internals are unsampled, so their connections are shown only where the README or source index supports them.

Main entry points: [`opd_evolver/runners/task_runner.py`](https://github.com/bingreeky/opd-evolver/blob/main/opd_evolver/runners/task_runner.py) (Task runners), [`opd_evolver/pipelines/memory_pipeline.py`](https://github.com/bingreeky/opd-evolver/blob/main/opd_evolver/pipelines/memory_pipeline.py) (Memory pipeline), [`opd_evolver/subagents/react_agent.py`](https://github.com/bingreeky/opd-evolver/blob/main/opd_evolver/subagents/react_agent.py) (ReAct agent), [`opd_evolver/memory/memory_manager.py`](https://github.com/bingreeky/opd-evolver/blob/main/opd_evolver/memory/memory_manager.py) (Hierarchy manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Agent Runtime"]
  node_runner["Task runners<br/>[task_runner.py]"]
  node_agent["ReAct agent<br/>[react_agent.py]"]
  node_agent_memory["Step memory<br/>[memory.py]"]
  node_main_agent["Main agent<br/>[main_agent.py]"]
  node_benchmark_eval["Benchmark evaluation"]
end

subgraph group_memory["Experience Memory"]
  node_memory_pipeline["Memory pipeline<br/>[memory_pipeline.py]"]
  node_memory_prompts["Selection and reflection<br/>[memory_prompts.py]"]
  node_memory_manager["Hierarchy manager<br/>[memory_manager.py]"]
  node_four_tiers[("Experience tiers")]
  node_memory_store[("Embedding search and storage<br/>[base_store.py]")]
  node_embeddings["Embedding providers<br/>[embeddings.py]"]
  node_memory_datasets["Selector and writer data"]
end

subgraph group_learning["Policy Learning"]
  node_opd_data["Executor OPD dataset"]
  node_trainer["OPD trainer<br/>[opsd_trainer.py]"]
  node_policy["Deployable policy"]
end

subgraph group_infra["Model Services"]
  node_llm["LLM client<br/>[async_llm.py]"]
end

node_user(("Task initiator"))
node_benchmarks["Benchmark tasks"]
node_embedding_service["Embedding service"]

node_user -->|"starts task"| node_runner
node_benchmarks -->|"supplies tasks"| node_runner
node_runner -->|"runs agent"| node_agent
node_agent -->|"acts in environment"| node_benchmarks
node_agent -->|"records steps"| node_agent_memory
node_runner -->|"invokes memory flow"| node_memory_pipeline
node_memory_pipeline -->|"retrieves and updates"| node_memory_manager
node_memory_pipeline -->|"uses prompts"| node_memory_prompts
node_memory_pipeline -->|"logs examples"| node_memory_datasets
node_memory_manager -->|"manages tiers"| node_four_tiers
node_memory_manager -->|"delegates search"| node_memory_store
node_memory_store -->|"uses embeddings"| node_embeddings
node_embeddings -.->|"requests vectors"| node_embedding_service
node_memory_pipeline -->|"generates reflections"| node_llm
node_agent -->|"requests actions"| node_llm
node_runner -->|"rollout data used to build"| node_opd_data
node_memory_datasets -.->|"supports capability training"| node_trainer
node_opd_data -->|"trains on dataset"| node_trainer
node_trainer -->|"updates policy"| node_policy
node_policy -->|"evaluated by"| node_benchmark_eval
node_runner -->|"benchmark rollout"| node_benchmark_eval
node_main_agent -->|"uses model client"| node_llm

click node_runner "https://github.com/bingreeky/opd-evolver/blob/main/opd_evolver/runners/task_runner.py"
click node_agent "https://github.com/bingreeky/opd-evolver/blob/main/opd_evolver/subagents/react_agent.py"
click node_agent_memory "https://github.com/bingreeky/opd-evolver/blob/main/opd_evolver/base/agent/memory.py"
click node_main_agent "https://github.com/bingreeky/opd-evolver/blob/main/opd_evolver/main_agent.py"
click node_memory_pipeline "https://github.com/bingreeky/opd-evolver/blob/main/opd_evolver/pipelines/memory_pipeline.py"
click node_memory_prompts "https://github.com/bingreeky/opd-evolver/blob/main/opd_evolver/pipelines/memory_prompts.py"
click node_memory_manager "https://github.com/bingreeky/opd-evolver/blob/main/opd_evolver/memory/memory_manager.py"
click node_four_tiers "https://github.com/bingreeky/opd-evolver/tree/main/opd_evolver/memory"
click node_memory_store "https://github.com/bingreeky/opd-evolver/blob/main/opd_evolver/memory/base_store.py"
click node_embeddings "https://github.com/bingreeky/opd-evolver/blob/main/opd_evolver/memory/embeddings.py"
click node_memory_datasets "https://github.com/bingreeky/opd-evolver/blob/main/opd_evolver/memory/selector_dataset.py"
click node_llm "https://github.com/bingreeky/opd-evolver/blob/main/opd_evolver/base/engine/async_llm.py"
click node_opd_data "https://github.com/bingreeky/opd-evolver/blob/main/scripts/dataset/build_awm_executor_opd_dataset.py"
click node_trainer "https://github.com/bingreeky/opd-evolver/blob/main/opd_evolver/trainer/opsd_trainer.py"
click node_benchmark_eval "https://github.com/bingreeky/opd-evolver/blob/main/scripts/eval/bench_simple_awm.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_runner,node_agent,node_agent_memory,node_main_agent,node_benchmark_eval toneBlue
class node_memory_pipeline,node_memory_prompts,node_memory_manager,node_four_tiers,node_memory_store,node_embeddings,node_memory_datasets toneAmber
class node_opd_data,node_trainer,node_policy toneMint
class node_llm,node_user,node_benchmarks toneRose
class node_embedding_service toneIndigo
```

## Components

### Agent Runtime

- [Task runners](https://github.com/bingreeky/opd-evolver/blob/main/opd_evolver/runners/task_runner.py): `opd_evolver/runners/task_runner.py`
- [ReAct agent](https://github.com/bingreeky/opd-evolver/blob/main/opd_evolver/subagents/react_agent.py): `opd_evolver/subagents/react_agent.py`
- [Step memory](https://github.com/bingreeky/opd-evolver/blob/main/opd_evolver/base/agent/memory.py): `opd_evolver/base/agent/memory.py`
- [Main agent](https://github.com/bingreeky/opd-evolver/blob/main/opd_evolver/main_agent.py): `opd_evolver/main_agent.py`
- [Benchmark evaluation](https://github.com/bingreeky/opd-evolver/blob/main/scripts/eval/bench_simple_awm.py): `scripts/eval/bench_simple_awm.py`

### Experience Memory

- [Memory pipeline](https://github.com/bingreeky/opd-evolver/blob/main/opd_evolver/pipelines/memory_pipeline.py): `opd_evolver/pipelines/memory_pipeline.py`
- [Selection and reflection](https://github.com/bingreeky/opd-evolver/blob/main/opd_evolver/pipelines/memory_prompts.py): `opd_evolver/pipelines/memory_prompts.py`
- [Hierarchy manager](https://github.com/bingreeky/opd-evolver/blob/main/opd_evolver/memory/memory_manager.py): `opd_evolver/memory/memory_manager.py`
- [Experience tiers](https://github.com/bingreeky/opd-evolver/tree/main/opd_evolver/memory): `opd_evolver/memory`
- [Embedding search and storage](https://github.com/bingreeky/opd-evolver/blob/main/opd_evolver/memory/base_store.py): `opd_evolver/memory/base_store.py`
- [Embedding providers](https://github.com/bingreeky/opd-evolver/blob/main/opd_evolver/memory/embeddings.py): `opd_evolver/memory/embeddings.py`
- [Selector and writer data](https://github.com/bingreeky/opd-evolver/blob/main/opd_evolver/memory/selector_dataset.py): `opd_evolver/memory/selector_dataset.py`

### Policy Learning

- [Executor OPD dataset](https://github.com/bingreeky/opd-evolver/blob/main/scripts/dataset/build_awm_executor_opd_dataset.py): `scripts/dataset/build_awm_executor_opd_dataset.py`
- [OPD trainer](https://github.com/bingreeky/opd-evolver/blob/main/opd_evolver/trainer/opsd_trainer.py): `opd_evolver/trainer/opsd_trainer.py`
- **Deployable policy**

### Model Services

- [LLM client](https://github.com/bingreeky/opd-evolver/blob/main/opd_evolver/base/engine/async_llm.py): `opd_evolver/base/engine/async_llm.py`

### Other components

- **Task initiator**
- **Benchmark tasks**
- **Embedding service**

## Connections

- Task initiator → Task runners: starts task (evidence: `README.md`)
- Benchmark tasks → Task runners: supplies tasks (evidence: `README.md`)
- Task runners → ReAct agent: runs agent (evidence: `opd_evolver/runners/task_runner.py`)
- ReAct agent → Benchmark tasks: acts in environment (evidence: `opd_evolver/subagents/react_agent.py`)
- ReAct agent → Step memory: records steps (evidence: `opd_evolver/base/agent/memory.py`)
- Task runners → Memory pipeline: invokes memory flow (evidence: `opd_evolver/runners/task_runner.py`)
- Memory pipeline → Hierarchy manager: retrieves and updates (evidence: `opd_evolver/pipelines/memory_pipeline.py`)
- Memory pipeline → Selection and reflection: uses prompts (evidence: `opd_evolver/pipelines/memory_pipeline.py`)
- Memory pipeline → Selector and writer data: logs examples (evidence: `opd_evolver/pipelines/memory_pipeline.py`)
- Hierarchy manager → Experience tiers: manages tiers (evidence: `opd_evolver/memory/memory_manager.py`)
- Hierarchy manager → Embedding search and storage: delegates search (evidence: `opd_evolver/memory/memory_manager.py`)
- Embedding search and storage → Embedding providers: uses embeddings (evidence: `opd_evolver/memory/memory_manager.py`)
- Embedding providers → Embedding service: requests vectors
- Memory pipeline → LLM client: generates reflections (evidence: `opd_evolver/pipelines/memory_pipeline.py`)
- ReAct agent → LLM client: requests actions
- Task runners → Executor OPD dataset: rollout data used to build (evidence: `README.md`)
- Selector and writer data → OPD trainer: supports capability training (evidence: `README.md`)
- Executor OPD dataset → OPD trainer: trains on dataset (evidence: `README.md`)
- OPD trainer → Deployable policy: updates policy (evidence: `README.md`)
- Deployable policy → Benchmark evaluation: evaluated by (evidence: `README.md`)
- Task runners → Benchmark evaluation: benchmark rollout (evidence: `README.md`)
- Main agent → LLM client: uses model client (evidence: `opd_evolver/main_agent.py`)
