altar 0.1.0__py3-none-any.whl

altar/__init__.py

@@ -0,0 +1,10 @@
+"""Infrastructure-neutral contracts and reference adapters for genomic analysis.
+
+The supported API is intentionally exposed through the documented façade modules such as
+:mod:`altar.models`, :mod:`altar.execution`, and :mod:`altar.sources`.  The package root only exposes the
+distribution version; it does not flatten those concept-specific namespaces.
+"""
+
+__version__: str = "0.1.0"
+
+__all__ = ["__version__"]

altar/access.py

@@ -0,0 +1,30 @@
+"""Provisional authentication-provider contract.
+
+Authentication extensions should implement :class:`AuthProvider` through this module.  Agent credentials
+and service-specific clients are not part of this API.
+
+Every name in this module is provisional and listed in ``__provisional__``: it remains importable, but it is
+excluded from the stable-API commitment.  Altar ships only the development-only ``DevAuthProvider`` and no
+component that consumes the contract.  The module becomes stable when a public production adapter, an
+in-repository consumer, documentation, and conformance coverage of that adapter exist.
+"""
+
+from altar.plugins.auth import AuthIdentity, AuthProvider, DevAuthProvider, InvalidTokenError, get_auth_registry
+
+
+__all__ = [
+    "AuthIdentity",
+    "AuthProvider",
+    "DevAuthProvider",
+    "InvalidTokenError",
+    "get_auth_registry",
+]
+
+# Exported but outside the stable-API commitment; see docs/public-api.md ("Provisional names").
+__provisional__ = (
+    "AuthIdentity",
+    "AuthProvider",
+    "DevAuthProvider",
+    "InvalidTokenError",
+    "get_auth_registry",
+)

altar/agent/__init__.py

@@ -0,0 +1,13 @@
+"""Experimental LangGraph agent and tools for triaging scored variants.
+
+This optional namespace is not part of the stable façade. Its contracts and imports may change without a
+compatibility period and require the `[agent]` extra plus provider credentials for real runs.
+
+The agent reasons over a scoring job's variants — filtering and ranking them, pulling candidate
+genes, cell-type expression, and literature, and (where a host supplies a knowledge provider)
+disease evidence — and streams its work back to a chat UI. It depends on its host only through small seams:
+data stores (`altar.agent.stores`), a knowledge provider (`altar.agent.knowledge`), an LLM
+API-key provider (`altar.agent.utils.llms`), and a genome-browser relay (`altar.agent.browser`).
+Each seam ships a built-in default, so the agent runs standalone and a host swaps in richer
+implementations by injecting or installing its own.
+"""

altar/agent/browser.py

@@ -0,0 +1,88 @@
+"""The genome-browser relay seam the browser-control tools depend on.
+
+The agent's genome-browser tools drive a Loom genome browser running in the user's UI over
+a live connection. A host that offers this connects the two ends and exposes a *relay*: a
+lookup, keyed by an opaque per-browser `session_id`, from that session to a connected Loom
+client, plus a readiness signal for it. One `session_id` identifies one browser instance
+(one UI panel), so a host that shows several browsers at once keeps them from colliding.
+
+The relay is process-wide infrastructure — a single registry of live connections per
+process — so it is installed once via `set_browser_relay` rather than threaded through
+every tool. Hosts that don't serve a live browser leave the built-in default in place: it
+reports every session as disconnected, so the browser tools stay dormant and return a "no
+browser is connected" message instead of failing.
+"""
+
+from __future__ import annotations
+import asyncio
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+
+if TYPE_CHECKING:
+    from loom_client import LoomClient
+
+
+@runtime_checkable
+class BrowserRelay(Protocol):
+    """Lookup from a browser `session_id` to its live connection and readiness signal.
+
+    `session_id` is an opaque token identifying one browser instance. The relay is
+    `runtime_checkable`, so a host can assert its own implementation conforms with an
+    `issubclass` check.
+    """
+
+    def is_browser_connected(self, session_id: str) -> bool:
+        """Return whether a browser is currently connected for this session."""
+        ...
+
+    def get_loom_client(self, session_id: str) -> LoomClient:
+        """Return the connected Loom client for this session.
+
+        Raises `ConnectionError` if no browser is connected.
+        """
+        ...
+
+    def get_browser_ready_event(self, session_id: str) -> asyncio.Event:
+        """Return (creating if needed) the readiness event for this session.
+
+        The event is set once the browser has mounted and can handle commands.
+        """
+        ...
+
+
+class DefaultBrowserRelay:
+    """The built-in default: no browser is ever connected.
+
+    With this relay installed the browser tools stay dormant — `is_browser_connected` is
+    always `False`, `get_loom_client` raises, and each `get_browser_ready_event` returns a
+    fresh event that is never set — so the tools report that no browser is connected instead
+    of acting on one.
+    """
+
+    def is_browser_connected(self, session_id: str) -> bool:
+        return False
+
+    def get_loom_client(self, session_id: str) -> LoomClient:
+        msg = "No genome browser is connected for this session."
+        raise ConnectionError(msg)
+
+    def get_browser_ready_event(self, session_id: str) -> asyncio.Event:
+        return asyncio.Event()
+
+
+_browser_relay: BrowserRelay = DefaultBrowserRelay()
+
+
+def set_browser_relay(relay: BrowserRelay) -> None:
+    """Install the relay the browser tools use to reach connected browsers.
+
+    Call once at startup. A host that serves a live genome browser installs a relay backed by
+    its connection registry; otherwise the no-browser default applies.
+    """
+    global _browser_relay
+    _browser_relay = relay
+
+
+def get_browser_relay() -> BrowserRelay:
+    """Return the installed browser relay (the no-browser default until overridden)."""
+    return _browser_relay

