Shuangyin/formulation-agent

FormulationAgent


🌐 Languages: English · 中文 · Live demo

What is FormulationAgent?

FormulationAgent is a bounded ReAct agent that automates PLGA nanoparticle formulation design. Given a target drug and delivery goal, it searches academic literature, retrieves analogous formulations from a curated database, generates candidate recipes, scores them with a trained predictor (NanoPFN V2), and — when a candidate fails the size constraint — runs a bounded ReAct repair loop that iteratively adjusts the formulation until it meets the target. Every recommendation is evidence-grounded and fully traceable.

Problem

Designing PLGA nanoparticle formulations today is manual and slow: researchers search literature, extract scattered formulation parameters from papers, mentally adapt published protocols to new drugs, and iterate through trial-and-error experiments. No existing tool integrates literature retrieval, formulation knowledge, and predictive modeling into a single auditable workflow.

How it works

Drug + Goal ─→ Scope Gate ─→ Gather Evidence ─→ Generate Candidates ─→ Predict ─→ Repair Loop ─→ Confidence Gate ─→ Ranked Candidates + Trace
                                   │                                                    │
                                   ▼                                                    ▼
                            RAG Sub-pipeline                                  ReAct: THINK (LLM) → ACT (policy) → OBSERVE (predict)
   Search → Dedup → Relevance → Fulltext → Extract → Tier                    iterate levers until size constraint met
  (Europe PMC)              (PMC OA)    (Regex+LLM)  (exact_match/same_drug/analogue/llm_generated/none)

1. 1.Input — Drug name (or SMILES), molecular properties (MW, logP, pKa, solubility), delivery goal, and optional constraints (target size, minimum EE%).
2. 2.Scope gate — A two-tier filter rejects drugs unsuitable for PLGA nanoprecipitation: Tier 1 (hard physicochemical rules: very hydrophilic or macromolecular) and Tier 2 (out-of-distribution with no supporting evidence), each suggesting an alternative method.
3. 3.Evidence gathering — Queries Europe PMC for PLGA nanoparticle literature, deduplicates by DOI/PMID, fetches PMC Open Access fulltext, extracts formulation parameters via regex (with optional LLM gap-fill), and assigns evidence tiers (exactmatch / samedrug / analogue / llm_generated / none). Also retrieves matching recipes from the canonical 416-record PLGA database (Goren et al. 2025, zinc-protoporphyrin excluded); if no direct evidence exists, expands to the nearest structural analogue by MW + logP.
4. 4.Candidate generation — Builds candidate recipes deterministically from database + literature evidence, optionally supplemented by LLM-proposed recipes when evidence is thin.
5. 5.ML prediction — Each candidate is scored by NanoPFN V2, a 30-feature predictor in which each ensemble member is a bi-cascade of 5 TabPFN regressors (PS → LC/EE in parallel → EE/LC conditioned, then averaged). Features add HSP solubility distance and one-hot solvent encoding on top of the base descriptors. It predicts particle size (nm), encapsulation efficiency (%), and drug loading (%), and bounds LC to the physical mass-balance maximum.
6. 6.Bounded ReAct repair loop — If the top candidate violates the size constraint, the agent iteratively repairs it. Each round: an LLM THINKS (picks one of 7 formulation levers — polymer MW, LA:GA ratio, drug:polymer ratio, surfactant concentration, aqueous:organic ratio, pH, solvent — and an exact value), a deterministic policy validates/clips the choice (and serves as a no-LLM fallback), and NanoPFN V2 OBSERVES the new prediction. A gap-proportional tolerance permits small EE/LC trade-offs to meet a large size violation; once size is satisfied, slack rounds optimize EE/LC. The loop is bounded (default 5 rounds) and never retries an exhausted lever/value.
7. 7.Confidence gating & decision — A 4-factor confidence score (evidence quality, case fit, applicability-domain coverage via Mahalanobis distance, candidate agreement) drives a recommend / recommend-with-caution / no-recommendation decision.
8. 8.Output — Ranked candidates with full step-by-step reasoning trace, literature provenance (DOI links), and reproducibility metadata.

Key capabilities

Evaluated on

• —Predictor accuracy on 416 PLGA formulations / 64 drugs (NanoPFN V2 30D): avg R² = 0.809 under random splits, exceeding 14D raw-descriptor baselines (TabPFN-14D, XGBoost, Random Forest, Ridge).
• —Generalization under leave-one-drug-out (64 folds): reliable in-domain but dropping off for structurally unseen drugs — the empirical basis for scope-gated, confidence-aware recommendations.
• —Repair loop on 60 drugs (paired): LLM-guided ReAct repair meets the size constraint for 41/60 (68%) of drugs vs. 35/60 (58%) for a rule-based policy (McNemar exact p = 0.031). An ablation shows the advantage comes mainly from better lever selection (gap-tolerance ablation costs 8 drugs; per-value retry costs 1).

Research use only. Outputs are computational hypotheses, not regulatory submissions. All recommendations must be experimentally validated before any in vivo or clinical use.

Repository overview

This workspace now contains:

• —curated local PLGA historical records under data/processed/
• —the Python agent package under src/formulation_agent/
• —example benchmark cases under examples/cases/
• —the React + FastAPI web app under web_app_v1/

Key Roots

