yuyangsunshine/bioproagent

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