celltype-cli 0.1.0__py3-none-any.whl

ct/tools/translational.py

@@ -0,0 +1,123 @@
+"""
+Translational strategy tools bridging biomarkers to development readiness.
+"""
+
+from __future__ import annotations
+
+from ct.tools import registry
+
+
+def _safe_int(value, default: int = 0) -> int:
+    try:
+        return int(value)
+    except Exception:
+        return default
+
+
+@registry.register(
+    name="translational.biomarker_readiness",
+    description="Assess translational readiness of a biomarker in a disease setting",
+    category="translational",
+    parameters={
+        "biomarker": "Biomarker gene/protein or signature label (e.g., PD-L1, IL23R, KRAS G12C)",
+        "indication": "Disease/indication context",
+        "max_evidence": "Maximum literature/trial records to include per source (default 10)",
+    },
+    usage_guide=(
+        "Use before clinical design to evaluate whether a biomarker is deployable for patient selection: "
+        "evidence depth, trial usage, and practical stratification signal."
+    ),
+)
+def biomarker_readiness(
+    biomarker: str,
+    indication: str,
+    max_evidence: int = 10,
+    **kwargs,
+) -> dict:
+    """Estimate biomarker readiness from trial and literature evidence."""
+    del kwargs
+    biomarker = (biomarker or "").strip()
+    indication = (indication or "").strip()
+    if not biomarker:
+        return {"summary": "biomarker is required.", "error": "missing_biomarker"}
+    if not indication:
+        return {"summary": "indication is required.", "error": "missing_indication"}
+
+    from ct.tools.clinical import trial_search
+    from ct.tools.literature import openalex_search, pubmed_search
+
+    max_evidence = max(1, min(int(max_evidence or 10), 25))
+    query = f"{biomarker} {indication}".strip()
+
+    trial_result = trial_search(query=query)
+    pubmed_result = pubmed_search(query=f"{query} predictive biomarker", max_results=max_evidence)
+    openalex_result = openalex_search(query=f"{query} biomarker stratification", max_results=max_evidence)
+
+    if "error" in trial_result and "error" in pubmed_result and "error" in openalex_result:
+        return {
+            "summary": f"Biomarker readiness failed for '{query}': data sources unavailable.",
+            "error": "all_sources_failed",
+            "sources": {
+                "trial_error": trial_result.get("error"),
+                "pubmed_error": pubmed_result.get("error"),
+                "openalex_error": openalex_result.get("error"),
+            },
+        }
+
+    trial_total = _safe_int(trial_result.get("total_count", 0))
+    status_dist = trial_result.get("status_distribution", {}) or {}
+    recruiting = _safe_int(status_dist.get("RECRUITING", 0))
+
+    pubmed_total = _safe_int(pubmed_result.get("total_count", 0))
+    openalex_total = _safe_int(openalex_result.get("total_count", 0))
+
+    score = 0
+    score += min(35, trial_total)
+    score += min(20, recruiting * 3)
+    score += min(30, (pubmed_total // 5) * 5)
+    score += min(15, (openalex_total // 10) * 5)
+    score = min(100, score)
+
+    if score >= 70:
+        readiness = "high"
+    elif score >= 40:
+        readiness = "moderate"
+    else:
+        readiness = "early"
+
+    risks = []
+    if trial_total == 0:
+        risks.append("No direct trial usage signal in the current query window.")
+    if recruiting == 0 and trial_total > 0:
+        risks.append("No recruiting trials currently detected; may indicate development pause.")
+    if pubmed_total < 5:
+        risks.append("Limited predictive biomarker publication depth.")
+
+    summary = (
+        f"Biomarker readiness for {biomarker} in {indication}: {readiness} ({score}/100). "
+        f"Trials={trial_total}, recruiting={recruiting}, literature={pubmed_total + openalex_total}."
+    )
+
+    return {
+        "summary": summary,
+        "biomarker": biomarker,
+        "indication": indication,
+        "readiness_level": readiness,
+        "readiness_score": score,
+        "risks": risks,
+        "trials": {
+            "total_count": trial_total,
+            "status_distribution": status_dist,
+            "phase_distribution": trial_result.get("phase_distribution", {}),
+            "records": (trial_result.get("trials") or [])[:max_evidence],
+            "error": trial_result.get("error"),
+        },
+        "literature": {
+            "pubmed_total": pubmed_total,
+            "openalex_total": openalex_total,
+            "pubmed_records": (pubmed_result.get("articles") or [])[:max_evidence],
+            "openalex_records": (openalex_result.get("articles") or [])[:max_evidence],
+            "pubmed_error": pubmed_result.get("error"),
+            "openalex_error": openalex_result.get("error"),
+        },
+    }

ct/tools/viability.py

@@ -0,0 +1,218 @@
+"""
+Viability tools: PRISM dose-response, IC50, tissue selectivity, therapeutic windows.
+"""
+
+import pandas as pd
+import numpy as np
+from ct.tools import registry
+
+
+@registry.register(
+    name="viability.dose_response",
+    description="Analyze dose-response curves for a compound across PRISM cell lines",
+    category="viability",
+    parameters={"compound_id": "Compound YU ID", "lfc_threshold": "LFC threshold for sensitivity (default: -0.5)"},
+    requires_data=["prism"],
+    usage_guide="You want to understand a compound's potency across cell lines — IC50 estimates, sensitivity vs resistance distribution. Use early in hit characterization.",
+)
+def dose_response(compound_id: str, lfc_threshold: float = -0.5, **kwargs) -> dict:
+    """Analyze PRISM dose-response for a compound."""
+    from ct.data.loaders import load_prism
+    from ct.tools._compound_resolver import resolve_compound
+
+    original_name = compound_id
+    compound_id = resolve_compound(compound_id, dataset="prism")
+    proxy_warning = ""
+    if original_name != compound_id:
+        proxy_warning = (
+            f" Note: '{original_name}' resolved to proxy compound "
+            f"{compound_id}. Results are for the proxy, not {original_name}."
+        )
+
+    prism = load_prism()
+    cpd_data = prism[prism["pert_name"] == compound_id]
+
+    if len(cpd_data) == 0:
+        return {"error": f"Compound {compound_id} not found in PRISM data", "summary": f"Compound {compound_id} not found in PRISM data"}
+    doses = sorted(cpd_data["pert_dose"].unique())
+    n_cells = cpd_data["ccle_name"].nunique()
+
+    # Per-dose statistics
+    dose_stats = []
+    for dose in doses:
+        dose_data = cpd_data[cpd_data["pert_dose"] == dose]["LFC"]
+        dose_stats.append({
+            "dose_um": dose,
+            "mean_lfc": round(float(dose_data.mean()), 3),
+            "median_lfc": round(float(dose_data.median()), 3),
+            "pct_killing": round(float((dose_data < lfc_threshold).mean() * 100), 1),
+            "n_cells": len(dose_data),
+        })
+
+    # Classify cell lines
+    high_dose = cpd_data[cpd_data["pert_dose"] == max(doses)]
+    per_cell = high_dose.groupby("ccle_name")["LFC"].mean()
+    n_sensitive = (per_cell < lfc_threshold).sum()
+    n_resistant = (per_cell > -0.1).sum()
+
+    # Estimate IC50 from 3-point dose-response
+    mean_lfcs = [s["mean_lfc"] for s in dose_stats]
+    if len(doses) >= 3 and mean_lfcs[-1] < lfc_threshold:
+        # Linear interpolation to find dose at LFC = threshold
+        for i in range(len(doses) - 1):
+            if mean_lfcs[i] > lfc_threshold >= mean_lfcs[i + 1]:
+                denom = mean_lfcs[i + 1] - mean_lfcs[i]
+                if abs(denom) < 1e-12:
+                    ic50 = (doses[i] + doses[i + 1]) / 2  # midpoint if flat
+                else:
+                    frac = (lfc_threshold - mean_lfcs[i]) / denom
+                    ic50 = doses[i] + frac * (doses[i + 1] - doses[i])
+                break
+        else:
+            ic50 = None
+    else:
+        ic50 = None
+
+    result = {
+        "summary": (
+            f"Dose-response for {compound_id}: {n_cells} cell lines, {len(doses)} doses\n"
+            f"Sensitive (LFC<{lfc_threshold} at {max(doses)}uM): {n_sensitive}/{len(per_cell)} "
+            f"({n_sensitive/len(per_cell)*100:.0f}%)\n"
+            f"Estimated IC50: {f'{ic50:.2f} uM' if ic50 else 'N/A'}"
+            + proxy_warning
+        ),
+        "compound": compound_id,
+        "dose_stats": dose_stats,
+        "n_cell_lines": n_cells,
+        "n_sensitive": int(n_sensitive),
+        "n_resistant": int(n_resistant),
+        "ic50_um": round(ic50, 3) if ic50 else None,
+    }
+    if original_name != compound_id:
+        result["original_query"] = original_name
+        result["is_proxy"] = True
+    return result
+
+
+@registry.register(
+    name="viability.tissue_selectivity",
+    description="Identify which tissue/cancer types are most sensitive to a compound",
+    category="viability",
+    parameters={"compound_id": "Compound YU ID", "dose": "Dose in uM (default: highest)", "lfc_threshold": "LFC threshold for sensitivity (default: -0.5)"},
+    requires_data=["prism", "depmap_model"],
+    usage_guide="You want to know which cancer types respond best to a compound. Use for indication selection and to assess whether killing is selective or broadly toxic.",
+)
+def tissue_selectivity(compound_id: str, dose: float = None, lfc_threshold: float = -0.5, **kwargs) -> dict:
+    """Profile tissue-level sensitivity for a compound."""
+    from ct.data.loaders import load_prism, load_model_metadata
+    from ct.tools._compound_resolver import resolve_compound
+
+    original_name = compound_id
+    compound_id = resolve_compound(compound_id, dataset="prism")
+    proxy_warning = ""
+    if original_name != compound_id:
+        proxy_warning = (
+            f" Note: '{original_name}' resolved to proxy compound "
+            f"{compound_id}. Results are for the proxy, not {original_name}."
+        )
+
+    prism = load_prism()
+    model = load_model_metadata()
+
+    cpd_data = prism[prism["pert_name"] == compound_id]
+    if len(cpd_data) == 0:
+        return {"error": f"Compound {compound_id} not found in PRISM data", "summary": f"Compound {compound_id} not found in PRISM data"}
+    if dose is None:
+        dose = cpd_data["pert_dose"].max()
+    cpd_dose = cpd_data[cpd_data["pert_dose"] == dose]
+
+    # Map cell lines to lineages
+    ccle_to_lineage = {}
+    for _, row in model.iterrows():
+        ccle = row.get("CCLEName", "")
+        lineage = row.get("OncotreeLineage", "Unknown")
+        if pd.notna(ccle) and pd.notna(lineage):
+            ccle_to_lineage[ccle] = lineage
+
+    cpd_dose = cpd_dose.copy()
+    cpd_dose["lineage"] = cpd_dose["ccle_name"].map(ccle_to_lineage)
+
+    # Per-lineage statistics
+    tissue_stats = []
+    for lineage, group in cpd_dose.groupby("lineage"):
+        if lineage == "Unknown" or len(group) < 3:
+            continue
+        tissue_stats.append({
+            "lineage": lineage,
+            "mean_lfc": round(float(group["LFC"].mean()), 3),
+            "median_lfc": round(float(group["LFC"].median()), 3),
+            "pct_sensitive": round(float((group["LFC"] < lfc_threshold).mean() * 100), 1),
+            "n_cells": len(group),
+        })
+
+    if not tissue_stats:
+        return {
+            "summary": f"No tissue selectivity data for {compound_id} at {dose}uM (no lineages with >=3 cell lines)",
+            "compound": compound_id,
+            "dose_um": dose,
+            "tissue_profiles": [],
+        }
+
+    tissue_df = pd.DataFrame(tissue_stats).sort_values("mean_lfc")
+
+    sensitive = tissue_df[tissue_df["pct_sensitive"] > 50]
+    resistant = tissue_df[tissue_df["pct_sensitive"] < 20]
+
+    result = {
+        "summary": (
+            f"Tissue selectivity for {compound_id} at {dose}uM:\n"
+            f"Most sensitive: {', '.join(sensitive['lineage'].head(3).tolist()) if len(sensitive) > 0 else 'none'}\n"
+            f"Most resistant: {', '.join(resistant['lineage'].tail(3).tolist()) if len(resistant) > 0 else 'none'}"
+            + proxy_warning
+        ),
+        "compound": compound_id,
+        "dose_um": dose,
+        "tissue_profiles": tissue_df.to_dict("records"),
+    }
+    if original_name != compound_id:
+        result["original_query"] = original_name
+        result["is_proxy"] = True
+    return result
+
+
+@registry.register(
+    name="viability.compare_compounds",
+    description="Compare potency and selectivity profiles of multiple compounds",
+    category="viability",
+    parameters={"compound_ids": "List of compound IDs to compare"},
+    requires_data=["prism"],
+    usage_guide="You have multiple compounds and want to rank them by potency and selectivity. Use for lead selection when choosing between compound candidates.",
+)
+def compare_compounds(compound_ids: list, **kwargs) -> dict:
+    """Compare multiple compounds on potency and selectivity metrics."""
+    results = []
+    for cpd_id in compound_ids:
+        dr = dose_response(cpd_id)
+        if "error" in dr:
+            continue
+        results.append({
+            "compound": cpd_id,
+            "ic50_um": dr.get("ic50_um"),
+            "n_sensitive": dr.get("n_sensitive"),
+            "n_resistant": dr.get("n_resistant"),
+            "n_cell_lines": dr.get("n_cell_lines"),
+            "sensitivity_rate": round(dr["n_sensitive"] / dr["n_cell_lines"] * 100, 1) if dr["n_cell_lines"] else 0,
+        })
+
+    if not results:
+        return {
+            "summary": f"No compounds found in PRISM data from: {', '.join(compound_ids)}",
+            "comparison": [],
+        }
+
+    df = pd.DataFrame(results).sort_values("ic50_um", na_position="last")
+
+    return {
+        "summary": f"Compared {len(results)} compounds. Most potent: {df.iloc[0]['compound'] if len(df) > 0 else 'N/A'}",
+        "comparison": df.to_dict("records"),
+    }

ct/ui/markdown.py

@@ -0,0 +1,31 @@
+"""
+Custom Markdown rendering for ct — left-aligned headings.
+
+Rich's default Markdown renderer centers headings. This module provides
+a LeftMarkdown class that renders headings left-aligned instead.
+"""
+
+from rich import box
+from rich.markdown import Heading, Markdown
+from rich.panel import Panel
+from rich.text import Text
+
+
+class _LeftHeading(Heading):
+    """Heading with left alignment instead of Rich's default centered."""
+
+    def __rich_console__(self, console, options):
+        text = self.text
+        text.justify = "left"
+        if self.tag == "h1":
+            yield Panel(text, box=box.HEAVY, style="markdown.h1.border")
+        else:
+            yield Text("")
+            yield text
+            yield Text("")
+
+
+class LeftMarkdown(Markdown):
+    """Markdown renderer with left-aligned headings."""
+
+    elements = {**Markdown.elements, "heading_open": _LeftHeading}

ct/ui/status.py

@@ -0,0 +1,258 @@
+"""
+Thinking status display for ct.
+
+Shows a DNA double-helix animation with rotating drug discovery themed words
+and an elapsed time counter. The helix scrolls at 8fps while words rotate
+every ~3 seconds.
+
+Usage:
+    with ThinkingStatus(console, "planning"):
+        result = llm.chat(...)
+"""
+
+import random
+import time
+from typing import List
+
+from rich.live import Live
+from rich.markdown import Markdown
+from rich.text import Text
+
+# ---------------------------------------------------------------------------
+# Spinner animations
+# ---------------------------------------------------------------------------
+
+_BASE = "\u2881\u2822\u2814\u2848\u2814\u2822"  # ⢁⠢⠔⡈⠔⠢
+DNA_HELIX_FRAMES: List[str] = [_BASE[i:] + _BASE[:i] for i in range(len(_BASE))]
+
+SPINNERS = {
+    "benzene_breathing": {
+        "frames": ['⬡', '⎔', '⌬', '⬢', '⌬', '⎔'],
+        "interval_ms": 125,
+    },
+    "dna_helix": {
+        "frames": DNA_HELIX_FRAMES,
+        "interval_ms": 125,
+    },
+}
+
+import math
+
+def apply_gradient(text: str, elapsed_s: float = 0.0) -> Text:
+    """Apply a #50fa7b (neon green) to #00e5ff (cyan) temporal gradient."""
+    if not text:
+        return Text("")
+    
+    # #50fa7b (80, 250, 123) to #00e5ff (0, 229, 255)
+    r1, g1, b1 = 80, 250, 123
+    r2, g2, b2 = 0, 229, 255
+    
+    # Cycle over 3 spinner loops (6 frames × 125ms × 3 = 2.25s)
+    cycle_duration_s = 2.25
+    t = (math.sin((elapsed_s % cycle_duration_s) * (2 * math.pi / cycle_duration_s)) + 1) / 2
+    r = int(r1 + (r2 - r1) * t)
+    g = int(g1 + (g2 - g1) * t)
+    b = int(b1 + (b2 - b1) * t)
+    hex_color = f"#{r:02x}{g:02x}{b:02x}"
+    
+    result = Text()
+    result.append(text, style=hex_color)
+    return result
+
+THINKING_WORDS = {
+    "planning": [
+        "Hypothesizing", "Mapping pathways", "Reviewing literature",
+        "Selecting tools", "Designing strategy", "Evaluating evidence",
+        "Prioritizing targets", "Cross-referencing data", "Consulting databases",
+        "Analyzing feasibility", "Scanning publications", "Charting biology",
+        "Surveying chemical space", "Assessing druggability", "Interrogating targets",
+        "Probing mechanisms", "Mining databases", "Scouting leads",
+        "Triaging candidates", "Devising experiments", "Calibrating approach",
+        "Querying knowledge base", "Formulating hypothesis", "Mapping the landscape",
+        "Checking prior art", "Weighing approaches", "Modeling the problem",
+    ],
+    "synthesizing": [
+        "Synthesizing findings", "Connecting pathways", "Weighing evidence",
+        "Integrating data", "Analyzing patterns", "Formulating insights",
+        "Evaluating significance", "Drafting conclusions", "Assessing confidence",
+        "Distilling results", "Building narrative", "Ranking findings",
+        "Reconciling data", "Crystallizing insights", "Spotting trends",
+        "Interpreting signals", "Assembling the picture", "Triangulating evidence",
+        "Parsing results", "Connecting the dots", "Extracting key findings",
+        "Gauging clinical relevance", "Framing the story", "Identifying next steps",
+    ],
+    "evaluating": [
+        "Evaluating results", "Checking completeness", "Assessing quality",
+        "Reviewing coverage", "Validating findings", "Gauging sufficiency",
+        "Scoring confidence", "Auditing data gaps", "Stress-testing conclusions",
+        "Verifying consistency", "Checking for blind spots", "Weighing completeness",
+    ],
+    "reasoning": [
+        "Reasoning through mechanisms", "Connecting biology to chemistry",
+        "Evaluating hypotheses", "Considering alternatives", "Weighing trade-offs",
+        "Modeling interactions", "Analyzing structure-activity", "Exploring mechanisms",
+        "Deconvolving signals", "Tracing pathways", "Dissecting mechanisms",
+        "Thinking through pharmacology", "Pondering selectivity",
+        "Probing binding kinetics", "Assessing off-target risk",
+    ],
+    "comparing": [
+        "Comparing options", "Benchmarking candidates", "Ranking alternatives",
+        "Evaluating trade-offs", "Scoring criteria", "Weighing pros and cons",
+        "Aligning properties", "Contrasting profiles", "Assessing differentiators",
+    ],
+    "summarizing": [
+        "Distilling key findings", "Extracting insights", "Condensing results",
+        "Identifying highlights", "Prioritizing conclusions", "Crystallizing takeaways",
+        "Compiling brief", "Summarizing evidence", "Framing recommendations",
+    ],
+    "coding": [
+        "Writing code", "Editing files", "Reading codebase", "Running tests",
+        "Debugging", "Refactoring", "Searching files", "Analyzing code",
+        "Applying changes", "Iterating on fixes",
+    ],
+}
+
+
+class _ThinkingRenderable:
+    """Self-updating renderable: Animated spinner + rotating bio-themed word + elapsed time.
+
+    Computes display state from wall-clock time on each refresh, so no
+    separate update thread is needed — Rich's Live refresh handles it.
+    """
+
+    def __init__(self, words, spinner_style="benzene_breathing"):
+        self.words = words
+        self.start_time = time.time()
+        
+        # Load spinner configuration
+        spinner_conf = SPINNERS.get(spinner_style, SPINNERS["benzene_breathing"])
+        self.frames = spinner_conf["frames"]
+        self.interval_ms = spinner_conf["interval_ms"]
+
+    def __rich_console__(self, console, options):
+        elapsed = time.time() - self.start_time
+        
+        # Determine current word (rotates every 3 seconds)
+        word_idx = int(elapsed / 3) % len(self.words)
+        word = self.words[word_idx]
+
+        # Determine current spinner frame
+        frame_idx = int(elapsed * (1000 / self.interval_ms)) % len(self.frames)
+        frame_str = self.frames[frame_idx]
+
+        if elapsed < 60:
+            time_str = f"{elapsed:.0f}s"
+        else:
+            mins = int(elapsed // 60)
+            secs = int(elapsed % 60)
+            time_str = f"{mins}m {secs}s"
+
+        # Apply gradient to spinner frame
+        output = apply_gradient(frame_str, elapsed_s=elapsed)
+        output.append("  ")
+        output.append(f"{word}…", style="cyan")
+        output.append("  ")
+        output.append(f"({time_str})", style="dim")
+
+        yield output
+
+
+class ThinkingStatus:
+    """Context manager showing a Claude Code-style thinking status.
+
+    Displays a spinner with rotating drug-discovery themed words and an
+    elapsed time counter. The status disappears when the context exits.
+
+    The Rich Live daemon thread may stall when the GIL is held by
+    CPU-bound tool code running via ``asyncio.to_thread()``.  To keep
+    the timer ticking, call :meth:`kick` from the async message loop
+    or start :meth:`async_refresh_task` as a background asyncio task.
+
+    Args:
+        console: Rich Console instance.
+        phase: One of the keys in THINKING_WORDS (planning, synthesizing, etc.).
+    """
+
+    def __init__(self, console, phase="planning"):
+        from ct.agent.config import Config
+        self.console = console
+        words = list(THINKING_WORDS.get(phase, THINKING_WORDS["planning"]))
+        random.shuffle(words)
+
+        # Determine spinner style from config
+        try:
+            cfg = Config.load()
+            spinner_style = cfg.get("ui.spinner", "benzene_breathing")
+        except Exception:
+            spinner_style = "benzene_breathing"
+
+        self._renderable = _ThinkingRenderable(words, spinner_style=spinner_style)
+        self._live = None
+        self._async_task = None
+
+    def __enter__(self):
+        self._live = Live(
+            self._renderable,
+            console=self.console,
+            refresh_per_second=8,
+            transient=True,
+        )
+        self._live.__enter__()
+        return self
+
+    def __exit__(self, *args):
+        self._cancel_async_task()
+        if self._live is not None:
+            return self._live.__exit__(*args)
+
+    def kick(self):
+        """Force a single refresh of the Live display.
+
+        Call from the async message loop to keep the timer updating
+        even when the daemon thread is GIL-starved.
+        """
+        if self._live is not None:
+            try:
+                self._live.refresh()
+            except Exception:
+                pass
+
+    def start_async_refresh(self):
+        """Start a background asyncio task that refreshes the display.
+
+        This supplements the Rich Live daemon thread: while a tool runs
+        in ``asyncio.to_thread()``, the event loop still gets cycles
+        during I/O waits and can drive this coroutine to keep the timer
+        updating.  Call :meth:`stop` or :meth:`_cancel_async_task` to
+        stop.
+        """
+        import asyncio
+
+        async def _refresh_loop():
+            try:
+                while True:
+                    await asyncio.sleep(0.125)
+                    self.kick()
+            except asyncio.CancelledError:
+                pass
+
+        try:
+            loop = asyncio.get_running_loop()
+            self._async_task = loop.create_task(_refresh_loop())
+        except RuntimeError:
+            pass  # No running event loop — daemon thread is the fallback
+
+    def _cancel_async_task(self):
+        if self._async_task is not None:
+            self._async_task.cancel()
+            self._async_task = None
+
+    def stop(self):
+        """Programmatically stop the animation (idempotent)."""
+        self._cancel_async_task()
+        if self._live is not None:
+            try:
+                self._live.__exit__(None, None, None)
+            except Exception:
+                pass
+            self._live = None