{
  "name": "biosingularity",
  "summary": "Policy-driven biomedical evidence linter. Typed propositions return ALLOW / REVIEW / BLOCK with exact receipts; experimental free-text discovery is capped at REVIEW.",
  "positioning": "Preflight biomedical evidence before publication or automated assertion.",
  "deterministic": true,
  "cardinal_rule": "A false 'pass' is the only unforgivable failure. Anything unverifiable degrades to review, never waved through.",
  "verdicts": [
    "review",
    "reject"
  ],
  "typed_decisions": [
    "SUPPORTED",
    "CONTRADICTED",
    "UNRESOLVED",
    "OUT_OF_SCOPE"
  ],
  "typed_recommendations": [
    "ALLOW",
    "REVIEW",
    "BLOCK"
  ],
  "discovery_verdicts": [
    "publish",
    "review",
    "reject"
  ],
  "claim_types": [
    {
      "type": "reference",
      "sources": [
        "PubMed",
        "Crossref/Retraction-Watch 74k-DOI local index"
      ],
      "demo": true
    },
    {
      "type": "gene_disease",
      "sources": [
        "Open Targets",
        "DisGeNET",
        "GWAS Catalog",
        "STRING"
      ],
      "demo": true
    },
    {
      "type": "drug",
      "sources": [
        "ChEMBL",
        "FDA Orange Book",
        "OpenFDA drug labels (boxed warnings / contraindications / dosage)",
        "OpenFDA/FAERS",
        "PharmGKB",
        "DGIdb"
      ],
      "demo": "labels+basic"
    },
    {
      "type": "drug_interaction",
      "sources": [
        "DDInter"
      ],
      "demo": false
    },
    {
      "type": "variant",
      "sources": [
        "ClinVar",
        "gnomAD",
        "dbNSFP",
        "eQTL/GTEx"
      ],
      "demo": false
    },
    {
      "type": "gene_essentiality",
      "sources": [
        "DepMap"
      ],
      "demo": false
    },
    {
      "type": "phenotype",
      "sources": [
        "HPO"
      ],
      "demo": false
    },
    {
      "type": "trial",
      "sources": [
        "ClinicalTrials.gov"
      ],
      "demo": true
    },
    {
      "type": "contested",
      "sources": [
        "scite Smart Citations (disputed / contrasting citations)"
      ],
      "demo": true
    },
    {
      "type": "gene_resolution",
      "sources": [
        "HGNC / genenames.org (resolve + abstain-on-ambiguous)"
      ],
      "demo": true
    },
    {
      "type": "cell_line",
      "sources": [
        "Cellosaurus (misidentified / contaminated register)"
      ],
      "demo": true
    },
    {
      "type": "trial_integrity",
      "sources": [
        "ClinicalTrials.gov (ICMJE prospective registration, FDAAA 801 results reporting)"
      ],
      "demo": true
    },
    {
      "type": "drug_label",
      "sources": [
        "openFDA structured product labels (boxed warning / contraindications / dosage)"
      ],
      "demo": true
    },
    {
      "type": "reproducibility",
      "sources": [
        "NCBI eutils (GEO, dbGaP)",
        "ENA Browser (the INSDC namespace)",
        "EBI BioStudies (ArrayExpress)",
        "RCSB PDB",
        "EBI PRIDE",
        "DataCite (Zenodo/figshare/Dryad)",
        "Europe PMC (full text + text-mined accessions)"
      ],
      "demo": false
    },
    {
      "type": "evidence_base",
      "sources": [
        "PubMed",
        "the local retraction index",
        "scite Smart Citations",
        "Crossref update-to"
      ],
      "demo": false
    },
    {
      "type": "manuscript_screen",
      "sources": [
        "composes references + cell lines + trial registry + uncheckable prose, behind an extraction-quality gate"
      ],
      "demo": false
    },
    {
      "type": "funder_portfolio",
      "sources": [
        "NIH RePORTER",
        "PubMed"
      ],
      "demo": false
    },
    {
      "type": "literature_candidates",
      "sources": [
        "OpenAlex API",
        "SemOpenAlex graph (DISCOVERY only; never verdict sources)"
      ],
      "demo": true
    },
    {
      "type": "scientific_review_candidates",
      "sources": [
        "exact manuscript text",
        "methods/statistics signal registry",
        "OpenAlex/SemOpenAlex discovery",
        "version-aware claim matching"
      ],
      "demo": true,
      "validation": "awaiting expert-adjudicated pilot labels"
    }
  ],
  "endpoints": [
    {
      "method": "POST",
      "path": "/api/v2/verify",
      "params": [
        "JSON body"
      ],
      "returns": "typed_decision",
      "demo": true,
      "hosted": true,
      "auth": "x-api-key (hosted)"
    },
    {
      "method": "POST",
      "path": "/api/scientific-review",
      "params": [
        "text",
        "manuscript_id",
        "previous_text",
        "review_issues",
        "discover"
      ],
      "returns": "scientific-review/1",
      "demo": true,
      "hosted": true,
      "auth": "x-api-key (hosted)"
    },
    {
      "method": "GET",
      "path": "/api/verify",
      "params": [
        "q"
      ],
      "returns": "verdict",
      "demo": true,
      "hosted": true,
      "auth": "x-api-key (hosted)"
    },
    {
      "method": "GET",
      "path": "/api/repair",
      "params": [
        "q"
      ],
      "returns": "repair",
      "demo": true,
      "hosted": true,
      "auth": "x-api-key (hosted)"
    },
    {
      "method": "GET",
      "path": "/api/discovery",
      "params": [
        "q"
      ],
      "returns": "discovery_verdict",
      "demo": false,
      "hosted": true,
      "auth": "x-api-key"
    },
    {
      "method": "GET",
      "path": "/api/audit",
      "params": [
        "q"
      ],
      "returns": "reference_audit",
      "demo": true,
      "hosted": true,
      "auth": "x-api-key (hosted)"
    },
    {
      "method": "GET",
      "path": "/api/target",
      "params": [
        "gene",
        "disease"
      ],
      "returns": "gene_disease",
      "demo": true,
      "hosted": true,
      "auth": "x-api-key (hosted)"
    },
    {
      "method": "GET",
      "path": "/api/entities",
      "params": [
        "drug",
        "nct"
      ],
      "returns": "drug_or_trial",
      "demo": true,
      "hosted": true,
      "auth": "x-api-key (hosted)"
    },
    {
      "method": "GET",
      "path": "/api/decompose",
      "params": [
        "q"
      ],
      "returns": "entities",
      "demo": true,
      "hosted": true,
      "auth": "x-api-key (hosted)"
    },
    {
      "method": "GET",
      "path": "/api/evidence/search",
      "params": [
        "q",
        "limit",
        "published_after",
        "open_access",
        "sources"
      ],
      "returns": "retrieval_packet",
      "demo": true,
      "hosted": true,
      "auth": "x-api-key (hosted)"
    },
    {
      "method": "GET",
      "path": "/api/evidence/neighbourhood",
      "params": [
        "work_id",
        "direction",
        "limit",
        "sources"
      ],
      "returns": "retrieval_packet",
      "demo": true,
      "hosted": true,
      "auth": "x-api-key (hosted)"
    },
    {
      "method": "GET",
      "path": "/api/evidence/resolve",
      "params": [
        "id",
        "sources"
      ],
      "returns": "retrieval_packet",
      "demo": true,
      "hosted": true,
      "auth": "x-api-key (hosted)"
    },
    {
      "method": "GET",
      "path": "/api/evidence/context",
      "params": [
        "id",
        "sources"
      ],
      "returns": "retrieval_packet",
      "demo": true,
      "hosted": true,
      "auth": "x-api-key (hosted)"
    },
    {
      "method": "GET",
      "path": "/api/cellline",
      "params": [
        "name",
        "q"
      ],
      "returns": "verdict",
      "demo": true,
      "hosted": true,
      "auth": "none (bundled register)"
    },
    {
      "method": "GET",
      "path": "/api/label",
      "params": [
        "drug"
      ],
      "returns": "verdict",
      "demo": true,
      "hosted": true,
      "auth": "none (public openFDA)"
    },
    {
      "method": "GET",
      "path": "/api/badge",
      "params": [
        "doi",
        "label"
      ],
      "returns": "image/svg+xml",
      "demo": true,
      "hosted": false,
      "auth": "none"
    },
    {
      "method": "GET",
      "path": "/api/repro",
      "params": [
        "doi",
        "q",
        "accession"
      ],
      "returns": "repro_ledger",
      "demo": false,
      "hosted": true,
      "auth": "x-api-key"
    },
    {
      "method": "GET",
      "path": "/api/evidence-base",
      "params": [
        "included",
        "bibliography"
      ],
      "returns": "evidence_base_score",
      "demo": false,
      "hosted": true,
      "auth": "x-api-key"
    },
    {
      "method": "GET",
      "path": "/api/desk",
      "params": [
        "q"
      ],
      "returns": "desk_screen",
      "demo": false,
      "hosted": true,
      "auth": "x-api-key"
    },
    {
      "method": "GET",
      "path": "/api/portfolio",
      "params": [
        "grants"
      ],
      "returns": "portfolio_report",
      "demo": false,
      "hosted": true,
      "auth": "x-api-key"
    },
    {
      "method": "GET",
      "path": "/api/contested",
      "params": [
        "doi"
      ],
      "returns": "verdict",
      "demo": true,
      "hosted": false,
      "auth": "none (public scite)"
    },
    {
      "method": "GET",
      "path": "/api/resolve",
      "params": [
        "gene"
      ],
      "returns": "verdict",
      "demo": true,
      "hosted": false,
      "auth": "none (public HGNC)"
    },
    {
      "method": "GET",
      "path": "/api/provenance",
      "params": [
        "ref"
      ],
      "returns": "receipt",
      "demo": false,
      "hosted": true,
      "auth": "x-api-key"
    },
    {
      "method": "GET",
      "path": "/api/health",
      "params": [],
      "returns": "datalake_health",
      "demo": false,
      "hosted": true,
      "auth": "none"
    },
    {
      "method": "GET",
      "path": "/api/capabilities",
      "params": [],
      "returns": "this_manifest",
      "demo": true,
      "hosted": false,
      "auth": "none"
    }
  ],
  "auth": {
    "header": "x-api-key",
    "idempotency_header": "Idempotency-Key",
    "quota": "per-key monthly; the key is reserved before work, so an exhausted key returns 429 without running the verifier"
  },
  "mcp": {
    "package": "biosingularity[mcp,store]",
    "install": "pip install 'biosingularity[mcp,store]'",
    "command": "biosingularity-mcp",
    "transport": "stdio",
    "add": "claude mcp add biosingularity -- biosingularity-mcp",
    "config": {
      "mcpServers": {
        "biosingularity": {
          "command": "biosingularity-mcp"
        }
      }
    },
    "start_here": [
      "verify_proposition",
      "verify_answer",
      "repair_answer",
      "attest_answer"
    ],
    "tools": [
      "verify_proposition",
      "search_evidence",
      "expand_evidence_neighbourhood",
      "resolve_research_object",
      "evidence_context_markers",
      "search_literature",
      "verify_answer",
      "repair_answer",
      "verify_discovery",
      "attest_answer",
      "audit_references",
      "citation_tallies",
      "verify_variant",
      "check_drug_interaction",
      "verify_cell_line",
      "gene_essentiality",
      "corroborate_gene_disease",
      "verify_variant_trait",
      "verify_phenotype",
      "check_drug",
      "check_trial",
      "verify_trial_integrity",
      "check_reproducibility",
      "evidence_base_integrity",
      "screen_manuscript",
      "screen_manuscript_text",
      "review_scientific_manuscript",
      "screen_submission_queue",
      "portfolio_integrity",
      "watch_check",
      "provenance",
      "scan_folder",
      "data_freshness"
    ]
  },
  "response_schema": {
    "recommend": "review|reject (free text cannot pass; use typed recommendation=ALLOW)",
    "verification_mode": "experimental_free_text",
    "overall_severity": "red|amber|info|green",
    "coverage_confidence": "number|null (share of checkable claims that resolved to a source — COVERAGE, not a probability)",
    "verdict_certainty": "high|moderate|low|null (how FIRM the recommendation is, from the deciding claims' evidence — threshold retry-vs-surface on this, not on coverage_confidence)",
    "reward": "number|null (a graded [0,1] scalar for RANKING/TRAINING — NOT a verdict; threshold the gate on `recommend`, rank best-of-N / RL on `reward`)",
    "confidence": "number|null (back-compat alias of coverage_confidence)",
    "summary": "string",
    "counts": {
      "red": "int",
      "amber": "int",
      "info": "int",
      "green": "int"
    },
    "coverage": {
      "level": "low|partial|high",
      "ratio": "number|null",
      "claims_checked": "int",
      "statements": "int"
    },
    "claims": [
      {
        "kind": "string",
        "ref": "string",
        "severity": "red|amber|info|green",
        "detail": "string",
        "receipt": "url|null",
        "grounded": "bool",
        "code": "string|null (stable reason code — the deciding Flag.kind, e.g. 'retracted', 'variant_common', 'gene_disease_contradicted'; branch on this, not the prose detail)",
        "remediation": "{action, instruction, target?} | absent (present only on red/amber claims — what to do about it, e.g. {action:'retract_assertion', instruction:'…'})",
        "adjudication": "supported|contradicted|cautioned|unresolvable (the training-signal partition — keep supported, drop contradicted, build preference pairs)",
        "checkable": "bool (did we have a source to adjudicate it — false = 'couldn't check', not 'clean')"
      }
    ],
    "graph": {
      "nodes": "[]",
      "edges": "[]",
      "relations": "{supports,contradicts,cautions,retracts,replicates,unverified}"
    }
  },
  "repair_schema": {
    "repaired_text": "string — the answer to SHIP (body + a labelled, sourced notes appendix)",
    "repaired_body": "string — the assertion text WITHOUT the appendix; re-verify THIS, not repaired_text",
    "edits": [
      {
        "kind": "removed_citation|removed_sentence|appended_note",
        "action": "string",
        "code": "string",
        "target": "string",
        "removed": "string?",
        "added": "string?"
      }
    ],
    "residual": [
      {
        "ref": "string",
        "code": "string",
        "severity": "red|amber",
        "action": "string",
        "instruction": "string",
        "why_not_applied": "string"
      }
    ],
    "ship_status": "SHIP|REVIEW_REQUIRED|DO_NOT_SHIP — decided after post-repair verification",
    "safe_to_ship": "deprecated bool alias of ship_status=SHIP",
    "residual_risk": "none|amber|red",
    "verdict_before": "verdict summary",
    "verdict_after": "verdict summary (over repaired_body)",
    "applied_actions": [
      "add_warning",
      "note_status",
      "remove_citation",
      "remove_recommendation",
      "retract_assertion",
      "retract_or_correct"
    ],
    "never_automated": "soften_claim / rephrase / cite_source / cite_trial / verify_dose / verify_manually — these require writing NEW prose, which a deterministic repairer must not do"
  },
  "not_offered": {
    "watch": "There is deliberately NO /api/watch. Standing surveillance is `biosingularity watch` — a JSON watchlist the USER owns plus their own cron, delivering via a 5-value exit code. An endpoint would have to store a user's bibliography server-side, which is the exact posture the file-backed design removes, and would add no verification capability (the checking is keyless PubMed either way).",
    "repro_at_the_edge": "/api/repro is hosted-only. It is keyless and fast enough for the edge, but the accession extractor and severity table are not yet ported to netlify/functions/*.mjs and there is no case in tests/test_js_parity.py. That harness has already caught two live severity-drift bugs, so an unverified port that softened an amber to info would tell a web user the CLI's amber does not exist.",
    "portfolio_at_the_edge": "/api/portfolio is hosted-only. It is keyless (NIH RePORTER + PubMed), but the non-attribution discipline — portfolio-level red unreachable, retracted and disputed never summed, counts labelled as floors — is not yet ported to netlify/functions/*.mjs and there is no case in tests/test_js_parity.py. That harness has already caught two live severity-drift bugs, so an unverified port that reddened a portfolio verdict would publish an accusation the CLI refuses to make.",
    "evidence_base_at_the_edge": "/api/evidence-base is hosted-only. It is keyless (PubMed + Crossref), but the denominator discipline — refuse rather than truncate, every percentage over the caller's included list — is not yet ported to netlify/functions/*.mjs and there is no case in tests/test_js_parity.py. That harness has already caught two live severity-drift bugs, so an unverified port that divided by what it managed to check would publish a number that improves as lookups fail.",
    "desk_at_the_edge": "/api/desk is hosted-only and TEXT-only — never a path parameter (a traversal surface). PDF/DOCX intake stays on the CLI/MCP, because the extraction quality IS the screen and a second extractor at the edge would drift from the tested one.",
    "scores_we_refuse_to_compute": "No pooled effect estimate, effect direction, p-value or I² from /api/evidence-base (we do not have your effect estimates), and no 0-100 reproducibility score from /api/repro (the denominator — how many accessions a paper SHOULD have declared — is unanswerable). Counts with a named denominator, or nothing.",
    "institution_rollup": "No institution-level portfolio view: RePORTER's org matching is a loose substring match carrying no ROR id, so it is verified infeasible keylessly rather than descoped.",
    "people": "No author, PI or investigator field exists in the portfolio data model at all. Note the honest bound: receipts are PubMed URLs, so this is not anonymity — the guarantee is that no person is ever a row, key, column, count or sort order."
  },
  "accuracy": {
    "benchmark_variants": 142119,
    "acmg_ba1_precision_pct": 100,
    "acmg_ba1_flagged": 5179,
    "false_contradiction_rate_pct": 0,
    "insilico_f1_pct": 83.69,
    "insilico_recall_pct": 96.86,
    "note": "ACMG BA1 (>=5% population frequency) reject rule scored on ClinVar-derived, gnomAD-frequencied variants; in-silico dbNSFP consensus is used as supporting evidence only, never a standalone verdict."
  },
  "reward_eval": {
    "reward": "every verdict carries reward∈[0,1] = mean(per-claim value) × coverage_factor; a red contradiction zeroes a claim, low coverage caps it (closes the hack of asserting fewer checkable claims). NOT a verdict — rank/train on it, gate on `recommend`.",
    "batch_scorer": "`biosingularity score --in rollouts.jsonl --offline` → one score per line (reward, recommend, hallucination_rate, per-claim adjudication) + a corpus rollup. Deterministic, content-hash cached, network-free (the local retraction index still runs).",
    "partition": "each claim's `adjudication` (supported/contradicted/cautioned/unresolvable) + `checkable` drive synthetic-data filtering & preference pairs; hallucination_rate = contradicted / checkable.",
    "reproducibility": "every verdict/score/receipt is tied to a snapshot_id (see /api/health) so a run reproduces and is citable — 'biosingularity@X / snapshot bss_…'."
  },
  "tool_specs": {
    "openai": "/tools/openai.json",
    "anthropic": "/tools/anthropic.json",
    "openapi": "/openapi.json"
  },
  "discovery": {
    "mcp": "/.well-known/mcp.json",
    "plugin": "/.well-known/ai-plugin.json"
  },
  "scientific_review": {
    "workbench": "/review-workbench.html",
    "schema": "https://github.com/markhahnel/biosingularity/blob/main/docs/schemas/scientific-review-v1.schema.json",
    "stages": [
      "claim_issue_extraction",
      "methods_statistics",
      "claim_evidence",
      "review_resolution"
    ],
    "maximum_heuristic_recommendation": "REVIEW",
    "discovery_decision_eligible": false,
    "validation": "candidate generation implemented; scientific accuracy awaits two domain reviewers and an adjudicator"
  },
  "docs": {
    "integrate": "/integrate.html",
    "methodology": "/methodology.html",
    "review_workbench": "/review-workbench.html",
    "llms_txt": "/llms.txt"
  }
}