How Genomi connects host agents, MCP, tools, local context, public libraries, Active Genome Index artifacts, and dashboard output.

Genomi is a local harness with an MCP surface. The host agent supplies reasoning and natural-language interaction; Genomi supplies structured genome and evidence operations.

Runtime Flow

How a host agent routes a question through Genomi.

runtimeprivate genomepublic evidencetoolsmemory/artifactsstatus gates

User asksVariant, drug, trait, disease, sequence, report, or memory question.

Host agentReads Genomi skills, resolves intent, and keeps chat-scoped context.

Genomi MCPgenomi serve exposes base tools and the genomi.invoke dispatcher.

Public-only path

No genome neededPublic variant, gene, phenotype, drug, pathway, or source question.

Evidence sourcesLocal libraries or declared network-backed public sources.

Personal genome path

Approval boundaryCurrent-chat source path, approved existing index, or selected default user.

Active Genome Indexgenomi.parse_source creates or refreshes local SQLite and VCF artifacts.

Base toolsgenomi.*, journal.*, and research.* appear directly in the MCP tool list.

Capability toolsSpecialized operations run through genomi.invoke after the matching skill is read.

Focused operationOne smallest useful action, such as variant, ClinVar, PGx, GWAS, PRS, ancestry, or sequence.

Result envelopeEvidence, defaults, coverage, warnings, source state, and next actions.

Agent inspectionChecks trust, conflicts, missing evidence, and clinical boundaries.

Journal or reportOptional traceable memory, reviewed findings, or dashboard-ready evidence.

AnswerEvidence-backed, informational, and limited to what the sources support.

Explicit statusesin_progress, requires_library_install, source_unavailable, and ask_user.

Runtime layers

Layer	Role
Host agent	Reads Genomi skills, asks for user approval, chooses tools, explains results
Skills	Static routing and operating rules in `SKILL.md` and `skills/*/SKILL.md`
MCP server	`genomi serve` over stdio
Operation registry	Validates operation names, schemas, defaults, and dispatch
Runtime context	Session context, user registry, response profile, AGI access grants
Active Genome Index	Local SQLite index and canonicalized source artifacts for a genome
Libraries	Local public data and managed tools under `GENOMI_HOME`
Capabilities	Focused tools for variant, ClinVar, PGx, GWAS, PRS, ancestry, sequence, and more
Journal	Agent-authored investigation notes and reviewed source findings
Decode dashboard	Self-contained HTML artifact rendered from supplied panel evidence

tools/list returns the base tool set by default. In current Genomi, that base set is the genomi capability plus the journal capability, which includes the journal operations and the reviewed-research operations in the research namespace.

Everything else is reached through genomi.invoke:

{
  "tool": "variant.resolve",
  "params": {
    "rsid": "rs429358"
  }
}

The host should read the matching capability skill before invoking a non-base operation. That skill explains when the tool is appropriate, what inputs are required, and what result semantics mean.

Operation catalog

The operation catalog is assembled from:

src/genomi/operations/catalog_base.json
src/genomi/runtime/tool_catalog.json
src/genomi/active_genome_index/tool_catalog.json
src/genomi/capabilities/*/tool_catalog.json

Each operation declares its capability, namespace, JSON input schema, privacy scope, operation scope, required context, produced evidence type, and dependency contract. The dispatcher uses this catalog to validate calls.

Result envelopes

Agents should inspect every result, not just the top-level answer text. Important states include:

State	Meaning
`defaults_applied`	The tool filled an omitted parameter. Treat this as part of the reasoning chain.
`status="in_progress"`	A background job is still running. Poll `genomi.check_background_job` with the returned `job_id`.
`status="requires_library_install"`	A local library or tool is missing. Ask before installing; do not treat missing library evidence as negative evidence.
`source_unavailable`	A network or external source could not be reached. State the answerability gap or try another source.
`ask_user`	The tool is explicitly asking the host to surface a user decision.

Context and privacy model

Live state comes from Genomi operations, not from documentation files. A genome source path supplied in the current chat grants access to that source for the current session. Reading an existing imported Active Genome Index requires explicit session approval unless it is the selected default user's active index.

Genomi keeps raw genome sources and parsed artifacts on local disk. Host agents may send selected evidence snippets to the model they are using. Use a local model or a host with an appropriate data policy when that matters.

Background jobs

Long operations can run through the background-job layer. MCP calls wait for a short timeout; if the job is not done, the result includes a job_id.

Continue by polling:

{
  "job_id": "<job-id>"
}

Do not restart a parse with max_records as a substitute for a complete Active Genome Index unless the user explicitly asked for a sampling/debug run.

Architecture