ngs-agent 0.2.0__py3-none-any.whl

ngs_agent/__init__.py

@@ -0,0 +1,3 @@
+"""NGS-Agent: pipeline log watcher and VCF/QC interpreter for wet-lab researchers."""
+
+__version__ = "0.2.0"

ngs_agent/acmg.py

@@ -0,0 +1,229 @@
+"""ACMG/AMP guidelines variant classification engine."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+ACMG_CRITERIA: dict[str, dict[str, Any]] = {
+    "PVS1": {
+        "code": "PVS1",
+        "strength": "Very Strong Pathogenic",
+        "category": "pathogenic",
+        "description": "Null variant in a gene where loss of function is a known disease mechanism.",
+    },
+    "PS1": {
+        "code": "PS1",
+        "strength": "Strong Pathogenic",
+        "category": "pathogenic",
+        "description": "Same amino acid change as a previously established pathogenic variant.",
+    },
+    "PS2": {
+        "code": "PS2",
+        "strength": "Strong Pathogenic",
+        "category": "pathogenic",
+        "description": "De novo variant (with confirmed maternity and paternity).",
+    },
+    "PS3": {
+        "code": "PS3",
+        "strength": "Strong Pathogenic",
+        "category": "pathogenic",
+        "description": "Functional studies show a validated damaging effect on protein function.",
+    },
+    "PS4": {
+        "code": "PS4",
+        "strength": "Strong Pathogenic",
+        "category": "pathogenic",
+        "description": "Prevalence in affected individuals is significantly increased over controls.",
+    },
+    "PM1": {
+        "code": "PM1",
+        "strength": "Moderate Pathogenic",
+        "category": "pathogenic",
+        "description": "Located in a known mutational hotspot or well-established functional domain.",
+    },
+    "PM2": {
+        "code": "PM2",
+        "strength": "Moderate Pathogenic",
+        "category": "pathogenic",
+        "description": "Absent or extremely rare in population databases (gnomAD).",
+    },
+    "PM4": {
+        "code": "PM4",
+        "strength": "Moderate Pathogenic",
+        "category": "pathogenic",
+        "description": "Protein length changes due to in-frame deletion/insertion or stop-loss.",
+    },
+    "PM5": {
+        "code": "PM5",
+        "strength": "Moderate Pathogenic",
+        "category": "pathogenic",
+        "description": "Novel missense at an amino acid residue where a different pathogenic missense is known.",
+    },
+    "PP1": {
+        "code": "PP1",
+        "strength": "Supporting Pathogenic",
+        "category": "pathogenic",
+        "description": "Cosegregation with disease in multiple affected family members.",
+    },
+    "PP2": {
+        "code": "PP2",
+        "strength": "Supporting Pathogenic",
+        "category": "pathogenic",
+        "description": "Missense variant in a gene where missense is a common disease mechanism.",
+    },
+    "PP3": {
+        "code": "PP3",
+        "strength": "Supporting Pathogenic",
+        "category": "pathogenic",
+        "description": "Multiple in silico computational tools predict a damaging effect.",
+    },
+    "PP5": {
+        "code": "PP5",
+        "strength": "Supporting Pathogenic",
+        "category": "pathogenic",
+        "description": "Reputable source reports pathogenic, but detailed evidence is not available.",
+    },
+    "BA1": {
+        "code": "BA1",
+        "strength": "Standalone Benign",
+        "category": "benign",
+        "description": "Allele frequency is > 5% in a major population database (gnomAD).",
+    },
+    "BS1": {
+        "code": "BS1",
+        "strength": "Strong Benign",
+        "category": "benign",
+        "description": "Allele frequency is greater than expected for disorder.",
+    },
+    "BS2": {
+        "code": "BS2",
+        "strength": "Strong Benign",
+        "category": "benign",
+        "description": "Observed in a healthy adult individual for a penetrant disorder.",
+    },
+    "BS3": {
+        "code": "BS3",
+        "strength": "Strong Benign",
+        "category": "benign",
+        "description": "Well-established functional studies show no damaging effect.",
+    },
+    "BP1": {
+        "code": "BP1",
+        "strength": "Supporting Benign",
+        "category": "benign",
+        "description": "Missense variant in a gene for which only truncating mutations cause disease.",
+    },
+    "BP4": {
+        "code": "BP4",
+        "strength": "Supporting Benign",
+        "category": "benign",
+        "description": "Multiple lines of computational evidence predict no damaging effect.",
+    },
+    "BP6": {
+        "code": "BP6",
+        "strength": "Supporting Benign",
+        "category": "benign",
+        "description": "Reputable source reports benign, but detailed evidence is not available.",
+    },
+    "BP7": {
+        "code": "BP7",
+        "strength": "Supporting Benign",
+        "category": "benign",
+        "description": "Synonymous variant with no predicted splice impact.",
+    },
+}
+
+
+@dataclass
+class ACMGEvaluation:
+    codes: list[str] = field(default_factory=list)
+    classification: str = "VUS"
+    explanation: str = ""
+    confidence: float = 0.0
+
+
+def compute_acmg_classification(criteria_codes: list[str]) -> ACMGEvaluation:
+    """Compute ACMG/AMP 5-tier classification from criteria codes."""
+    codes = [c.upper().strip() for c in criteria_codes if c.upper().strip() in ACMG_CRITERIA]
+
+    pvs1 = codes.count("PVS1")
+    ps = sum(1 for c in codes if c.startswith("PS"))
+    pm = sum(1 for c in codes if c.startswith("PM"))
+    pp = sum(1 for c in codes if c.startswith("PP"))
+
+    ba1 = codes.count("BA1")
+    bs = sum(1 for c in codes if c.startswith("BS"))
+    bp = sum(1 for c in codes if c.startswith("BP"))
+
+    has_pathogenic = (pvs1 > 0 or ps > 0 or pm > 0 or pp > 0)
+    has_benign = (ba1 > 0 or bs > 0 or bp > 0)
+
+    # Standalone Benign
+    if ba1 >= 1 and not has_pathogenic:
+        return ACMGEvaluation(
+            codes=codes,
+            classification="Benign",
+            explanation="Standalone Benign: Allele frequency > 5% in population databases (BA1).",
+            confidence=0.99,
+        )
+
+    # Pathogenic combinations
+    is_pathogenic = (
+        (pvs1 >= 1 and (ps >= 1 or pm >= 2 or (pm >= 1 and pp >= 1) or pp >= 2))
+        or (ps >= 2)
+        or (ps >= 1 and (pm >= 3 or (pm >= 2 and pp >= 2) or (pm >= 1 and pp >= 4)))
+    )
+    if is_pathogenic and not has_benign:
+        return ACMGEvaluation(
+            codes=codes,
+            classification="Pathogenic",
+            explanation=f"Meets ACMG/AMP Pathogenic criteria rules ({len(codes)} criteria applied).",
+            confidence=0.95,
+        )
+
+    # Likely Pathogenic combinations
+    is_likely_pathogenic = (
+        (pvs1 >= 1 and pm >= 1)
+        or (ps >= 1 and (pm in (1, 2) or pp >= 2))
+        or (pm >= 3)
+        or (pm >= 2 and pp >= 2)
+        or (pm >= 1 and pp >= 4)
+    )
+    if is_likely_pathogenic and not has_benign:
+        return ACMGEvaluation(
+            codes=codes,
+            classification="Likely Pathogenic",
+            explanation=f"Meets ACMG/AMP Likely Pathogenic criteria rules ({len(codes)} criteria applied).",
+            confidence=0.90,
+        )
+
+    # Benign combinations
+    if bs >= 2 and not has_pathogenic:
+        return ACMGEvaluation(
+            codes=codes,
+            classification="Benign",
+            explanation=f"Meets ACMG/AMP Benign criteria rules ({len(codes)} criteria applied).",
+            confidence=0.95,
+        )
+
+    # Likely Benign combinations
+    is_likely_benign = (
+        (bs >= 1 and bp >= 1)
+        or (bp >= 2)
+    )
+    if is_likely_benign and not has_pathogenic:
+        return ACMGEvaluation(
+            codes=codes,
+            classification="Likely Benign",
+            explanation=f"Meets ACMG/AMP Likely Benign criteria rules ({len(codes)} criteria applied).",
+            confidence=0.90,
+        )
+
+    return ACMGEvaluation(
+        codes=codes,
+        classification="VUS",
+        explanation="Criteria do not reach Pathogenic or Benign thresholds or exhibit conflicting evidence; remains Variant of Uncertain Significance.",
+        confidence=0.75,
+    )

ngs_agent/analyzer.py

@@ -0,0 +1,221 @@
+"""VCF parser, QC scanner, and report rendering."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+
+from ngs_agent.qc import QCMetric, QCParser
+
+
+@dataclass
+class Variant:
+    chrom: str
+    pos: int
+    ref: str
+    alt: str
+    gene: str
+    consequence: str
+    clinvar: str
+    af: float | None
+    depth: int | None
+    vaf: float | None
+    is_pathogenic: bool = False
+    is_vus: bool = False
+    samples: dict[str, dict[str, Any]] = field(default_factory=dict)
+
+
+def _parse_consequence(csq_or_ann: str | None) -> str:
+    if not csq_or_ann or csq_or_ann == ".":
+        return "."
+    first_allele_csq = csq_or_ann.split(",")[0]
+    if "|" in first_allele_csq:
+        parts = first_allele_csq.split("|")
+        if len(parts) > 1 and parts[1]:
+            return parts[1]
+        return parts[0]
+    return first_allele_csq
+
+
+def parse_vcf(path: Path) -> list[Variant]:
+    variants: list[Variant] = []
+    with path.open(encoding="utf-8") as fh:
+        sample_names: list[str] = []
+        for line in fh:
+            if line.startswith("##"):
+                continue
+            if line.startswith("#CHROM"):
+                headers = line.strip().split("\t")
+                if len(headers) > 9:
+                    sample_names = headers[9:]
+                continue
+
+            parts = line.strip().split("\t")
+            if len(parts) < 8:
+                continue
+            chrom, pos_s, _id, ref, alt = parts[0], parts[1], parts[2], parts[3], parts[4]
+            info = parts[7]
+            format_keys = parts[8].split(":") if len(parts) > 8 else []
+            fmt = parts[9] if len(parts) > 9 else ""
+
+            csq_raw = _info_field(info, "CSQ") or _info_field(info, "ANN") or _info_field(info, "CONSEQUENCE") or "."
+            consequence = _parse_consequence(csq_raw)
+
+            gene = _info_field(info, "GENE") or _info_field(info, "SYMBOL")
+            if not gene or gene == ".":
+                if csq_raw != ".":
+                    first_csq = csq_raw.split(",")[0]
+                    csq_parts = first_csq.split("|")
+                    if len(csq_parts) >= 4 and csq_parts[3] and csq_parts[3] != ".":
+                        gene = csq_parts[3]
+                    elif len(csq_parts) >= 5 and csq_parts[4] and csq_parts[4] != ".":
+                        gene = csq_parts[4]
+            if not gene:
+                gene = "."
+
+            clinvar = _info_field(info, "CLNSIG") or _info_field(info, "CLINVAR") or "."
+            af = _parse_float(_info_field(info, "AF"))
+            depth, vaf = _parse_sample(fmt, format_keys)
+
+            clinvar_lower = clinvar.lower()
+            is_pathogenic = "pathogenic" in clinvar_lower and "conflict" not in clinvar_lower
+            is_vus = (
+                "uncertain" in clinvar_lower
+                or "vus" in clinvar_lower
+                or "unknown significance" in clinvar_lower
+                or "unknown_significance" in clinvar_lower
+            )
+
+            # Parse multisample columns if available
+            sample_data = {}
+            if sample_names and len(parts) > 9:
+                for idx, sname in enumerate(sample_names):
+                    if 9 + idx < len(parts):
+                        sfmt = parts[9 + idx]
+                        s_dp, s_vaf = _parse_sample(sfmt, format_keys)
+                        sample_data[sname] = {"dp": s_dp, "vaf": s_vaf, "raw": sfmt}
+
+            variants.append(
+                Variant(
+                    chrom=chrom,
+                    pos=int(pos_s),
+                    ref=ref,
+                    alt=alt,
+                    gene=gene,
+                    consequence=consequence,
+                    clinvar=clinvar,
+                    af=af,
+                    depth=depth,
+                    vaf=vaf,
+                    is_pathogenic=is_pathogenic,
+                    is_vus=is_vus,
+                    samples=sample_data,
+                )
+            )
+    return variants
+
+
+def _info_field(info: str, key: str) -> str | None:
+    for part in info.split(";"):
+        if part.startswith(f"{key}="):
+            return part.split("=", 1)[1]
+    return None
+
+
+def _parse_float(value: str | None) -> float | None:
+    if value is None:
+        return None
+    try:
+        return float(value.split(",")[0])
+    except ValueError:
+        return None
+
+
+def _parse_sample(fmt: str, format_keys: list[str]) -> tuple[int | None, float | None]:
+    if not fmt or fmt == ".":
+        return None, None
+    values = fmt.split(":")
+    fields = dict(zip(format_keys, values, strict=False))
+
+    depth = None
+    vaf = None
+    if "DP" in fields:
+        try:
+            depth = int(float(fields["DP"]))
+        except (ValueError, TypeError):
+            depth = None
+    if "AD" in fields:
+        try:
+            ad_parts = fields["AD"].split(",")
+            ads = [int(float(x)) for x in ad_parts if x not in (".", "")]
+            if len(ads) >= 2 and sum(ads) > 0:
+                vaf = ads[1] / sum(ads)
+                if depth is None:
+                    depth = sum(ads)
+        except (ValueError, TypeError):
+            vaf = None
+    return depth, vaf
+
+
+def scan_qc(path: Path) -> list[QCMetric]:
+    """Scan any QC file (FastQC, MultiQC, Samtools, or plain text)."""
+    return QCParser.parse(path)
+
+
+def render_report(
+    variants: list[Variant],
+    qc_metrics: list[QCMetric] | None = None,
+    console: Console | None = None,
+) -> None:
+    con = console or Console()
+    pathogenic = [v for v in variants if v.is_pathogenic]
+    vus = [v for v in variants if v.is_vus]
+    other = [v for v in variants if not v.is_pathogenic and not v.is_vus]
+
+    con.print(Panel("[bold]NGS-Agent Variant Report[/bold]", style="blue"))
+
+    if qc_metrics:
+        qc_table = Table(title="QC Summary", show_header=True)
+        qc_table.add_column("Metric")
+        qc_table.add_column("Value")
+        qc_table.add_column("Status")
+        for m in qc_metrics:
+            style = {"pass": "green", "warn": "yellow", "fail": "red"}.get(m.status, "white")
+            qc_table.add_row(m.name, m.value, f"[{style}]{m.status.upper()}[/{style}]")
+        con.print(qc_table)
+        con.print()
+
+    def _variant_table(title: str, rows: list[Variant], style: str) -> None:
+        if not rows:
+            return
+        table = Table(title=title, show_header=True, header_style=style)
+        table.add_column("Gene")
+        table.add_column("Variant")
+        table.add_column("Consequence")
+        table.add_column("ClinVar")
+        table.add_column("Depth/VAF")
+        for v in rows:
+            loc = f"{v.chrom}:{v.pos} {v.ref}>{v.alt}"
+            dv = f"{v.depth or '—'}/{f'{v.vaf:.0%}' if v.vaf is not None else '—'}"
+            table.add_row(v.gene, loc, v.consequence[:40], v.clinvar, dv)
+        con.print(table)
+        con.print()
+
+    _variant_table("Pathogenic / Likely Pathogenic", pathogenic, "bold red")
+    _variant_table("Variants of Uncertain Significance (VUS)", vus, "bold yellow")
+    _variant_table("Other Variants", other, "bold")
+
+    con.print(
+        Panel(
+            f"Total: {len(variants)} variants | "
+            f"Pathogenic: {len(pathogenic)} | VUS: {len(vus)} | Other: {len(other)}\n"
+            "Run [bold]ngsagent debate[/bold] on VUS entries (requires LLM).",
+            title="Summary",
+        )
+    )

