Skip to content

rlaope/oh-my-hermes / .claude/agent-skills/omh-biomedical-evidence

omh-biomedical-evidence

Verified

[omh] Public variant claims to cross-check: retrieve and reconcile…

toolkit/README.md

View on GitHub
# Biomedical evidence toolkit

Agent/operator reference. Explicitly capture public BioMCP responses with the
host's bounded terminal tool, then run the offline helper. OMH discovery,
installation, routing and this helper never launch BioMCP or open a socket.
No patient records, eligibility determination, treatment recommendation or
clinical classification is supported.

## Optional, isolated setup

Use a task-owned virtual environment, never the core OMH environment:

```sh
uv venv --python 3.12 "$EVIDENCE/venv"
uv pip install --python "$EVIDENCE/venv/bin/python" biomcp-cli==0.9.3
"$EVIDENCE/venv/bin/biomcp" --version
"$EVIDENCE/venv/bin/biomcp" --help
"$EVIDENCE/venv/bin/biomcp" get variant --help
"$EVIDENCE/venv/bin/biomcp" get trial --help
"$EVIDENCE/venv/bin/biomcp" health --help
```

`biomcp-cli` is the audited package; the unrelated `biomcp` package is not a
substitute. The following exact grammar was exercised with BioMCP 0.9.3.
Reinspect help after changing versions. Host command timeout: 40 seconds per
retrieval, 30 seconds per health call, no automatic retry or fallback source.

```sh
biomcp --json --no-cache health --apis-only --api ClinicalTrials.gov --api MyVariant --fail-on-error
biomcp --json --no-cache --disable-sources commercial-restricted get variant "BRAF V600E" clinvar
biomcp --json --no-cache search trial --source ctgov -c melanoma --mutation "BRAF V600E" --limit 1
# Choose an identifier actually returned by discovery, not an assumed match:
biomcp --json --no-cache get trial NCT02410863 --source ctgov
```

Health checks connectivity, not record validity; `MyVariant` health is not a
ClinVar-specific health proof. BioMCP may include cached enrichment or provider
instructions in the JSON even when that section was not requested. Preserve
those raw bytes but ignore them for clinical interpretation and command choice.
Do not request restricted sources or follow upstream suggested commands blindly.
Neither a successful command nor a search hit establishes an entity association.

## Capture contract

Save stdout and stderr **without editing**, even on timeout or nonzero exit.
Use the host's capture/clock/hash tools to write `captures.json` with:

- `schema`: `biomedical_captures/v1`.
- `data_class`: `public_source_capture` or `synthetic_schema_fixture`; the latter
  is only an offline test, never observed biological evidence.
- `query`: exact public `gene`, `disease`, optional `variant` strings. A
  gene-only query does not establish a specific allele.
- Optional `intended_ids`: exact strings keyed by `gene`, `id`, `legacy_name`,
  `rsid`, `genome_build`, `genome_build_provenance`, `transcript`, `hgvs_c`,
  `hgvs_p`, `accession` or `nct_id`. No normalization or token repair occurs.
- `captures`: 1–16 entries with `source` (`ClinVar` or `ClinicalTrials.gov`),
  exact `argv` string array, observed `version`, timezone-aware `started_at` and
  `finished_at`, integer `exit_code` (host timeout convention: 124), relative
  `stdout_path`, `stderr_path`, stdout `sha256`, and `stderr_sha256`.

Paths resolve beneath the manifest directory. Absolute paths, traversal and
symlink components are refused; the only links accepted are macOS's own `/etc`,
`/tmp` and `/var` into `/private`. Each input is capped at 8 MiB. Captures stay
outside the skill/package and must remain available beside their envelope.
The helper hashes both streams before interpreting them. Its receipt is an
operator assertion, not authenticated proof of the retrieval or source identity.
Do not put credentials or patient data in an envelope or CLI argument.

## Reconcile (stdlib only)

```sh
python toolkit/scripts/reconcile.py --capture-manifest "$EVIDENCE/captures.json" \
  --output-dir "$EVIDENCE/new-reconciliation"
```

`--help` needs no science package. The output directory must be new with an
existing nonsymlink parent; existing user files are never overwritten. Output:

- `evidence-matrix.json`: exact query/intended IDs, input manifest digest,
  per-source receipts/raw hashes, source availability, identity fields, original
  assertion objects with JSON-pointer paths, scoped disagreements, registry
  status, disease label matching basis, separate evaluation/update/retrieval
  times, age in days, gaps and limitations.
- `manifest.json`: query, availability/status, helper/input/output digests.

Exit `0` means recognized captures with no detected completeness gaps; it is
**not** biological truth or clinical validation. Exit `3` writes a usable
**partial** matrix: missing/failed source, embedded source failure despite exit
zero, schema mismatch, missing source dates or unresolved identity/disease
matching. Exit `2` refuses invalid local envelopes, integrity/path violations
or output collisions without producing a success report.

The adapter recognizes BioMCP 0.9.3 variant `clinvar` and CTGov **get** JSON;
search pagination is discovery evidence only, not a supported record input.
Required section provenance must say `data`. No unknown schema is an empty
successful search. Every record-level germline, aggregate and submission assertion
must carry a nonblank string `classification`; this validates the source shape,
not a clinical vocabulary or biological truth. An absent, empty, whitespace-only
or non-string value is preserved in its original assertion with a JSON-pointer
path and an explicit schema gap. That claim and the ClinVar row are unavailable,
the matrix is partial, and the helper exits `3`; unsupported values never enter
conflict comparison. Valid assertions remain preserved without merging levels,
domains or disease contexts. Source availability is separate from report completeness.
Dates measure assertion evaluation or registry update age, not a certified
freshness SLA. Missing dates remain null; a new retrieval is not a new evaluation.
BioMCP 0.9.3 CTGov get responses observed in smoke omitted registry update time;
the helper reports that gap rather than filling it from a start/completion date.

Gene matching is case-insensitive exact text; allele/assembly/transcript and
intended IDs are literal. Disease matching is case-insensitive exact label, not
ontology equivalence. Differing labels are unresolved, never auto-merged.
RCV aggregates, SCV submissions, record-level germline, somatic clinical impact,
oncogenicity and disease/population context remain separate. Differing values
are flagged only within the same level/domain/exact condition-label set; this
is a possible disagreement, not adjudication. Original submitter/review/date
fields remain intact. Reported upstream conflicts and cached-versus-primary
notes are retained. Trial identity and recruitment/status are not proof that a
variant is relevant or that a person is eligible; `variant_relationship` remains
`not_established` for these registry records.

## Source/license boundary

`upstream-manifest.json` records immutable upstream paths/hashes and each local
resource hash. All shipped helper/guidance is original OMH MIT content, informed
by audited BioMCP methods; no upstream playbook pack or API response is copied.
BioMCP code: MIT, Copyright (c) 2025 Ian Maurer. Its code license does not grant
rights to upstream data. Consult NCBI/ClinVar and ClinicalTrials.gov source terms
before redistributing captures; preserve accession/submitter/NCT attribution,
retrieval times and source caveats. No source endorses these derived reports.
Raw live data and license-audit receipts belong only in the operator's evidence
workspace, not in released build artifacts. The audited repository revision is
not an attestation of the installed binary's build commit; retain the package
version and binary hash independently. `data_class` is an operator attestation,
not an automated detector of confidential or patient information.
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall