{"id":50873692,"url":"https://github.com/hinanohart/foldconsensus","last_synced_at":"2026-06-15T07:31:23.757Z","repository":{"id":360492009,"uuid":"1250406230","full_name":"hinanohart/foldconsensus","owner":"hinanohart","description":"Physics-gated cross-model cofolding ranker for commercially-redistributable structure predictors (Apache-2.0, pre-alpha)","archived":false,"fork":false,"pushed_at":"2026-06-10T10:53:16.000Z","size":339,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-10T11:07:48.339Z","etag":null,"topics":["boltz","calibration","co-folding","ensemble-ranking","posebusters","protein-structure","structural-biology"],"latest_commit_sha":null,"homepage":"https://github.com/hinanohart/foldconsensus","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hinanohart.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-26T15:44:27.000Z","updated_at":"2026-06-10T10:53:20.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/hinanohart/foldconsensus","commit_stats":null,"previous_names":["hinanohart/foldconsensus"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/hinanohart/foldconsensus","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hinanohart%2Ffoldconsensus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hinanohart%2Ffoldconsensus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hinanohart%2Ffoldconsensus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hinanohart%2Ffoldconsensus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hinanohart","download_url":"https://codeload.github.com/hinanohart/foldconsensus/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hinanohart%2Ffoldconsensus/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34353189,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-15T02:00:07.085Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["boltz","calibration","co-folding","ensemble-ranking","posebusters","protein-structure","structural-biology"],"created_at":"2026-06-15T07:31:21.830Z","updated_at":"2026-06-15T07:31:23.749Z","avatar_url":"https://github.com/hinanohart.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# foldconsensus\n\n**Physics-gated cross-model ranker for commercially-redistributable protein co-folding outputs.**\n\nModern co-folding models (Boltz-2, Chai-1, Protenix, OpenFold3, …) each emit their own confidence scores in their own scale. A high model confidence does **not** guarantee a physically valid pose — a structure can score well yet contain steric clashes or impossible bond geometry.\n\n`foldconsensus` is a small, dependency-light harness that:\n\n1. **Normalizes** raw confidence/affinity from each backend into a common scale (one module owns every sign and unit convention, so a backend quirk cannot leak silently into the ranking).\n2. **Calibrates** per-model confidence with a self-contained isotonic / Platt layer (numpy + scipy only — no torch in the core), and combines models with a uniform-weighted ensemble by default; an inverse-error (inverse-Brier) weighting is available and is adopted only when it beats the uniform baseline on held-out data (otherwise uniform is kept).\n3. **Physics-gates** every candidate with [PoseBusters](https://github.com/maabuu/posebusters): a pose that fails a *hard* physical check is multiplicatively zeroed (`hard_valid = False ⇒ Q = 0`) rather than merely down-weighted.\n4. **Ranks** the surviving candidates by the gated score `Q(x)`.\n\n## Architecture\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"docs/architecture.png\" alt=\"foldconsensus architecture\" width=\"840\"\u003e\n\u003c/div\u003e\n\n## What this is (and is not)\n\n**v0.1.0a3 CLAIM — the PoseBusters physics gate.**\n`foldconsensus` demonstrates, on real crystal-structure ligand poses (PoseBusters-benchmark PDB entries), that a high-confidence pose which fails a hard physical check is multiplicatively zeroed and removed from the top of the ranking. The gate is backend-agnostic; running it on a live Boltz-2 cofolder needs a GPU and is deferred to v0.1.1.\n\n**v0.1.0a3 NOT a claim — calibration accuracy.**\nThe bundled calibration is validated for **algorithmic correctness only** (monotonicity, ECE→0 under perfect calibration, NaN-safety). Correcting the real miscalibration of a specific cofolder is **deferred to v0.1.1** and is reported, if measured on synthetic data, with an explicit `algorithm-validation-only` disclaimer.\n\n`foldconsensus` does **not** bundle any model weights. It is a ranking layer that runs on top of backends you install yourself. AlphaFold 3 is deliberately **not** a backend (its weights are non-commercial); every bundled backend is commercially redistributable. See [NOTICE](NOTICE).\n\n### Relation to prior work\n\n[ABCFold](https://github.com/rigdenlab/ABCFold) runs several folding models and visualizes their raw outputs side by side. `foldconsensus` differs in the *ranking logic*: cross-model calibration plus a multiplicative physics gate, rather than a side-by-side display of raw scores.\n\n## Install\n\n```bash\npip install foldconsensus            # core: numpy + scipy only\npip install \"foldconsensus[physics]\" # + rdkit + posebusters (physics gate)\npip install \"foldconsensus[boltz]\"   # + boltz + torch (Boltz-2 backend)\n```\n\n## Quickstart\n\n```bash\nfoldconsensus doctor                    # backend availability (live vs mock), honest\nfoldconsensus rank -i candidates.json   # rank candidate poses with the physics gate\nfoldconsensus calibrate -i scores.json  # fit / report a calibration curve\n```\n\n**Input notes for `rank`:**\n\n- The input schema (with a runnable example) is [`examples/candidates.json`](examples/candidates.json).\n- `physics_checks` values **must be booleans** (pass/fail); a non-boolean is rejected rather than silently treated as a pass — raw PoseBusters numeric columns must be reduced to booleans first (the `[physics]` adapter does this for you).\n- A candidate with *no* `physics_checks` is **not gated** (treated as valid): the gate only removes poses with positive evidence of invalidity.\n- The optional `affinity` field is collected but **not yet used** in v0.1.0a3 ranking (deferred to v0.2).\n\n## How it works\n\nThe core ranking formula is:\n\n```\nQ(x) = hard_valid(x) * [ α * p_ensemble + β * (1 - u) + γ * pb_pass_rate ]\n```\n\nwhere `α = β = γ = 1/3` (fixed, untuned in this release; weight learning is deferred to v0.2).\n\n| Term | Meaning |\n|------|---------|\n| `p_ensemble` | Calibrated ensemble probability across all available backends |\n| `u` | Epistemic uncertainty; `(1 - u)` rewards agreement across models |\n| `pb_pass_rate` | Fraction of PoseBusters checks passed (soft heuristics included in rate but not in hard gate) |\n| `hard_valid` | Multiplicative gate: if any *hard* physical check fails, `Q` is forced to exactly 0 |\n\nSoft checks (e.g. `internal_energy`, `non-aromatic_ring_non-flatness`) count toward `pb_pass_rate` but do not alone trigger the hard gate. Every other PoseBusters boolean check is treated as hard.\n\n## Results (v0.1.0a1)\n\nAll numbers are generated by `scripts/measure.py` into `bench_results/*.json` (env-stamped, deterministic) and are never hand-edited. The `v0.1.0a1` filenames are intentional: v0.1.0a2/a3 were packaging/CI-only patches with no metric or logic change.\n\n**Physics gate (the claim) — real data.**\nOn the real PoseBusters-benchmark PDB ligands (`1s3v`, `1of6`, `1uou`, `1ia1`, including one protein–ligand `mol_cond` run):\n\n- All 5 real poses pass the hard gate.\n- A controlled atomic perturbation of the real `1uou` ligand (bond-length/angle violation) is zeroed to **Q = 0** despite a **0.97** model confidence — a high-confidence but physically invalid pose is removed, not merely down-weighted.\n\nSource: `bench_results/gate_v0.1.0a1.json`. Live cofolder (Boltz-2) inference needs a GPU and is deferred to v0.1.1; the gate is backend-agnostic, so real ligand poses stand in for \"a confident pose that violates physics\".\n\n**Calibration — algorithm validation only (synthetic).**\nOn synthetic miscalibrated data, the isotonic calibrator:\n\n- Reduces **ECE 0.159 → 0.022** (held-out test split; bootstrap 95% CI [0.018, 0.046])\n- Reduces **Brier 0.199 → 0.170**\n- Preserves ranking (Spearman rho ~ 0.998)\n\n*This is a correctness check of the calibration algorithm, not a claim about correcting any real cofolder's miscalibration* (deferred to v0.1.1). Source: `bench_results/calibration_v0.1.0a1.json`.\n\n## Status\n\n`v0.1.0a3` — **pre-alpha**.\n\n- Implemented backend: Boltz-2 (adapter; the live cofolder needs the `[boltz]` extra + a GPU).\n- Chai-1 is v0.1.1; Protenix / OpenFold3 are stubs (`NotImplementedError`, never placeholder values).\n- A structural-agreement ranking axis (pairwise TM-score / RMSD median across the top poses) is **not yet implemented** and is deferred to v0.1.1; it is not part of the gated score `Q`.\n\n## Changelog\n\n- **v0.1.0a3** — packaging/CI hygiene (no metric or logic change; the `v0.1.0a1` measurement artifacts are unchanged). Bounded `requires-python` to `\u003c3.14` so the `[boltz]` extra's transitive dependency pins resolve (fixes a dependency-resolver failure on the 3.14 split); bumped CI actions to the Node 24 runtime (`actions/checkout@v6`, `astral-sh/setup-uv@v7`).\n- **v0.1.0a2** — hardening patch (no metric changes; the `v0.1.0a1` measurement artifacts are unchanged). The physics gate now **fails closed** on non-boolean `physics_checks` input (a raw numeric clash distance can no longer be mistaken for a pass via the CLI); added an input-schema example, cleaner CLI errors, and `bench_results`/`examples` in the sdist.\n- **v0.1.0a1** — initial pre-alpha: calibration core, Boltz-2 adapter, PoseBusters physics gate.\n\n## Audit-trail integration (memcanon)\n\n[`memcanon`](https://github.com/hinanohart/memcanon) v0.2+ accepts events from this repo via a thin in-process shim and content-hashes them into a local audit store:\n\n\u003e memcanon is not on PyPI yet. Install it from the tagged release:\n\u003e\n\u003e ```bash\n\u003e pip install \"git+https://github.com/hinanohart/memcanon@v0.2.0a2\"\n\u003e ```\n\n```python\nfrom memcanon.emit import emit\nfrom memcanon.store.local import LocalStore\n\nwith LocalStore(\"audit\") as store:\n    emit(\"foldconsensus\", {\"kind\": \"...\", \"decision\": \"...\"}, store=store)\n```\n\nEach record is tagged `source:foldconsensus` + `schema:memcanon-emit/1`. Memcanon's `memcanon export --format eu-ai-act-12 --to OUT.json` can then build an Article 12(2) paragraph-mapped audit-log artefact (SHAPE only, NOT a conformity assessment).\n\n## License\n\nMIT. See [LICENSE](LICENSE) for third-party components.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhinanohart%2Ffoldconsensus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhinanohart%2Ffoldconsensus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhinanohart%2Ffoldconsensus/lists"}