# victorzhong0110/llm-research-os architecture

> Architecture diagram of the GitHub repository victorzhong0110/llm-research-os, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/victorzhong0110/llm-research-os
- Repository: https://github.com/victorzhong0110/llm-research-os

## Overview

LLM Research OS is a model-, training-backend-, and compute-provider-neutral research control plane. Researchers define and validate research specifications, compose experiments, and may use AI to propose or contest plans; authorization gates sensitive actions before runs execute on simulated, local, or remote Workers. The system records events and artifacts, then supports evidence import, metrics, reports, lineage, and research decisions. The README documents these major capabilities; sampled source confirms the shared application façade, append-only event store, Worker client, and reviewed-execution constraints, but not every subsystem’s wiring.

Main entry points: [`src/llm_research_os/storage/store.py`](https://github.com/victorzhong0110/llm-research-os/blob/main/src/llm_research_os/storage/store.py) (Append-only event store), [`src/llm_research_os/artifacts/store.py`](https://github.com/victorzhong0110/llm-research-os/blob/main/src/llm_research_os/artifacts/store.py) (Content-addressed artifacts), [`src/llm_research_os/application/service.py`](https://github.com/victorzhong0110/llm-research-os/blob/main/src/llm_research_os/application/service.py) (Command service), [`src/llm_research_os/runs/control.py`](https://github.com/victorzhong0110/llm-research-os/blob/main/src/llm_research_os/runs/control.py) (Run control)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_authoring["Research authoring"]
  node_spec["Research specification<br/>[io.py]"]
  node_blocks["Experiment blocks<br/>[registry.py]"]
  node_research["Research decisions<br/>[control.py]"]
end

subgraph group_control["Execution control"]
  node_application["Command service<br/>[service.py]"]
  node_planning["Plan and dry run<br/>[planner.py]"]
  node_authorization["Authorization gate<br/>[authorization.py]"]
  node_reviewed["Reviewed execution<br/>[native_reviewed.py]"]
  node_runs["Run control<br/>[control.py]"]
  node_workerplane["Worker control plane<br/>[plane.py]"]
end

subgraph group_records["Facts and evidence"]
  node_events["Event catalog<br/>[catalog.py]"]
  node_eventstore[("Append-only event store<br/>[store.py]")]
  node_projections["Replay projections<br/>[replay.py]"]
  node_artifacts[("Content-addressed artifacts<br/>[store.py]")]
  node_evidence["Evidence import<br/>[control.py]"]
end

subgraph group_integrations["Compute and analysis"]
  node_workerclient["Worker client<br/>[client.py]"]
  node_runtime["Execution runtimes<br/>[kernel.py]"]
  node_training["Training adapters<br/>[ms_swift.py]"]
  node_providers["Model providers<br/>[control.py]"]
  node_report["Metrics and reports<br/>[render.py]"]
end

node_researcher(("Researcher"))
node_ai(("AI adviser"))
node_cli["Research CLI<br/>[parser.py]"]
node_worker(("Remote Worker"))

node_researcher -->|"submits commands"| node_cli
node_ai -.->|"proposes or contests"| node_research
node_cli -->|"dispatches commands"| node_application
node_cli -->|"validates documents"| node_spec
node_application -->|"records facts"| node_eventstore
node_application -->|"executes run commands"| node_runs
node_application -->|"loads manifests"| node_blocks
node_spec -->|"supplies experiment"| node_planning
node_blocks -->|"supplies block registry"| node_planning
node_planning -->|"plans actions"| node_authorization
node_authorization -->|"records decisions"| node_eventstore
node_reviewed -->|"verifies authorization facts"| node_eventstore
node_reviewed -->|"verifies execution material"| node_artifacts
node_runs -->|"records run facts"| node_eventstore
node_workerplane -->|"records Worker facts"| node_eventstore
node_workerplane -->|"serves artifacts"| node_artifacts
node_workerclient -->|"polls and reports"| node_workerplane
node_workerclient -->|"uploads artifacts"| node_artifacts
node_worker -->|"runs client"| node_workerclient
node_runs -->|"dispatches execution"| node_runtime
node_runtime -.->|"uses training backend"| node_training
node_eventstore -->|"replays facts"| node_projections
node_evidence -->|"stores evidence"| node_artifacts
node_evidence -->|"records imports"| node_eventstore
node_eventstore -->|"supplies run facts"| node_report
node_artifacts -->|"supplies result material"| node_report
node_providers -.->|"enables model calls"| node_ai
node_research -->|"records decisions"| node_eventstore

click node_cli "https://github.com/victorzhong0110/llm-research-os/blob/main/src/llm_research_os/cli/parser.py"
click node_application "https://github.com/victorzhong0110/llm-research-os/blob/main/src/llm_research_os/application/service.py"
click node_spec "https://github.com/victorzhong0110/llm-research-os/blob/main/src/llm_research_os/spec/io.py"
click node_blocks "https://github.com/victorzhong0110/llm-research-os/blob/main/src/llm_research_os/blocks/registry.py"
click node_research "https://github.com/victorzhong0110/llm-research-os/blob/main/src/llm_research_os/research/control.py"
click node_planning "https://github.com/victorzhong0110/llm-research-os/blob/main/src/llm_research_os/execution/planner.py"
click node_authorization "https://github.com/victorzhong0110/llm-research-os/blob/main/src/llm_research_os/execution/authorization.py"
click node_reviewed "https://github.com/victorzhong0110/llm-research-os/blob/main/src/llm_research_os/execution/native_reviewed.py"
click node_runs "https://github.com/victorzhong0110/llm-research-os/blob/main/src/llm_research_os/runs/control.py"
click node_workerplane "https://github.com/victorzhong0110/llm-research-os/blob/main/src/llm_research_os/workers/plane.py"
click node_workerclient "https://github.com/victorzhong0110/llm-research-os/blob/main/src/llm_research_os/workers/client.py"
click node_runtime "https://github.com/victorzhong0110/llm-research-os/blob/main/src/llm_research_os/execution/kernel.py"
click node_training "https://github.com/victorzhong0110/llm-research-os/blob/main/src/llm_research_os/training/ms_swift.py"
click node_providers "https://github.com/victorzhong0110/llm-research-os/blob/main/src/llm_research_os/providers/control.py"
click node_events "https://github.com/victorzhong0110/llm-research-os/blob/main/src/llm_research_os/events/catalog.py"
click node_eventstore "https://github.com/victorzhong0110/llm-research-os/blob/main/src/llm_research_os/storage/store.py"
click node_projections "https://github.com/victorzhong0110/llm-research-os/blob/main/src/llm_research_os/projections/replay.py"
click node_artifacts "https://github.com/victorzhong0110/llm-research-os/blob/main/src/llm_research_os/artifacts/store.py"
click node_evidence "https://github.com/victorzhong0110/llm-research-os/blob/main/src/llm_research_os/evidence/control.py"
click node_report "https://github.com/victorzhong0110/llm-research-os/blob/main/src/llm_research_os/report/render.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_spec,node_blocks,node_research toneBlue
class node_application,node_planning,node_authorization,node_reviewed,node_runs,node_workerplane toneAmber
class node_events,node_eventstore,node_projections,node_artifacts,node_evidence toneMint
class node_workerclient,node_runtime,node_training,node_providers,node_report,node_worker toneRose
class node_researcher,node_ai toneIndigo
class node_cli toneTeal
```

## Components

### Research authoring

- [Research specification](https://github.com/victorzhong0110/llm-research-os/blob/main/src/llm_research_os/spec/io.py): `src/llm_research_os/spec/io.py`
- [Experiment blocks](https://github.com/victorzhong0110/llm-research-os/blob/main/src/llm_research_os/blocks/registry.py): `src/llm_research_os/blocks/registry.py`
- [Research decisions](https://github.com/victorzhong0110/llm-research-os/blob/main/src/llm_research_os/research/control.py): `src/llm_research_os/research/control.py`

### Execution control

- [Command service](https://github.com/victorzhong0110/llm-research-os/blob/main/src/llm_research_os/application/service.py): `src/llm_research_os/application/service.py`
- [Plan and dry run](https://github.com/victorzhong0110/llm-research-os/blob/main/src/llm_research_os/execution/planner.py): `src/llm_research_os/execution/planner.py`
- [Authorization gate](https://github.com/victorzhong0110/llm-research-os/blob/main/src/llm_research_os/execution/authorization.py): `src/llm_research_os/execution/authorization.py`
- [Reviewed execution](https://github.com/victorzhong0110/llm-research-os/blob/main/src/llm_research_os/execution/native_reviewed.py): `src/llm_research_os/execution/native_reviewed.py`
- [Run control](https://github.com/victorzhong0110/llm-research-os/blob/main/src/llm_research_os/runs/control.py): `src/llm_research_os/runs/control.py`
- [Worker control plane](https://github.com/victorzhong0110/llm-research-os/blob/main/src/llm_research_os/workers/plane.py): `src/llm_research_os/workers/plane.py`

### Facts and evidence

- [Event catalog](https://github.com/victorzhong0110/llm-research-os/blob/main/src/llm_research_os/events/catalog.py): `src/llm_research_os/events/catalog.py`
- [Append-only event store](https://github.com/victorzhong0110/llm-research-os/blob/main/src/llm_research_os/storage/store.py): `src/llm_research_os/storage/store.py`
- [Replay projections](https://github.com/victorzhong0110/llm-research-os/blob/main/src/llm_research_os/projections/replay.py): `src/llm_research_os/projections/replay.py`
- [Content-addressed artifacts](https://github.com/victorzhong0110/llm-research-os/blob/main/src/llm_research_os/artifacts/store.py): `src/llm_research_os/artifacts/store.py`
- [Evidence import](https://github.com/victorzhong0110/llm-research-os/blob/main/src/llm_research_os/evidence/control.py): `src/llm_research_os/evidence/control.py`

### Compute and analysis

- [Worker client](https://github.com/victorzhong0110/llm-research-os/blob/main/src/llm_research_os/workers/client.py): `src/llm_research_os/workers/client.py`
- [Execution runtimes](https://github.com/victorzhong0110/llm-research-os/blob/main/src/llm_research_os/execution/kernel.py): `src/llm_research_os/execution/kernel.py`
- [Training adapters](https://github.com/victorzhong0110/llm-research-os/blob/main/src/llm_research_os/training/ms_swift.py): `src/llm_research_os/training/ms_swift.py`
- [Model providers](https://github.com/victorzhong0110/llm-research-os/blob/main/src/llm_research_os/providers/control.py): `src/llm_research_os/providers/control.py`
- [Metrics and reports](https://github.com/victorzhong0110/llm-research-os/blob/main/src/llm_research_os/report/render.py): `src/llm_research_os/report/render.py`

### Other components

- **Researcher**
- **AI adviser**
- [Research CLI](https://github.com/victorzhong0110/llm-research-os/blob/main/src/llm_research_os/cli/parser.py): `src/llm_research_os/cli/parser.py`
- **Remote Worker**

## Connections

- Researcher → Research CLI: submits commands
- AI adviser → Research decisions: proposes or contests
- Research CLI → Command service: dispatches commands
- Research CLI → Research specification: validates documents
- Command service → Append-only event store: records facts
- Command service → Run control: executes run commands
- Command service → Experiment blocks: loads manifests
- Research specification → Plan and dry run: supplies experiment
- Experiment blocks → Plan and dry run: supplies block registry
- Plan and dry run → Authorization gate: plans actions
- Authorization gate → Append-only event store: records decisions
- Reviewed execution → Append-only event store: verifies authorization facts
- Reviewed execution → Content-addressed artifacts: verifies execution material
- Run control → Append-only event store: records run facts
- Worker control plane → Append-only event store: records Worker facts
- Worker control plane → Content-addressed artifacts: serves artifacts
- Worker client → Worker control plane: polls and reports
- Worker client → Content-addressed artifacts: uploads artifacts
- Remote Worker → Worker client: runs client
- Run control → Execution runtimes: dispatches execution
- Execution runtimes → Training adapters: uses training backend
- Append-only event store → Replay projections: replays facts
- Evidence import → Content-addressed artifacts: stores evidence
- Evidence import → Append-only event store: records imports
- Append-only event store → Metrics and reports: supplies run facts
- Content-addressed artifacts → Metrics and reports: supplies result material
- Model providers → AI adviser: enables model calls
- Research decisions → Append-only event store: records decisions