celltype-cli 0.1.0__py3-none-any.whl

ct/tools/http_client.py

@@ -0,0 +1,146 @@
+"""
+Shared HTTP helpers for ct tools.
+
+Provides retry/backoff, normalized errors, and JSON parsing wrappers for
+API-heavy tool modules.
+"""
+
+import time
+
+
+_RETRYABLE_STATUS = {429, 500, 502, 503, 504}
+
+
+def _call_httpx(method: str, url: str, **kwargs):
+    import httpx
+
+    method = method.upper()
+    # Avoid passing unsupported kwargs (e.g., json/data to httpx.get).
+    cleaned_kwargs = {k: v for k, v in kwargs.items() if v is not None}
+    if method == "GET":
+        cleaned_kwargs.pop("json", None)
+        cleaned_kwargs.pop("data", None)
+        return httpx.get(url, **cleaned_kwargs)
+    if method == "POST":
+        return httpx.post(url, **cleaned_kwargs)
+    return httpx.request(method, url, **cleaned_kwargs)
+
+
+def _format_http_error(response) -> str:
+    status = getattr(response, "status_code", "unknown")
+    body = (getattr(response, "text", "") or "").strip().replace("\n", " ")
+    body = body[:300]
+    return f"HTTP {status}" + (f": {body}" if body else "")
+
+
+def request(
+    method: str,
+    url: str,
+    *,
+    params: dict | None = None,
+    json: dict | None = None,
+    data: dict | None = None,
+    headers: dict | None = None,
+    timeout: int = 30,
+    retries: int = 2,
+    backoff_seconds: float = 0.5,
+    raise_for_status: bool = True,
+) -> tuple[object | None, str | None]:
+    """Perform HTTP request with retry/backoff.
+
+    Returns `(response, error)`. Exactly one is non-None.
+    """
+    try:
+        import httpx
+    except ImportError:
+        return None, "httpx required (pip install httpx)"
+
+    delay = max(backoff_seconds, 0.0)
+    last_error = None
+
+    for attempt in range(max(retries, 0) + 1):
+        try:
+            resp = _call_httpx(
+                method,
+                url,
+                params=params,
+                json=json,
+                data=data,
+                headers=headers,
+                timeout=timeout,
+            )
+        except (httpx.TimeoutException, httpx.RequestError) as exc:
+            last_error = str(exc)
+            if attempt < retries:
+                time.sleep(delay)
+                delay *= 2
+                continue
+            return None, last_error
+        except Exception as exc:
+            return None, str(exc)
+
+        status = int(getattr(resp, "status_code", 0) or 0)
+        if status in _RETRYABLE_STATUS and attempt < retries:
+            time.sleep(delay)
+            delay *= 2
+            continue
+
+        if raise_for_status:
+            try:
+                resp.raise_for_status()
+            except httpx.HTTPStatusError:
+                return None, _format_http_error(resp)
+            except Exception as exc:
+                return None, str(exc)
+
+        return resp, None
+
+    return None, last_error or "Request failed"
+
+
+def request_json(
+    method: str,
+    url: str,
+    *,
+    params: dict | None = None,
+    json: dict | None = None,
+    data: dict | None = None,
+    headers: dict | None = None,
+    timeout: int = 30,
+    retries: int = 2,
+    backoff_seconds: float = 0.5,
+    raise_for_status: bool = True,
+) -> tuple[dict | list | None, str | None]:
+    """Perform HTTP request and parse JSON body."""
+    resp, error = request(
+        method,
+        url,
+        params=params,
+        json=json,
+        data=data,
+        headers=headers,
+        timeout=timeout,
+        retries=retries,
+        backoff_seconds=backoff_seconds,
+        raise_for_status=raise_for_status,
+    )
+    if error:
+        return None, error
+
+    # Validate Content-Type before parsing — some APIs return HTML on 200
+    content_type = ""
+    try:
+        ct_raw = resp.headers.get("content-type", "")
+        if isinstance(ct_raw, str):
+            content_type = ct_raw.lower()
+    except Exception:
+        pass
+    if content_type and "json" not in content_type and "javascript" not in content_type:
+        status = getattr(resp, "status_code", "unknown")
+        return None, f"Expected JSON but got {content_type} (HTTP {status})"
+
+    try:
+        return resp.json(), None
+    except Exception:
+        status = getattr(resp, "status_code", "unknown")
+        return None, f"Invalid JSON response (HTTP {status})"