ngs_agent/backends/__init__.py

@@ -0,0 +1,6 @@
+"""LLM backend registry."""
+
+from ngs_agent.backends.base import LLMBackend, NoBackend
+from ngs_agent.backends.factory import get_backend
+
+__all__ = ["LLMBackend", "NoBackend", "get_backend"]

ngs_agent/backends/anthropic.py

@@ -0,0 +1,30 @@
+"""Anthropic Claude backend."""
+
+from __future__ import annotations
+
+import os
+
+from ngs_agent.backends.base import LLMBackend
+
+
+class AnthropicBackend(LLMBackend):
+    def __init__(self, model: str = "claude-sonnet-4-20250514", api_key: str | None = None) -> None:
+        self.model = model
+        self.api_key = api_key or os.environ.get("ANTHROPIC_API_KEY", "")
+
+    def complete(self, prompt: str, system: str = "") -> str:
+        if not self.api_key:
+            raise RuntimeError("ANTHROPIC_API_KEY is not set.")
+
+        import anthropic
+
+        client = anthropic.Anthropic(api_key=self.api_key)
+        kwargs: dict = {
+            "model": self.model,
+            "max_tokens": 2048,
+            "messages": [{"role": "user", "content": prompt}],
+        }
+        if system:
+            kwargs["system"] = system
+        message = client.messages.create(**kwargs)
+        return message.content[0].text

ngs_agent/backends/base.py

@@ -0,0 +1,24 @@
+"""Abstract LLM backend interface."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+
+class LLMBackend(ABC):
+    """Base class for LLM providers."""
+
+    @abstractmethod
+    def complete(self, prompt: str, system: str = "") -> str:
+        """Return model text for a prompt."""
+
+
+class NoBackend(LLMBackend):
+    """Placeholder when no LLM is configured."""
+
+    def complete(self, prompt: str, system: str = "") -> str:
+        raise RuntimeError(
+            "No LLM backend configured. Run `ngsagent config wizard` or set llm in "
+            "~/.ngsagent/config.yaml. Only `debate` requires an LLM; `watch` and "
+            "`analyze` work without one."
+        )

ngs_agent/backends/factory.py

@@ -0,0 +1,80 @@
+"""Backend factory supporting multi-provider LLMs."""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from ngs_agent.backends.anthropic import AnthropicBackend
+from ngs_agent.backends.base import LLMBackend, NoBackend
+from ngs_agent.backends.gemini import GeminiBackend
+from ngs_agent.backends.ollama import OllamaBackend
+from ngs_agent.backends.openai_compat import OpenAICompatBackend, PROVIDER_PRESETS
+
+
+def get_backend(cfg: dict[str, Any]) -> LLMBackend:
+    llm = cfg.get("llm", "none").lower()
+
+    if not llm or llm == "none":
+        # Auto-detect from environment variables if not set in config
+        if os.environ.get("GEMINI_API_KEY"):
+            return GeminiBackend(model=cfg.get("gemini_model", "gemini-2.0-flash"))
+        if os.environ.get("ANTHROPIC_API_KEY"):
+            return AnthropicBackend(model=cfg.get("anthropic_model", "claude-3-7-sonnet-20250219"))
+        if os.environ.get("OPENAI_API_KEY"):
+            return OpenAICompatBackend(
+                base_url="https://api.openai.com/v1",
+                api_key=os.environ.get("OPENAI_API_KEY", ""),
+                model=cfg.get("openai_model", "gpt-4o"),
+            )
+        return NoBackend()
+
+    if llm == "gemini":
+        return GeminiBackend(
+            model=cfg.get("gemini_model", "gemini-2.0-flash"),
+            api_key=cfg.get("gemini_api_key"),
+        )
+
+    if llm == "anthropic":
+        return AnthropicBackend(
+            model=cfg.get("anthropic_model", "claude-3-7-sonnet-20250219"),
+            api_key=cfg.get("anthropic_api_key"),
+        )
+
+    if llm == "ollama":
+        return OllamaBackend(
+            model=cfg.get("ollama_model", "llama3.2"),
+            host=cfg.get("ollama_host", "http://localhost:11434"),
+        )
+
+    if llm == "openai":
+        return OpenAICompatBackend(
+            base_url="https://api.openai.com/v1",
+            api_key=cfg.get("openai_api_key") or os.environ.get("OPENAI_API_KEY", ""),
+            model=cfg.get("openai_model", "gpt-4o"),
+        )
+
+    if llm == "openai_compat":
+        return OpenAICompatBackend(
+            base_url=cfg.get("openai_compat_base_url", "https://openrouter.ai/api/v1"),
+            api_key=cfg.get("openai_compat_api_key"),
+            model=cfg.get("openai_compat_model", "openrouter/auto"),
+        )
+
+    if llm in PROVIDER_PRESETS:
+        base_url, default_model = PROVIDER_PRESETS[llm]
+        env_key = f"{llm.upper()}_API_KEY"
+        api_key = cfg.get(f"{llm}_api_key") or os.environ.get(env_key, "")
+        model = cfg.get(f"{llm}_model", default_model)
+        extra: dict[str, str] = {}
+        if llm == "openrouter":
+            extra["HTTP-Referer"] = "https://github.com/ranaalyan1/NGS-Agent"
+            extra["X-Title"] = "NGS-Agent"
+        return OpenAICompatBackend(
+            base_url=base_url,
+            api_key=api_key,
+            model=model,
+            extra_headers=extra,
+        )
+
+    return NoBackend()

ngs_agent/backends/gemini.py

@@ -0,0 +1,61 @@
+"""Google Gemini native LLM backend."""
+
+from __future__ import annotations
+
+import os
+from typing import Optional
+
+import httpx
+
+from ngs_agent.backends.base import LLMBackend
+
+
+class GeminiBackend(LLMBackend):
+    """Direct Google Gemini REST backend using Google AI Studio / Gemini API."""
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        model: str = "gemini-2.0-flash",
+    ) -> None:
+        self.api_key = api_key or os.environ.get("GEMINI_API_KEY", "")
+        self.model = model
+
+    def complete(self, prompt: str, system: Optional[str] = None) -> str:
+        if not self.api_key:
+            raise RuntimeError(
+                "Gemini API key not found. Set GEMINI_API_KEY environment variable or run `ngsagent config wizard`."
+            )
+
+        url = f"https://generativelanguage.googleapis.com/v1beta/models/{self.model}:generateContent?key={self.api_key}"
+
+        contents = []
+        if system:
+            contents.append({"role": "user", "parts": [{"text": f"System Instructions: {system}"}]})
+            contents.append({"role": "model", "parts": [{"text": "Understood. I will follow these instructions."}]})
+
+        contents.append({"role": "user", "parts": [{"text": prompt}]})
+
+        payload = {
+            "contents": contents,
+            "generationConfig": {
+                "temperature": 0.2,
+                "maxOutputTokens": 1024,
+            },
+        }
+
+        try:
+            with httpx.Client(timeout=30.0) as client:
+                response = client.post(url, json=payload)
+                response.raise_for_status()
+                data = response.json()
+                candidates = data.get("candidates", [])
+                if candidates:
+                    parts = candidates[0].get("content", {}).get("parts", [])
+                    if parts:
+                        return parts[0].get("text", "").strip()
+                return "[No response text generated by Gemini]"
+        except httpx.HTTPStatusError as exc:
+            raise RuntimeError(f"Gemini API error ({exc.response.status_code}): {exc.response.text}") from exc
+        except Exception as exc:
+            raise RuntimeError(f"Failed to communicate with Gemini API: {exc}") from exc