altar/agent/checkpointer.py

@@ -0,0 +1,18 @@
+"""Shared LangGraph checkpointer singleton for the application."""
+
+from langgraph.checkpoint.postgres.aio import AsyncPostgresSaver
+
+
+_checkpointer: AsyncPostgresSaver | None = None
+
+
+def get_checkpointer() -> AsyncPostgresSaver:
+    if _checkpointer is None:
+        msg = "Checkpointer not initialized — call set_checkpointer() during app startup"
+        raise RuntimeError(msg)
+    return _checkpointer
+
+
+def set_checkpointer(cp: AsyncPostgresSaver) -> None:
+    global _checkpointer
+    _checkpointer = cp

altar/agent/knowledge.py

@@ -0,0 +1,107 @@
+"""The agent's host-knowledge seam.
+
+Altar does not build, store, or traverse a knowledge graph (see the repository's architectural
+invariants). Some hosts have one, and the variant-prioritization agent can use context derived
+from it: HPO id → name resolution, HGNC symbol → Ensembl id, ontology term names, and per-variant
+evidence for the `ExamineVariant` tool. Every such touchpoint routes through this one protocol, so
+the host owns graph construction, ontology traversal, and disease-evidence synthesis, and the agent
+only consumes the resulting typed values. Two implementations satisfy it:
+
+  * a host that has a knowledge graph supplies an implementation backed by it — the agent gains
+    whatever disease context, ontology names, and gene-id resolution that host provides;
+  * `DefaultKnowledgeProvider` below is the built-in fallback — a fully functional agent for the
+    core prioritization loop that simply lacks those host-derived signals.
+
+The provider is injected the same way the data-store seams are: closed over in
+`create_prioritization_graph` and handed to the tools that need it (`ExamineVariant`,
+`GetGeneExpression`, `GetRelevantModels`) and to the system prompt (HPO names). Nothing in Altar
+imports a graph implementation.
+
+The four surfaces and what the built-in default returns when no host provider is wired:
+
+  | method               | resolves                                   | default (no provider) |
+  | -------------------- | ------------------------------------------ | --------------------- |
+  | `hpo_id_to_name`     | HPO id → human-readable name               | `{}`                  |
+  | `resolve_ensembl_id` | HGNC gene symbol → Ensembl gene id         | `None`                |
+  | `ontology_term_name` | ontology term id (e.g. a CL id) → name     | `None`                |
+  | `examine_variant`    | per-variant `VariantEvidence`              | stub evidence         |
+"""
+
+from __future__ import annotations
+from typing import Protocol, runtime_checkable
+
+from altar.agent.tools.variant_analysis.schemas import VariantEvidence
+
+
+@runtime_checkable
+class AgentKnowledgeProvider(Protocol):
+    """The host-knowledge surface the prioritization agent depends on.
+
+    A host with a knowledge graph implements these four methods against it; the built-in
+    `DefaultKnowledgeProvider` answers empty when no provider is wired.
+    """
+
+    def hpo_id_to_name(self) -> dict[str, str]:
+        """Return the full HPO id → human-readable name map (`{}` when unavailable)."""
+        ...
+
+    async def resolve_ensembl_id(self, symbol: str) -> str | None:
+        """Resolve an HGNC gene symbol to its Ensembl gene id (`None` when unavailable)."""
+        ...
+
+    def ontology_term_name(self, term_id: str) -> str | None:
+        """Resolve an ontology term id (e.g. a CL cell-type id) to its name (`None` when unavailable)."""
+        ...
+
+    async def examine_variant(
+        self,
+        job_id: str,
+        variant_id: str,
+        phenotypes: list[str],
+    ) -> VariantEvidence:
+        """Return host-derived evidence for one variant (`chr:pos:ref:alt`).
+
+        How the evidence is assembled is entirely the host's concern; Altar only defines the
+        returned `VariantEvidence` shape (nearby genes, model scores, motif effects, cCRE
+        overlaps, disease links, phenotype paths, and a markdown `agent_summary`). The built-in
+        default returns a minimal `VariantEvidence` carrying only the variant id and a
+        "no knowledge provider" note.
+        """
+        ...
+
+
+class DefaultKnowledgeProvider:
+    """The built-in `AgentKnowledgeProvider` with no host knowledge — the default a host gets
+    when it wires none.
+
+    The agent stays fully functional for the core prioritization loop (filter/count/candidate
+    genes/literature/sublists/KB); it just cannot resolve HPO or ontology names, cannot map gene
+    symbols to Ensembl ids (so `GetGeneExpression` finds nothing to query), and `ExamineVariant`
+    returns a stub rather than host evidence. A host with its own knowledge source replaces this
+    with a conforming provider.
+    """
+
+    def hpo_id_to_name(self) -> dict[str, str]:
+        return {}
+
+    async def resolve_ensembl_id(self, symbol: str) -> str | None:
+        return None
+
+    def ontology_term_name(self, term_id: str) -> str | None:
+        return None
+
+    async def examine_variant(
+        self,
+        job_id: str,
+        variant_id: str,
+        phenotypes: list[str],
+    ) -> VariantEvidence:
+        return VariantEvidence(
+            variant_id=variant_id,
+            agent_summary=(
+                f"## Variant: {variant_id}\n"
+                "No host knowledge provider is configured, so no disease or phenotype evidence is "
+                "available for this variant. Use FilterJobVariants and the variant's model scores "
+                "for prioritization instead."
+            ),
+        )