active-genome-index

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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.

From yo-steven/genomi-exploration-20260613, Apache-2.0.

More from yo-steven/genomi-exploration-20260613