BioSymphony Ferm DoE gives scientists and AI agents tools to choose experiments, compare designs, analyze results, and plan the next batch. It combines design of experiments (DoE), optional optimization adapters, and a tool knowledge base that explains when to use each method.
Your agent reads the repository skill, selects a tool, calls the CLI or a Python adapter, and inspects the returned JSON or CSV before choosing the next call. A shared campaign_manifest.json carries the objective, factors, responses, and constraints across those calls.
| Task | Tools and knowledge included | Result |
|---|---|---|
| Choose an experimental design | Family recommendations, classical generators, and candidate comparison | Run settings, design diagnostics, and selection reasons |
| Use specialized optimizers | BoTorch, BoFire, ENTMOOT, OMLT, and TabPFN adapters | Candidate experiments with method and availability reports |
| Learn from supplied results | Regression, assay-power checks, and sequential planning | Effect estimates, follow-up candidates, and reasons to continue or pause |
| Compare process scales | Scale criteria, engineering calculations, and bridge checks | Declared transfer conditions and evidence gaps |
| Connect the work across sessions | Shared campaign files, result tables, and learning records | Inputs and decisions that another agent can reuse |
Outputs are plans for scientific review. Lab execution and experimental validation remain separate; see scope and limitations.
The tool registry and its machine-readable JSON describe 54 tools and research candidates. Entries record use cases, routing reasons, package requirements, source links, checked dates, and limitations. The adapter map gives the actual call surfaces.
| Read or run | What it tells your agent |
|---|---|
| Repository skill | How to frame the campaign and use the planning tools |
| Tool registry | Which tools fit the task and which are implemented, evaluation candidates, or watchlist entries |
| Adapter map | How to call each implemented adapter and interpret its output |
ferm-doe doctor |
Repository configuration and dependency availability |
| Design recipes | How factor types, constraints, and run budgets affect design choice |
The registry is a reference your agent reads. Tools marked evaluate_next or watch, including Docling, PaperQA2, and GOLLuM, are research candidates. Their presence does not install or connect them.
Chain calls through campaign files and inspect each result before continuing. Your agent controls the sequence; the tools return files it can read, compare, and reuse.
| Call | Read before the next call |
|---|---|
validate → recommend-family |
Input errors, proposed family, and its rationale |
generate-design |
Design CSV, method metadata, and factor bounds |
analyze --results … |
Effect estimates, uncertainty, and model diagnostics |
plan-wave2 --results … |
Recommendation, candidate rows, excluded results, and manifest patch |
analyze and plan-wave2 each read the supplied result CSV and campaign manifest. The analysis JSON helps your agent assess the plan; it is not a required planner input. The demo includes synthetic results, so you can try the chain without running a lab experiment.
git clone https://github.com/BioSymphony/ferm-doe.git
cd ferm-doe
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e .
ferm-doe doctorThe base package uses the Python standard library. Add scientific dependencies when you need their adapters; see Optional Extras.
Open the checkout in an agent that can read files and run commands. Paste:
Read skills/biosymphony-ferm-doe/SKILL.md, docs/tool-registry.json,
and docs/ADAPTER_MAP.md. Run ferm-doe doctor.
Use examples/demo-pb-screening-public and write outputs under /tmp/demo-pb.
Validate the inputs, explain the design-family recommendation, and generate
a design. Analyze the bundled synthetic results, then plan a follow-up batch
with a remaining run budget of 3. Inspect each output before the next call.
Explain which tools ran, why they fit, what the results support, and which
inputs need attention. Keep the fixtures unchanged and all outputs local.
The same tool chain runs in a shell:
ferm-doe validate examples/demo-pb-screening-public --summary
ferm-doe recommend-family examples/demo-pb-screening-public
ferm-doe generate-design examples/demo-pb-screening-public \
--out /tmp/demo-pb/wave1_design.csv \
--metadata-out /tmp/demo-pb/wave1_design.metadata.json --seed 0
ferm-doe analyze examples/demo-pb-screening-public \
--results examples/demo-pb-screening-public/inputs/wave1_results.csv \
--out /tmp/demo-pb/wave1_analysis.json --seed 0
ferm-doe plan-wave2 examples/demo-pb-screening-public \
--results examples/demo-pb-screening-public/inputs/wave1_results.csv \
--out-dir /tmp/demo-pb/wave2 --remaining-budget 3Validation returns error_count: 0 and status: YELLOW for this synthetic demo. Inspect wave2/wave2_recommendation.json for the next action and wave2/augment_design.csv for candidate runs. Resolve blocking errors before generating a design.
| Need | Callable route | Key condition |
|---|---|---|
| Classical screening, response surfaces, or mixtures | generate-design |
Choose the family in the manifest; inspect method labels |
| Compare candidate designs | engine compare-designs |
Review feasibility, model diagnostics, and selection reasons |
| Gaussian-process Bayesian candidates | plan-wave2 --backend botorch |
Numeric factors, prepared results, and the botorch extra |
| Constrained or multi-fidelity candidates | BoFire Python adapter | Translate supported constraints and inspect the route report |
| Cardinality constraints, such as choosing at most three components | ENTMOOT or OMLT Python adapter | Compatible solver and supported constraint forms |
| Foundation-model surrogate candidates | TabPFN Python adapter | Optional dependencies and model access |
| Sensitivity analysis | SALib Python adapter | Inputs appropriate for the selected sensitivity method |
The adapter map links the Python entry points. BoFire, ENTMOOT, OMLT, and TabPFN are callable modules; the public follow-up CLI does not dispatch them automatically. The BoTorch CLI emits a separate candidate report; its walkthrough explains preparation and outputs.
Install only the adapters you plan to call, for example:
python -m pip install -e '.[bofire]'| Extra | Adds |
|---|---|
botorch |
Gaussian-process models and acquisition functions |
bofire |
Constrained and multi-fidelity candidate generation |
entmoot, omlt |
Solver-backed surrogate optimization |
tabpfn |
Foundation-model surrogate; model access required |
scipy, pydoe3 |
Additional statistics and classical design methods |
sensitivity |
SALib sensitivity analysis |
report, contracts |
Plotly reports and Frictionless table checks |
Availability and execution are separate. Inspect the returned adapter status, candidate count, and issues; a package can be installed without running on a particular call. The supported BoFire adapter has a documented Bayesian NChooseK limit; see ENTMOOT and OMLT guidance.
| Try | What you learn |
|---|---|
| Screening walkthrough | Connect design, result analysis, and follow-up planning |
| Constrained media design | Call BoFire on synthetic constraint examples |
| Cardinality constraints | Evaluate the ENTMOOT adapter |
| Multi-arm campaign | Keep designs and results scoped to each campaign arm |
| Scale bridge | Compare declared source and target conditions |
| Custom design | Inspect candidate comparisons and design diagnostics |
See the use-case guide for other starting points. Examples use synthetic data or documented public sources. Keep your own campaign inputs in a separate workspace.
Use any agent that can read files and call the CLI or Python. Your harness owns model calls and task dispatch. For parallel work, task contracts and issue packs define inputs, outputs, and dependencies. Linear and OpenAI Symphony are optional orchestration choices; see harness configurations and workflows.
| Topic | Read |
|---|---|
| Tools and methods | Registry, adapter map, capability index |
| Commands and examples | CLI reference, agent quickstart |
| Visual guides | Tool use and workflow, Mermaid workflow |
| Planning details | Design recipes, scale criteria, cost estimates |
| Continuing a campaign | Learning records, task contracts |
| Sharing work | Security model, release checklist |
The documentation map includes reporting, deployment, and extended workflow references.
Pre-alpha (0.1.0a0). Review method labels, constraint coverage, and data quality before using candidate experiments. See scope and limitations.
See Contributing. Run make release-check for tests, example validation, and release checks. Before public sharing, make public-ready also scans the history and working tree for secrets.
MIT.