gsmagent

An AI agent that assembles an SBML genome-scale metabolic model (GEM) from a microbial genome, with swappable model backbones, swappable reconstruction methods, a dual-track benchmark, and a tamper-evident lab book for provenance instead of a flat log file.

The design principle: the LLM is an orchestrator. It plans the reconstruction, chooses parameters, reads diagnostics, and reacts to failures — but every reaction, formula, flux, and quality number comes from deterministic tools (cobrapy, libSBML, MEMOTE). The model never invents biochemistry.

pip install -e .            # core (cobra, libsbml, numpy, pyyaml)
pip install -e ".[all]"     # + anthropic, openai, memote, pytest

Core runs fully offline using the built-in mock provider and mock backend, so you can try everything before wiring up an API key or CarveMe.

# Deterministic baseline (no LLM)
gsmagent reconstruct --genome data/genomes/toy.fna --organism "E. coli" \
    --out runs/ecoli --mode deterministic

# Agent, offline mock backbone
gsmagent reconstruct --genome data/genomes/toy.fna --organism "E. coli" \
    --out runs/ecoli --mode agent --provider mock

# Agent, real Claude backbone (needs: pip install anthropic; ANTHROPIC_API_KEY)
gsmagent reconstruct --genome genome.fna --organism "E. coli" \
    --out runs/ecoli --mode agent --provider anthropic --model claude-sonnet-5

# Dual-track benchmark across configs x organisms -> leaderboard.md
gsmagent benchmark --config configs/benchmark.yaml --out runs/bench

# Inspect / verify a lab book
gsmagent labbook runs/ecoli --verify

Add a provider or backend by writing one class and registering it in the respective __init__.py; it becomes selectable from config with no other change.

Every run writes an append-only, hash-chained lab notebook (labbook.jsonl + rendered labbook.md) recording the objective, materials (inputs, tool versions), each action and observation, and — crucially — every decision with its rationale and the alternatives considered. Because entries are chained by SHA-256, any later edit is detectable (gsmagent labbook <dir> --verify). The same book is produced by the deterministic pipeline and by any agent, so runs are directly comparable and replayable. See docs/ARCHITECTURE.md.

• Track A — model quality: MEMOTE (or a transparent proxy), reaction/ metabolite/gene overlap vs a reference model, and gene-essentiality agreement (MCC) vs experimental knockout data.
• Track B — agent performance: success rate, tokens/cost, tool calls, iterations, wall time, decision count, and lab-book integrity, plus a reproducibility (variance) helper across repeated runs.

The benchmark reloads the exported SBML and scores that artifact, so Track A measures what the model actually shipped.

gsmagent/
  labbook.py      tamper-evident lab notebook
  providers/      swappable LLM backbones (base, mock, anthropic, openai)
  backends/       swappable reconstruction methods (base, mock, carveme, modelseed)
  tools/          deterministic biochemistry (annotation, cobra_ops, quality, sbml_io)
  toolkit.py      shared execution core (used by both pipeline and agent)
  pipeline.py     deterministic Phase-0 baseline
  agent.py        LLM-orchestrated reconstruction loop
  eval/           Track A (reference, essentiality) + Track B (performance) + benchmark
  cli.py          reconstruct | benchmark | labbook

This is a working scaffold (Phase 0–1 of the roadmap in docs/ARCHITECTURE.md): the deterministic pipeline, the agent loop, the lab book, and the dual benchmark all run and are covered by tests (pytest). Real backends (CarveMe/ModelSEED) and real annotators (Prodigal/Bakta) are wired as optional external tools with clear errors when absent. The curation loop (Phase 2) and literature grounding (Phase 4) are the natural next steps.