# yuyangsunshine/bioproagent architecture

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

- Interactive diagram: https://gitdiagram.com/yuyangsunshine/bioproagent
- Repository: https://github.com/yuyangsunshine/bioproagent

## Overview

#### Purpose and entry points
BioProAgent is an API-first, neuro-symbolic agent for constrained biological protocol planning. It couples LLM reasoning with a deterministic Design–Verify–Rectify FSM to produce automation-aligned machine instructions safely.

- Interactive CLI: `main.py`
- Reusable/evaluation runtime and `ProAgent`: `main_evaluate.py`
- Runtime settings and model credentials: `config/settings.py`, `data/keys.env`

#### Agent runtime and session boundary
`ProAgent` owns the request lifecycle: create/update session state, receive a scientific query, invoke planned tools, retain working/episodic artifacts, and return a response. Session state supports symbolic references such as drafts and retrieved knowledge instead of repeatedly embedding large payloads.

- `main_evaluate.py`
- `src/tools/tool_definitions.py`
- `src/tools/tool_descriptions.json`

#### Deterministic planner/FSM
The planner transfer matrix is the central control boundary around probabilistic LLM output. It infers the current FSM state and produces an allowed tool plan, enforcing ordered Design, Verify, and Rectify transitions rather than unconstrained agent actions.

- `src/core/planner_transfer_matrix.py`
- `src/prompts/planner.py`
- `src/prompts/prompts.py`

#### LLM and memory integration
LLM calls are external API-backed rather than local checkpoints. The LLM layer initializes configured model roles (fast, general, quality, long-context) and the long-memory backend interface. Model endpoint names, keys, and URLs come from environment-backed settings.

- `src/core/llms.py`
- `config/settings.py`
- `data/keys.env.example`

#### Design-stage capabilities
Design tools clarify experimental scope, retrieve relevant knowledge, produce a scientific draft, and reflect or modify it. Retrieval is an explicitly replaceable public shell, allowing private lab knowledge connectors or embedding endpoints without changing the FSM-facing tool contract.

- `src/capabilities/retrieval/knowledge_sources.py`
- `src/baselines/base_agent.py`
- `src/baselines/react_agent.py`

#### Automation grounding and registries
Automation modules transform a validated scientific draft into parameterized machine code. Registry abstractions resolve instruments and consumables from canonical data, forming the symbolic grounding boundary between natural-language plans and lab-specific resources.

- `src/capabilities/automation/parameter_builder.py`
- `src/capabilities/automation/parameter_filler.py`
- `src/capabilities/registry/device_registry.py`
- `data/registry/instruments_en.json`
- `data/registry/consumables_en.json`

#### Verification and repair loop
Verification separates scientific review from physical/code checks. Failed reviews return control to draft or code repair; only passing machine-code validation completes the execution-oriented planning flow. The public physical-rule implementation is intentionally a replaceable shell.

- `src/capabilities/verification/engine.py`
- `src/capabilities/automation/parameter_processing.py`
- `src/tools/tool_definitions.py`

#### Benchmark evaluation
Public evaluation drives the same `ProAgent` loop over four BioProBench-derived subsets. Profiles configure thresholds, sample limits, simulator/scientific-evaluation flags, and result behavior; benchmark JSON files supply task instances.

- `config/evaluation_profiles.json`
- `tests/eval_config.py`
- `data/benchmarks/ProAgent-SubsetA.json`
- `data/benchmarks/ProAgent-SubsetB.json`

