biode 0.1.0

BiODE — Evidence-scored registry for coupled biological ODE systems

BiODE

Evidence-scored registry for coupled biological ODE systems.

bio.xen.so · PyPI · GitHub

---

Register published ODE models. Compose them into coupled systems. Detect conflicts automatically. Score evidence quality. Every parameter traces to a DOI.

148 models · 699 ODEs · 70 coupling interactions · 148 evidence scores

Installation

# Recommended
uv add biode

# Or with pip
pip install biode

# With MCP server support (for AI-assisted model discovery)
uv add "biode[mcp]"

Requires Python 3.11+.

Quickstart

from biode import Registry, ODEModel, EvidenceScore

# Create a local registry
reg = Registry()  # stored at ~/.biode/registry.db

# Register a published model with full provenance
reg.register_model(ODEModel(
    name="serotonin_terminal",
    source="Best et al. 2010",
    pmcid="PMC2942809",
    doi="10.1186/1742-4682-7-34",
    n_odes=9,
    status="implemented",
    output_chemicals=["5HT"],
    parameters={
        "SERT_Vmax": {"value": 4700, "units": "uM/hr", "source": "Best 2010 Table 1"},
        "SERT_Km": {"value": 0.17, "units": "uM", "source": "Best 2010 Table 1"},
    },
    state_variables=[
        {"name": "e5ht", "units": "uM", "description": "extracellular serotonin"},
    ],
))

# Score its evidence quality
reg.score_evidence(EvidenceScore(
    model_name="serotonin_terminal",
    doi_verified=True,
    pmcid_verified=True,
    journal_tier=2,           # 1=Nature/Science, 2=field-top, 3=peer-reviewed, 4=preprint
    citation_count=245,
    reproduced=True,
    params_from_table=True,   # parameters from paper table, not estimated
    year=2010,
))
# → score: 0.824

# Register coupling between models
reg.register_interaction(
    source_model="hpa_axis",
    target_model="serotonin_terminal",
    mechanism="cortisol_suppresses_tph2",
    direction="inhibitory",
    citation="Donner et al. 2012",
    pmcid="PMC3392182",
    tier=2,  # 1=published coupling, 2=novel contribution
)

# Validate — catches conflicts automatically
conflicts = reg.validate()
for c in conflicts:
    print(f"[{c.severity}] {c.description}")

# Rank all models by evidence
for m in reg.rank():
    print(f"  {m['evidence_score']:.3f}  {m['name']}")

CLI

BiODE ships with a Rich-powered terminal interface:

biode list                        # All registered models
biode list --status implemented   # Filter by status
biode rank                        # Evidence-scored ranking
biode validate                    # Run all conflict checks
biode summary                     # High-level overview
biode show serotonin_terminal     # Full model details (params, equations, provenance)
biode conflicts                   # Active conflicts and warnings

Evidence Scoring

Every model receives a credibility score from 0.0 to 1.0, computed transparently:

Component	Weight	What it measures
DOI verified	0.15	Paper exists in CrossRef
PMCID verified	0.10	Paper exists in PubMed Central
Journal tier	0.02–0.20	Nature/Science=0.20, field-top=0.15, peer-reviewed=0.10, preprint=0.02
Citation count	up to 0.15	Capped at 500 citations
Independently reproduced	0.15	Another group validated the model
Parameters from paper table	0.15	vs. estimated/fitted (penalty if estimated)
In BioModels database	0.05	SBML file publicly available
Published since 2015	0.05	Recency bonus

A reviewer can verify every component. The score formula is open source.

Conflict Detection

BiODE catches composition errors that manual model-wiring misses:

• Duplicate chemical drivers — two models both claiming to produce serotonin → ERROR
• Missing citations — implemented model without DOI or PMCID → ERROR
• Positive feedback loops — cycles up to length 4 with net positive gain → WARNING
• Parameter conflicts — same parameter name with different values across models → WARNING

During development, BiODE caught 5 duplicate driver conflicts and 4 positive feedback loops across 148 models — all in real time during agent-driven registration.

Chemical Normalization

Prevents duplicate entries from naming inconsistencies:

reg.normalize_chemical("serotonin")  # → "5HT"
reg.normalize_chemical("cortisol")   # → "CORT"
reg.normalize_chemical("dopamine")   # → "DA"

28 canonical chemical names with common aliases. Agents registering "5-HT", "5HT", or "serotonin" all resolve to the same canonical entry.

Unified Solver

Compose any subset of registered models into a coupled ODE system:

from biode import Registry
from biode.solver import UnifiedSolver, register_ode_func

reg = Registry()
solver = UnifiedSolver(reg)

# Solve 24 hours of coupled dynamics
sol = solver.solve([0, 1440])  # minutes
print(f"Solved {solver.total_dim} coupled ODEs in {len(sol.t)} steps")

The solver uses scipy's solve_ivp with Radau method (stiff-capable) and supports event detection for threshold-crossing dynamics.

MCP Server

For AI-assisted model discovery and registration:

uv add "biode[mcp]"
python -m biode.mcp_server

Exposes 9 tools via Model Context Protocol:

Tool	Description
register_ode_model	Register a published ODE model with full provenance
register_interaction	Register coupling between two models
score_evidence	Score a model's credibility
list_models	List all registered models
get_model	Get full model details
rank_models	Evidence-scored ranking
validate_registry	Run all conflict checks
get_conflicts	Get active conflicts
registry_summary	High-level registry stats

Configure in Claude Code (.mcp.json):

{
  "mcpServers": {
    "biode": {
      "command": "python3",
      "args": ["-m", "biode.mcp_server"],
      "env": { "PYTHONPATH": "." }
    }
  }
}

Central Registry

The public BiODE registry is live at bio.xen.so:

• Dashboard — live model count, evidence ranking, interaction graph
• REST API — GET /api/models, GET /api/rank, GET /api/pull
• Full dump — GET /api/pull returns the entire registry as JSON

# Pull the full public registry to your local cache
curl -s https://bio.xen.so/api/pull > ~/.biode/registry.json

Security

Write access to the central registry is protected by a 5-gate security pipeline:

1. Challenge quiz — proof-of-competence questions generated from the submission
2. Parameter verification — submitted values checked against published paper ground truth
3. Quarantine — all non-admin writes held for review, with immutable audit log
4. Consensus — promotion requires 2+ independent sources agreeing on parameter values
5. GPG signing — admin-signed canonical models override everything

Rate limiting (per-key + global + anomaly detection) defends against distributed attacks. ORCID-verified identity for write access.

What BiODE is NOT

• Not a simulation tool — BiODE registers and validates models. Use the solver or export to SBML for simulation.
• Not a replacement for reading papers — evidence scores quantify credibility but don't replace domain expertise.
• Not a database of equations — equations are stored as metadata. The scientific value is in the coupling, conflict detection, and evidence scoring.

License

AGPL-3.0-or-later — open core. Free to use, modify, and distribute. Network service deployments must publish source code.

Citation

If you use BiODE in your research, please cite:

@software{miraj2026biode,
  author = {Miraj, Mansib},
  title = {BiODE: Evidence-Scored Registry for Coupled Biological ODE Systems},
  year = {2026},
  url = {https://bio.xen.so},
  version = {0.1.0}
}

Author

Mansib Miraj — GitHub · bio.xen.so