ct/tools/imaging.py

@@ -0,0 +1,319 @@
+"""
+Imaging tools: compound bioactivity profiling via PubChem and structural similarity.
+
+Uses PubChem bioactivity data and RDKit molecular descriptors for mechanism
+classification. Structural fingerprint similarity as a proxy for phenotypic similarity.
+"""
+
+from ct.tools import registry
+from ct.tools.http_client import request
+
+
+@registry.register(
+    name="imaging.cellpainting_lookup",
+    description="Look up compound bioactivity and compute mechanism class via PubChem assays and RDKit descriptors",
+    category="imaging",
+    parameters={
+        "compound": "Compound name, InChIKey, or SMILES string",
+        "source": "Data source: 'pubchem' (default). JUMP Cell Painting data requires local parquet files (not yet integrated).",
+    },
+    usage_guide="You want to understand a compound's bioactivity profile and infer its mechanism class. Queries PubChem bioassay data and computes RDKit molecular descriptors for heuristic mechanism classification. Note: full Cell Painting morphological profiles from JUMP require downloading parquet files from the JUMP Cell Painting Gallery (S3-hosted, no REST API).",
+)
+def cellpainting_lookup(compound: str, source: str = "pubchem", **kwargs) -> dict:
+    """Look up compound bioactivity and mechanism class.
+
+    Queries PubChem for bioassay data and computes RDKit molecular descriptors
+    for heuristic mechanism classification. Full JUMP Cell Painting morphological
+    profiles are not yet integrated (data is S3-hosted parquet, no REST API).
+    """
+    compound_info = {"query": compound, "source": source}
+
+    # Step 1: Try to resolve compound via PubChem for identifiers
+    cid = None
+    canonical_smiles = None
+    inchikey = None
+    compound_name = compound
+
+    # Check if input looks like SMILES (contains special chars)
+    is_smiles = any(c in compound for c in "()=#/\\@[]")
+    # Check if input looks like InChIKey (14-10-1 pattern)
+    is_inchikey = len(compound) == 27 and compound.count("-") == 2
+
+    if is_smiles:
+        resp, error = request(
+            "POST",
+            "https://pubchem.ncbi.nlm.nih.gov/rest/pug/compound/smiles/property/CID,CanonicalSMILES,InChIKey,IUPACName/JSON",
+            data={"smiles": compound},
+            timeout=10,
+            raise_for_status=False,
+        )
+    elif is_inchikey:
+        resp, error = request(
+            "GET",
+            f"https://pubchem.ncbi.nlm.nih.gov/rest/pug/compound/inchikey/{compound}/property/CID,CanonicalSMILES,InChIKey,IUPACName/JSON",
+            timeout=10,
+            raise_for_status=False,
+        )
+    else:
+        import urllib.parse
+        encoded = urllib.parse.quote(compound, safe="")
+        resp, error = request(
+            "GET",
+            f"https://pubchem.ncbi.nlm.nih.gov/rest/pug/compound/name/{encoded}/property/CID,CanonicalSMILES,InChIKey,IUPACName/JSON",
+            timeout=10,
+            raise_for_status=False,
+        )
+
+    if not error and resp.status_code == 200:
+        try:
+            props = resp.json().get("PropertyTable", {}).get("Properties", [])
+        except Exception:
+            props = []
+        if props:
+            cid = props[0].get("CID")
+            canonical_smiles = props[0].get("CanonicalSMILES")
+            inchikey = props[0].get("InChIKey")
+            compound_name = props[0].get("IUPACName", compound)
+
+    compound_info["cid"] = cid
+    compound_info["canonical_smiles"] = canonical_smiles
+    compound_info["inchikey"] = inchikey
+
+    # Step 2: Search PubChem for bioactivity data
+    mechanism_cluster = None
+    bioactivity_data = []
+    if cid:
+        bio_resp, bio_error = request(
+            "GET",
+            f"https://pubchem.ncbi.nlm.nih.gov/rest/pug/compound/cid/{cid}/assaysummary/JSON",
+            timeout=10,
+            raise_for_status=False,
+        )
+        if not bio_error and bio_resp.status_code == 200:
+            try:
+                assays = bio_resp.json().get("Table", {}).get("Row", [])
+            except Exception:
+                assays = []
+            # Filter for cell-based / imaging assays
+            for row in assays[:50]:
+                cells = row.get("Cell", [])
+                # Each row is a dict with Cell entries
+                if isinstance(cells, list) and len(cells) > 5:
+                    aid = cells[0].get("StringValue", "") if isinstance(cells[0], dict) else str(cells[0])
+                    activity = cells[3].get("StringValue", "") if len(cells) > 3 and isinstance(cells[3], dict) else ""
+                    bioactivity_data.append({
+                        "aid": aid,
+                        "activity_outcome": activity,
+                    })
+
+    # Step 3: Compute molecular descriptors using RDKit if SMILES available
+    rdkit_descriptors = None
+    if canonical_smiles or is_smiles:
+        try:
+            from rdkit import Chem
+            from rdkit.Chem import Descriptors, rdMolDescriptors
+
+            smi = canonical_smiles or compound
+            mol = Chem.MolFromSmiles(smi)
+            if mol is not None:
+                rdkit_descriptors = {
+                    "molecular_weight": round(Descriptors.MolWt(mol), 2),
+                    "logp": round(Descriptors.MolLogP(mol), 2),
+                    "tpsa": round(Descriptors.TPSA(mol), 2),
+                    "hba": Descriptors.NumHAcceptors(mol),
+                    "hbd": Descriptors.NumHDonors(mol),
+                    "rotatable_bonds": Descriptors.NumRotatableBonds(mol),
+                    "aromatic_rings": Descriptors.NumAromaticRings(mol),
+                    "fsp3": round(rdMolDescriptors.CalcFractionCSP3(mol), 3),
+                }
+
+                # Heuristic mechanism class based on molecular properties
+                mw = rdkit_descriptors["molecular_weight"]
+                logp = rdkit_descriptors["logp"]
+                if mw < 500 and rdkit_descriptors["aromatic_rings"] >= 2:
+                    mechanism_cluster = "kinase_inhibitor_like"
+                elif mw < 600 and logp < 2:
+                    mechanism_cluster = "protein_degrader_like"
+                elif mw > 800:
+                    mechanism_cluster = "macrocycle_like"
+                else:
+                    mechanism_cluster = "small_molecule"
+        except ImportError:
+            pass
+
+    # Build summary
+    has_data = bool(bioactivity_data or rdkit_descriptors)
+    if has_data:
+        cluster_str = f", mechanism cluster: '{mechanism_cluster}'" if mechanism_cluster else ""
+        n_assays = len(bioactivity_data)
+        assay_str = f", {n_assays} PubChem bioassay(s)" if n_assays > 0 else ""
+        summary = (
+            f"Compound profile for {compound}: "
+            f"CID={cid or 'N/A'}{cluster_str}{assay_str}"
+        )
+    else:
+        summary = (
+            f"Compound profile for {compound}: no bioactivity data found in PubChem. "
+            f"CID={cid or 'N/A'}"
+        )
+
+    result = {
+        "summary": summary,
+        "compound_info": compound_info,
+        "compound_name": compound_name,
+        "mechanism_cluster": mechanism_cluster,
+        "bioactivity_assays": bioactivity_data[:20],
+        "n_assays": len(bioactivity_data),
+    }
+
+    if rdkit_descriptors:
+        result["molecular_descriptors"] = rdkit_descriptors
+
+    return result
+
+
+@registry.register(
+    name="imaging.morphology_similarity",
+    description="Compare two compounds by structural fingerprint similarity (Morgan/MACCS Tanimoto) as a proxy for phenotypic similarity",
+    category="imaging",
+    parameters={
+        "smiles_a": "SMILES string for compound A",
+        "smiles_b": "SMILES string for compound B",
+    },
+    usage_guide="You want to compare two compounds by structural similarity as a proxy for phenotypic similarity. Uses Morgan fingerprints (radius=2, 2048 bits), MACCS keys, and physicochemical property comparison. Structural similarity correlates with morphological similarity for ~60% of compound pairs (Bray et al. 2017). For actual Cell Painting profile comparison, pre-computed profiles from JUMP would be needed.",
+)
+def morphology_similarity(smiles_a: str, smiles_b: str, **kwargs) -> dict:
+    """Compare two compounds by morphological similarity.
+
+    Uses RDKit Morgan fingerprints (radius=2, 2048 bits) as a structural proxy
+    for morphological similarity. Structural similarity correlates with morphological
+    similarity for ~60% of compound pairs (Bray et al., Nat Biotechnol 2017).
+    Also computes MACCS keys similarity and physicochemical property comparison.
+    """
+    try:
+        from rdkit import Chem, DataStructs
+        from rdkit.Chem import AllChem, Descriptors, rdMolDescriptors, MACCSkeys
+    except ImportError:
+        return {
+            "error": "RDKit is required for morphology similarity. Install with: pip install rdkit",
+            "summary": "RDKit not installed — needed for fingerprint-based similarity",
+        }
+
+    import numpy as np
+
+    mol_a = Chem.MolFromSmiles(smiles_a)
+    mol_b = Chem.MolFromSmiles(smiles_b)
+
+    if mol_a is None:
+        return {"error": f"Invalid SMILES for compound A: {smiles_a}", "summary": f"Could not parse SMILES: {smiles_a}"}
+    if mol_b is None:
+        return {"error": f"Invalid SMILES for compound B: {smiles_b}", "summary": f"Could not parse SMILES: {smiles_b}"}
+
+    # Morgan fingerprint similarity (main metric)
+    fp_a = AllChem.GetMorganFingerprintAsBitVect(mol_a, 2, nBits=2048)
+    fp_b = AllChem.GetMorganFingerprintAsBitVect(mol_b, 2, nBits=2048)
+    morgan_sim = DataStructs.TanimotoSimilarity(fp_a, fp_b)
+
+    # MACCS keys similarity (complementary metric)
+    maccs_a = MACCSkeys.GenMACCSKeys(mol_a)
+    maccs_b = MACCSkeys.GenMACCSKeys(mol_b)
+    maccs_sim = DataStructs.TanimotoSimilarity(maccs_a, maccs_b)
+
+    # Dice similarity (alternative metric)
+    dice_sim = DataStructs.DiceSimilarity(fp_a, fp_b)
+
+    # Physicochemical property comparison
+    def _get_props(mol):
+        return {
+            "mw": round(Descriptors.MolWt(mol), 2),
+            "logp": round(Descriptors.MolLogP(mol), 2),
+            "tpsa": round(Descriptors.TPSA(mol), 2),
+            "hba": Descriptors.NumHAcceptors(mol),
+            "hbd": Descriptors.NumHDonors(mol),
+            "rotatable_bonds": Descriptors.NumRotatableBonds(mol),
+            "aromatic_rings": Descriptors.NumAromaticRings(mol),
+            "fsp3": round(rdMolDescriptors.CalcFractionCSP3(mol), 3),
+        }
+
+    props_a = _get_props(mol_a)
+    props_b = _get_props(mol_b)
+
+    # Compute property similarity (normalized)
+    prop_diffs = {}
+    shared_features = []
+    for key in props_a:
+        diff = abs(props_a[key] - props_b[key])
+        prop_diffs[key] = round(diff, 3)
+
+        # Flag shared features
+        if key == "mw" and diff < 50:
+            shared_features.append("similar molecular weight")
+        elif key == "logp" and diff < 1:
+            shared_features.append("similar lipophilicity")
+        elif key == "tpsa" and diff < 20:
+            shared_features.append("similar polarity")
+        elif key == "aromatic_rings" and diff == 0:
+            shared_features.append(f"same aromatic ring count ({props_a[key]})")
+        elif key == "hbd" and diff == 0 and props_a[key] > 0:
+            shared_features.append(f"same H-bond donors ({props_a[key]})")
+
+    # Infer morphological similarity class
+    combined_sim = 0.6 * morgan_sim + 0.3 * maccs_sim + 0.1 * dice_sim
+    if combined_sim > 0.85:
+        sim_class = "highly similar"
+        morphology_prediction = "Very likely similar morphological profiles"
+    elif combined_sim > 0.6:
+        sim_class = "moderately similar"
+        morphology_prediction = "Possibly similar morphological effects"
+    elif combined_sim > 0.4:
+        sim_class = "weakly similar"
+        morphology_prediction = "Some shared structural features; morphology may differ"
+    else:
+        sim_class = "dissimilar"
+        morphology_prediction = "Likely different morphological profiles"
+
+    # Heuristic mechanism class
+    def _mechanism_class(props):
+        if props["aromatic_rings"] >= 3 and props["hba"] >= 2:
+            return "kinase_inhibitor_like"
+        elif props["mw"] < 600 and props["logp"] < 2:
+            return "polar_small_molecule"
+        elif props["mw"] > 800:
+            return "macrocycle_like"
+        else:
+            return "standard_small_molecule"
+
+    mech_a = _mechanism_class(props_a)
+    mech_b = _mechanism_class(props_b)
+
+    summary = (
+        f"Morphological similarity between compounds: {combined_sim:.2f} ({sim_class}). "
+        f"Morgan Tanimoto: {morgan_sim:.3f}, MACCS: {maccs_sim:.3f}. "
+        f"{morphology_prediction}"
+    )
+    if shared_features:
+        summary += f". Shared: {', '.join(shared_features[:4])}"
+
+    return {
+        "summary": summary,
+        "similarity_scores": {
+            "morgan_tanimoto": round(morgan_sim, 4),
+            "maccs_tanimoto": round(maccs_sim, 4),
+            "dice": round(dice_sim, 4),
+            "combined": round(combined_sim, 4),
+        },
+        "similarity_class": sim_class,
+        "morphology_prediction": morphology_prediction,
+        "shared_features": shared_features,
+        "compound_a": {
+            "smiles": smiles_a,
+            "properties": props_a,
+            "mechanism_class": mech_a,
+        },
+        "compound_b": {
+            "smiles": smiles_b,
+            "properties": props_b,
+            "mechanism_class": mech_b,
+        },
+        "property_differences": prop_diffs,
+    }