• —data/: datasets and provenance
• —models/: checkpoints and model registry files
• —configs/: benchmark, model, and app configuration
• —src/: core Python package (formulation_agent, incl. the benchmark harness)
• —scripts/: experiment and reporting scripts
• —results/: committed experiment outputs (current 30D system)
• —web_app_v1/: frontend and backend app layer

The agent package lives in src/formulation_agent/; the web app in web_app_v1/.

Core Components

• —DrugCase, FormulationCandidate, LiteratureEvidence, HistoricalRecord, and ReasoningStep contracts
• —structured PLGA database retrieval over the curated 416-record corpus + nearest-analogue expansion (MW + logP)
• —Europe PMC literature retrieval with an evidence-tier system (exactmatch / samedrug / analogue / llm_generated / none)
• —NanoPFNV2Predictor — bi-cascade of 5 TabPFN regressors over 30 engineered features, predicting size / EE / LC
• —two-tier scope gate (physicochemical hard rules + applicability-domain check)
• —bounded ReAct repair loop (7 levers, LLM-guided with deterministic policy fallback)
• —FormulationAgent orchestrating the full pipeline with a structured reasoning trace
• —benchmark harness for case replay, ablation runs, and leave-one-drug-out studies
• —CLI entrypoints for single-case runs and benchmark execution

Quick Start

CLI

Run the agent on a single case file:

python -m formulation_agent run examples/cases/replay/paclitaxel_case.json \
  --output results/cases/paclitaxel_recommendation.json

Run from a natural-language query (English or Chinese):

python -m formulation_agent run \
  --query "Design PLGA nanoparticles for paclitaxel, size < 200 nm, prefer nanoprecipitation, give 3 candidates."

Natural-language drug-property resolution retries transient PubChem 503 PUGREST.ServerBusy responses and caches successful lookups under data/cache/pubchem_properties.json, so repeated queries for the same drug reuse the cached structured resolution.

Run the benchmark suite (replay, ablation, llm-comparison, or all):

python -m formulation_agent benchmark --mode replay \
  --output-dir results/benchmarks

Web UI

Development mode (frontend on :5173 proxying /api to the backend on :8000):

# terminal 1 — frontend
cd web_app_v1/frontend && npm install && npm run dev

# terminal 2 — backend
uvicorn web_app_v1.backend.main:app --reload

Single-process production build (frontend built then served by the backend):

./scripts/serve_web.sh          # or: HOST=0.0.0.0 PORT=8000 ./scripts/serve_web.sh

A hosted demo is available at https://Shuangyin-formulation-agent.hf.space.

Current Benchmark Outputs

The benchmark suite now exports three complementary views:

• —case_replay: literature-style retrospective case reconstruction
• —ablation: tool-availability arms (database_only, literature_only, predictor_only, all_tools)
• —leave_one_drug_out: a small quantitative study comparing formulation_agent against nearest_neighbor and heuristic_search

Committed result files for the current 30D system live under results/main_30d/. The three paper figures are regenerated from that directory via python scripts/make_figures.py. results/overnight_2026_05_25/ holds a supplementary ablation grid (documented by its SUMMARY.md); it is not a figure input.

Configuration & Integrations

The model is configured by one file; the LLM and live-literature integrations are configured through environment variables.

• —configs/model/nanopfn_v2.json: NanoPFN V2 (30D) model path, schema version, and device. The model weights must be present locally — there is no silent fallback to heuristics.

The LLM brain is reached through a Poe-style OpenAI-compatible API. The CLI reads credentials from the environment; without them the agent runs in deterministic regex-only mode (regex literature extraction, rule-based candidates, and policy-based repair):

export POE_BASE_URL=https://api.poe.com/v1
export POE_API_KEY=your_key

For live Europe PMC / PubMed literature retrieval, set NCBI credentials:

export NCBI_EMAIL=you@example.org
export NCBI_API_KEY=your_ncbi_api_key

The NanoPFN V2 weights are not redistributed in this repository (models/**/*.pkl is git-ignored). Place the ensemble checkpoints under models/nanopfn_v2/row_level/ — see `models/nanopfn_v2/README.md` for how to obtain them.

Data Source & Attribution

This project's curated PLGA formulation table (data/raw/NP_dataset*.csv, data/processed/plga_formulations.json) is derived from:

Goren, A., Bao, Z., Martinez Lozano, J. P., & Allen, C. (2025). A formulation dataset of poly(lactide-co-glycolide) nanoparticles for small molecule delivery. Scientific Data, 12, 1182. https://doi.org/10.1038/s41597-025-05520-9

We use 416 of the 433 published formulations (17 dropped during preprocessing for insufficient feature coverage). The 416 cited DOIs from the dataset's reference column drive our PubMed/PMC literature retrieval pipeline.

License notice: the Scientific Data article describing the dataset is published under CC BY-NC-ND 4.0 (article text/figures only — does not apply to the data). The dataset itself is licensed CC BY 4.0 (verified 2026-05-31 on its Mendeley record, https://data.mendeley.com/datasets/sbjf5csrdm/1), which permits subsetting, derivative works, and redistribution with attribution and indication of changes. Our processed 416-record derivative is included here on that basis; see `DATA_ATTRIBUTION.md` for the change log.

For full attribution, license analysis, funding acknowledgements, and compliance checklist, see `DATA_ATTRIBUTION.md`. A complete prior-art bibliography is in `CITATIONS.md`.