---
name: active-genome-index
description: |
  Register, parse, and digitize private genome source files into a local Active Genome Index and
  supporting evidence stores. Use when the session explicitly supplies a VCF/gVCF, BAM,
  genome.computer .genome/1.0 bundle, 23andMe raw genotype export, AncestryDNA raw genotype export, MyHeritage raw
  genotype export, FamilyTreeDNA Family Finder export, Living DNA autosomal export, supported source zip/tar,
  or known Active Genome Index.
tools:
  - genomi.describe_context
  - active_genome_index.approve_access
  - active_genome_index.select_user
  - active_genome_index.assign_user_genome
  - genomi.parse_source
  - active_genome_index.rename_user
  - active_genome_index.set_default_user
  - active_genome_index.clear_default_user
  - active_genome_index.summarize
  - active_genome_index.classify_callset_qc
  - active_genome_index.classify_genotype_support
  - active_genome_index.classify_region_callability
  - active_genome_index.clear_selection
  - active_genome_index.revoke_access
  - active_genome_index.list
  - active_genome_index.remove
mutating: true
---

# 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 or an Active Genome Index explicitly approved in the current session 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 as metadata for every session using this `GENOMI_HOME`; its selected Active Genome Index still requires current-session approval before a private read.
- `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 current-session approval, including for 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 selected as metadata by default in every session.

**Why necessary**: Default selection identifies one profile without selecting every genome or user; it does not grant private read access.

**Example prompts**: Make Alice the default user.

**Result semantics**: Sets exactly one default user for metadata selection. The selected Active Genome Index requires explicit approval in every session before private reads.

## 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
  for that user's selected Active Genome Index.
- 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` or supplies its source path. Default
  user selection is metadata-only.
- 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 metadata; approve any previously imported Active Genome Index before reading it.
- 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.