Genomi

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.
• A configured default user may select an Active Genome Index as metadata, but default selection never replaces current-session read approval.
• 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 default set:

• Core genomi.*, research.*, and journal.* operations.
• The complete direct genomilab.* host-application boundary.
• genomi.invoke — the dispatcher for every other capability tool.

Before using a genomilab.* operation, load skills/genomilab/SKILL.md. Those tools keep the current Claude/Codex task in control; they require a query-ready selected Active Genome Index, bind patient authorization to the current MCP session, and use the portal only for onboarding, exact approvals, provider setup, and committed-event monitoring.

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.