Skip to content

Project Status

Version: v1.6.0 Stage: Beta. Engineering-validated infrastructure; scientifically unvalidated by independent domain experts.

This document exists so that any reader — reviewer, auditor, potential contributor, downstream user — can in 60 seconds form an accurate expectation of what this project is and is not.


Validation matrix

Dimension Status Evidence
Offline unit tests Passing uv run pytest tests/ on every PR; CI matrix across Python 3.11–3.13
Line + branch coverage 100% on shipped surface nox -s cov; enforced by --cov-fail-under=100
Static analysis Clean ruff check, mypy --strict, bandit on every PR
Security scanning Automated PR checks passing on verified commits CodeQL security-extended runs in CI; repository-wide open security alerts require a separate Security-tab check
Release provenance Sigstore signature bundles + CycloneDX SBOM attached; SLSA L3 generated in CI release.yml (its final job dispatches verify-published-release.yml after publishing); scripts/replicate.sh recomputes the PyPI wheel and sdist SHA-256 digests and runs cosign verify-blob on their Sigstore bundles (and, from 1.4.7, the signed SBOM bundles) against the release.yml@refs/tags/<tag> workflow identity
Integration tests (live APIs) One narrow live check; no continuous live suite pdbe-sifts-live.yml queries UniProt, PDBe and SIFTS live for one residue correspondence (Q8VH51, position 495) on pull requests that change its script, test or workflow file, and on manual dispatch. Every other test runs offline: upstream HTTP is intercepted with respx and answered from mocked or recorded responses; AFDB's renamed fields and isoform selection have regression fixtures, not independent live-API verification
Scientific validation Not performed ACMG mapping and druggability tier are unreviewed by domain experts; the structure heuristics are not validated (LIMITATIONS.md L10 to L12)
Clinical validation Not performed No clinical geneticist has signed off on any output
Regulatory certification None Not certified for HIPAA, GxP, 21 CFR Part 11, FedRAMP, FIPS, or SOC 2
Production deployment None Never deployed as a long-running service for real users

What is solid

Code architecture

  • Five subpackages with clear single responsibilities — clients/ (11 specialized clients + 1 shared base), domain/ (3 modules: disease types, the pure druggability heuristic, and UniProt accession syntax), tools/ (4 MCP-tool modules), storage/ (2 modules: SQLite KG + boot seed), server/ (2 modules: the FastMCP application + the stdio transport). The inventory now includes the conditional UniProtKB isoform verifier and optional PDBe/IUCr text-mined residue annotations; general UniProtKB annotations and independently verified PDB/SIFTS coordinate mapping are not shipped.
  • The previous monolith (~6,000 lines) is archived under _archive/legacy/ and excluded from coverage and lint.
  • No circular imports; client retry/circuit-breaker logic is a single module reused by every upstream client.

Test suite

  • Comprehensive offline unit-test suite (including parametrised expansions) across the shipped surface.
  • 100% line + branch coverage on the shipped surface (src/alphafold_sovereign/, excluding the archived monolith).
  • Tests use respx to mock HTTP semantics (not just return values) and pytest-asyncio for async client tests.
  • The ACMG mapping, druggability tier scoring, and KG queries all have parametrised tests covering known input/output pairs from the implementation.
  • Synthetic offline regression tests in tests/test_synthetic_variant_pipeline.py exercise source-response handling and transcript identity with fabricated records and intercepted HTTP requests. The previous named clinical replay collection was retired. These tests do not independently validate clinical interpretation.

Security & supply chain

  • Bandit + pip-audit on every PR and in the local nox -s security session.
  • CodeQL security-extended on every push (public repo).
  • CycloneDX SBOM generated from the installed package on every release tag (an SPDX document is also attached; populating it from the full dependency tree is a roadmap item).
  • SLSA L3 in-toto build provenance generated in CI; Sigstore (cosign) keyless signing of every release artefact.
  • PyPI publishing via OIDC Trusted Publishing (no API tokens stored in repo secrets).
  • SQL parameterised everywhere; CWE-89 closed.

Distribution

  • Published to PyPI at https://pypi.org/project/alphafold-sovereign-mcp/ (install with pip install alphafold-sovereign-mcp).
  • Zenodo concept DOI: 10.5281/zenodo.20134773 — version-independent identifier that redirects to the latest archived version. Each tagged GitHub Release mints its own version-specific DOI under this concept via the GitHub-Zenodo integration (verified on v1.1.3 at 10.5281/zenodo.20262463).
  • mkdocs documentation site auto-deploys to GitHub Pages on every push to main.

CI matrix

  • Python 3.11 / 3.12 / 3.13 on Ubuntu and macOS.
  • One further job installs the optional [tda] extra (GUDHI) on Python 3.12 and runs the same suite with the same coverage gate, so the persistent-homology path is executed in CI.
  • Lint (ruff), format (ruff format), type-check (mypy strict), build (sdist + wheel), MCP schema validation.
  • Apache 2.0 (LICENSE). Pure Apache 2.0 — no commercial-edition carve-out.
  • NOTICE, TRADEMARKS, CONTRIBUTING, SECURITY, CODE_OF_CONDUCT, GOVERNANCE, INCIDENT_RESPONSE, AUDIT, PRIVACY, SUPPORT.

