Skip to content

Variant-investigation agent

Experimental

The optional altar.agent package provides a LangGraph workflow for investigating scored variants. It can filter and count results, examine host-supplied variant evidence, identify candidate genes, query cell-type expression from CELLxGENE, search literature in Europe PMC and bioRxiv, save sublists, and maintain an investigation knowledge base. Gene symbols are resolved to Ensembl identifiers through the host's knowledge provider, not through an identifier service.

It is not part of Altar's stable façade. Its graph state, tools, service clients, and host interfaces may change before 1.0.

Install

pip install "altar[agent]"

Real investigations also require an LLM provider key and access to any external evidence services selected by the host.

What the host supplies

  • scored variant and job context, including the job's models (each may name its plugin architecture, which the system prompt uses instead of assuming a model family);
  • persistent stores for variants, sublists, and investigation state;
  • an optional knowledge provider (altar.agent.knowledge.AgentKnowledgeProvider);
  • a LangGraph checkpointer;
  • LLM configuration and credentials;
  • optional genome-browser relay;
  • authentication, authorization, tenancy, and request policy.

Knowledge-graph context

Altar does not build, store, or traverse a knowledge graph, and the agent contains no graph-path search or disease-hypothesis synthesis. Knowledge-graph context reaches the agent only through the host-supplied AgentKnowledgeProvider, which answers four narrow questions: HPO term names, gene symbol to Ensembl identifier, ontology term names, and per-variant VariantEvidence for the ExamineVariant tool. How a host derives that evidence (for example, path search over its own graph) is the host's concern.

Without a provider, the built-in DefaultKnowledgeProvider is used. Filtering, counting, candidate genes, literature search, sublists, and the knowledge base work normally; ontology names are unresolved, gene expression lookups find no Ensembl identifiers, and ExamineVariant returns a stub rather than disease evidence.

The investigation "knowledge base" is a per-job store of notes the agent writes and reads across conversations. It is not a knowledge graph.

Service clients

altar.apis contains thin async clients for Europe PMC, bioRxiv, HGNC, GTEx, and CELLxGENE. They hold no host state and share a rate-limited REST base (altar.apis.rest_api). The agent's tools call the Europe PMC, bioRxiv, and CELLxGENE clients.

Reference host

The repository's altar/reference directory contains a FastAPI backend and React interface backed by SQLite. It includes a synthetic demonstration job and streams agent output in Vercel AI SDK format.

cd altar/reference
ANTHROPIC_API_KEY=sk-... docker compose up --build

The backend image builds from the repository root and installs altar-identity from identity/, altar[agent], and the altar-chrombpnet binding, which the demo's stubbed scorer resolves through the model registry.

Open http://localhost:5173. The reference host is deliberately single-tenant and unauthenticated; do not deploy it as a production service without adding access control and operational policy.

Interpretation limits

Agent-generated hypotheses require expert review. Verify citations against their sources, distinguish absent service results from negative biological evidence, and preserve tool/service provenance in downstream reports.