Pinakes Verifiable Retrieval

Pinakes Verifiable Retrieval

Pinakes is a deterministic, verifiable input layer for AI agents over 26 public biomedical sources, shipped as one static Go binary that exposes the same 8 verbs over an MCP server (pinakes_<verb> tools), an identical CLI (pinakes <verb>), and a loopback REST server. Its value is invisible from the tool schemas, which is why this skill exists: every result pins a content-addressed snapshot (byte-reproducible forever), retrieval is complete-or-fail (reconciled against the source's authoritative total — never a silent partial), and every result ships a re-runnable manifest that verify re-derives offline. This skill teaches the judgement layer — pin or you get no determinism, read completeness honestly, verify before you cite — not the schemas (tools/list and pinakes catalog already carry field names, operators, and enums; do not duplicate them here).

Boundary. Pinakes fixes the input only. It does not run analysis, does not build evolutionary trees, and never claims a source is wrong — the public databases are authoritative. It fixes naive client retrieval (no imposed order, no reconciliation, no provenance). It covers public sources only. The arXiv literature corpus is not yet shipped — do not assume it. Hand the verified manifest to a domain skill for the actual science.

When to Use This Skill

✅ Use when:

• An agent must pull biomedical data that has to be reproducible / deterministic / byte-identical across runs.
• You need a record count that goes in a methods section and must reproduce next month.
• You need a cited fact a reviewer can independently re-fetch and check.
• You are handed a manifest and must confirm it reproduces before building on it (verify-before-cite).
• A query was rejected (UNKNOWN_FIELD, BAD_ENUM, INVALID_FILTER, UNSATISFIABLE_QUERY) and the agent must self-correct rather than retry blind.
• You must know whether a result is complete vs best_effort vs partial, or whether it is reproducible at all.
• You are pulling from PDB, UniProt, NCBI Protein, NCBI Virus, ClinVar, Ensembl, gnomAD, PubChem, AlphaFold, ChEMBL, ClinicalTrials, openFDA, cBioPortal, or NCBI Datasets and want provenance, not just bytes.

❌ Do not use when:

• The task is analysis (differential expression, alignment, tree-building, modeling). Use this to fetch the verified input, then a domain skill.
• You want to assert a source is wrong or compute a "true eternal count" — Pinakes does neither; a count is a property of a pin, not of all time.
• The source is private/internal or behind a login — Pinakes serves public databases only.
• You need the arXiv corpus — not shipped yet.
• A raw, throwaway lookup where reproducibility genuinely does not matter (rare — if it will be cited or re-run, it matters).

Clarification Questions

1. ⚠️ CRITICAL: ASK THIS FIRST — Will this result be reported, cited, or re-run?

If yes, you MUST pin a concrete snapshot_version (sha256:…, never empty, never latest) and verify the manifest before citing. An unpinned result is served from latest ⇒ reproducible:false, and a re-run next month silently returns a different set — so a bare count or fact with no pin is not a fact you can cite. If the answer is genuinely no (a throwaway lookup nobody will repeat), you may skip the pin — but confirm that explicitly, because this is rare.

2. Which source, and is it materializable?

• Which of the 26 sources answers the question (run catalog to confirm the id and its filter schema)?
• Is that source L2+ and HostServe? A copyleft source (ChEMBL, served live) can never be reproducible:true — if the task demands reproducibility, route to a materializable source instead (see Picking a Connector).

3. Does the answer have to be complete, or is best-effort acceptable?

• If it must be the whole answer, do not pass a limit — a cap below the authoritative total downgrades the result to best_effort (it cannot be reconciled). Let complete-or-fail reconcile.
• If a sample is fine, label it best_effort honestly — never present a capped or best-effort set as "all matching records".

Setup & Surface Detection

Pinakes is client-neutral: the same 8 verbs are an MCP tool and a CLI subcommand. Detect the surface and degrade gracefully.

Rule: use the MCP pinakes_<verb> tool if it is present in your tools; else shell out to the identical pinakes <verb> CLI. Every recipe below is shown in both forms — they are interchangeable.

• MCP present (tools named pinakes_catalog, pinakes_search, …): call them directly. Generic stdio registration is just:

  {"mcpServers": {"pinakes": {"command": "pinakes", "args": ["mcp"]}}}
  

  No token, no Docker, no env. If a GUI client can't find pinakes on its PATH, replace "command": "pinakes" with the absolute path from which pinakes.
• CLI only (no MCP tools, but which pinakes resolves): run pinakes <verb> with the same arguments. Pass a manifest as --manifest @manifest.json.
• Neither (which pinakes is empty): you cannot fetch. Say so plainly and stop — do not fabricate records or a manifest. Point the user at install (depth → references/setup.md).

Confirm wiring with pinakes catalog (CLI) or pinakes_catalog (MCP) before the first real query. Depth: references/setup.md.

The Core Loop (1–8)

Run this loop for any retrieval that will be reported, cited, or re-run. The hinge steps are 4 (pin a snapshot), 5 (read the manifest), and 7 (verify) — skip any one and the determinism guarantee silently evaporates.

1. Catalog. pinakes_catalog / pinakes catalog to list sources (id, maturity, license); scope to one source to get its filter schema (fields, operators, enums). This is how you learn what is queryable.
2. Validate locally. Check every filter field/operator/value against that schema before any network call. A bad one is rejected locally with a precise code (UNKNOWN_FIELD / BAD_ENUM / INVALID_FILTER) — fix it here, cheaply.
3. Estimate (optional). pinakes_estimate / pinakes estimate for a dry-run record/byte/call count. An estimate never substitutes for reconciliation — it is a cost preview, not a completeness claim.
4. Retrieve WITH a pinned snapshot_version. search / get / resolve, always passing a concrete snapshot_version (sha256:…). Empty or latest ⇒ not reproducible. This is the #1 footgun (see below).
5. Read Completeness + reproducible. Inspect the manifest: is completeness.state complete? Is reproducible true? Do not report until you have read these — the records alone don't tell you.
6. Export (optional). pinakes_export / pinakes export to materialize to parquet/json/fasta/vcf/mmcif. The reproducibility anchor stays the canonical NDJSON logical_record_hash, not the export bytes.
7. Verify. pinakes_verify / pinakes verify --manifest @manifest.json re-derives the count and record hash from the pinned snapshot offline. Exit 0 / verified:true ⇒ it reproduces. A refusal ⇒ stop, do not cite.
8. Cite the manifest. The citation is the manifest: source_id, pinned snapshot_version, logical_record_hash, completeness.state, and per-source license/attribution. Hand this to the next skill.

Copy-able checklist:

[ ] 1. catalog → confirmed source + read filter schema
[ ] 2. filters validated locally (no UNKNOWN_FIELD / BAD_ENUM / INVALID_FILTER)
[ ] 3. (estimate, if cost matters — not a completeness claim)
[ ] 4. snapshot_version pinned (concrete sha256:… — NOT empty, NOT "latest")
[ ] 5. manifest read: completeness.state == complete? reproducible == true?
[ ] 6. (export, if a file is needed — hash is over NDJSON, not export bytes)
[ ] 7. verify → exit 0 / verified:true (offline)
[ ] 8. cited the manifest (source_id + snapshot_version + logical_record_hash
       + completeness + license/attribution)

Pin or no determinism (the #1 footgun)

This is the single most common failure. The snapshot_version is what makes a result reproducible. No pin ⇒ the engine serves latest ⇒ reproducible:false, and a re-run next month silently returns a different set. A bare count or fact with no pin is not a fact you can cite.

A manifest is reproducible:true only when ALL of these hold (the engine's SetReproducible enforces every one — you cannot bypass it):

If any row fails, reproducible is false — honestly. The fix is almost always row 1/4: pass a snapshot_version. Full table: references/manifest-and-completeness.md.

Reading the Manifest

The manifest is the product. Read it; never infer from the record list.

Completeness decision table (completeness.state):

The limit footgun. A limit below the source's authoritative total cannot be reconciled, so the engine downgrades the result to best_effort — not complete. If you need a complete answer, drop the cap and let complete-or-fail reconcile, or report honestly that the set is best_effort. Treating a limit-capped set as "all matching records" is a classic error.

Key manifest fields to cite: manifest_schema_version, engine_version, per- source snapshot_version + maturity + license, logical_record_hash (the SHA-256 over canonical NDJSON — the anchor), completeness, served_from, and reproducible. Depth: references/manifest-and-completeness.md.

Picking a Connector

Short routing table (26 sources). L0 = catalog-only (not queryable); L1 = queryable but never reproducible (live proxy); L2+ = reproducible against a pinned snapshot. All 26 shipped connectors are L2. catalog is the live source of truth; this table is the at-a-glance version, the full one with SPDX and attribution flags lives in references/sources.md.

⚠️ Copyleft caveat (ChEMBL, Guide to PHARMACOLOGY). These two are Creative Commons Attribution-ShareAlike (copyleft / share-alike). The engine refuses to materialize a share-alike source, so every result from them is served live and is reproducible:false by construction — no pin makes it reproducible. Carry the attribution string; for a reproducible drug-data answer, prefer a materializable source. Full routing, license postures, and attribution rules: references/sources.md.

Worked Recipe A — Ebola, reproduced (flagship)

Goal: the complete-genome records for Zaire ebolavirus in NCBI Virus, pinned, complete, and offline-verified. Exact values from the repo case study.

MCP form:

{
  "name": "pinakes_search",
  "arguments": {
    "source_id": "ncbi-virus",
    "filters": [
      { "field": "organism_taxon_id", "operator": "eq", "value": "186538" },
      { "field": "complete_only",     "operator": "eq", "value": "true" },
      { "field": "released_since",    "operator": "gte", "value": "2023-01-01" }
    ],
    "snapshot_version": "sha256:b1983c09cd5c70137db4724494d2efaf263baa88c795b4ff1a457ba82fe72f90"
  }
}

Then pinakes_verify with the returned manifest.

CLI form (identical):

PIN=sha256:b1983c09cd5c70137db4724494d2efaf263baa88c795b4ff1a457ba82fe72f90
pinakes search --source-id ncbi-virus \
  --filters organism_taxon_id:eq:186538 \
  --filters complete_only:eq:true \
  --filters released_since:gte:2023-01-01 \
  --snapshot-version "$PIN"            # → 32 records, Complete (32/32)
pinakes verify --manifest @manifest.json   # → {"verified": true}, offline

Result (this pin): 32 records, completeness.state = complete (32 == 32 authoritative), logical_record_hash = sha256:01fffd0c…, NCBI datasets version 18.30.1, reproducible: true. verify re-derives the count and hash from the snapshot offline — a shortened or altered snapshot is refused (COMPLETENESS_DRIFT / HASH_MISMATCH).

Cite it like this: "NCBI Virus, complete-genome records for taxon 186538 released since 2023-01-01; snapshot sha256:b1983c09…; 32 records, Complete (32/32); logical_record_hash sha256:01fffd0c…; verified offline." The "32" is a property of this pin, not an eternal count — NCBI grows daily; the pin always yields this set. More recipes (UniProt, resolve, export, multi-filter): references/recipes.md.

Error Handling

Stable, surface-independent codes (identical across MCP/CLI/REST). Group them by action, not by name:

A verify that returns a drift code is doing its job — refusing a result that does not reproduce. Full ~28-code table grouped by recover-or-stop: references/errors.md.

Decision Points

Common Issues

Suggested Next Steps

Pinakes produces the verified input; hand the manifest to a domain skill for the science:

1. Variant work (clinvar / gnomad / ensembl results) → genetic-variant-annotation, genetic-target-hypothesis.
2. Drug / compound data (chembl / pubchem / openfda) → clinicaltrials-landscape, literature-preclinical.
3. Structures (pdb / alphafold) → structure-facing wet-lab skills (e.g. adaptyv-api for characterization).
4. Any dataset → data-analysis-best-practices before the first model — carry the manifest as the provenance record.

Always pass along the logical_record_hash + snapshot_version so the next skill inherits a re-checkable input, not a loose number.

References

Bundled (one level deep, on-demand):

• references/verbs.md — the 8 verbs, chaining, gotchas, and the pinakes_<verb> ↔ CLI mapping.
• references/manifest-and-completeness.md — completeness + reproducible truth tables, manifest citation fields.
• references/errors.md — the full stable error-code vocabulary grouped by recover-or-stop action.
• references/sources.md — the 26-connector routing table, maturity, license/posture.
• references/setup.md — client-neutral install, generic stdio config, which pinakes fallback, MCP-or-CLI rule.
• references/recipes.md — Recipes B–F (UniProt, resolve, export, …), each ending in cite-the-manifest, in both MCP + CLI forms.

Scripts:

• scripts/verify_and_cite.sh — verify a manifest, and on pass print a paste-ready citation; degrades to a no-op message if pinakes is absent.

Self-describing surface: pinakes catalog and MCP tools/list carry the live source list, filter schemas, and every verb's parameters — the contract is in-band. This skill is the judgement layer on top.