What is NOT solid

Scientific / clinical validation

  • No clinical geneticist has reviewed the ACMG mapping. The mapping covers two candidate signals only, PVS1 and BP7, derived from VEP consequence terms on the author's reading of the 2015 Richards et al. guidelines. They are observations for expert review, not met criteria, and no independent expert has signed off on them. BA1, BS1, PM2, PP3 and BP4 are reported as NOT_ASSESSED: gnomAD allele frequencies and predictor outputs are returned as observations and are not mapped onto criteria. No other criterion is evaluated and no pathogenicity class is assigned. Use generate_variant_clinical_report or classify_variant_acmg as a research aid, never as clinical decision support.
  • The druggability tier scoring is a heuristic. Cut-offs for the HOT / WARM / COLD / NOT_DRUGGABLE buckets were chosen by the author based on rough literature priors. They have not been calibrated against a benchmark of known druggable / non-druggable targets and are not citation-backed.
  • The structure heuristics are not validated. analyze_structural_confidence does not identify protein domains, score_binding_pocket_geometry does not detect binding pockets or assess druggability, and the Cα topology vector is not a validated similarity measure. An internal audit in November 2026 did not support the earlier descriptions of these outputs as domain boundaries, scored pockets and a 64-component fingerprint; see LIMITATIONS.md L10 to L12 for what was measured.
  • No independent PDBe/SIFTS validation. The optional literature client verifies accession and residue identity from PDBe's returned data, not SIFTS mapping or HGVS-to-UniProt numbering. Its deterministic tests use the public PDBe notebook schema and mocked HTTP, not a new live service-level contract or clinically adjudicated residue set.
  • No end-to-end validation against real-world cases. The test suite mocks every upstream API. The pipeline has not been run against a held-out set of variants/targets/diseases with known expected outputs.
  • No outcome data. Nobody has measured how often the report agrees with a human geneticist, or how often the druggability tier predicts actual drug-discovery success.

Operational

  • No production deployment. This software has never been deployed as a long-running service for real users. Memory, latency, rate-limit, and failure-mode behaviour at scale is unknown.
  • No usage telemetry. We do not collect any data on which tools are called, with what arguments, or whether results are useful.
  • No SLA. Upstream APIs (Ensembl, Open Targets, ClinVar, gnomAD, AlphaFold DB, etc.) can change schema or go down; we do best-effort retries but make no availability guarantees.

Project maturity

  • Single maintainer. No bus factor > 1.
  • No external contributors yet. Review process is documented in CONTRIBUTING.md but has not been exercised.
  • No formal release cadence. v1.6.0 is the current release; later versions will be tagged as the validation milestones below are met.

What this means for users

If you are … You can use this project for … You should NOT use this project for …
A researcher exploring a target Pulling and joining data from 9 core upstream sources via MCP, plus conditional UniProtKB isoform verification Making a final go/no-go decision on a drug programme
A clinical geneticist Quickly assembling a literature snapshot for a variant Issuing a clinical report; ACMG candidate signals produced here are not validated and should be re-derived from raw sources
A platform engineer Studying a tested example of an MCP server with retries Production deployment without your own validation, monitoring, and SLA work
A bioinformatician Prototyping a workflow that calls 9 sources behind one API Reproducible publication-grade analyses (upstream APIs are not pinned by us)

Roadmap (validation, post-1.2.0)

The validation gap is the highest-priority work after v1.2.0. The planned, sequenced steps are:

  1. Offline regression examples. Synthetic, fabricated ClinVar records exercise report composition with intercepted HTTP in tests/test_synthetic_variant_pipeline.py. The previous clinical replays were retired; live API concordance, independently validated allele identity, and clinical validation are not claimed. Independent scientific validation remains items 3–4.
  2. ACMG traceability matrix. A markdown table stating, for each criterion (PVS1, PS1–4, PM1–6, PP1–5, BA1, BS1–4, BP1–7), whether the tools emit a candidate signal (currently PVS1 and BP7 only), report it as NOT_ASSESSED (currently BA1, BS1, PM2, PP3 and BP4) or do not evaluate it, with the line of code that implements that state, the test that exercises it, and the 2015 Richards et al. section it derives from.
  3. External review. One clinical geneticist to review the ACMG mapping; one medicinal chemist to review the druggability heuristic. Findings published as issues, then closed by PRs.
  4. Benchmark calibration. Run druggability on a held-out set of approved-drug targets vs. failed-development targets and report precision/recall.
  5. Schema pinning. Pin upstream API schemas to specific dates, with a documented refresh policy.

Last updated

2026-11-11. This document is part of the repo; PRs to correct or expand it are welcome.