ct/tools/intel.py

@@ -0,0 +1,223 @@
+"""
+Competitive and pipeline intelligence tools for pharma R&D.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+from ct.tools import registry
+
+
+def _to_int(value: Any, default: int = 0) -> int:
+    try:
+        return int(value)
+    except Exception:
+        return default
+
+
+@registry.register(
+    name="intel.pipeline_watch",
+    description="Track pipeline activity for a target/indication across trials and literature",
+    category="intel",
+    parameters={
+        "query": "Target, drug class, or mechanism to monitor",
+        "indication": "Optional disease/indication filter",
+        "max_trials": "Maximum trial records to retain (default 20)",
+        "max_papers": "Maximum papers per source to retain (default 10)",
+    },
+    usage_guide=(
+        "Use for ongoing landscape monitoring. Aggregates clinical trial momentum and publication "
+        "velocity into a concise watchlist snapshot for strategy discussions."
+    ),
+)
+def pipeline_watch(
+    query: str,
+    indication: str = "",
+    max_trials: int = 20,
+    max_papers: int = 10,
+    **kwargs,
+) -> dict:
+    """Create a compact pipeline watch snapshot from public sources."""
+    del kwargs
+    if not query or not query.strip():
+        return {"summary": "query is required.", "error": "missing_query"}
+
+    from ct.tools.clinical import trial_search
+    from ct.tools.literature import openalex_search, pubmed_search
+
+    max_trials = max(1, min(int(max_trials or 20), 100))
+    max_papers = max(1, min(int(max_papers or 10), 50))
+
+    search_query = f"{query} {indication}".strip()
+    trial_result = trial_search(query=search_query)
+    pubmed_result = pubmed_search(query=search_query, max_results=max_papers)
+    openalex_result = openalex_search(query=search_query, max_results=max_papers)
+
+    if "error" in trial_result and "error" in pubmed_result and "error" in openalex_result:
+        return {
+            "summary": (
+                f"Pipeline watch failed for '{search_query}': all upstream sources returned errors."
+            ),
+            "error": "all_sources_failed",
+            "sources": {
+                "trials_error": trial_result.get("error"),
+                "pubmed_error": pubmed_result.get("error"),
+                "openalex_error": openalex_result.get("error"),
+            },
+        }
+
+    trials = (trial_result.get("trials") or [])[:max_trials]
+    phase_dist = trial_result.get("phase_distribution", {}) or {}
+    status_dist = trial_result.get("status_distribution", {}) or {}
+    recruiting = _to_int(status_dist.get("RECRUITING", 0), 0)
+    phase3 = _to_int(phase_dist.get("PHASE3", 0), 0)
+
+    pubmed_articles = pubmed_result.get("articles", []) if isinstance(pubmed_result, dict) else []
+    openalex_articles = openalex_result.get("articles", []) if isinstance(openalex_result, dict) else []
+
+    current_year = datetime.utcnow().year
+    recent_pubmed = 0
+    for item in pubmed_articles:
+        pub_date = str(item.get("pub_date", ""))
+        if str(current_year) in pub_date or str(current_year - 1) in pub_date:
+            recent_pubmed += 1
+
+    recent_openalex = 0
+    for item in openalex_articles:
+        year = _to_int(item.get("publication_year"), 0)
+        if year >= current_year - 1:
+            recent_openalex += 1
+
+    momentum_score = 0
+    momentum_score += min(40, _to_int(trial_result.get("total_count", 0), 0))
+    momentum_score += min(25, recruiting * 3)
+    momentum_score += min(20, phase3 * 5)
+    momentum_score += min(15, recent_pubmed + recent_openalex)
+    momentum_score = min(100, momentum_score)
+
+    if momentum_score >= 70:
+        momentum = "high"
+    elif momentum_score >= 40:
+        momentum = "moderate"
+    else:
+        momentum = "early"
+
+    summary = (
+        f"Pipeline watch for '{search_query}': momentum={momentum} ({momentum_score}/100). "
+        f"Trials={trial_result.get('total_count', 0)}, recruiting={recruiting}, phase3={phase3}, "
+        f"recent publications={recent_pubmed + recent_openalex}."
+    )
+
+    return {
+        "summary": summary,
+        "query": query,
+        "indication": indication or None,
+        "momentum": momentum,
+        "momentum_score": momentum_score,
+        "trials": {
+            "total_count": trial_result.get("total_count", 0),
+            "phase_distribution": phase_dist,
+            "status_distribution": status_dist,
+            "records": trials,
+            "error": trial_result.get("error"),
+        },
+        "literature": {
+            "pubmed_total": pubmed_result.get("total_count", 0),
+            "pubmed_recent_last_2y": recent_pubmed,
+            "openalex_total": openalex_result.get("total_count", 0),
+            "openalex_recent_last_2y": recent_openalex,
+            "pubmed_top": pubmed_articles[:max_papers],
+            "openalex_top": openalex_articles[:max_papers],
+            "pubmed_error": pubmed_result.get("error"),
+            "openalex_error": openalex_result.get("error"),
+        },
+    }
+
+
+@registry.register(
+    name="intel.competitor_snapshot",
+    description="Generate a one-shot competitor snapshot for a target and indication",
+    category="intel",
+    parameters={
+        "gene": "Target gene symbol (e.g., LRRK2, IL23R)",
+        "indication": "Optional indication filter",
+        "max_programs": "Maximum trial/program records to include (default 15)",
+    },
+    usage_guide=(
+        "Use for decision meetings and external positioning. Summarizes active sponsors, phases, "
+        "mechanism diversity, and top benchmark endpoints around a target."
+    ),
+)
+def competitor_snapshot(
+    gene: str,
+    indication: str = "",
+    max_programs: int = 15,
+    **kwargs,
+) -> dict:
+    """Build a compact competitor snapshot using clinical and target landscape tools."""
+    del kwargs
+    if not gene or not gene.strip():
+        return {"summary": "gene is required.", "error": "missing_gene"}
+
+    from ct.tools.clinical import competitive_landscape, trial_design_benchmark
+
+    max_programs = max(1, min(int(max_programs or 15), 50))
+    landscape = competitive_landscape(gene=gene.strip(), indication=indication.strip())
+    benchmark = trial_design_benchmark(
+        query=f"{gene} {indication}".strip(),
+        max_results=min(100, max_programs * 2),
+    )
+
+    if "error" in landscape and "error" in benchmark:
+        return {
+            "summary": f"Competitor snapshot failed for {gene}: upstream sources unavailable.",
+            "error": "snapshot_failed",
+            "sources": {
+                "landscape_error": landscape.get("error"),
+                "benchmark_error": benchmark.get("error"),
+            },
+        }
+
+    trial_records = ((landscape.get("trials") or {}).get("top_trials") or [])[:max_programs]
+    sponsors = {}
+    for trial in trial_records:
+        sponsor = str(trial.get("sponsor", "")).strip()
+        if sponsor:
+            sponsors[sponsor] = sponsors.get(sponsor, 0) + 1
+    top_sponsors = sorted(sponsors.items(), key=lambda kv: kv[1], reverse=True)[:10]
+
+    phase_dist = ((landscape.get("trials") or {}).get("phase_distribution") or {})
+    chembl = (landscape.get("chembl") or {})
+    ot = (landscape.get("open_targets") or {})
+    top_endpoints = (benchmark.get("top_primary_endpoints") or [])[:5]
+
+    differentiation_flags = []
+    if _to_int(phase_dist.get("PHASE3", 0), 0) == 0:
+        differentiation_flags.append("No Phase 3 pressure detected in returned trial window.")
+    if _to_int(chembl.get("unique_compounds", 0), 0) < 10:
+        differentiation_flags.append("Limited small-molecule density; potential white space.")
+    if _to_int(ot.get("n_known_drugs", 0), 0) == 0:
+        differentiation_flags.append("No known drugs in Open Targets snapshot for this target.")
+
+    summary = (
+        f"Competitor snapshot for {gene}{f' in {indication}' if indication else ''}: "
+        f"{_to_int((landscape.get('trials') or {}).get('total_count', 0), 0)} trial records, "
+        f"{_to_int(chembl.get('unique_compounds', 0), 0)} ChEMBL compounds, "
+        f"{_to_int(ot.get('n_known_drugs', 0), 0)} known drugs."
+    )
+
+    return {
+        "summary": summary,
+        "gene": gene,
+        "indication": indication or None,
+        "top_sponsors": [{"sponsor": name, "trial_count": count} for name, count in top_sponsors],
+        "phase_distribution": phase_dist,
+        "top_primary_endpoints": top_endpoints,
+        "mechanism_classes": sorted(chembl.get("moa_types", []) or []),
+        "differentiation_flags": differentiation_flags,
+        "programs": trial_records,
+        "landscape": landscape,
+        "benchmark": benchmark,
+    }