Main entry points: [`src/tools/tool_definitions.py`](https://github.com/yuyangsunshine/bioproagent/blob/main/src/tools/tool_definitions.py) (Tool contract), [`main_evaluate.py`](https://github.com/yuyangsunshine/bioproagent/blob/main/main_evaluate.py) (ProAgent runtime), [`src/core/planner_transfer_matrix.py`](https://github.com/yuyangsunshine/bioproagent/blob/main/src/core/planner_transfer_matrix.py) (Planner transfer matrix), [`tests/eval_config.py`](https://github.com/yuyangsunshine/bioproagent/blob/main/tests/eval_config.py) (Evaluation runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_cli["Interactive CLI<br/>entry point<br/>[main.py]"]
  node_proagent["ProAgent runtime<br/>agent lifecycle<br/>[main_evaluate.py]"]
  node_tool_contract["Tool contract<br/>tool interface"]
  node_tool_descriptions["Tool descriptions<br/>tool metadata"]
  node_llm_layer{{"LLM and memory layer<br/>external model adapter<br/>[llms.py]"}}
end

subgraph group_control["Planning Control"]
  node_planner{{"Planner transfer matrix<br/>deterministic FSM"}}
  node_planner_prompt["Planner prompts<br/>prompt layer<br/>[planner.py]"]
end

subgraph group_capabilities["Protocol Capabilities"]
  node_retrieval["Knowledge retrieval shell<br/>replaceable retrieval interface"]
  node_design_agents["Design baselines<br/>agent implementations<br/>[base_agent.py]"]
  node_parameter_builder["Parameter builder<br/>automation compiler"]
  node_parameter_filler["Parameter filler<br/>automation compiler"]
  node_registry[("Device registry<br/>resource resolver<br/>[device_registry.py]")]
  node_verification{{"Verification engine<br/>review and validation<br/>[engine.py]"}}
  node_parameter_processing["Physical-rule shell<br/>replaceable validator"]
end

subgraph group_resources["External Resources"]
  node_settings["Runtime settings<br/>configuration<br/>[settings.py]"]
  node_instruments[("Instrument catalog<br/>registry data")]
  node_consumables[("Consumable catalog<br/>registry data")]
end

subgraph group_evaluation["Benchmark Evaluation"]
  node_eval_profiles["Evaluation profiles<br/>benchmark configuration"]
  node_eval_runner["Evaluation runner<br/>benchmark runtime<br/>[eval_config.py]"]
  node_benchmark_a["BioProBench Subset A<br/>benchmark tasks"]
  node_benchmark_b["BioProBench Subset B<br/>benchmark tasks"]
end

node_cli -->|"starts session"| node_proagent
node_proagent -->|"requests allowed plan"| node_planner
node_proagent -->|"invokes tools"| node_tool_contract
node_tool_descriptions -.->|"documents"| node_tool_contract
node_planner_prompt -->|"guides inference"| node_planner
node_planner -->|"uses constrained reasoning"| node_llm_layer
node_settings -->|"configures"| node_llm_layer
node_tool_contract -->|"design retrieval"| node_retrieval
node_tool_contract -->|"draft and reflect"| node_design_agents
node_tool_contract -->|"compile validated draft"| node_parameter_builder
node_parameter_builder -->|"fill machine parameters"| node_parameter_filler
node_parameter_filler -->|"resolve resources"| node_registry
node_instruments -->|"canonical instruments"| node_registry
node_consumables -->|"canonical consumables"| node_registry
node_tool_contract -->|"review and validate"| node_verification
node_verification -->|"physical/code checks"| node_parameter_processing
node_verification -.->|"failure triggers rectify"| node_planner
node_eval_runner -->|"drives agent loop"| node_proagent
node_eval_profiles -->|"configures"| node_eval_runner
node_benchmark_a -->|"task instances"| node_eval_runner
node_benchmark_b -->|"task instances"| node_eval_runner

click node_cli "https://github.com/yuyangsunshine/bioproagent/blob/main/main.py"
click node_proagent "https://github.com/yuyangsunshine/bioproagent/blob/main/main_evaluate.py"
click node_tool_contract "https://github.com/yuyangsunshine/bioproagent/blob/main/src/tools/tool_definitions.py"
click node_tool_descriptions "https://github.com/yuyangsunshine/bioproagent/blob/main/src/tools/tool_descriptions.json"
click node_settings "https://github.com/yuyangsunshine/bioproagent/blob/main/config/settings.py"
click node_llm_layer "https://github.com/yuyangsunshine/bioproagent/blob/main/src/core/llms.py"
click node_planner "https://github.com/yuyangsunshine/bioproagent/blob/main/src/core/planner_transfer_matrix.py"
click node_planner_prompt "https://github.com/yuyangsunshine/bioproagent/blob/main/src/prompts/planner.py"
click node_retrieval "https://github.com/yuyangsunshine/bioproagent/blob/main/src/capabilities/retrieval/knowledge_sources.py"
click node_design_agents "https://github.com/yuyangsunshine/bioproagent/blob/main/src/baselines/base_agent.py"
click node_parameter_builder "https://github.com/yuyangsunshine/bioproagent/blob/main/src/capabilities/automation/parameter_builder.py"
click node_parameter_filler "https://github.com/yuyangsunshine/bioproagent/blob/main/src/capabilities/automation/parameter_filler.py"
click node_registry "https://github.com/yuyangsunshine/bioproagent/blob/main/src/capabilities/registry/device_registry.py"
click node_instruments "https://github.com/yuyangsunshine/bioproagent/blob/main/data/registry/instruments_en.json"
click node_consumables "https://github.com/yuyangsunshine/bioproagent/blob/main/data/registry/consumables_en.json"
click node_verification "https://github.com/yuyangsunshine/bioproagent/blob/main/src/capabilities/verification/engine.py"
click node_parameter_processing "https://github.com/yuyangsunshine/bioproagent/blob/main/src/capabilities/automation/parameter_processing.py"
click node_eval_profiles "https://github.com/yuyangsunshine/bioproagent/blob/main/config/evaluation_profiles.json"
click node_eval_runner "https://github.com/yuyangsunshine/bioproagent/blob/main/tests/eval_config.py"
click node_benchmark_a "https://github.com/yuyangsunshine/bioproagent/blob/main/data/benchmarks/ProAgent-SubsetA.json"
click node_benchmark_b "https://github.com/yuyangsunshine/bioproagent/blob/main/data/benchmarks/ProAgent-SubsetB.json"

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_cli,node_proagent,node_tool_contract,node_tool_descriptions,node_llm_layer toneBlue
class node_planner,node_planner_prompt toneAmber
class node_retrieval,node_design_agents,node_parameter_builder,node_parameter_filler,node_registry,node_verification,node_parameter_processing toneMint
class node_settings,node_instruments,node_consumables toneRose
class node_eval_profiles,node_eval_runner,node_benchmark_a,node_benchmark_b toneIndigo
```

## Components

### Runtime

- [Interactive CLI](https://github.com/yuyangsunshine/bioproagent/blob/main/main.py): entry point · `main.py`
- [ProAgent runtime](https://github.com/yuyangsunshine/bioproagent/blob/main/main_evaluate.py): agent lifecycle · Owns sessions, artifacts, tool calls, and responses. · `main_evaluate.py`
- [Tool contract](https://github.com/yuyangsunshine/bioproagent/blob/main/src/tools/tool_definitions.py): tool interface · `src/tools/tool_definitions.py`
- [Tool descriptions](https://github.com/yuyangsunshine/bioproagent/blob/main/src/tools/tool_descriptions.json): tool metadata · `src/tools/tool_descriptions.json`
- [LLM and memory layer](https://github.com/yuyangsunshine/bioproagent/blob/main/src/core/llms.py): external model adapter · Initializes API-backed model roles and long-memory backend. · `src/core/llms.py`

### Planning Control

- [Planner transfer matrix](https://github.com/yuyangsunshine/bioproagent/blob/main/src/core/planner_transfer_matrix.py): deterministic FSM · Constrains LLM output to ordered Design, Verify, and Rectify tool plans. · `src/core/planner_transfer_matrix.py`
- [Planner prompts](https://github.com/yuyangsunshine/bioproagent/blob/main/src/prompts/planner.py): prompt layer · `src/prompts/planner.py`

### Protocol Capabilities

- [Knowledge retrieval shell](https://github.com/yuyangsunshine/bioproagent/blob/main/src/capabilities/retrieval/knowledge_sources.py): replaceable retrieval interface · Supports private knowledge connectors without changing tool contracts. · `src/capabilities/retrieval/knowledge_sources.py`
- [Design baselines](https://github.com/yuyangsunshine/bioproagent/blob/main/src/baselines/base_agent.py): agent implementations · Provide scientific drafting, reflection, and modification patterns. · `src/baselines/base_agent.py`
- [Parameter builder](https://github.com/yuyangsunshine/bioproagent/blob/main/src/capabilities/automation/parameter_builder.py): automation compiler · Transforms validated scientific drafts into parameterized machine code. · `src/capabilities/automation/parameter_builder.py`
- [Parameter filler](https://github.com/yuyangsunshine/bioproagent/blob/main/src/capabilities/automation/parameter_filler.py): automation compiler · `src/capabilities/automation/parameter_filler.py`
- [Device registry](https://github.com/yuyangsunshine/bioproagent/blob/main/src/capabilities/registry/device_registry.py): resource resolver · Grounds plans against canonical instrument and consumable data. · `src/capabilities/registry/device_registry.py`
- [Verification engine](https://github.com/yuyangsunshine/bioproagent/blob/main/src/capabilities/verification/engine.py): review and validation · Separates scientific review from physical and machine-code checks. · `src/capabilities/verification/engine.py`
- [Physical-rule shell](https://github.com/yuyangsunshine/bioproagent/blob/main/src/capabilities/automation/parameter_processing.py): replaceable validator · `src/capabilities/automation/parameter_processing.py`

### External Resources

- [Runtime settings](https://github.com/yuyangsunshine/bioproagent/blob/main/config/settings.py): configuration · Environment-backed model roles, endpoints, and credentials. · `config/settings.py`
- [Instrument catalog](https://github.com/yuyangsunshine/bioproagent/blob/main/data/registry/instruments_en.json): registry data · `data/registry/instruments_en.json`
- [Consumable catalog](https://github.com/yuyangsunshine/bioproagent/blob/main/data/registry/consumables_en.json): registry data · `data/registry/consumables_en.json`

### Benchmark Evaluation

- [Evaluation profiles](https://github.com/yuyangsunshine/bioproagent/blob/main/config/evaluation_profiles.json): benchmark configuration · `config/evaluation_profiles.json`
- [Evaluation runner](https://github.com/yuyangsunshine/bioproagent/blob/main/tests/eval_config.py): benchmark runtime · Runs the same ProAgent loop with subset-specific thresholds and flags. · `tests/eval_config.py`
- [BioProBench Subset A](https://github.com/yuyangsunshine/bioproagent/blob/main/data/benchmarks/ProAgent-SubsetA.json): benchmark tasks · `data/benchmarks/ProAgent-SubsetA.json`
- [BioProBench Subset B](https://github.com/yuyangsunshine/bioproagent/blob/main/data/benchmarks/ProAgent-SubsetB.json): benchmark tasks · `data/benchmarks/ProAgent-SubsetB.json`

## Connections

- Interactive CLI → ProAgent runtime: starts session
- ProAgent runtime → Planner transfer matrix: requests allowed plan
- ProAgent runtime → Tool contract: invokes tools
- Tool descriptions → Tool contract: documents
- Planner prompts → Planner transfer matrix: guides inference
- Planner transfer matrix → LLM and memory layer: uses constrained reasoning
- Runtime settings → LLM and memory layer: configures
- Tool contract → Knowledge retrieval shell: design retrieval
- Tool contract → Design baselines: draft and reflect
- Tool contract → Parameter builder: compile validated draft
- Parameter builder → Parameter filler: fill machine parameters
- Parameter filler → Device registry: resolve resources
- Instrument catalog → Device registry: canonical instruments
- Consumable catalog → Device registry: canonical consumables
- Tool contract → Verification engine: review and validate
- Verification engine → Physical-rule shell: physical/code checks
- Verification engine → Planner transfer matrix: failure triggers rectify
- Evaluation runner → ProAgent runtime: drives agent loop
- Evaluation profiles → Evaluation runner: configures
- BioProBench Subset A → Evaluation runner: task instances
- BioProBench Subset B → Evaluation runner: task instances