Metadata-Version: 2.4
Name: biode
Version: 0.1.1
Summary: BiODE — Evidence-scored registry for coupled biological ODE systems
Author: Mansib Miraj
License-Expression: AGPL-3.0-or-later
Project-URL: Homepage, https://github.com/theMansib/biode
Project-URL: Documentation, https://github.com/theMansib/biode#readme
Project-URL: Issues, https://github.com/theMansib/biode/issues
Keywords: ode,systems-biology,computational-neuroscience,psychobiology,registry
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.26.0
Requires-Dist: scipy>=1.12.0
Requires-Dist: typer>=0.12.0
Requires-Dist: rich>=13.0.0
Provides-Extra: mcp
Requires-Dist: mcp>=1.0.0; extra == "mcp"
Provides-Extra: all
Requires-Dist: mcp>=1.0.0; extra == "all"
Requires-Dist: matplotlib>=3.8.0; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.24.0; extra == "dev"
Dynamic: license-file

<p align="center">
  <h1 align="center">BiODE</h1>
  <p align="center"><strong>Evidence-scored registry for coupled biological ODE systems.</strong></p>
  <p align="center">
    <a href="https://bio.xen.so">bio.xen.so</a> · <a href="https://pypi.org/project/biode">PyPI</a> · <a href="https://github.com/theMansib/biode">GitHub</a>
  </p>
</p>

---

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

```bash
# 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

```python
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:

```bash
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](https://github.com/theMansib/biode/blob/main/biode/registry.py).

## 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:

```python
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:

```python
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:

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

Exposes 9 tools via [Model Context Protocol](https://modelcontextprotocol.io):

| 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 |

### Quick spawn with uvx

```bash
# One command — no install needed, runs directly from PyPI
uvx --from "biode[mcp]" biode mcp-serve
```

### Claude Code configuration (`.mcp.json`)

```json
{
  "mcpServers": {
    "biode": {
      "command": "uvx",
      "args": ["--from", "biode[mcp]", "biode", "mcp-serve"]
    }
  }
}
```

### Or if already installed

```json
{
  "mcpServers": {
    "biode": {
      "command": "biode",
      "args": ["mcp-serve"]
    }
  }
}
```

## Central Registry

The public BiODE registry is live at [bio.xen.so](https://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

```bash
# 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](LICENSE) — 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:

```bibtex
@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](https://github.com/theMansib) · [bio.xen.so](https://bio.xen.so)

