Genomi

Genomi gives agents local tools for genetics and DNA-aware evidence work. Use it when the user's request is about variants, genes, phenotypes, disease genes, biological screens, medication response, ancestry reference-panel context, polygenic-score context, or a genome source.

How To Call Genomi

Call Genomi through the MCP server: mcp__genomi__<operation> (or your host's equivalent namespace).

If those tools are missing from the current session's tool list but the host's MCP list shows Genomi connected, the session pre-dates the server's registration. Ask the user to start a new session.

Core Rules

• Public by default: if the chat has not mentioned a genome source, answer from public/tool sources only.
• Active Genome Index context is chat-scoped: use it only when this conversation provides a genome source, names a previous run, asks about the selected Active Genome Index context, or says something like "my Active Genome Index" or "my genome".
• If the user provides a genome source path in this chat, that is approval to read that source for this session.
• If the user says "my Active Genome Index" or "my genome" without a path, it is acceptable to check for an already imported Active Genome Index context.
• Reading imported/parsed Active Genome Index artifacts, resuming a previous run for evidence, or searching for an existing "my Active Genome Index"/"my genome" context requires explicit user approval for this session. Record approval with active_genome_index.approve_access before calling those tools.
• Do not use unrelated genome sources from other chats, workspaces, or external evaluation tasks.
• Call narrow tools first and inspect evidence before making a claim.
• Treat this root skill as static startup guidance. Do not infer live session state from it; use genomi.describe_context, genomi.check_libraries, and tool result envelopes for changing context.
• If an MCP tool returns status="in_progress", call genomi.check_background_job with the returned job_id. Do not retry the same work with a capped parse or raw text scan unless the user asks for that fallback.
• Only send parameters supplied by the current user request, current Genomi context, a previous Genomi result, explicit user approval, or an explicit override. Omit unknown optional parameters.
• Defaults are part of the reasoning chain. Tool definitions expose parameterDefaults; returned results include defaults_applied for omitted defaults so the host agent can inspect and override them in a follow-up call when the user intent requires it.
• Tool definitions expose dependencyContract when a tool needs local installed libraries or external network/API sources. Missing local libraries return requires_library_install; unavailable external sources return source_unavailable; local source-file requirements appear as localResources.
• In the final answer, mention Active Genome Index use only when it materially affects the result: for example, it supports or refutes a user-specific claim, changes a limitation, blocks an operation until approval, or explains a required next action. Do not add a routine source-status line.
• Derive confidence dynamically for each Genomi-guided answer from tool evidence, source trust, coverage, conflicts, and missing evidence. Do not use a static default confidence or a user-selected confidence profile. Genomi result fields describe evidence support, coverage, overlap, and source state; they are not final answer-confidence labels.
• Use genomi.describe_context when the user asks about personal context, their own genome/context, a genome source, a previous run, a selected user, or before making sample-specific claims. When you call it, inspect active_response_profile.guidance; the active profile id is persisted in the Genomi registry (set via genomi.set_response_profile) and falls back to the catalog default when none is set. Do not call it only to bootstrap a public-only question.
• Handle Active Genome Index lifecycle states yourself. When a read op's envelope or genomi.describe_context returns active_genome_index_readiness.status == "needs_reparse", look up the recorded source path under active_genome_index.agi_intake_source_path and call genomi.parse_source with it — routine maintenance, no user prompt needed. Only ask the user when availability.agi_intake_source_path is false (path moved or deleted) or the status is schema_too_new (Genomi runtime out of date). Never proceed with a stale Active Genome Index while silently substituting placeholder data; use the Active Genome Index skill for the full procedure.
• For search-like operations, pass host-inferred alternate wording in semantic_context when the current chat reasonably supports alternate biomedical wording. Send the user's original wording as raw_query, add host_expansions only as retrieval terms, and add host_entities for helpful proposed spans such as drug, gene, phenotype, trait_or_condition, variant, or rsid. These terms are retrieval inputs, not evidence; Genomi reports source/retrieval hits in term_matches and no-hit terms in term_misses.

Routing

MCP tools/list returns only the base set:

• genomi.* and journal.* ops (always direct-callable).
• genomi.invoke — the dispatcher for every other capability tool.

To use a non-base capability tool, load the matching focused capability skill, then call:

genomi.invoke({"tool": "<operation_name>", "params": {...}})

Example:

genomi.invoke({"tool": "variant.resolve", "params": {"rsid": "rs429358"}})

The dispatcher validates the registered operation name, runs the underlying tool's input-schema validation, and returns the underlying tool's response with an added dispatched_tool field.

Operation namespaces are tool-name prefixes, not disclosure branches. Use namespace filters only for debugging or audits.

Resolve context, select the intent capability, read its skill markdown, call the smallest useful operation through genomi.invoke (or direct call for base tools), inspect evidence, journal material findings, and continue until the answer is supported. Use genomi.describe_context only when this chat asks about personal context, the user's own genome/context, Active Genome Index context, a selected user, a genome source, or a previous run.

Setup

genomi.install installs or updates Genomi, and genomi install / genomi update are the same operation. It always updates everything that can be updated: the runtime code (git pull --ff-only on a git checkout, unless GENOMI_SKIP_RUNTIME_GIT_PULL is set for a non-git distribution), all public reference libraries into GENOMI_HOME (idempotent — each installed library is checked against its source and re-downloaded only if it changed upstream, so re-running transfers nothing when nothing changed; pass force to re-download regardless), host-agent skill symlinks in detected host skill directories (including stale/dangling repair and obsolete Genomi capability-link removal), the public retrieval indexes, and a background reparse of any genome whose index schema is older than the updated runtime's. There are no per-step skip flags — genomi update does the full update by default. The libraries parameter only narrows which reference libraries to materialize (default everything): pass a specific library (or comma-separated set) to install just those — both for an install-time subset the user chose and to add a single new library on demand at runtime (the "install this missing library" path). To see which libraries are already installed vs missing before deciding, call genomi.check_libraries (its summary reports installed_count / missing_count). This applies once Genomi is installed; first-time setup on a machine without the genomi runtime follows the source bootstrap in INSTALL_FOR_AGENTS.md.

Parsing A Genome Source

genomi.parse_source is a core genomi.* tool: it detects, parses, and digitizes a genome source (VCF/gVCF, BAM, paired-end FASTQ, or a consumer-array raw genotype export from 23andMe, AncestryDNA, MyHeritage, FamilyTreeDNA, or Living DNA; bare text/CSV, gzip/bzip2/xz-compressed, or inside a zip/tar archive; or a .genome/1.0 bundle such as sample.genome.tar.gz) into a queryable Active Genome Index.

• Use when: the user supplied a genome source in this chat and downstream questions need a queryable Active Genome Index this session.
• Why: raw VCF/BAM/genotype files are too large and irregular for reliable direct reasoning; parsing builds the scoped index later tools query.
• Not for: public-only genetics questions, selecting an already-parsed index, or capped sample scans that should not replace a complete index.
• Result: digitizes local intake into an Active Genome Index; Genomi auto-detects the source type. Supplying user_nickname links the parsed artifact to a user profile. It does not run whole-callset annotation — focused tools materialize public libraries lazily when their evidence is needed.
• If it returns status="in_progress" with a job_id, poll genomi.check_background_job; don't substitute a capped parse or raw scan unless the user explicitly asks for a fallback.
• gVCFs parse in two phases. A gVCF is ~96% reference blocks, so the parse returns as soon as every variant is stored and indexed — the result reports variants_ready (not yet completed) and the whole interpretation surface (rsID, gene, region, exact-allele lookup, ClinVar, PRS, …) is already correct. The reference-block tail is appended by a detached background job (active_genome_index.build_reference_pass) whose job_id is surfaced in the result's next_actions. Until that job reports completed, only "is this locus confirmed reference vs not-callable" coverage answers are provisional — every readiness/coverage result carries reference_pending to say so. Plain VCFs, small files, and capped (max_records) parses stay single-phase. Other sources (consumer arrays, BAM/FASTQ) have no reference tail to defer.
• After a parse, offer to name the profile. When the user did not pass user_nickname, the result includes an ask_user next action: ask them for a profile nickname and whether to set it as the machine default, then record it by re-running with user_nickname (+ set_default_user=true) or via the invoke-only active_genome_index.assign_user_genome / set_default_user tools — exactly the offer INSTALL_FOR_AGENTS.md Step 8 makes.

The parse/digitize/user-management workflow (selecting users, approving access, assigning a genome to a profile, lifecycle reparse) lives in the Active Genome Index skill, which also owns the active_genome_index.* interpretation tools.

Journal

Use journal when an investigation spans multiple Genomi tools and the host agent needs to record reasoning over evidence. Journal entries are agent notes with traceability links; they are not source evidence and should not be used as candidate-ranking source_records.

Default Tools

These tools appear in the default tool list. Their full metadata is available without expansion.

Genomi context and users:

• genomi.check_background_job
• genomi.check_libraries
• genomi.describe_context
• genomi.install
• genomi.invoke
• genomi.list_resources
• genomi.search_indexes

Active Genome Index:

• genomi.parse_source

All other active_genome_index.* tools are invoke-only: reach them via genomi.invoke after loading the Active Genome Index skill.

ClinVar:

• clinvar.match_variants
• clinvar.scan_candidates

ClinVar exact matching uses the build-specific optional library clinvar-grch38 or clinvar-grch37. If the tool reports requires_library_install, use genomi.check_libraries and ask before installing.

Variant evidence:

• variant.resolve

Journal and research memory:

• research.build_target_packet
• research.list_sources

Phenotype, disease, and candidate gene:

• phenotype.compare_disease_evidence
• phenotype.compare_drug_target_evidence
• phenotype.compare_gene_hpo_evidence
• phenotype.plan_risk_investigation
• phenotype.retrieve_disease_drug_targets
• phenotype.retrieve_gene_disease_associations
• phenotype.retrieve_trait_gene_records

Pharmacogenomics:

• pharmacogenomics.review_medication

GWAS Catalog:

• gwas.compare_gene_associations
• gwas.compare_variant_associations

Functional genomics:

• functional_genomics.compare_gene_perturbation

Ancestry reference-panel context:

• ancestry.list_reference_panels
• ancestry.estimate_population_context

Polygenic scores:

• prs.search_scores
• prs.calculate_score

Sequence:

• sequence.analyze

Analytical grounding:

• cell_type.retrieve_markers
• pathway.retrieve_members
• region.retrieve_features

Journal:

• journal.append_entry
• journal.search_entries

Default-complete categories:

• gwas-catalog
• analytical-grounding

Candidate Evidence

Candidate and ranking operations return evidence views, decision_evidence, warnings, and coverage. Use source-specific candidate-gene tools instead of a universal comparator: phenotype.compare_gene_hpo_evidence for HPO/single-subject phenotype matching, gwas.compare_gene_associations for GWAS Catalog gene-field evidence, phenotype.compare_drug_target_evidence for drug-target evidence, and functional_genomics.compare_gene_perturbation for perturbation evidence. phenotype.retrieve_trait_gene_records retrieves trait-to-gene records from integrated sources. Records labelled association_only_not_causal are visible evidence, not an answer. Any operation that exposes an answer-shaped candidate result must expose the evidence behind that result. Use that evidence for the host-agent decision.

Multi-Stream Synthesis

When multiple Genomi capabilities can contribute orthogonal evidence to the same question, combine them — both in the initial plan and in follow-ups.

A scope-limited single-capability result (missing calibration, no record at locus, association-only, library-not-installed, low overlap, source unavailable, etc.) is not a final user-facing answer when other Genomi capabilities can contribute orthogonal evidence to the same question. Returning "I cannot answer" while applicable capabilities remain unexamined is a host-agent failure mode, not a Genomi limitation.

When multiple plausible plans differ materially in cost, surface the choice once with the tradeoff and commit to the user's pick. Over-checkpointing is itself a failure mode.

Answering

Lead with the answer. When a finding is grounded in a public dataset (ClinVar, GWAS Catalog, PGS Catalog, 1000 Genomes panel, etc.) and that source materially shapes the result, name the dataset inline in the prose. Keep clinical language informational and recommend clinical confirmation for medical decisions. Confidence is an answer-time synthesis judgment, not static metadata. Adapt explanation depth to the selected response profile without weakening evidence limits, privacy boundaries, or clinical-confirmation language.

Active Genome Index

Use this skill when the user provides a genome result file, asks to parse a genome source, asks what local Active Genome Index context exists, or asks a sample-specific question that requires a user file.

Goal

Create or refresh the private Active Genome Index and local evidence stores. Interpret health meaning only after the relevant evidence skill gathers support for the user's claim.

Convention: See skills/conventions/context-routing.md. Convention: See skills/_output-rules.md.

Contract

Contract:

• A supplied source file, an approved agi_id, or a default user's selected Active Genome Index is accessible before sample-specific work.
• GENOMI_HOME stores durable Active Genome Index records.
• Every genome source parsed by Genomi becomes an Active Genome Index record.
• User/profile nicknames belong to users, not genome artifacts.
• A user can have multiple genome records and one selected Active Genome Index.
• A default user is auto-selected for every session using this GENOMI_HOME, and readable access is scoped only to that user's selected Active Genome Index.
• genomi.parse_source digitizes the intake file so future inquiries use the Active Genome Index.
• The original intake path is hidden from normal agent-facing context after parsing.
• Parsing success creates a source-appropriate Active Genome Index for later interpretation.

Supported Sources

• VCF/gVCF: variant callsets with VCF records, genotype fields, optional depth/quality, and possible region callability.
• BAM: aligned sequencing reads. Genomi derives a local VCF from the reads with a matching reference FASTA, then builds an Active Genome Index for the derived callset for normal sample-specific tools.
• FASTQ (paired-end): raw reads from sequencing services such as Nebula, Dante Labs, and Sequencing.com. Genomi auto-detects the R2 sibling, picks minimap2 (long reads) or bwa-mem2 (short reads) by the median sniffed read length, sorts the aligned BAM with samtools, then hands the BAM off to the standard BAM → derived-VCF path. Requires the wgs-alignment install purpose (or aligner binaries on PATH); a missing aligner returns requires_library_install instead of failing.
• 23andMe raw genotype text or zip/tar archive: consumer SNP-array calls with rsid, chromosome, position, and plus-strand genotype on GRCh37.
• genome.computer .genome/1.0 bundle directory or archive with manifest.json, schema.json, and partitioned variants.parquet records.
• AncestryDNA raw genotype text or zip/tar archive: consumer SNP-array calls with rsid, chromosome, position, allele1, and allele2 on GRCh37/build 37.1.
• MyHeritage raw genotype CSV or zip/tar archive: comma-delimited RSID,CHROMOSOME,POSITION,RESULT exports prefixed with a # MyHeritage DNA raw data banner, GRCh37.
• FamilyTreeDNA Family Finder autosomal CSV or compressed/zip/tar archive: same RSID,CHROMOSOME,POSITION,RESULT columns as MyHeritage but with no banner, build encoded in the filename (_o37_), GRCh37.
• Living DNA autosomal text or zip/tar archive: tab-separated rsid/chromosome/position/genotype rows with a # Living DNA customer genotype data banner on GRCh37.

VCF deliverables from named consumer sequencing services (Nebula Genomics, Dante Labs, Sequencing.com) are accepted through the generic VCF path; the source provider is detected from header signatures and surfaced as provider on the parse result.

Cross-Capability Synthesis

A scope-limited result from this capability is not a final user-facing answer when other Genomi capabilities can contribute orthogonal evidence to the same question. Returning "cannot answer" while applicable capabilities remain unexamined is a host-agent failure mode.

Tools

active_genome_index.classify_callset_qc

Classify genome callset shape, depth/quality field availability, and absence-claim boundaries using an Active Genome Index.

Use when: Use before broad Active Genome Index claims when the agent needs callset shape, QC fields, and absence-claim boundaries.

Why necessary: Broad Active Genome Index claims depend on whether the artifact actually contains the fields and coverage needed to support them.

active_genome_index.summarize

Summarize local parse/readiness/evidence state for an Active Genome Index.

Use when: The agent needs a compact status check for an Active Genome Index before deciding whether parsing, library-scoped evidence materialization, or evidence refresh is needed.

Why necessary: Agents need Active Genome Index readiness and artifact status before deciding whether to reuse, resume, materialize, or answer.

Example prompts: What Active Genome Index context is active?

Result semantics: Summarizes local Active Genome Index and evidence artifact state; it does not parse new input or perform interpretation.

active_genome_index.assign_user_genome

Assign an existing or supplied genome source to a user/profile and optionally make it that user's selected Active Genome Index.

Use when: A genome source or existing genomi agi should belong to a named user/profile.

Why necessary: One user can own multiple genome artifacts while selecting exactly one Active Genome Index as active for that profile.

Not for: Parsing a source into a complete Active Genome Index; use genomi.parse_source when digitization is needed.

Example prompts: Assign this VCF to Alice.

Result semantics: Links user metadata to genomi agi metadata. Supplying a source path grants scoped session access to that source's resolved Active Genome Index.

active_genome_index.clear_default_user

Clear persistent default user/profile selection for this GENOMI_HOME.

Use when: The user no longer wants any user/profile auto-selected by default.

Why necessary: Users need an explicit way to remove persistent default Active Genome Index context without deleting users or Active Genome Index artifacts.

Example prompts: Stop auto-selecting the default user.

Result semantics: Clears default=true from all known users; session selections and artifacts remain.

active_genome_index.list

List users and Active Genome Index records.

Use when: The user asks what AGIs or users exist, or gives a vague AGI lifecycle request that needs disambiguation before selecting exact records.

Result semantics: Returns structured users and active_genome_indexes; AGI records include IDs, hashes, names, typed source references, source metadata, linked users, readiness, and artifact availability. It does not approve private reads.

active_genome_index.remove

Remove confirmed Active Genome Index records, user/profile records, and Genomi-owned AGI artifacts.

Use when: The user has confirmed the exact AGI and/or user/profile record(s) to remove.

Result semantics: AGI targets remove the targeted AGI registry/session record, session access grant, user/profile AGI links, and Genomi-owned run artifacts. User targets remove user/profile metadata and default/session user selection; linked AGIs remain unless the same confirmed call also targets those AGIs. The original intake source and shared evidence database are not deleted.

genomi.parse_source

genomi.parse_source is a core genomi.* tool, documented in the root Genomi skill (SKILL.md → "Parsing A Genome Source"). This skill drives the workflow around it — select user, approve access, assign the parsed genome to a profile, and lifecycle reparse — plus the active_genome_index.* interpretation tools.

active_genome_index.rename_user

Rename a user/profile nickname.

Use when: The user wants to rename a person/profile.

Why necessary: Human-friendly names belong to users, while Active Genome Index IDs remain stable hash-based artifact identifiers.

Example prompts: Rename this user to Alice.

Result semantics: Updates one user nickname. Active Genome Index artifact IDs are unchanged.

active_genome_index.select_user

Select a user/profile for this session without granting private artifact access.

Use when: The user names a person/profile and the agent needs to make that user's selected Active Genome Index the session metadata context.

Why necessary: Selecting another user should be metadata-only until active_genome_index.approve_access grants access to that user's selected Active Genome Index.

Example prompts: Use Alice's genome context.

Result semantics: Sets the selected user and selected Active Genome Index metadata; private reads still require scoped access approval unless this is the default user.

active_genome_index.set_default_user

Set the default user/profile for this GENOMI_HOME.

Use when: The user wants one profile's selected Active Genome Index available by default in every session.

Why necessary: Default access is scoped to a user's selected Active Genome Index rather than all genomes or all users.

Example prompts: Make Alice the default user.

Result semantics: Sets exactly one default user. Persistent private read access applies only to that user's active_agi_id.

Selection Notes

• Use genomi.describe_context to inspect selected session context.
• If the user supplied a source file and the answer needs sample evidence, first inspect whether the same source or a known complete Active Genome Index is already selected. Use the existing complete Active Genome Index when available; call genomi.parse_source --params '{"source":"<path>"}' only when no complete matching Active Genome Index exists or Genomi reports the Active Genome Index is incomplete.
• If genomi.parse_source returns status="in_progress" with a job_id, keep polling genomi.check_background_job for that job. Do not switch to a capped parse or raw text scan as a substitute for the full active Active Genome Index unless the user explicitly asks for a temporary fallback.
• Do not add max_records for user-facing inspection when a complete Active Genome Index may already exist. A capped parse is only an explicit sampling/debug choice, not the normal path for "anything notable?".
• If a focused evidence tool returns status="requires_library_install", explain what the named library enables for the user's intent and ask whether they want it installed. Do not treat missing library data as negative evidence.
• If the user supplied a known agi_id, call active_genome_index.approve_access --params '{"approved_by_user":true,"agi_id":"..."}' only after explicit approval for this session.
• If the user supplied a user nickname, call active_genome_index.select_user for metadata selection, then call active_genome_index.approve_access if sample evidence is needed and the selected user is not the default user.
• For interpretation work, load the matching focused capability skill and call its capability tools through genomi.invoke.

Boundaries

• Raw genome source files stay local.
• Durable Active Genome Index records in GENOMI_HOME become readable only when the session explicitly approves the resolved agi_id, supplies a source path, or uses the default user's selected Active Genome Index.
• VCF/gVCF parsing does not import public sources or build whole-callset static artifacts. Use focused tools such as clinvar.match_variants, active_genome_index.classify_genotype_support, or region.retrieve_features when that evidence is needed. BAM parsing also requires local samtools and bcftools.
• Consumer array calls support rsID/locus presence checks. Sequencing depth, genotype quality, phasing, and region callability come from sequencing-derived sources.
• If the user asks a tiny factual question and an Active Genome Index already exists, prefer variant.resolve from the variant evidence skill to resolve the target and query the Active Genome Index.
• If parsing already succeeded, the original file is an intake source. Future inquiries should normally use the Active Genome Index.
• For genetics questions outside Active Genome Index workflows, use Journal source-review memory, GWAS, or normal agent research without adding a routine source-status line.

Reference pass (variants_ready → completed)

A gVCF parse returns variants_ready once every variant is stored, then appends the reference-block tail in a detached background job. At variants_ready every variant query is correct; only "is this locus confirmed reference vs not-callable" coverage answers are provisional (readiness and the individual coverage/callability/genotype-support results carry reference_pending). Don't reparse to "finish" it — poll genomi.check_background_job with the surfaced job_id, or simply re-query once readiness reports completed.

active_genome_index.build_reference_pass

Internal — do not invoke by hand. genomi.parse_source launches this automatically as a background job after a gVCF reaches variants_ready, and surfaces its job_id in the parse result's next_actions. It appends the reference-block tail to the variants_ready index and flips it to completed. It is idempotent (a no-op on an already-complete index). The only thing you do with it is poll its job_id via genomi.check_background_job if the user is waiting on reference-coverage answers.

After Parsing

Select the focused skill from the user intent:

• ClinVar discovery: ClinVar skill
• Specific variant/gene/rsID: variant evidence skill
• GWAS phenotype plus rsIDs: GWAS Catalog skill
• All-at-once dashboard / one-shot rundown: decode skill

Lifecycle: handle needs_reparse and schema_too_new automatically

genomi.describe_context (and every read op's error envelope) returns an active_genome_index_readiness block with status and a structured reason code. The agent must reconcile lifecycle state on its own before falling back to the user.

status: needs_reparse (reason: active_genome_index_needs_reparse)

The on-disk Active Genome Index was built by an older Genomi runtime than the current SCHEMA_VERSION. Reparse rebuilds it at the current schema.

1. Read active_genome_index.agi_intake_source_path from genomi.describe_context. Check active_genome_index.availability.agi_intake_source_path.
2. If availability.agi_intake_source_path is true (path is still on disk), call genomi.parse_source({"source": "<path-from-describe_context>"}) without prompting the user — this is routine maintenance.
3. If availability.agi_intake_source_path is false (path moved or deleted), ask the user once: "Your Active Genome Index needs to be reparsed at the new schema, but the original source isn't at <recorded path> anymore. Send me the current path, or restore the file there." Wait for the user, then parse that path.
4. After reparse, call genomi.describe_context again to confirm active_genome_index_readiness.status == "complete". Then continue the original request (decode, variant lookup, PharmCAT, whatever the user asked for).

status: schema_too_new (reason: active_genome_index_schema_too_new)

The Active Genome Index was built by a newer Genomi than the current process. Do not reparse — that would downgrade the Active Genome Index. Tell the user the runtime is out of date and they need to upgrade Genomi.

Incomplete (missing objects)

Continue with what's available; surface honest "Not gathered" notes in any downstream artifacts. Do not silently substitute mock or placeholder data.

Context Checks

• Select the Active Genome Index from the session's source path, approved agi_id, or default user.
• Use an existing Active Genome Index when it answers the question.
• Use variant.resolve for rsID, allele, locus, or region checks after parsing.
• Treat broad candidate inventories as triage inputs.
• Keep raw genome source content and broad match files local.

Analytical Grounding

Use this skill for source-declared records that ground an analytical statement, without asking Genomi to choose the interpretation.

Use When

• The input is a controlled pathway or gene-set name/id and the agent needs its canonical member genes.
• The input is a controlled cell type and the agent needs marker-gene records.
• The input is a genomic interval and the agent needs overlaps against declared GENCODE or ENCODE annotation files.

Operations

• pathway.retrieve_members: retrieve Reactome, KEGG human pathway, or supplied or installed MSigDB Hallmark GMT member genes. Use a source for free-text pathway names unless the identifier prefix makes the source clear.
• cell_type.retrieve_markers: retrieve HPA single-cell marker records, installed CellMarker/PanglaoDB tables, or supplied marker tables.
• region.retrieve_features: retrieve interval overlaps from supplied or installed GENCODE GTF and/or ENCODE cCRE BED files for GRCh37/GRCh38. Supply assembly; without it the tool reports unsupported assembly instead of guessing a genome build.

Boundaries

• These are retrieval verbs over declared source coverage.
• Do not use them as experimental protocol recommendations, workflow templates, or free-text biological interpretation.
• Treat coverage_status literally:
  • data_returned: declared source records were returned.
  • in_scope_empty: the input was in declared scope, and no records matched.
  • out_of_scope_for_input: the source, assembly, identifier, or required source file is outside declared coverage.
• Preserve source priors. A pathway member, marker gene, interval overlap, or druggable-target membership row is evidence context, not a selected answer.

Examples

• pathway.retrieve_members with {"pathway_id_or_name":"R-HSA-70635"}
• pathway.retrieve_members with {"pathway_id_or_name":"hsa00010"}
• cell_type.retrieve_markers with {"cell_type_id_or_name":"hepatocytes","source":"hpa"}
• cell_type.retrieve_markers with {"cell_type_id_or_name":"Hepatocyte","source":"cellmarker"}
• region.retrieve_features with {"region":"1:1000-1250","assembly":"GRCh38"}

The installer can cache gencode-grch38, gencode-grch37, encode-ccre-grch38, panglaodb-markers, and cellmarker-human under GENOMI_HOME. MSigDB Hallmark requires a user-supplied official GMT export.

Cross-Capability Synthesis

A scope-limited result from this capability is not a final user-facing answer when other Genomi capabilities can contribute orthogonal evidence to the same question. Returning "cannot answer" while applicable capabilities remain unexamined is a host-agent failure mode.

Tools

cell_type.retrieve_markers

Retrieve canonical marker genes for a controlled cell-type source entity.

Use when: Returns source-declared marker genes for HPA single-cell records or supplied CellMarker, PanglaoDB, or ENCODE marker tables.

Why necessary: Cell-type identity questions need marker records, not disease genetics or GWAS evidence.

Result semantics: Returns marker records only; it does not annotate clusters, assign cell identities, rank cell types, or interpret cell states. Free-text cluster IDs and hypothetical cell-state labels are out of scope.

pathway.retrieve_members

Retrieve canonical member genes for a controlled pathway or gene-set source entity.

Use when: Returns source-declared member genes for Reactome pathways, KEGG human pathways, or supplied MSigDB Hallmark GMT gene sets.

Why necessary: Pathway membership is a grounding fact and should be retrieved separately from disease or variant claims.

Result semantics: Returns pathway membership records only; it does not infer pathway activity, choose genes, or summarize pathway biology. Free-text pathway names should include source unless the identifier prefix implies a declared source.

region.retrieve_features

Retrieve genomic-region feature annotations from supplied or installed GENCODE and ENCODE annotation files.

Use when: The user or an upstream tool supplies a genomic interval and the agent needs transcript or regulatory-feature overlaps for an explicit GRCh37 or GRCh38 assembly.

Why necessary: Genomic coordinates need gene and regulatory feature context before they can be biologically discussed.

Result semantics: Returns source-declared interval overlaps for the assembly shown in query. Empty results mean no overlap in declared files, not biological absence outside declared coverage.

Ancestry Reference-Panel Context

Use this skill when the user asks about ancestry, population context, PCA projection, reference-panel similarity, or which public reference samples their genome is closest to.

Contract

• This capability is a local reference-panel workflow, not an ethnicity or race predictor.
• Private tools require current-session Active Genome Index access approval or a genome source path supplied in the current chat.
• Public metadata tools do not read an Active Genome Index.
• Private genotype data stays local. Do not upload sample genotypes to external APIs or URLs.
• The MVP supports GRCh38 and GRCh37. If genome_build is omitted, the tool default is GRCh38 unless an approved Active Genome Index provides another build; the returned defaults_applied records that default.
• Labels are 1000 Genomes reference-panel labels, not ethnicity, nationality, race, tribe, caste, religion, or personal identity.
• Output is qualitative reference-panel similarity in PCA space. Do not produce component percentages, admixture proportions, haplogroups, local ancestry, ancestry dates, or relative matching.

Convention: See skills/conventions/context-routing.md. Convention: See skills/conventions/evidence-quality.md. Convention: See skills/_output-rules.md.

First Actions

1. Use ancestry.list_reference_panels to check whether the matching-build 1000 Genomes 30x panel is installed and to inspect source URLs and label definitions.
2. Use ancestry.build_source_context when the user asks what the panel means or when you need explicit label and method boundaries before answering.
3. For sample-specific questions, use genomi.describe_context only when the chat asks about current Active Genome Index context or already mentioned a genome source. If the user supplied a genome source path, that is approval to read it for this session.
4. Use ancestry.estimate_population_context as the default sample-specific entry point. It runs overlap QC and PCA projection when enough markers are usable.
5. Use ancestry.check_sample_overlap when you only need QC readiness, and ancestry.project_pca when the host agent needs raw PCA coordinates and nearest reference-neighbor distances.

Library Handling

The required optional library is build-specific: ancestry-1000g-30x-grch38 for GRCh38 samples and ancestry-1000g-30x-grch37 for GRCh37 samples. If a private ancestry tool returns requires_library_install, explain that the compact local panel is needed for marker overlap and PCA projection, then ask before installing with the returned ask_user.install_command or missing_library.install_command. For example:

genomi install --libraries ancestry-1000g-30x-grch38
genomi install --libraries ancestry-1000g-30x-grch38,liftover-chains,ancestry-1000g-30x-grch37

Do not treat a missing panel as evidence about the sample.

Interpretation Rules

• Report marker overlap, projection readiness, marker-overlap quality, nearest reference group labels, and the method boundary.
• Marker-overlap quality is graded by the fraction of the loaded panel covered by usable sample dosages. There is no absolute marker-count floor.
• If less than 20% of the loaded panel is usable, do not project.
• If 20%-49% of the loaded panel is usable, projection is allowed with low marker-overlap quality and reference-neighbor context only.
• If 50%-79% of the loaded panel is usable, projection is allowed with moderate marker-overlap quality.
• If at least 80% of the loaded panel is usable, projection is allowed with high marker-overlap quality.
• Use wording like: "The sample projects closest to the EUR reference cluster in this panel."
• Do not say "predict ethnicity", "determine origin", or imply personal identity from a reference-panel label.

User-Facing Answer Shape

If an Active Genome Index was projected, give the qualitative reference-panel similarity, marker-overlap quality, and limitations. If the tool only returned public metadata, answer directly without an Active Genome Index status disclaimer.

Cross-Capability Synthesis

A scope-limited result from this capability is not a final user-facing answer when other Genomi capabilities can contribute orthogonal evidence to the same question. Returning "cannot answer" while applicable capabilities remain unexamined is a host-agent failure mode.

Tools

ancestry.build_source_context

Explain 1000 Genomes ancestry panel provenance, label meanings, sampling limits, and method boundaries.

Use when: The user asks what the ancestry panel means, where labels come from, or why output is reference similarity rather than identity.

Why necessary: Ancestry language is easy to overstate; source context gives agents explicit label and method boundaries before answering.

Not for: Reading or projecting a user's genome; use ancestry.estimate_population_context after approval.

Example prompts: Explain the source and limitations of the ancestry panel.

Result semantics: Public metadata only; no Active Genome Index is read.

ancestry.check_sample_overlap

Check how many installed 1000 Genomes ancestry panel markers are usable in an approved Active Genome Index.

Use when: The agent needs to know if a selected sample has enough overlap with the installed ancestry reference panel before projection.

Why necessary: Projection is not interpretable below the overlap thresholds; this tool separates QC from interpretation.

Not for: Public panel metadata; use ancestry.list_reference_panels. Ethnicity or origin prediction; ancestry tools provide reference-panel similarity only.

Example prompts: Does my Active Genome Index have enough overlap with the ancestry panel?

Result semantics: Reports usable marker count and projection readiness. It must not be interpreted as ethnicity, nationality, race, tribe, caste, religion, or identity.

ancestry.estimate_population_context

Estimate qualitative reference-panel similarity for an approved GRCh37 or GRCh38 sample using local 1000 Genomes PCA projection.

Use when: The user asks for ancestry or population context from their genome and has approved Active Genome Index use in this session.

Why necessary: Provides a bounded default entry that combines overlap QC and PCA projection while preserving reference-similarity language.

Not for: Ethnicity prediction, determining origin, component percentages, haplogroups, local ancestry, or relative matching.

Example prompts: What 1000 Genomes reference cluster is my Active Genome Index closest to?

Result semantics: The interpretation is qualitative reference-panel similarity only and must never be phrased as ethnicity, nationality, race, tribe, caste, religion, or personal identity.

ancestry.list_reference_panels

List local ancestry reference panels, installation state, public source URLs, label definitions, and method boundaries.

Use when: The user asks what ancestry reference panels are available, whether the 1000 Genomes panel is installed, or what source data and labels are used.

Why necessary: Public panel metadata can be inspected without Active Genome Index access approval and tells agents whether private projection tools are answerable.

Not for: Projecting or interpreting a user's genome; use ancestry.estimate_population_context after Active Genome Index access approval.

Example prompts: What ancestry reference panel does Genomi have installed?

Result semantics: Returns public reference-panel metadata and install status only; it does not read Active Genome Index.

ancestry.project_pca

Project an approved sample into the installed 1000 Genomes ancestry PCA space and return nearest reference neighbors.

Use when: The user or host agent needs PCA coordinates and nearest reference neighbors after scoped Active Genome Index access is approved.

Why necessary: This is the focused computational step behind ancestry.estimate_population_context and avoids component/admixture proportion claims.

Not for: Haplogroups, local ancestry, relative matching, component proportions, or identity/origin prediction.

Example prompts: Project my genome into the matching-build 1000 Genomes PCA panel.

Result semantics: Returns PCA coordinates and reference-neighbor distances only; labels are reference-panel labels, not personal identity labels.

ClinVar Evidence

Use this skill when the user asks about clinical labels, carrier findings, pathogenic/likely pathogenic entries, VUS, conflicting classifications, drug response, risk-factor labels, or ClinVar-derived discovery.

Goal

Build a candidate landscape from exact ClinVar matches. Use candidate_inventory as variant-level provenance evidence and candidate_review_groups as the carrier/condition review inventory.

Convention: See skills/conventions/evidence-quality.md.

Contract

• ClinVar matches provide exact/static evidence for source-backed interpretation.
• Exact matching requires the optional build-specific library clinvar-grch38 or clinvar-grch37.
• Candidate inventories are variant-level evidence, not interpretation.
• Candidate review groups are review targets. A heterozygous P/LP group can be carrier-relevance evidence; it is not a carrier-status conclusion.
• clinvar.scan_candidates returns an evidence view, grouped support, warnings, and coverage; use those fields rather than inferring priority from prose.
• By default, clinvar.scan_candidates includes P/LP, conflicting, VUS, risk/association/protective, drug-response, and benign ClinVar groups.
• If ClinVar matches are missing, clinvar.scan_candidates materializes them from the Active Genome Index before building the candidate inventory.
• VUS, conflicts, and low-review assertions are downgraded unless reviewed source evidence supports a stronger claim.
• Drug-response rows use pharmacogenomic source context before actionability is implied.

Cross-Capability Synthesis

A scope-limited result from this capability is not a final user-facing answer when other Genomi capabilities can contribute orthogonal evidence to the same question. Returning "cannot answer" while applicable capabilities remain unexamined is a host-agent failure mode.

Tools

clinvar.match_variants

Materialize exact ClinVar matches for comparable Active Genome Index variants using the installed build-specific ClinVar library.

Use when: After an Active Genome Index and the matching build-specific ClinVar library are available to materialize exact ClinVar/sample matches.

Why necessary: ClinVar matching is library-scoped materialization; it turns installed public ClinVar rows into exact matches for an Active Genome Index without forcing every genome-artifact task to run ClinVar.

clinvar.scan_candidates

Build a deterministic candidate inventory and candidate review groups from exact ClinVar matches, materializing those matches from the Active Genome Index when needed.

Use when: Broad Active Genome Index disease or risk triage when exact ClinVar candidate inventory is needed.

Why necessary: Broad disease triage needs bounded ClinVar variant provenance plus review groups instead of ad hoc spot checks over a large genome file. It performs missing match materialization internally before candidate scanning.

Interpretation Rules

• Pathogenic/likely pathogenic labels need zygosity, inheritance, population frequency, gene-disease context, and source quality.
• Carrier language belongs in phenotype.plan_risk_investigation with investigation_type:"carrier_review" after reviewing the group gates.
• VUS and conflicting labels use uncertainty/conflict wording.
• Drug-response labels require pharmacogenomic guideline context before clinical actionability is implied.
• Common association/risk/protective labels usually provide limited context for personal common-disease risk.

Routing Checks

• Prioritize ClinVar matches by actionability, review status, uncertainty, population context, inheritance, and zygosity.
• If a ClinVar operation returns status="requires_library_install", explain how the named library helps this request and ask before installing it.
• Treat ClinVar condition strings as database labels that need interpretation.
• Keep the whole candidate inventory local; send selected public targets to Journal source-review memory.

Drug Targets

Use this skill for disease-scoped clinical drug-target retrieval, direct drug-target records, PharmaProjects-style target context, ChEMBL mechanism genes, DrugBank target context, or candidate-gene review for a drug, drug class, or mechanism.

Contract

• Direct drug-target or mechanism evidence outranks target-disease association scores and GWAS-style association.
• ChEMBL, DrugBank, and PharmaProjects-style records can support direct target claims when the source supports both the gene and the drug, class, mechanism, or indication context.
• Open Targets association context is useful for review; direct drug-target evidence comes from source records that support the drug, class, or mechanism relationship.
• Open Targets disease drug and clinical candidate records can retrieve disease-scoped clinical drug-target genes when the drug target comes from a mechanism-of-action row.
• Treat returned rankings as source evidence. The agent decides whether the drug-target prior matches the question. When using cross-source comparison, use prior_fit before reading a panel as task-relevant and audit decision_evidence before answering.

Tool Flow

1. phenotype.retrieve_disease_drug_targets retrieves Open Targets clinical drug candidate target genes for a supplied disease anchor.
2. phenotype.compare_drug_target_evidence compares candidate genes against direct drug-side context: drug, drug class, or mechanism.
3. If source support is missing, use research.list_sources to choose direct target sources, review them, and store narrow findings with research.record.
4. Re-run the same selected tool after recording reviewed findings.

Example:

• phenotype.retrieve_disease_drug_targets with {"disease":"asthma","genes":["ADRB2","IL13"]}
• phenotype.compare_drug_target_evidence with {"drug_class":"beta agonist","phenotype":"asthma","genes":["ADRB2","IL13"],"source_records":[{"genes":["ADRB2"],"drug_class":"beta agonist","verified_fields":{"genes":["ADRB2"],"drug_class":"beta agonist"},"support_spans":[{"field":"genes","text":"source-backed ADRB2 text"}]}]}

Source Records

Prefer source records with:

• genes: candidate target genes named by the source.
• drug, drug_class, indication, or mechanism.
• source_title, source_url, and source_type.
• finding or text: short source-backed finding.
• verified_fields and support_spans showing where the source supports the gene and drug-target or mechanism context.

Answering

Use a direct gene-symbol answer only when reviewed evidence supports the drug-target or mechanism relationship requested by the question. Otherwise state the source gap and summarize the strongest reviewed evidence without presenting it as the final target.

Cross-Capability Synthesis

A scope-limited result from this capability is not a final user-facing answer when other Genomi capabilities can contribute orthogonal evidence to the same question. Returning "cannot answer" while applicable capabilities remain unexamined is a host-agent failure mode.

Tools

phenotype.compare_drug_target_evidence

Compare candidate genes using direct drug-target or mechanism evidence only.

Use when: Returns direct drug-target, target-mechanism, ChEMBL, DrugBank, or PharmaProjects evidence for candidate genes.

Why necessary: Drug-target questions require direct target/mechanism evidence, which is distinct from disease association evidence.

Result semantics: Returns source-local drug-target evidence only; association-only evidence cannot create direct target support.

phenotype.retrieve_disease_drug_targets

Retrieve disease-scoped clinical drug-target genes from Open Targets drug candidate records.

Use when: Returns Open Targets clinical drug candidate target genes for a supplied disease anchor, with optional gene_membership projection for supplied candidate genes.

Why necessary: Clinical drug-target records answer therapeutic-target membership without implying causal genetics or treatment efficacy.

Result semantics: Returns disease-scoped clinical drug-target records and source-local ordering; the host agent decides how they apply. mode='gene_membership' projects the same source records into per-gene membership booleans and highest observed phase for supplied genes. Does not ingest agent-supplied evidence and does not infer treatment efficacy or final causal-gene answers.

Functional Genomics Perturbation Evidence

Retrieve functional-genomics perturbation evidence for a declared experimental context plus candidate genes. Screens are one supported perturbation experiment subtype, not the capability name.

Contract

Perturbation evidence comes from native public retrieval, user-provided local tables, reviewed stored research, or explicitly supplied source records. Generic gene biology can explain a result, but it should not outrank direct perturbation-source evidence.

Direct support is source-verified perturbation evidence. Source records carry verified fields or support spans for the requested cell line, perturbation, assay/readout, and candidate gene relationship; broader biology remains adjacent or plausibility-only evidence.

Native coverage currently includes BioGRID ORCS when a BioGRID ORCS access key is available, DepMap CRISPR gene-effect release tables when a CSV URL or path is configured, and bounded NCBI GEO metadata/table discovery. GEO's advantage is source discovery for public or published perturbation datasets: SeriesMatrix files, supplementary tables, and accession-indexed study records that curated screen APIs may not expose for the requested cell line, perturbation, assay, or readout. If native sources cannot be queried, the response makes that coverage state visible rather than weak ranking evidence.

Tool Flow

1. Extract candidate gene symbols and the requested context: organism, cell line, perturbation, assay, phenotype, resistance, sensitivity, viability, or readout.
2. Call functional_genomics.compare_gene_perturbation for the normal flow. It retrieves native public perturbation records when configured, verifies source records, and returns candidate evidence rows.
3. Call functional_genomics.retrieve_perturbation_records only for explicit native-source inspection, coverage debugging, or source availability review.
4. Call functional_genomics.query_geo when the advantage is public source discovery: the question mentions a published/public screen dataset, study accession, supplementary table, SeriesMatrix-style file, or compare has insufficient BioGRID/DepMap/stored evidence for a requested perturbation context that likely came from a public study. The user does not need to name GEO. GEO metadata alone is not direct evidence; direct support still requires table-derived, source-verified candidate gene and perturbation-context fields.
5. If the source is a local CSV/TSV result table, call functional_genomics.import_perturbation_table first.
6. Pass supplied, imported, or retrieved source records to functional_genomics.compare_gene_perturbation; it verifies source records before comparing candidate genes.
7. Use verified perturbation-source evidence when the user asks for only the gene symbol. Audit decision_evidence before explaining the result.

functional_genomics.compare_gene_perturbation returns evidence rather than a universal answer. If source records do not support an identifier-only answer, do not invent a gene; state the source gap or gather better source records.

Source Record Shape

functional_genomics.compare_gene_perturbation accepts reviewed source records. Prefer records that include the source title or URL, named genes, the source-backed finding, source type, and any verified perturbation context such as cell line, perturbation, assay, phenotype, readout, PMID, or DOI.

When a paper or dataset directly supports the requested perturbation context, include the specific source-backed spans that verify the cell line, perturbation, assay/readout, and gene relationship. Generic pathway or co-mention literature should remain adjacent evidence.

Direct perturbation-source context outranks generic literature or pathway plausibility only when source-backed fields verify the context. If no source records are supplied, or if records are generic literature without context verification, the tool cannot fairly make a high-support ranking.

Cross-Capability Synthesis

A scope-limited result from this capability is not a final user-facing answer when other Genomi capabilities can contribute orthogonal evidence to the same question. Returning "cannot answer" while applicable capabilities remain unexamined is a host-agent failure mode.

Tools

functional_genomics.compare_gene_perturbation

Compare candidate genes by verified functional-genomics perturbation experiment evidence.

Use when: Retrieves native public perturbation experiment records when configured, verifies source records, and returns candidate-gene evidence rows for the declared perturbation context.

Why necessary: Screen and dependency questions need verified perturbation evidence, not inherited-variant or disease association evidence.

Example prompts: Which candidate gene is best supported by this CRISPR resistance screen?

Result semantics: Runs source-record verification before candidate comparison; generic literature stays separate from direct perturbation experiment evidence.

functional_genomics.import_perturbation_table

Extract verified perturbation experiment source records from a local CSV or TSV result table.

Use when: The agent has a local CSV/TSV perturbation, dependency, viability, resistance, or supplementary result table and needs source records before candidate comparison.

Why necessary: User-supplied screen tables need structured extraction before they can support gene comparisons.

Result semantics: Extracts table rows into source records and verifies row-level genes plus perturbation context; it does not select the answer gene.

functional_genomics.query_geo

Query NCBI GEO metadata and bounded public study tables for functional-genomics perturbation source records.

Use when: The advantage is public dataset discovery: a published/public screen, study accession, supplementary table, SeriesMatrix-style file, or an under-covered perturbation context where curated sources did not provide direct source records.

Why necessary: GEO can find source-backed tables for study-specific cell lines, perturbations, assays, and readouts that BioGRID ORCS, DepMap, or stored reviewed records may not cover; it keeps metadata-only hits separate from direct perturbation evidence.

Result semantics: Returns GEO metadata hits, download candidates with skip reasons, and verified source records when candidate genes are supplied. Metadata-only matches never count as direct evidence; direct support requires source-verified gene plus requested perturbation context fields.

functional_genomics.retrieve_perturbation_records

Retrieve native public functional-genomics perturbation records from BioGRID ORCS and DepMap for candidate genes and declared experimental context.

Use when: Explicit native-source inspection, source availability review, or coverage debugging for BioGRID ORCS and configured DepMap perturbation records.

Why necessary: Raw native-source retrieval lets agents inspect what BioGRID ORCS or DepMap returned, or why a native source was unavailable, without running candidate comparison.

Result semantics: Returns native functional-genomics source records from BioGRID ORCS and configured DepMap release tables; it does not select the final gene. For normal candidate-gene comparison, use functional_genomics.compare_gene_perturbation directly because it can retrieve native records when configured. BioGRID ORCS requires an access key; DepMap requires a configured public CRISPR gene-effect CSV URL or path.

Genomic Inquiry

Use this skill as the default entry for natural-language DNA questions: personal triage, "what matters in my genome?", "do I have this variant?", variant/gene interpretation, GWAS-style questions, or public genomic background.

Goal

Turn the user's question into the smallest useful evidence action. A genome source is optional context. Use the Active Genome Index when present and relevant; with public-only context, answer from public sources, GWAS, and shared reviewed evidence.

Convention: See skills/conventions/context-routing.md before selecting Active Genome Index. Convention: See skills/conventions/evidence-quality.md before making personal or medical claims.

Contract

Contract:

• User intent drives the selected evidence path.
• The host agent resolves intent from this skill pack and tool outputs.
• Personal claims use only explicitly selected session context.
• Public-source answers do not need a routine Active Genome Index status line.
• Tool outputs are inspected before choosing additional operations.
• Operation metadata and focused skills guide tool choice; tool results are evidence for the host agent to interpret.
• Candidate and ranking tools return evidence views, alternatives, warnings, coverage, and source-prior detail for the host agent to interpret.

Agent Start

1. Use genomi.describe_context when the Active Genome Index is unknown.
2. Extract obvious fields from the user request: source, agi_id, user/profile nickname, rsid, gene, exact allele, phenotype, drug, condition, or topic.
3. Load the most specific focused capability skill, then call its capability tools through genomi.invoke.
4. Call one narrow tool and inspect its output before selecting additional evidence operations.

Personal Source Triage

For "what matters in my genome?" or similar broad personal questions:

• If a source path is supplied, build/select it with genomi.parse_source when an Active Genome Index is needed. The supplied source path is approval to read that source for this session.
• Run clinvar.scan_candidates to build a deterministic ClinVar candidate inventory. If the build-specific ClinVar library is missing, ask before installing clinvar-grch38 or clinvar-grch37.
• Inspect structured candidate guidance before selecting findings for follow-up or final interpretation.
• Drill into selected findings with variant.gather_allele_context, variant.gather_gene_context, active_genome_index.classify_genotype_support, or active_genome_index.classify_region_callability.

Group raw matches by actionability, clinical assertion strength, uncertainty/conflict, carrier context, common-risk or trait context, and limitations.

After genomi.parse_source, use the Active Genome Index for normal future inquiries. Surface the original intake file path for rebuild or validation work.

Specific Questions

• Personal rsID question with an Active Genome Index: use variant.resolve first.
• Personal exact allele question: use active_genome_index.classify_genotype_support and variant.gather_allele_context when allele support and source context are needed.
• Gene-level sample question: use variant.gather_gene_context and only make sample-specific statements for observed/sample-supported variants.
• Absence/reference claims require active_genome_index.classify_region_callability.
• Public variant/gene question with public-only context: use research.list_sources, research.build_target_packet, focused source review, and research.record when useful.
• Candidate genes: use the source-specific tool when the source family is clear: phenotype.compare_gene_hpo_evidence for HPO or single-subject phenotype matching, gwas.compare_gene_associations for explicit GWAS Catalog reported_gene/mapped_gene/source gene-field evidence, and phenotype.compare_drug_target_evidence for drug-target or mechanism evidence. phenotype.retrieve_trait_gene_records retrieves trait-to-gene records from integrated public sources and can be filtered by candidate genes. If several source families could answer the question, call the relevant source-specific tools separately and keep their evidence priors separate in the answer. GWAS Catalog mapped genes are not causal-gene assignments, and association_only_not_causal records cannot be the final support for a causal-gene answer.
• Analytical grounding: use pathway.retrieve_members for Reactome, KEGG, or Hallmark pathway member genes; cell_type.retrieve_markers for HPA, CellMarker, PanglaoDB, or ENCODE marker sources; and region.retrieve_features for local GENCODE/ENCODE interval overlaps.
• GWAS phenotype plus candidate rsIDs: load the GWAS Catalog skill, call gwas.compare_variant_associations, then select additional operations from the returned evidence. Variant lookup, ClinVar, Mendelian, sample, same-gene, or pathway context is follow-up context to report beside the population-trait GWAS Catalog rsID ranking.
• Functional-genomics perturbation context plus candidate genes: load the functional genomics skill, call functional_genomics.compare_gene_perturbation for the normal native-retrieve, verify, and compare flow, and answer from verified perturbation-source evidence rather than generic co-mention.

Outcome-Shaped Questions

Outcome-shaped questions ("will I get X?", "am I at higher risk for X?", "how likely am I to X?", "will I go bald?") are answered by combining capabilities that contribute orthogonal evidence to the same question. The combination is question-dependent.

Answer Contract

User-facing answers must include:

• The evidence classes used: sample observation, ClinVar/static source, population frequency, GWAS association, reviewed source, or limitation.
• Whether Active Genome Index evidence changed the result, limitation, blocker, or next action when that is material to the answer.
• The candidate evidence basis when present: source prior, direct versus adjacent or plausibility-only support, and any warnings.
• What matters for decision-making: answer support, genotype support, callability, source review, clinical confirmation, or user/clinical context.

Use informational medical language. Clinical decisions need clinician confirmation. Personal risk percentages need cited source support. External services receive selected public targets only.

Intent Checks

• Use source intake for questions that provide or require a genome source file.
• Resolve intent as the host agent using this skill pack and tool metadata.
• Treat session-selected source Active Genome Index records or Active Genome Index records as the Active Genome Index.
• Keep answers from public sources clear without adding a routine "no Active Genome Index" disclaimer.
• Use narrow variant/source tools for small factual lookups.

Cross-Capability Synthesis

A scope-limited result from this capability is not a final user-facing answer when other Genomi capabilities can contribute orthogonal evidence to the same question. Returning "cannot answer" while applicable capabilities remain unexamined is a host-agent failure mode.

Tools

phenotype.retrieve_trait_gene_records

Retrieve native trait-to-gene records from integrated public sources, optionally filtered to gene symbols.

Use when: Retrieves trait-to-gene records from Open Targets target-disease associations and disease clinical drug candidate records. The genes array is an optional filter, not the scope of the capability.

Why necessary: Trait-to-gene retrieval supplies native public records for complex traits without pretending to rank final causal genes.

Result semantics: Returns native retrieved source records grouped by gene and evidence regime; it does not return a recommended answer. Association-only records are labelled as association_only_not_causal. A clean empty result means the declared sources had no matching trait-to-gene records for the input trait and optional gene filter.

Population Frequency (gnomAD)

Fetch public gnomAD population allele frequencies for one variant. Results are cached locally in the evidence database so subsequent queries reuse them.

Activation

To call the tool below, invoke it through the MCP dispatcher:

genomi.invoke({
  "tool": "gnomad.fetch_population_frequency",
  "params": {
    "chrom": "19",
    "pos": 44908684,
    "ref": "T",
    "alt": "C",
    "genome_build": "GRCh38"
  }
})

The dispatcher validates the params against the underlying tool's input schema and returns the underlying tool's response with an added dispatched_tool field.

When to use this skill

• "What is the gnomAD frequency of rs429358?"
• "Is this variant rare in gnomAD?"
• "Allele frequency in African populations for rs1042522."
• Any question that needs MAF, AF, population-stratified counts.

Boundaries

• Variant-anchored only — query one allele at a time.
• Public population data only — does not read the user's Active Genome Index.
• Cached after first fetch — subsequent queries for the same variant reuse the local evidence store.

Cross-Capability Synthesis

A scope-limited result from this capability is not a final user-facing answer when other Genomi capabilities can contribute orthogonal evidence to the same question. Returning "cannot answer" while applicable capabilities remain unexamined is a host-agent failure mode.

Tools

gnomad.fetch_population_frequency

Fetch reusable gnomAD public population frequency for one allele and write it into evidence storage.

Use when: The agent needs gnomAD allele frequency, MAF, or population-stratified counts for a specific variant (rsID, chrom/pos/ref/alt, or VCF locus).

Why necessary: gnomAD is the canonical public population frequency source; cached results keep subsequent calls cheap.

Not for: Genome-wide rare-variant screening, ad-hoc curated annotations, anything not anchored to a specific variant.

Example prompts: What's the gnomAD frequency of rs429358? Is rs1042522 rare in East Asian populations?

Result semantics: Returns the gnomAD record with population-stratified counts and frequencies plus a populations block; writes to the local evidence database for reuse.

GWAS Catalog Association Evidence

Use GWAS Catalog association records for supplied phenotypes plus candidate variants or genes.

For phenotype plus candidate genes, gwas.compare_gene_associations returns GWAS Catalog reported_gene, mapped_gene, or source gene-field association evidence. phenotype.retrieve_trait_gene_records retrieves native trait-to-gene records from integrated public sources, optionally filtered by gene. If another source prior is relevant, call that source-specific tool separately and keep the evidence regimes separate. HPO or single-subject phenotype matching belongs outside this skill.

Goal

Retrieve and compare GWAS Catalog association evidence with explicit source-field and phenotype-match limitations. Personal interpretation requires separate sample support and careful wording.

Convention: See skills/conventions/evidence-quality.md.

Cross-Capability Synthesis

A scope-limited result from this capability is not a final user-facing answer when other Genomi capabilities can contribute orthogonal evidence to the same question. Returning "cannot answer" while applicable capabilities remain unexamined is a host-agent failure mode.

Tools

gwas.compare_gene_associations

Compare candidate genes using GWAS Catalog reported_gene and mapped_gene trait-association evidence.

Use when: The user gives a phenotype or trait plus candidate genes and asks for GWAS Catalog gene-field association support.

Why necessary: GWAS Catalog gene fields are source annotations for population-trait associations; they should stay separate from causal-gene, HPO, or drug-target evidence.

Not for: causal-gene claims unless separate causal evidence is supplied.

Result semantics: Returns source-local GWAS Catalog gene-field association evidence only. reported_gene and mapped_gene are source annotations and are not causal-gene evidence. Causal-gene or effector-gene wording returns wrong_evidence_regime with a routing hint.

gwas.compare_variant_associations

Compare candidate rsIDs by population-trait GWAS Catalog association evidence.

Use when: Returns GWAS Catalog population-trait association records for candidate rsIDs, ranked by trait match and p-value.

Why necessary: Population-trait rsID ranking needs GWAS Catalog evidence, not ClinVar or personal genotype evidence.

Not for: clinical disease diagnosis or personal genotype support.

Example prompts: Compare these rsIDs for LDL cholesterol GWAS evidence.

Result semantics: Returns public GWAS association evidence rows ranked by source trait match and p-value. For population-trait lead-variant tasks, GWAS Catalog evidence rows are the ranking source. Personal interpretation uses separate sample genotype evidence tools only after the source-ranked rsID decision.

Boundary

GWAS prioritization answers “which candidate has public association support for this phenotype?” Personal risk interpretation requires sample support, phenotype context, ancestry/source limitations, and careful claim wording.

For phenotype-plus-rsID questions, call gwas.compare_variant_associations directly. If personal context exists, choose follow-up rsIDs from the returned association evidence before checking sample support. Keep ClinVar, Mendelian, sample genotype, same-gene, or pathway context as follow-up context beside the GWAS Catalog population-trait ranking.

For phenotype-plus-gene-list questions, call gwas.compare_gene_associations only when GWAS Catalog reported_gene/mapped_gene/source gene-field association is the intended prior. If a trait-to-gene source record is needed, retrieve native trait-to-gene records with phenotype.retrieve_trait_gene_records. If it returns only association_only_not_causal records, do not answer from those records alone. Call separate source-specific tools when drug-target, curated association, or locus-to-gene evidence also matters; do not collapse those priors into the GWAS Catalog association result. HPO or single-subject phenotype matching belongs to phenotype.compare_gene_hpo_evidence.

For GWAS variant prioritization, exact GWAS Catalog trait matches outrank nearby trait matches. P-value breaks ties inside the same evidence level; ClinVar, Mendelian disease, same-gene, pathway, or sample context does not rerank the population-trait lead-variant result.

Routing Checks

• Present GWAS associations as association evidence.
• Preserve ancestry/source limitations.
• Check whether the selected rsID is present in the Active Genome Index before personal interpretation.
• Preserve which phenotype/query produced the ranking.
• Prefer direct GWAS Catalog records over inferring a winner from prose.
• Treat variant.resolve as context-only follow-up after the GWAS source ranking is chosen.
• Interpret GWAS Catalog mapped_genes as source gene-field association context, not causal-gene evidence.
• If the selected candidate is not direct-source supported, say the result is lower-support adjacent GWAS evidence.

Genomi

Genomi gives agents local tools for genetics and DNA-aware evidence work. Use it when the user's request is about variants, genes, phenotypes, disease genes, biological screens, medication response, ancestry reference-panel context, polygenic-score context, or a genome source.

How To Call Genomi

Call Genomi through the MCP server: mcp__genomi__<operation> (or your host's equivalent namespace).

If those tools are missing from the current session's tool list but the host's MCP list shows Genomi connected, the session pre-dates the server's registration. Ask the user to start a new session.

Core Rules

• Public by default: if the chat has not mentioned a genome source, answer from public/tool sources only.
• Active Genome Index context is chat-scoped: use it only when this conversation provides a genome source, names a previous run, asks about the selected Active Genome Index context, or says something like "my Active Genome Index" or "my genome".
• If the user provides a genome source path in this chat, that is approval to read that source for this session.
• If the user says "my Active Genome Index" or "my genome" without a path, it is acceptable to check for an already imported Active Genome Index context.
• Reading imported/parsed Active Genome Index artifacts, resuming a previous run for evidence, or searching for an existing "my Active Genome Index"/"my genome" context requires explicit user approval for this session. Record approval with active_genome_index.approve_access before calling those tools.
• Do not use unrelated genome sources from other chats, workspaces, or external evaluation tasks.
• Call narrow tools first and inspect evidence before making a claim.
• Treat this root skill as static startup guidance. Do not infer live session state from it; use genomi.describe_context, genomi.check_libraries, and tool result envelopes for changing context.
• If an MCP tool returns status="in_progress", call genomi.check_background_job with the returned job_id. Do not retry the same work with a capped parse or raw text scan unless the user asks for that fallback.
• Only send parameters supplied by the current user request, current Genomi context, a previous Genomi result, explicit user approval, or an explicit override. Omit unknown optional parameters.
• Defaults are part of the reasoning chain. Tool definitions expose parameterDefaults; returned results include defaults_applied for omitted defaults so the host agent can inspect and override them in a follow-up call when the user intent requires it.
• Tool definitions expose dependencyContract when a tool needs local installed libraries or external network/API sources. Missing local libraries return requires_library_install; unavailable external sources return source_unavailable; local source-file requirements appear as localResources.
• In the final answer, mention Active Genome Index use only when it materially affects the result: for example, it supports or refutes a user-specific claim, changes a limitation, blocks an operation until approval, or explains a required next action. Do not add a routine source-status line.
• Derive confidence dynamically for each Genomi-guided answer from tool evidence, source trust, coverage, conflicts, and missing evidence. Do not use a static default confidence or a user-selected confidence profile. Genomi result fields describe evidence support, coverage, overlap, and source state; they are not final answer-confidence labels.
• Use genomi.describe_context when the user asks about personal context, their own genome/context, a genome source, a previous run, a selected user, or before making sample-specific claims. When you call it, inspect active_response_profile.guidance; the active profile id is persisted in the Genomi registry (set via genomi.set_response_profile) and falls back to the catalog default when none is set. Do not call it only to bootstrap a public-only question.
• Handle Active Genome Index lifecycle states yourself. When a read op's envelope or genomi.describe_context returns active_genome_index_readiness.status == "needs_reparse", look up the recorded source path under active_genome_index.agi_intake_source_path and call genomi.parse_source with it — routine maintenance, no user prompt needed. Only ask the user when availability.agi_intake_source_path is false (path moved or deleted) or the status is schema_too_new (Genomi runtime out of date). Never proceed with a stale Active Genome Index while silently substituting placeholder data; use the Active Genome Index skill for the full procedure.
• For search-like operations, pass host-inferred alternate wording in semantic_context when the current chat reasonably supports alternate biomedical wording. Send the user's original wording as raw_query, add host_expansions only as retrieval terms, and add host_entities for helpful proposed spans such as drug, gene, phenotype, trait_or_condition, variant, or rsid. These terms are retrieval inputs, not evidence; Genomi reports source/retrieval hits in term_matches and no-hit terms in term_misses.

Routing

MCP tools/list returns only the base set:

• genomi.* and journal.* ops (always direct-callable).
• genomi.invoke — the dispatcher for every other capability tool.

To use a non-base capability tool, load the matching focused capability skill, then call:

genomi.invoke({"tool": "<operation_name>", "params": {...}})

Example:

genomi.invoke({"tool": "variant.resolve", "params": {"rsid": "rs429358"}})

The dispatcher validates the registered operation name, runs the underlying tool's input-schema validation, and returns the underlying tool's response with an added dispatched_tool field.

Operation namespaces are tool-name prefixes, not disclosure branches. Use namespace filters only for debugging or audits.

Resolve context, select the intent capability, read its skill markdown, call the smallest useful operation through genomi.invoke (or direct call for base tools), inspect evidence, journal material findings, and continue until the answer is supported. Use genomi.describe_context only when this chat asks about personal context, the user's own genome/context, Active Genome Index context, a selected user, a genome source, or a previous run.

Setup

genomi.install installs or updates Genomi, and genomi install / genomi update are the same operation. It always updates everything that can be updated: the runtime code (git pull --ff-only on a git checkout, unless GENOMI_SKIP_RUNTIME_GIT_PULL is set for a non-git distribution), all public reference libraries into GENOMI_HOME (idempotent — each installed library is checked against its source and re-downloaded only if it changed upstream, so re-running transfers nothing when nothing changed; pass force to re-download regardless), host-agent skill symlinks in detected host skill directories (including stale/dangling repair and obsolete Genomi capability-link removal), the public retrieval indexes, and a background reparse of any genome whose index schema is older than the updated runtime's. There are no per-step skip flags — genomi update does the full update by default. The libraries parameter only narrows which reference libraries to materialize (default everything): pass a specific library (or comma-separated set) to install just those — both for an install-time subset the user chose and to add a single new library on demand at runtime (the "install this missing library" path). To see which libraries are already installed vs missing before deciding, call genomi.check_libraries (its summary reports installed_count / missing_count). This applies once Genomi is installed; first-time setup on a machine without the genomi runtime follows the source bootstrap in INSTALL_FOR_AGENTS.md.

Parsing A Genome Source

genomi.parse_source is a core genomi.* tool: it detects, parses, and digitizes a genome source (VCF/gVCF, BAM, paired-end FASTQ, or a consumer-array raw genotype export from 23andMe, AncestryDNA, MyHeritage, FamilyTreeDNA, or Living DNA; bare text/CSV, gzip/bzip2/xz-compressed, or inside a zip/tar archive; or a .genome/1.0 bundle such as sample.genome.tar.gz) into a queryable Active Genome Index.

• Use when: the user supplied a genome source in this chat and downstream questions need a queryable Active Genome Index this session.
• Why: raw VCF/BAM/genotype files are too large and irregular for reliable direct reasoning; parsing builds the scoped index later tools query.
• Not for: public-only genetics questions, selecting an already-parsed index, or capped sample scans that should not replace a complete index.
• Result: digitizes local intake into an Active Genome Index; Genomi auto-detects the source type. Supplying user_nickname links the parsed artifact to a user profile. It does not run whole-callset annotation — focused tools materialize public libraries lazily when their evidence is needed.
• If it returns status="in_progress" with a job_id, poll genomi.check_background_job; don't substitute a capped parse or raw scan unless the user explicitly asks for a fallback.
• gVCFs parse in two phases. A gVCF is ~96% reference blocks, so the parse returns as soon as every variant is stored and indexed — the result reports variants_ready (not yet completed) and the whole interpretation surface (rsID, gene, region, exact-allele lookup, ClinVar, PRS, …) is already correct. The reference-block tail is appended by a detached background job (active_genome_index.build_reference_pass) whose job_id is surfaced in the result's next_actions. Until that job reports completed, only "is this locus confirmed reference vs not-callable" coverage answers are provisional — every readiness/coverage result carries reference_pending to say so. Plain VCFs, small files, and capped (max_records) parses stay single-phase. Other sources (consumer arrays, BAM/FASTQ) have no reference tail to defer.
• After a parse, offer to name the profile. When the user did not pass user_nickname, the result includes an ask_user next action: ask them for a profile nickname and whether to set it as the machine default, then record it by re-running with user_nickname (+ set_default_user=true) or via the invoke-only active_genome_index.assign_user_genome / set_default_user tools — exactly the offer INSTALL_FOR_AGENTS.md Step 8 makes.

The parse/digitize/user-management workflow (selecting users, approving access, assigning a genome to a profile, lifecycle reparse) lives in the Active Genome Index skill, which also owns the active_genome_index.* interpretation tools.

Journal

Use journal when an investigation spans multiple Genomi tools and the host agent needs to record reasoning over evidence. Journal entries are agent notes with traceability links; they are not source evidence and should not be used as candidate-ranking source_records.

Default Tools

These tools appear in the default tool list. Their full metadata is available without expansion.

Genomi context and users:

• genomi.check_background_job
• genomi.check_libraries
• genomi.describe_context
• genomi.install
• genomi.invoke
• genomi.list_resources
• genomi.search_indexes

Active Genome Index:

• genomi.parse_source

All other active_genome_index.* tools are invoke-only: reach them via genomi.invoke after loading the Active Genome Index skill.

ClinVar:

• clinvar.match_variants
• clinvar.scan_candidates

ClinVar exact matching uses the build-specific optional library clinvar-grch38 or clinvar-grch37. If the tool reports requires_library_install, use genomi.check_libraries and ask before installing.

Variant evidence:

• variant.resolve

Journal and research memory:

• research.build_target_packet
• research.list_sources

Phenotype, disease, and candidate gene:

• phenotype.compare_disease_evidence
• phenotype.compare_drug_target_evidence
• phenotype.compare_gene_hpo_evidence
• phenotype.plan_risk_investigation
• phenotype.retrieve_disease_drug_targets
• phenotype.retrieve_gene_disease_associations
• phenotype.retrieve_trait_gene_records

Pharmacogenomics:

• pharmacogenomics.review_medication

GWAS Catalog:

• gwas.compare_gene_associations
• gwas.compare_variant_associations

Functional genomics:

• functional_genomics.compare_gene_perturbation

Ancestry reference-panel context:

• ancestry.list_reference_panels
• ancestry.estimate_population_context

Polygenic scores:

• prs.search_scores
• prs.calculate_score

Sequence:

• sequence.analyze

Analytical grounding:

• cell_type.retrieve_markers
• pathway.retrieve_members
• region.retrieve_features

Journal:

• journal.append_entry
• journal.search_entries

Default-complete categories:

• gwas-catalog
• analytical-grounding

Candidate Evidence

Candidate and ranking operations return evidence views, decision_evidence, warnings, and coverage. Use source-specific candidate-gene tools instead of a universal comparator: phenotype.compare_gene_hpo_evidence for HPO/single-subject phenotype matching, gwas.compare_gene_associations for GWAS Catalog gene-field evidence, phenotype.compare_drug_target_evidence for drug-target evidence, and functional_genomics.compare_gene_perturbation for perturbation evidence. phenotype.retrieve_trait_gene_records retrieves trait-to-gene records from integrated sources. Records labelled association_only_not_causal are visible evidence, not an answer. Any operation that exposes an answer-shaped candidate result must expose the evidence behind that result. Use that evidence for the host-agent decision.

Multi-Stream Synthesis

When multiple Genomi capabilities can contribute orthogonal evidence to the same question, combine them — both in the initial plan and in follow-ups.

A scope-limited single-capability result (missing calibration, no record at locus, association-only, library-not-installed, low overlap, source unavailable, etc.) is not a final user-facing answer when other Genomi capabilities can contribute orthogonal evidence to the same question. Returning "I cannot answer" while applicable capabilities remain unexamined is a host-agent failure mode, not a Genomi limitation.

When multiple plausible plans differ materially in cost, surface the choice once with the tradeoff and commit to the user's pick. Over-checkpointing is itself a failure mode.

Answering

Lead with the answer. When a finding is grounded in a public dataset (ClinVar, GWAS Catalog, PGS Catalog, 1000 Genomes panel, etc.) and that source materially shapes the result, name the dataset inline in the prose. Keep clinical language informational and recommend clinical confirmation for medical decisions. Confidence is an answer-time synthesis judgment, not static metadata. Adapt explanation depth to the selected response profile without weakening evidence limits, privacy boundaries, or clinical-confirmation language.

Journal and Research Memory

Use journal when an investigation spans multiple Genomi tools and the host agent needs to record reasoning, evidence links, or reviewed source findings.

Goal

Record the host agent's observations, hypotheses, decisions, contradictions, plans, summaries, and unresolved questions while preserving traceability to Genomi operations and evidence identifiers.

Journal entries are the append-only notebook. Reviewed research records are source-memory entries in the evidence DB. They live in the same capability because both preserve investigation memory, but they have different roles: journal entries explain what the host agent concluded or still needs to check; reviewed research records store source-backed findings for reuse.

Neither journal entries nor reviewed research records rank candidates by themselves. Candidate ranking still belongs to the relevant evidence tools, with reviewed source records passed only when a tool explicitly accepts them.

Scopes

• session: current chat/session notebook. It may link private/sample evidence only after scoped Active Genome Index access is approved for this session.
• project: current workspace notebook. It is public/target-scoped and rejects private/sample evidence links.

Cross-Capability Synthesis

A scope-limited result from this capability is not a final user-facing answer when other Genomi capabilities can contribute orthogonal evidence to the same question. Returning "cannot answer" while applicable capabilities remain unexamined is a host-agent failure mode.

Tools

journal.append_entry

Append a new journal entry, or append evidence links and/or an amendment to an existing entry.

Use when: Record an observation, hypothesis, decision, contradiction, plan, summary, unresolved question, or append evidence/amendment to an existing entry.

Why necessary: Multi-tool investigations need one append-only write path for notes, evidence links, and corrections so agents do not sequence separate journal mutations.

Not for: Not source evidence and not a candidate-ranking input by itself.

Example prompts: Record this supported Genomi finding with evidence links.

Result semantics: With no entry_id, creates a new entry. With entry_id, adds evidence_links and/or stores content as an append-only amendment; original entry text is preserved.

journal.export_memory

Return a MemOS-shaped JSON memory artifact from journal entries without requiring or writing to MemOS.

Use when: The user or host agent explicitly wants the journal exported for ingestion by another memory system.

Why necessary: External memory systems need a shaped export without requiring Genomi to write to that system.

Result semantics: Exports journal memory records only; private evidence links are omitted unless explicitly requested and approved.

journal.search_entries

Token-search session and project journal entries by scope, target, tag, entry type, and text.

Use when: The host agent needs to recover recorded investigation state before continuing a multi-tool Genomi analysis.

Why necessary: Agents need to recover prior investigation state without treating chat memory as authoritative evidence.

Result semantics: Returns agent-authored notes and traceability links; journal entries are not source evidence.

journal.summarize

Summarize journal state into observations, decisions, contradictions, unresolved questions, and commonly linked evidence sources.

Use when: The host agent needs a compact state of an ongoing Genomi investigation before deciding next evidence steps.

Why necessary: Long investigations need compact journal state before the agent chooses the next evidence step.

Result semantics: Summarizes journaled reasoning only; evidence authority remains in the linked Genomi outputs and public sources.

Operating Checks

• Link evidence for traceability, but treat linked Genomi outputs and public sources as the authority.
• When a downstream tool needs source_records, provide reviewed research or tool-returned source records that satisfy that tool's verified source-record input contract.
• Use journal.append_entry with entry_id for corrections; do not silently overwrite entries.
• Omit private evidence links from memory exports unless the user explicitly requests them and scoped Active Genome Index access is approved for the session.

Nutrigenomics

Use this skill when the user asks how a germline variant affects nutrient metabolism, food tolerance, or taste perception within declared domains:

• folate metabolism
• vitamin D status
• iron storage
• lactose tolerance
• lipid diet response (APOE e2/e3/e4)
• obesity predisposition (single-marker context only)

Out of scope — refuse, do not approximate

Do NOT use this skill for, and DO surface as refusals:

• Macronutrient ratio prescriptions ("eat X% fat because of your APOE")
• Specific supplement dosing recommendations
• Weight-loss outcome prediction from genotype
• Diet-matching to genotype for fitness goals
• Microbiome-mediated dietary effects
• "Methylation cycle" prescriptions beyond folate marker context
• General health-outcome prediction from a small marker set
• "Detox capacity" framings
• Food allergy risk prediction
• Vitamin megadose prescriptions

The capability returns coverage_status: out_of_scope_for_input for these domain ids. Treat the refusal literally — do not reach for adjacent records that look similar.

Contract

• Reads public catalogue metadata only; does not read an Active Genome Index.
• For scanning an active genome, compose with active_genome_index.classify_genotype_support using the variant coordinates carried in each record.
• For stratified allele frequencies, call gnomad.fetch_population_frequency.
• For primary GWAS effect sizes, call gwas.compare_variant_associations using the gwas_catalog_id carried in each record's downstream_traits_with_gwas.

Convention: See skills/conventions/context-routing.md. Convention: See skills/conventions/evidence-quality.md. Convention: See skills/_output-rules.md.

First Actions

1. If the request is shaped like a diet prescription, supplement dosing, weight-loss prediction, or any item in the out-of-scope list, refuse first. Do not call retrieval tools.
2. Use nutrigenomics.list_domains to confirm the relevant domain is declared and to inspect evidence-tier counts before drilling in.
3. Use nutrigenomics.build_source_context when grounding a discussion in provenance is needed — e.g. when a user asks where the records come from or why diet prescriptions are out of scope.
4. Use nutrigenomics.retrieve_domain_markers with the validated domain_id. Default min_evidence_tier="established". Loosen to "probable" only when the question explicitly invites less-replicated evidence.
5. Use nutrigenomics.retrieve_variant_records when the agent already has an rsID and wants to know which declared domains reference it.

Interpretation Rules

• Each record carries out_of_scope_claims. Surface these as explicit disclaimers — do not paraphrase around them.
• evidence_tier is literal. An emerging record is not equivalent to an established one; hedge in any agent-generated text accordingly.
• Single-marker evidence does not substitute for measured lab values (serum 25(OH)D, ferritin/transferrin saturation, homocysteine, lipid panel) when clinical decisions are at stake.
• Absence of a marker from the catalogue is not evidence of negligible effect — the catalogue is intentionally small and curated.

User-Facing Answer Shape

Do not add a routine Active Genome Index status line for these public catalogue tools. For each cited marker:

• Variant identifier (rsID + gene)
• Established effect (single sentence)
• Evidence tier
• One or two of the most relevant out_of_scope_claims as disclaimers
• The single most relevant lab measurement that should accompany the marker (when applicable: homocysteine for MTHFR, 25(OH)D for vitamin D markers, ferritin + transferrin saturation for HFE)

Cross-Capability Synthesis

A scope-limited result from this capability is not a final user-facing answer when other Genomi capabilities can contribute orthogonal evidence to the same question. Returning "cannot answer" while applicable capabilities remain unexamined is a host-agent failure mode.

Tools

nutrigenomics.build_source_context

Explain nutrigenomic catalogue provenance, domain definitions, evidence-tier meanings, method limitations, and the non-prescription boundary.

Use when: The user or agent asks what the nutrigenomics catalogue is, where the records come from, what evidence tiers mean, or why the capability refuses diet prescriptions.

Why necessary: Nutrigenomic language is easy to overstate. Explicit source context grounds the agent in the boundary before it interprets records.

Not for: Returning marker records; use nutrigenomics.retrieve_domain_markers or nutrigenomics.retrieve_variant_records.

Example prompts: Explain the source and limitations of Genomi's nutrigenomic catalogue.

Result semantics: Public metadata only. Returns capability provenance, declared domains, evidence-tier definitions, out-of-scope-by-construction items, and the non-prescription boundary note.

nutrigenomics.list_domains

List declared nutrigenomic domains with evidence-tier coverage and explicit out-of-scope-by-construction notes.

Use when: The user asks what nutrigenomic domains Genomi covers, or the host agent needs to validate that a domain is in scope before retrieving markers.

Why necessary: Nutrigenomics is a pseudoscience-prone domain. Listing declared domains and explicit out-of-scope-by-construction items lets the agent refuse out-of-scope questions before reaching for marker records.

Not for: Returning specific marker records; use nutrigenomics.retrieve_domain_markers. Diet prescriptions, supplement dosing, weight-loss prediction.

Example prompts: What nutrigenomic domains does Genomi cover? Is weight-loss diet matching in scope for Genomi nutrigenomics?

Result semantics: Returns the declared domain catalogue, evidence-tier counts per domain, the out-of-scope-by-construction list, and the non-prescription boundary note.

nutrigenomics.retrieve_domain_markers

Retrieve curated single-marker records for a declared nutrigenomic domain, filtered by minimum evidence tier.

Use when: The host agent needs curated single-marker evidence for a declared domain (folate_metabolism, lactose_tolerance, iron_storage, vitamin_d_status, lipid_diet_response, obesity_predisposition).

Why necessary: Returns evidence-tiered records with explicit out_of_scope_claims so the agent can ground a nutrient/tolerance discussion without propagating pseudoscience claims about the variant.

Not for: Diet prescriptions, supplement dosing, weight-loss prediction. Polygenic risk scoring; this is single-marker evidence only. Genome scanning; compose with active_genome_index.classify_genotype_support using the variant coordinates from each record. Population-stratified allele frequencies; use gnomad.fetch_population_frequency. Primary GWAS effect sizes; use gwas.compare_variant_associations with the gwas_catalog_id from downstream_traits_with_gwas.

Example prompts: What does Genomi have on folate_metabolism markers? Retrieve established-tier iron_storage records.

Result semantics: Each record carries variant identifiers, established_effect with GWAS Catalog chain-out, evidence_tier, resolvable source citations, established_caveats, and out_of_scope_claims. The agent must surface out_of_scope_claims as disclaimers rather than paraphrase around them.

nutrigenomics.retrieve_variant_records

Retrieve any nutrigenomic catalogue records referencing a specific rsID.

Use when: The host agent has a specific variant identifier and wants to know whether the nutrigenomic catalogue carries any records for it.

Why necessary: A variant may participate in more than one declared domain. Variant-anchored lookup surfaces all matching curated records at once.

Not for: Variant resolution from coordinate to rsID; use variant.resolve first. Variants outside declared nutrigenomic domains; in_scope_empty indicates the catalogue does not cover the variant.

Example prompts: What does Genomi say about rs1801133 nutrigenomically? Are there nutrigenomic records for rs429358?

Result semantics: Returns one or more curated records referencing the variant. coverage_status='in_scope_empty' when the variant is not in the catalogue; absence is not evidence of negligible effect.

Pharmacogenomics

Use this skill when the user asks about medication response, PGx guidelines, drug-gene or variant-drug evidence, PGxDB, ATC codes, DrugBank IDs, PharmCAT, or pharmacogene sample evidence.

Contract

• Drug-response claims use public PGx source evidence.
• Personal drug-response statements cite separate local genotype or PGx caller support.
• External PGx lookups receive selected public targets only.
• Source-backed PGx findings can be stored as shared reviewed research.
• User-specific sample interpretations can be stored as private reviewed research.

Convention: See skills/conventions/evidence-quality.md. Convention: See skills/_output-rules.md.

Primary Flow

1. Use pharmacogenomics.review_medication for ordinary medication questions. It combines ClinPGx, FDA PGx tables, PGxDB, stored reviewed research, and optional selected sample evidence in one bounded review.
2. Inspect evidence_envelope, medication_review_matrix, evidence_matrix, target_inventory, answer_support, and unanswered_answer_components before answering. Treat each medication_review_matrix.rows[] entry as the review unit.
3. If the answer needs source review beyond returned public records, use research.list_sources, review the selected public target, then store the finding with research.record.
4. If the answer needs personal sample evidence, use the Active Genome Index only when selected or supplied in this chat. Confirm relevant alleles with variant.resolve or active_genome_index.classify_genotype_support.

Tool Choices

• pharmacogenomics.review_medication: bounded medication evidence review; public-only by default, with Active Genome Index evidence when selected.
• pharmacogenomics.fetch_clinpgx, pharmacogenomics.fetch_fda_labels, and pharmacogenomics.fetch_pgxdb: focused public PGx source retrieval when the medication review needs a source-specific follow-up.
• pharmacogenomics.describe_gene_requirements: gene-specific sample evidence requirements for named allele matching, outside calls, HLA, MT-RNR1, G6PD, and SV/CNV-sensitive genes.
• pharmacogenomics.check_pharmcat: check local PharmCAT availability.
• pharmacogenomics.preflight_pharmcat: inspect whether the selected Active Genome Index can provide a suitable PharmCAT input before running it.
• pharmacogenomics.prepare_outside_call_tsv and pharmacogenomics.validate_outside_call_tsv: prepare or validate specialized outside-call evidence for PharmCAT.
• pharmacogenomics.run_pharmcat: run broad PharmCAT calling from the selected Active Genome Index and return provenance plus sample_pgx_matrix rows projected from report, phenotype, calls-only, and matcher artifacts.
• pharmacogenomics.import_pharmcat_artifacts: import existing PharmCAT JSON, TSV, matcher, phenotype, missing-position, or output-directory artifacts and return sample_pgx_matrix.

PGx capability metadata is exposed through genomi.list_resources; there is no separate PGx capability-listing tool.

Answering

• Mention Active Genome Index evidence only when it changes the medication interpretation, limitation, blocker, or next action.
• Keep PGx language informational and recommend clinical confirmation for medication decisions.
• Do not infer medication actionability from a genotype alone; connect sample evidence to public drug-response evidence.
• Treat user-provided diplotypes, phenotypes, activity scores, and outside calls as supplied sample evidence that may need independent confirmation.

Cross-Capability Synthesis

A scope-limited result from this capability is not a final user-facing answer when other Genomi capabilities can contribute orthogonal evidence to the same question. Returning "cannot answer" while applicable capabilities remain unexamined is a host-agent failure mode.

Tools

pharmacogenomics.check_pharmcat

Check local PharmCAT availability and version provenance for broad PGx calling from an AGI-derived PharmCAT input.

Use when: The agent needs to know whether broad PharmCAT PGx calling is available before running pharmacogenomics.run_pharmcat.

Why necessary: External PGx calls need availability and version provenance before they are trusted.

Result semantics: Reports local PharmCAT executable/jar availability and version probe output for auditability before broad PGx calling.

pharmacogenomics.describe_gene_requirements

Return pharmacogene-specific sample evidence requirements for PharmCAT named allele matching, outside calls, CYP2D6 SV/CNV handling, HLA typing, MT-RNR1, and G6PD chrX representation.

Use when: The selected medication or source evidence names a pharmacogene and the agent needs to choose sample evidence, PharmCAT, outside-call, or targeted lookup handling.

Why necessary: Complex pharmacogenes require special evidence handling that a simple rsID lookup cannot provide.

Result semantics: Returns packaged source-backed pharmacogene sample-evidence requirements, candidate tools, and source references for the selected gene.

pharmacogenomics.fetch_clinpgx

Fetch traceable ClinPGx pharmacogenomic guideline, clinical annotation, and FDA label evidence for a selected drug, gene, or rsID; compact normalized records are returned by default.

Use when: The question involves medication response, adverse effects, CPIC/DPWG guidance, FDA drug-label PGx context, PharmGKB/ClinPGx annotations, or drug plus gene/rsID interpretation.

Why necessary: Guideline, clinical annotation, and label rows are separate public PGx evidence from sample genotype calls.

Result semantics: Fetches public guideline, annotation, and label rows; raw API records are opt-in with include_raw_records; personal interpretation requires separate local genotype or diplotype evidence.

pharmacogenomics.fetch_fda_labels

Fetch targeted FDA pharmacogenomic biomarker-labeling and pharmacogenetic-association table rows from official FDA pages.

Use when: The question needs FDA biomarker-labeling table context or FDA pharmacogenetic association table context for a selected drug or gene.

Why necessary: FDA biomarker and pharmacogenetic-association tables are official label evidence with their own boundaries.

Result semantics: Fetches official FDA table rows; keep biomarker-labeling rows separate from pharmacogenetic-association rows and combine with separate sample evidence for personal interpretation.

pharmacogenomics.fetch_pgxdb

Fetch targeted PGxDB pharmacogenomic evidence for a selected drug, ATC code, DrugBank ID, rsID, variant marker, or gene.

Use when: The question involves medication response, adverse effects, pharmacogenomics, PharmGKB-style evidence, a drug plus rsID, or a drug plus gene.

Why necessary: PGxDB association records provide targeted drug-variant evidence distinct from guideline recommendations.

Result semantics: Fetches public PGxDB rows; sample interpretation requires separate local genotype evidence.

pharmacogenomics.import_pharmcat_artifacts

Import existing PharmCAT report JSON, calls-only TSV, matcher JSON, phenotype JSON, missing-position VCF, or output directory without executing PharmCAT.

Use when: The agent has existing PharmCAT artifacts and needs sample-side PGx evidence without running local PharmCAT.

Why necessary: Existing PharmCAT outputs should be reused rather than rerun when sample-side PGx evidence already exists.

Result semantics: Parses existing PharmCAT artifacts into sample_pgx_matrix, evidence summaries, and record_research_payloads used by pharmacogenomics.run_pharmcat, including interpretation readiness and missing-position review facts.

pharmacogenomics.preflight_pharmcat

Inspect selected Active Genome Index structure for broad PharmCAT PGx calling without running PharmCAT or writing artifacts.

Use when: The agent needs read-only Active Genome Index structure, sample-column, genotype-field, or header evidence before broad PharmCAT PGx calling.

Why necessary: Broad PharmCAT runs need input suitability checks before execution or artifact interpretation.

Result semantics: Returns local AGI-derived preflight facts without exposing the raw AGI path; PharmCAT coverage sufficiency is judged from execution artifacts, especially missing PGx position review.

pharmacogenomics.prepare_outside_call_tsv

Prepare a PharmCAT outside-call TSV from supported specialized caller output such as OptiType HLA calls, StellarPGx CYP2D6 summaries, or generic gene/diplotype tables.

Use when: The agent has specialized caller output for HLA-A, HLA-B, CYP2D6, MT-RNR1, or another pharmacogene and needs a PharmCAT outside-call TSV.

Why necessary: Specialized callers for HLA, CYP2D6, and related genes need conversion before PharmCAT can consume them.

Result semantics: Writes a canonical outside-call TSV under Genomi output storage or the requested output_file, validates it, and returns output.path for pharmacogenomics.run_pharmcat with parsed rows, invalid rows, warnings, caller format, and sample identity facts.

pharmacogenomics.review_medication

Review medication pharmacogenomic evidence as medication-first rows combining ClinPGx guideline/label context, FDA PGx table rows, PGxDB association evidence, Active Genome Index rsID lookup when selected, implemented marker-definition evidence when selected, evidence components, and target inventory.

Use when: Combines public PGx evidence with selected active-genome-index or marker evidence for one medication.

Why necessary: Medication-response questions need drug-specific PGx sources plus optional personal genotype evidence in one bounded review.

Not for: diagnosing disease risk; it is medication-response evidence.

Example prompts: Does my DNA say anything about clopidogrel?

Result semantics: Returns medication_review_matrix where each row carries drug, gene, variant/diplotype/phenotype, recommendation/source text, evidence IDs, sample relevance, row readiness, and clinical boundary. Public-only by default unless active-genome-index context is selected.

pharmacogenomics.run_pharmcat

Run a local PharmCAT installation from an approved Active Genome Index for broad PGx diplotype, phenotype, recommendation artifacts, and sample_pgx_matrix rows.

Use when: Runs local PharmCAT from the selected Active Genome Index to generate broad PGx diplotype, phenotype, and recommendation artifacts.

Why necessary: Broad PGx diplotype and recommendation artifacts require a specialized external caller.

Result semantics: Runs local PharmCAT as sample-side PGx evidence generation; returns input preflight, runtime provenance, outside-call validation, sample_pgx_matrix, artifacts, warnings, interpretation readiness, and record_research_payloads for synthesis.

pharmacogenomics.validate_outside_call_tsv

Validate PharmCAT outside-call TSV structure and summarize selected diplotype, phenotype, or activity-score evidence.

Use when: The PGx sample evidence path already has a PharmCAT outside-call TSV for CYP2D6, HLA-A, HLA-B, MT-RNR1, or another specialized caller result before PharmCAT execution.

Why necessary: Outside calls can override complex gene evidence, so their structure must be validated before use.

Result semantics: Validates outside-call TSV shape, hides the local path, returns parsed rows, invalid rows, warnings, and explains that outside calls override PharmCAT VCF-derived calls for the same gene.

Polygenic Scores

Use this skill when the user asks about polygenic risk scores, PRS, PGS Catalog scores, common disease or trait risk from many variants, or applying a published scoring file to their genome.

Boundaries

• PRS/PGS here means applying published variant weights from a scoring file. Genomi does not train new PRS models from GWAS summary statistics.
• Default genome build is GRCh38 when omitted; use GRCh37 only when the Active Genome Index is GRCh37/hg19.
• Active Genome Index artifacts stay local. Public score metadata may use PGS Catalog, but private genotypes are not uploaded to external services.
• A raw PRS is common-risk or trait context, not a diagnosis, absolute disease risk, treatment recommendation, or clinical category.
• Only state standardized score context when valid score_mean and score_sd are supplied for the same score, build, cohort/reference distribution, and scoring convention.
• Do not use PRS output for ethnicity, identity, monogenic diagnosis, medication response, or rare-disease causality.

Workflow

1. Use prs.search_scores for public trait or score discovery. If the user already supplies a PGS ID, use that ID directly.
2. Use prs.fetch_score_metadata when the source publication, build, variant count, scoring-file URLs, licensing, or cohort/evaluation context matters.
3. Use prs.calculate_score with the chosen pgs_id and the user's genome source to get the raw weighted score plus overlap QC.
4. Use prs.check_score_overlap when you only need readiness and QC without a calculated score.
5. Use prs.list_imported_scores when the user asks what scores are already available locally.
6. Use prs.build_source_context when the user asks what PRS can or cannot tell them.

When published calibration is missing

PGS Catalog rarely publishes a reference cohort mean/SD, so a raw weighted score has units on an arbitrary scale. Deliver a defensible directional or quantitative answer for this specific question by combining capabilities that contribute orthogonal evidence — population allele frequencies feeding a closed-form z, direct effect-allele dosages at well-replicated lead loci, additional published scores derived by different methods, treatment-response context when the outcome is treatable, mechanism context from functional or pathway evidence, or whatever else Genomi currently exposes that fits. Disclose the assumptions of any closed-form estimate (HWE, variant independence, ancestry of the allele-frequency source).

Answering

When an Active Genome Index is scored or its overlap changes the result, report the score ID/source, genome build, overlap status, matched/missing/excluded variant counts, and whether the result is raw or calibrated. Do not add a routine Active Genome Index status line for public score metadata lookups.

Use careful language:

• "The raw weighted score was calculated from N matched score variants."
• "This is source-bound PRS context, not an absolute risk estimate."
• "Performance may not transfer across ancestry/evaluation cohorts."
• When grounded in an analytic z from gnomAD or a multi-score consensus: "Your analytic z relative to under HWE is +X.X, ~Yth percentile. This is a closed-form estimate, not an empirical reference-cohort percentile."

Directional language ("leans above population average", "in the upper tertile of the analytic z distribution") is appropriate when grounded in the orthogonal evidence the synthesis combined.

Avoid:

• Clinical-risk category labels (high/elevated/low risk) unless a validated calibration and category threshold from the same source context is explicitly supplied.
• Absolute outcome probabilities ("X% chance of disease by age N") — these require an empirical risk-calibration model.
• "This diagnoses", "rules out", "predicts disease", or "determines origin".

Cross-Capability Synthesis

A scope-limited result from this capability is not a final user-facing answer when other Genomi capabilities can contribute orthogonal evidence to the same question. Returning "cannot answer" while applicable capabilities remain unexamined is a host-agent failure mode.

Tools

prs.build_source_context

Explain PGS Catalog provenance, local scoring workflow, genome-build defaults, calibration limits, and PRS risk boundaries.

Use when: The user asks what PRS can and cannot tell them, whether PRS means common risk analysis, or how Genomi applies published scores.

Why necessary: PRS answers require explicit boundaries around calibration, cohort portability, missing variants, and clinical non-diagnosis.

Not for: Calculating a personal score; use prs.calculate_score after Active Genome Index access approval.

Example prompts: Explain how Genomi implements PRS. Does PRS give common disease risk?

Result semantics: Returns public method context only; it does not read Active Genome Index.

prs.calculate_score

Apply a published polygenic score to an approved Active Genome Index and return raw weighted score plus QC.

Use when: The user asks to calculate or apply a published PRS/PGS score to their genome.

Why necessary: This keeps Active Genome Index local, applies only selected published weights, reports overlap and build defaults, and avoids unsupported risk-category claims.

Not for: Training a new PRS model. Diagnosis, monogenic disease interpretation, medication response, or absolute-risk prediction without a validated calibration model. Ancestry or identity inference.

Example prompts: Calculate PGS000001 for my Active Genome Index. Apply this local scoring file to my GRCh38 genome.

Result semantics: Output is a raw weighted score and QC unless explicit calibration parameters are supplied. Do not phrase it as diagnosis, absolute disease risk, ethnicity, or clinical actionability.

prs.check_score_overlap

Check how many variants from a polygenic score are usable in an approved Active Genome Index.

Use when: The agent needs PRS overlap/readiness before calculating or interpreting a published polygenic score.

Why necessary: A PRS score can be misleading with low variant overlap, build mismatch, unharmonized palindromic alleles, or missing genotype records.

Not for: Public score search; use prs.search_scores. Diagnosis or absolute risk classification.

Example prompts: Does my genome have enough overlap with PGS000001?

Result semantics: Reports overlap and calculation readiness only; missing score variants are not negative evidence for disease risk.

prs.fetch_score_metadata

Fetch detailed public PGS Catalog metadata for one score ID, including scoring-file URLs and source publication context.

Use when: The agent needs the exact PGS Catalog record context — trait, build, variant count, source publication, cohort, ancestry/evaluation, licensing — before explaining or applying a score.

Why necessary: The score metadata carries build, trait, source publication, cohort, ancestry/evaluation, and licensing context that determines whether applying a score is appropriate.

Not for: Calculating a personal score; use prs.calculate_score with the chosen pgs_id.

Example prompts: Fetch metadata for PGS000001.

Result semantics: Returns public PGS Catalog metadata only and may report source_unavailable if the external source cannot be reached.

prs.import_scoring_file

Import a PGS Catalog or local scoring file into Genomi's local PRS score cache for a declared genome build.

Use when: A score has been selected and needs to be materialized locally before overlap checking or scoring.

Why necessary: Private genotype scoring must run against local score artifacts rather than uploading genotypes to external services.

Not for: Reading Active Genome Index; import is public/local score materialization only. Interpreting the score as risk; use prs.calculate_score and preserve its limitations.

Example prompts: Import PGS000001 for GRCh38. Import this local scoring file for GRCh37.

Result semantics: Creates a local cache of variant weights and manifest metadata. The default genome_build is GRCh38 when omitted and is disclosed in defaults_applied.

prs.list_imported_scores

List polygenic scores available locally for use without reading Active Genome Index.

Use when: The user asks which polygenic scores are available locally.

Why necessary: Knowing which scores are already available locally helps the agent pick a matching genome build and avoid re-fetching.

Not for: Calculating personal PRS values; use prs.calculate_score after approval.

Example prompts: Which PRS scores are imported locally?

Result semantics: Lists local score-cache metadata only; it does not read Active Genome Index.

prs.search_scores

Search public PGS Catalog score metadata by trait, score ID, EFO term, or free-text query without reading Active Genome Index.

Use when: The user asks which published PGS/PRS scores exist for a trait or provides a PGS Catalog score ID.

Why necessary: Score selection is source-specific and must expose trait, build, variant count, publication, evaluation, and licensing context before using a score on Active Genome Index.

Not for: Reading or scoring a user's genome; pass the chosen pgs_id to prs.calculate_score after Active Genome Index access approval. Training a new PRS from GWAS summary statistics.

Example prompts: Find PGS Catalog scores for coronary artery disease. What is PGS000001?

Result semantics: Returns public score candidates and source metadata only; it does not read Active Genome Index.

Condition Review

Use this skill when the user asks about rare disease, hereditary disease, cancer risk genes, hereditary cancer, GeneCards-style gene context, MalaCards disease context, HPO/phenotype-to-disease review, HPO-style phenotype-to-gene review, carrier-relevance evidence, observed-condition review, or disease-gene source review.

Not for common-trait phenotypes. Common, complex-disease, GWAS-style, or drug-target candidate-gene questions use the matching source-specific tool. Use this skill when the phenotype is explicitly rare/Mendelian, HPO-style, or hereditary cancer.

Contract

Support both public-only questions and selected active genome evidence.

• Public-only questions stay public-only.
• Active genome evidence is used only when the current chat has selected or approved active genome access.
• GeneCards and MalaCards are context sources, not clinical-validity sources by themselves.
• Cancer-gene role, somatic cancer evidence, and inherited germline risk remain separate unless a reviewed source links them.
• Carrier-review output consumes ClinVar carrier_relevance groups and ranks review targets by evidence strength plus missing interpretation gates.
• Observed-condition review consumes observed-condition, uncertainty/conflict, risk-association, benign/counterevidence, and population-context groups.
• Reviewed source findings are stored before final interpretation or reporting.
• HPO and symptom overlap can prioritize review targets, but it is not a diagnosis.

First Tool

Call phenotype.plan_risk_investigation first. Provide any public targets the user gave:

• phenotype.plan_risk_investigation with {"question":"BRCA1 hereditary breast cancer risk","gene":"BRCA1","investigation_type":"cancer_risk"}
• phenotype.plan_risk_investigation with {"question":"carrier relevance review","investigation_type":"carrier_review"}
• phenotype.plan_risk_investigation with {"question":"observed ClinVar condition review","investigation_type":"observed_condition_review"}

For a selected Active Genome Index, add:

• phenotype.plan_risk_investigation with {"question":"rare disease review for GENE2","gene":"GENE2","include_active_genome_index":true}

If the user did not select active genome evidence, do not add active genome parameters.

For phenotype-first questions, normalize and rank the public targets:

• phenotype.normalize_terms with {"text":"ataxia; microcephaly; seizures; HP:0001250"}
• phenotype.retrieve_gene_disease_associations with {"genes":["PIEZO2"]}
• phenotype.compare_disease_evidence with {"phenotypes":["ataxia","microcephaly","seizures"],"candidate_diseases":["condition A","condition B"],"source_records":[{"diseases":["condition A"],"verified_fields":{"diseases":["condition A"],"phenotypes":["ataxia"]},"support_spans":[{"field":"phenotypes","text":"source-backed ataxia text"}]}]}
• phenotype.compare_disease_evidence with {"hpo_ids":["HP:0000822","HP:0001965"],"genes":["PIEZO2"]}
• phenotype.compare_gene_hpo_evidence with {"phenotypes":["ataxia","microcephaly"],"genes":["PNKP","SPG7"],"source_records":[{"genes":["PNKP"],"verified_fields":{"genes":["PNKP"],"phenotypes":["ataxia","microcephaly"]},"support_spans":[{"field":"genes","text":"source-backed PNKP text"}]}]}

Use phenotype.compare_disease_evidence when the answer choices are diseases or syndromes. Also use it when the input is HPO terms plus known or candidate genes but the requested output is a disease name, syndrome name, or OMIM-style diagnosis. In that shape, gene resolution is not the answer; the load-bearing step is within-gene disease-family discrimination by the patient's specific HPO pattern. phenotype.retrieve_gene_disease_associations returns the GenCC primary gene-disease association set for supplied genes. phenotype.compare_disease_evidence uses that association set as the gene-derived candidate universe and uses HPO disease annotations only for phenotype terms. Use phenotype.compare_gene_hpo_evidence for HPO IDs, patient-specific phenotypes, rare-disease phenotype matching, or single-subject causal-gene questions. Keep this phenotype/HPO evidence separate from population-trait, drug-target, and perturbation evidence. When HPO IDs are available, pass them so public phenotype-to-gene annotation can be checked across the full candidate set. Do not pick a gene from partially reviewed evidence; gather better source support or state that the source evidence is incomplete.

Source Review

Use the investigation guidance to decide which source to review next:

• ClinVar for exact variant assertions and review status.
• gnomAD for public population frequency when an exact allele matters.
• ClinGen and GenCC for gene-disease validity.
• GeneReviews for inheritance, mechanism, penetrance, and disease context.
• GeneCards for gene aliases, function, pathways, and disease-association triage.
• MalaCards for disease aliases, phenotype context, and associated genes.
• NCI cancer genetics for hereditary cancer background and counseling boundaries.
• COSMIC Cancer Gene Census for cancer-gene role context, not standalone germline-risk evidence.
• HPO for phenotype identifiers and synonyms.
• MONDO for disease identifiers, aliases, and ontology context.
• Orphanet and OMIM for rare disease phenotype and gene relationship context.

Evidence Checks

For active genome evidence:

• Use variant.gather_gene_context for selected genes.
• Use variant.gather_allele_context for selected exact alleles.
• Use active_genome_index.classify_genotype_support before personal wording about an observed allele.
• Use active_genome_index.classify_region_callability before negative or absence wording.
• Use gnomad.fetch_population_frequency when public frequency is missing and would change interpretation.

For phenotype-first ranking, use reviewed records with source-backed fields or support spans. Direct answers require a source to support both the candidate and the relevant phenotype, disease, or HPO context.

Answering

Mention Active Genome Index use only when it changes the result, limitation, or next action. Keep risk language qualitative unless a cited source gives a quantitative estimate. Recommend clinical genetics confirmation for medical decisions.

Cross-Capability Synthesis

A scope-limited result from this capability is not a final user-facing answer when other Genomi capabilities can contribute orthogonal evidence to the same question. Returning "cannot answer" while applicable capabilities remain unexamined is a host-agent failure mode.

Tools

phenotype.compare_disease_evidence

Compare supplied or primary gene-derived diseases against phenotype/HPO evidence without selecting the diagnosis.

Use when: Compares phenotype/HPO terms against supplied diseases, disease source records, or primary gene-disease associations. Uses GenCC primary gene-disease associations as the gene-derived disease candidate universe when gene symbols are supplied.

Why necessary: Candidate diseases must be compared against phenotype/HPO evidence without letting the tool choose a diagnosis.

Result semantics: Returns phenotype/disease evidence rows, disease identifiers, HPO overlap counts, and source coverage; the host agent chooses the answer. The tool uses primary gene-disease retrieval for enumeration and HPO disease annotations for phenotype terms.

phenotype.compare_gene_hpo_evidence

Compare candidate genes using phenotype, HPO, and curated rare-disease annotation evidence only.

Use when: Returns phenotype, HPO, OMIM, Orphanet, and rare-disease annotation evidence for candidate genes.

Why necessary: Rare-disease candidate genes need HPO/phenotype evidence, not GWAS, drug-target, or pathway priors.

Not for: common-trait GWAS ranking, drug-target evidence, or medication response.

Example prompts: Which of these genes best matches ataxia and microcephaly?

Result semantics: Returns source-local phenotype/HPO evidence only; the host agent decides whether this prior matches the question.

phenotype.normalize_terms

Normalize phenotype text and HPO IDs into public evidence-review targets.

Use when: Normalizes supplied HPO IDs or free-text phenotypes into public evidence-review targets.

Why necessary: Free-text symptoms need normalization before HPO and rare-disease tools can compare them reliably.

Result semantics: Returns lexical phenotype normalization and safe public targets; it does not diagnose or call external ontology APIs.

phenotype.plan_risk_investigation

Plan rare disease, cancer risk, carrier-relevance, or observed-condition investigation from public targets and optionally selected Active Genome Index evidence.

Use when: Returns rare disease, hereditary disease, hereditary cancer, cancer-risk-gene, carrier-relevance, observed-condition, and disease-gene source-review plans. Can include selected active-genome-index review targets when explicitly supplied or approved.

Why necessary: Broad disease and cancer-risk questions need declared source-review boundaries before any personal-risk wording.

Example prompts: Any inherited disease or cancer-risk findings worth following up?

Result semantics: Returns structured investigation guidance, relevant public source classes, reviewed-research gaps, and optional selected active-genome-index candidate_review_groups. Without include_active_genome_index or explicit matches, the operation stays public-only. GeneCards and MalaCards are treated as context sources that require cross-checking before clinical, carrier, or personal-risk wording.

phenotype.retrieve_gene_disease_associations

Retrieve primary gene-disease associations from GenCC for supplied gene symbols.

Use when: Returns GenCC primary gene-disease associations for supplied genes, filtered to declared validity classifications.

Why necessary: Gene-disease validity should come from primary association sources before phenotype matching or diagnosis-like wording.

Result semantics: Returns a primary gene-disease candidate universe for downstream phenotype/HPO comparison. Does not ingest agent-supplied source records and does not diagnose.

Sequence

Use this skill when the user supplies a DNA sequence and asks for ORFs, translation, restriction sites, Kozak context, primer checks, local FASTA record matching, or simple bench-style sequence QA.

Contract

• These tools operate only on supplied sequence strings and explicitly supplied local reference FASTA files.
• They do not use active genome context or external services.
• Report deterministic sequence facts directly. Add biological interpretation only when the user supplies enough context or separate source evidence.

Tool Flow

• Use sequence.analyze when more than one deterministic sequence fact may be needed.
• Use sequence.match_reference when a local FASTA can identify the supplied sequence before downstream reasoning.
• Use sequence.translate for frame/strand translation.
• Use sequence.find_orfs for ATG-to-stop ORF discovery.
• Use sequence.find_restriction_sites for common enzymes or custom motifs.
• Use sequence.classify_kozak for ATG start-context checks.
• Use sequence.check_primers for basic GC, Wallace Tm, self-complementarity, and optional template amplicons.

Examples:

• sequence.translate with {"sequence":"ATGGCCATTGTAATGGGCCGCTGA","frame":1}
• sequence.find_orfs with {"sequence":"AAATGAAATAG","min_aa":1}
• sequence.find_restriction_sites with {"sequence":"GAATTCGGATCC","enzymes":["EcoRI","BamHI"]}
• sequence.match_reference with {"sequence":"ATGAAATAA","reference_fasta":"refs.fa"}

Answering

Give the computed result and enough coordinates or frame details to make the answer auditable. Do not turn sequence utility output into medical or personal-genome interpretation.

Cross-Capability Synthesis

A scope-limited result from this capability is not a final user-facing answer when other Genomi capabilities can contribute orthogonal evidence to the same question. Returning "cannot answer" while applicable capabilities remain unexamined is a host-agent failure mode.

Tools

sequence.analyze

Run a compact deterministic sequence analysis bundle and point to focused sequence tools when needed.

Use when: The user supplies DNA/RNA sequence text and may need translation, ORF, motif, Kozak, or local FASTA identity facts.

Why necessary: Supplied DNA strings need deterministic sequence utilities before any biological interpretation.

Example prompts: Translate this DNA sequence and find ORFs.

Result semantics: Computes deterministic sequence facts from supplied text and optional local FASTA reference matches; no external annotation is performed.

sequence.check_primers

Check basic primer properties and optional template amplicons.

Use when: Checks primer GC, melting temperature, self-complementarity, and optional amplicon context.

Why necessary: Primer checks combine basic thermodynamic and amplicon facts that are not variant evidence.

Result semantics: Performs lightweight deterministic primer checks; it does not replace full primer-design thermodynamics.

sequence.classify_kozak

Classify Kozak sequence context around ATG start codons.

Use when: Checks Kozak/start-codon context around a supplied DNA sequence position.

Why necessary: Start-codon context is a specialized expression-design check and should stay separate from general translation.

Result semantics: Uses the simple -3 A/G and +4 G Kozak rule; experimental expression strength needs separate evidence.

sequence.find_orfs

Find ATG-to-stop open reading frames in a supplied DNA sequence.

Use when: Finds open reading frames and coding-sequence candidates in a supplied DNA sequence.

Why necessary: ORF detection identifies candidate coding regions without relying on external annotation.

Result semantics: Finds simple ATG-to-stop ORFs from supplied sequence text; biological annotation requires separate source evidence.

sequence.find_restriction_sites

Find common restriction enzyme or custom motif sites in a supplied DNA sequence.

Use when: Maps restriction enzyme sites and sequence motifs in a supplied DNA sequence.

Why necessary: Cloning and motif checks need exact site positions in the supplied sequence.

Result semantics: Reports motif positions in the supplied sequence; it does not model methylation or digestion conditions.

sequence.match_reference

Match a supplied DNA sequence against local FASTA records and return record identifiers plus annotations.

Use when: The task supplies a DNA sequence and a local FASTA/reference set that can identify the sequence record before downstream reasoning.

Why necessary: Local FASTA matching identifies sequence records before downstream reasoning about that sequence.

Result semantics: Returns exact local FASTA record matches and header annotations; the host agent decides whether a matched record answers the question.

sequence.translate

Translate a DNA sequence in a selected frame and strand using the standard genetic code.

Use when: Translates a supplied DNA sequence into codons or amino acids for the requested frame and strand.

Why necessary: Protein translation requires explicit frame and strand control rather than informal sequence reading.

Result semantics: Computes deterministic sequence facts from the supplied string only; no genome context or external IO is used.

Journal Source Research

Use this Journal sub-skill when a claim needs source context beyond local static rows: current ClinVar assertion, gene mechanism, inheritance, penetrance, guideline evidence, population tension, or literature/source conflict.

Goal

Review focused public targets and write reviewed findings back into the local evidence DB before using them in final interpretation. In capability discovery, these tools are part of journal because they create reusable investigation memory rather than a separate evidence category.

Works with Active Genome Index context and public-only context. If Active Genome Index context exists, use its evidence DB for user-specific context. With public-only context, use the shared evidence DB and frame the answer as public-target source review.

Convention: See skills/conventions/evidence-quality.md. Convention: See skills/_output-rules.md.

Contract

Contract:

• External research uses selected public targets only.
• API-backed sources are marked in tool dependencyContract.externalNetwork; local source files are marked in dependencyContract.localResources. If an API source is unavailable, the tool returns source_unavailable.
• Reviewed source findings are written back before final interpretation.
• Shared evidence is reusable public-target knowledge.
• Private evidence is reserved for user-specific combinations and context.
• Public-only answers describe public-target evidence.

Cross-Capability Synthesis

A scope-limited result from this capability is not a final user-facing answer when other Genomi capabilities can contribute orthogonal evidence to the same question. Returning "cannot answer" while applicable capabilities remain unexamined is a host-agent failure mode.

Tools

gnomad.fetch_population_frequency

Fetch reusable gnomAD public population frequency for one allele and write it into evidence storage.

Use when: gnomAD population frequency would change interpretation of an exact public allele or candidate variant.

Why necessary: gnomAD allele frequency changes interpretation; common and rare variants should not be discussed the same way.

Result semantics: Writes reusable aggregate public gnomAD frequency rows using selected public allele data.

research.build_target_packet

Build a target-centric evidence packet after the agent identifies the user's target.

Use when: The agent has selected a gene, drug, condition, topic, or allele and needs local/source context for synthesis.

Why necessary: A target packet keeps gene, drug, condition, topic, and allele context grouped before synthesis.

Result semantics: Returns context and source candidates for agent synthesis.

research.list_sources

List source catalogs relevant to a target type or one source ID.

Use when: choosing public source families for a target type or inspecting one source contract.

Why necessary: Source choice is part of the evidence contract; agents need to know which public adapters fit a target.

Result semantics: Returns source adapter and focused-review contracts for the host agent's selected public target.

research.query

Retrieve reviewed research for an exact target from local evidence storage.

Use when: the agent needs stored reviewed research for one exact target.

Why necessary: Exact-target research retrieval prevents agents from relying on vague memory of prior reviews.

research.record

Store reviewed source findings or tool-returned record_research_payloads in evidence storage with explicit shared/private scope.

Use when: Use after the agent has a reviewed source finding or tool-returned research payload that should be stored with scope.

Why necessary: Reviewed findings need durable, scoped storage so later answers can reuse source-backed evidence.

Result semantics: Writes reviewed public-target or private user-specific findings according to scope; private scope requires an active/private evidence DB.

research.search

Token-search reviewed research findings stored in local evidence storage.

Use when: the agent needs token search across stored reviewed findings and does not have exact target fields.

Why necessary: Token search recovers stored findings when exact target fields are unknown.

Privacy Boundary

External research may use selected public targets: gene, rsID, normalized allele, drug, condition, topic, or guideline question. Intake files, broad candidate inventories, and private phenotype/medication/family context stay local unless the user explicitly chooses broader sharing.

Record Before Use

For source-backed interpretation, store a reviewed finding JSON file or an inline payload returned by a Genomi source tool:

• research.record with {"input":"finding.json","scope":"shared"}
• research.record with {"payload":{"target":{"type":"drug","drug":"clopidogrel"},"source":{"title":"CPIC","url":"https://cpicpgx.org/guidelines/"},"finding":{"type":"pgx_guideline","text":"short reviewed finding"}},"scope":"shared"}

With public-only context, db can be omitted and Genomi will use the shared evidence DB.

Use shared for reusable public-target knowledge. Use private for user-specific combinations, phenotype, medications, family history, or personal interpretation. Private scope uses the selected Active Genome Index evidence DB or an explicit private db.

Source Selection

Use research.list_sources before focused review when the source choice is uncertain. Each source returns:

• query_mode: implemented operation or focused source review.
• public_target_inputs: the fields safe to use for external review.
• available_operations: Genomi tools that support the source.
• reviewed_finding_shape: fields to store with research.record.

For GeneCards- or MalaCards-style context, use phenotype.plan_risk_investigation to keep gene function, disease association, and clinical-validity cross-checks separated.

For implemented sources, call the listed adapter first. For focused-review sources, review the official source or primary literature for the selected public target, extract the narrow finding needed for the user's question, and write it back as reviewed evidence.

Operating Checks

• Send selected public targets to external research.
• Use cited source findings as final evidence.
• Store reusable public-target knowledge as shared evidence.
• Store user-specific interpretation as private evidence.
• Write reviewed findings back before using a source in an answer.

Variant And Gene Evidence

Use this skill when the user asks about a specific rsID, allele, gene, genomic region, observed genotype, absence/reference claim, or whether the user's own Active Genome Index supports a claim.

Goal

Answer with the smallest evidence packet needed. Use sample support and callability checks when the claim requires them.

Run genomi.describe_context first if the Active Genome Index is unknown. If an active Active Genome Index exists, use it for sample-specific lookup. With public-only context, answer from public/source evidence or ask the user for a file only when personal evidence is required.

Use variant.resolve as the umbrella first lookup when the user's target is an rsID, coordinate, exact allele, locus, region, or mixed text. It resolves flexible input, checks the Active Genome Index, gathers existing deterministic ClinVar/population/reviewed-source facts, and can search explicitly selected accessible Active Genome Index records with agi_id or include_known_active_genome_indexes.

Convention: See skills/conventions/evidence-quality.md. Convention: See skills/_output-rules.md.

Contract

Contract:

• Personal variant claims are grounded in the selected Active Genome Index.
• Public-only variant answers are clearly marked public-only.
• Absence/reference claims require callability.
• Positive allele claims use genotype support when answer confidence matters.
• Medical meaning beyond static rows uses Journal source-review memory.

Cross-Capability Synthesis

A scope-limited result from this capability is not a final user-facing answer when other Genomi capabilities can contribute orthogonal evidence to the same question. Returning "cannot answer" while applicable capabilities remain unexamined is a host-agent failure mode.

Tools

active_genome_index.classify_genotype_support

Classify whether one exact allele has enough sample support to be used in a personal interpretation.

Use when: A user-specific interpretation depends on whether one exact allele is actually supported by Active Genome Index genotype/QC evidence.

Why necessary: A reported variant match still needs depth, genotype quality, and allele support before user-specific wording is justified.

Example prompts: Does this exact allele have enough support in my Active Genome Index?

Result semantics: Returns support_status and evidence_class; the host agent decides whether weak or missing support is a gap.

active_genome_index.classify_region_callability

Classify whether a region can support reference or absence claims.

Use when: A negative, reference, absent-marker, or no-variant claim depends on whether the region was callable.

Why necessary: Absence claims require callability; a missing variant in a poorly covered region is not evidence of absence.

Example prompts: Can this region support saying a variant was absent?

Result semantics: Returns callability_status and support for negative/reference wording; the host agent writes the claim.

variant.gather_allele_context

Gather existing sample, static, population, and reviewed research evidence for one allele.

Use when: The agent needs a consolidated context pack for one exact allele before interpreting or reporting it.

Why necessary: Variant reports need sample, static, population, and reviewed-research evidence gathered without recomputing unrelated evidence.

Result semantics: Combines stored sample/static/population/research evidence; missing sections are facts for the agent to interpret.

variant.gather_gene_context

Gather existing sample, ClinVar, and reviewed research evidence for one gene.

Use when: a selected gene needs existing sample, ClinVar, and reviewed-research context before synthesis.

Why necessary: Gene-level interpretation needs gene-scoped context, which is different from one exact variant lookup.

Result semantics: Combines stored gene-scoped sample, static, and reviewed research evidence; absence of a section is not negative evidence by itself.

variant.resolve

Resolve one variant target and return deterministic public, local sample, and stored evidence facts.

Use when: The user gives an rsID, chromosome coordinate, allele string, locus, region, or mixed variant text and needs deterministic facts before interpretation. The agent wants one lookup that can check the selected Active Genome Index and optionally approved previously parsed Active Genome Index records.

Why necessary: Precise variant questions need deterministic target resolution before public or personal evidence can be interpreted.

Not for: ranking population-trait candidate rsIDs; use gwas.compare_variant_associations for that task.

Example prompts: What is known about rs429358, and do I have it?

Result semantics: Returns resolved targets, local sample matches from Active Genome Index records, stored ClinVar/population/research facts, and target_inventory facts for host-agent synthesis. Previously parsed Active Genome Index records are searched only when agi_id or include_known_active_genome_indexes is supplied and scoped access is approved. ClinVar, Mendelian, stored research, and sample evidence are interpretation context, not population-trait lead-variant ranking evidence. target_inventory exposes resolved rsID, allele, sample, support, population, and reviewed-research facts; unanswered_answer_components identifies unresolved lookup components and missing inputs. The host agent decides whether any additional operation is relevant to the user's question.

Evidence Requirements

• Positive personal allele claims use sample observation plus genotype support from active_genome_index.classify_genotype_support or a current private genotype_support row.
• Negative or reference claims use active_genome_index.classify_region_callability.
• Medical meaning beyond static rows uses the Journal source-review sub-skill in the source research skill and reviewed findings stored with research.record.
• Gene/variant background with public-only context uses research.list_sources, research.query, research.search, or public research.

Gene Synthesis Checks

When variant.gather_gene_context is the selected evidence packet, cover only the pieces supported by the returned data and reviewed sources:

• Gene function in the user's question context.
• Sample observations and zygosity limits.
• ClinVar/static database labels with informational interpretation wording.
• Inheritance, mechanism, and penetrance only when supported by reviewed sources.
• Population evidence tension when allele frequency affects interpretation.
• Shared public-source knowledge versus private user-specific interpretation.
• Citations for every finding that reaches the user-facing answer.

Use explicit user/source evidence for phenotype, family history, medications, and phase. Use source titles or URLs as citations, not evidence classes. Keep medical language informational and include clinical-confirmation boundaries.

User-Facing Answer Shape

Lead with whether the file contains/supports the allele or region claim. Then explain what public evidence supports, its limitations, and what would reduce uncertainty.

Routing Checks

• Use callability for negative or reference claims.
• Use variant.resolve before narrower VCF or evidence tools when the input can be interpreted multiple ways or may exist in the Active Genome Index.
• Check ref/alt when rsID interpretation depends on the exact allele.
• Keep gene background separate from sample-specific interpretation.
• Use target-specific evidence packets for final interpretation.

Genomi Decode

The /genomi decode kicker tells the agent to assemble every relevant Genomi capability's evidence about the user's active genome and emit a single self-contained Genomi Dashboard.html artifact. Activate this skill whenever the user types /genomi decode, asks for "the dashboard", asks to "decode my genome", or asks for a one-shot evidence rundown.

Activation

This skill requires an Active Genome Index session and explicit approval to read it. The same approval gate that protects variant.resolve, clinvar.*, and the PGx ops protects decode.render_dashboard. If no active genome is selected the op fails with active_genome_index_required; if approval has not been granted it fails with active_genome_index_approval_required.

Reconcile Active Genome Index lifecycle before gathering panels

Call genomi.describe_context first. If active_genome_index.active_genome_index_readiness.status is needs_reparse or schema_too_new, handle the lifecycle before gathering any panel evidence — do not proceed with a stale Active Genome Index and silently bound the panels.

The full procedure lives in the Active Genome Index skill under the lifecycle guidance for needs_reparse and schema_too_new. Summary for decode:

1. If needs_reparse and availability.agi_intake_source_path is true, call genomi.parse_source({"source": active_genome_index.agi_intake_source_path}) without prompting. Routine maintenance.
2. If needs_reparse and the source path is gone, ask the user once for the current path and parse that. Don't continue with a stale Active Genome Index.
3. If schema_too_new, the user's runtime is out of date — tell them to upgrade Genomi, stop.
4. Only after active_genome_index_readiness.status == "complete" call the decode operation.

Dashboard Build

Call decode.render_dashboard. Decode owns panel gathering, panel shaping, and rendering. The agent may choose dashboard categories through structured parameters such as panels and select declared score/domain options. Omitted panels means every dashboard category. The agent does not assemble panel evidence and does not ask which PGx route to run; decode owns that work.

The renderer normalizes native upstream-op shapes internally:

• overview — adapts active_genome_index.summarize output; snake_case keys (genome_build, nickname, active_genome_index_completed_at, nearest_reference_groups) are mapped automatically.
• variants — adapts clinvar.scan_candidates variant inventory rows; clinvar.match_variants JSONL rows ({sample_variant, clinvar}) are also handled. Carrier/condition review groups render under risk, not variants.
• nutrigenomics — adapts nutrigenomics.retrieve_domain_markers; it extracts gene.symbol, variant.rsid, established_effect.claim (→ recommendation), evidence_tier, and domain label (→ marker).
• ancestry — adapts ancestry.estimate_population_context.
• pgx — adapts PharmCAT sample_pgx_matrix and medication-review medication_review_matrix rows into PGx cards without merging separate medication recommendations by gene alone.
• risk — adapts native prs.calculate_score results and phenotype.plan_risk_investigation carrier/condition review rows into risk/review cards.
• variants_all — uses the ClinVar matches JSONL path materialized by decode.

Decode also gathers the current carrier/condition and PGx review contracts:

• For risk, decode runs the declared risk_review_types from the selected Active Genome Index ClinVar matches scope. Omitted risk_review_types means carrier_review plus observed_condition_review; pass an empty array only when the user wants PRS-only risk evidence.
• For pgx, decode runs pharmacogenomics.review_medication for explicit pgx_review_targets and for drug/gene targets discovered in PharmCAT sample_pgx_matrix rows, up to pgx_review_target_limit. Gene-only sample rows can be preserved as sample evidence, but decode does not invent medication-specific recommendations without a declared drug/source target.

If no PRS scores are installed in the user's library, the builder supplies a typed empty risk state so stale risk evidence is cleared rather than preserved.

Verify before claiming success

The renderer's response is the source of truth:

• panels_rendered: panels that landed with real data.
• panels_empty: panels with no usable evidence — they render as category-specific unavailable states in the UI.
• evidence_build.panels_running: panels still running in a background job.
• evidence_build.panel_states: per-panel source status, including PGx background job ids and check operations when applicable.

Read panels_empty and any evidence_build.panel_states before telling the user the dashboard is ready. Surface incomplete categories honestly with their typed state.

Refresh vs. reuse

Call decode.render_dashboard again to refresh the dashboard after installing libraries or changing category selections. Panels without usable evidence render as category-specific unavailable states.

Output location

By default the artifact is written to <tmp>/genomi-dashboards/<sample>/dashboard.html. The user may override output with any absolute filesystem path; the parent directory is created on demand.

Serving the dashboard

decode.render_dashboard returns a serve block:

{
  "serve": {
    "status": "started",
    "directory": "...",
    "filename": "dashboard.html",
    "port": 8766,
    "url": "http://127.0.0.1:8766/dashboard.html",
    "command": "python3 -m http.server 8766 --bind 127.0.0.1 --directory ..."
  }
}

Normal runtime calls start a local static dashboard server automatically and choose a free localhost port. Tell the user serve.url. If serve.status is ready_to_start or start_failed, run serve.command as a fallback and then tell the user the adjusted URL.

Boundaries

• Active Genome Index session approval is required.
• Decode owns panel evidence collection and shaping for the dashboard artifact.
• The artifact is a single self-contained HTML file that renders fully offline — React/ReactDOM and the precompiled app JS are inlined, no CDN, no in-browser Babel. (One optional Google Fonts stylesheet is referenced; it falls back to system fonts offline and carries no genome data.) It opens by double-click; the local server is only there so the user can hit a URL.

Tool

decode.build_dashboard_evidence

Support operation used by decode.render_dashboard to inspect panel readiness and gaps. Normal dashboard requests should call decode.render_dashboard.

decode.render_dashboard

Build, shape, and render the Genomi Dashboard HTML artifact from the approved Active Genome Index. Returns { status, dashboard_path, panels_rendered, panels_empty, serve } plus the standard evidence_envelope. The serve block tells the host agent how to expose the dashboard at a localhost URL — see the "Serving the dashboard" section above.

Cross-Capability Synthesis

A scope-limited result from this capability is not a final user-facing answer when other Genomi capabilities can contribute orthogonal evidence to the same question. Returning "cannot answer" while applicable capabilities remain unexamined is a host-agent failure mode.