added clinical download and web query agents

Author: Parekh

app.py

@@ -47,6 +47,7 @@
 import tools.bih_query as bih_mod
 import tools.tcia_download as tcia_dl_mod
 import tools.idc_download as idc_dl_mod
+import tools.clinical_data as clin_mod
 from tools.shared import TOOL_REGISTRY
 
 
@@ -108,6 +109,7 @@ def oauth_callback(
 midrc_dl_mod.configure_midrc_download_tool()
 tcia_dl_mod.configure_tcia_download_tool()
 idc_dl_mod.configure_idc_download_tool()
+clin_mod.configure_clinical_data_tool()
 
 _ = dq_mod.idc_query_runner
 _ = img_mod.imaging_runner
@@ -120,6 +122,7 @@ def oauth_callback(
 _ = midrc_dl_mod.midrc_download_runner
 _ = tcia_dl_mod.tcia_download_runner
 _ = idc_dl_mod.idc_download_runner
+_ = clin_mod.clinical_data_download_runner
 
 ALL_TOOLS: tuple[BaseTool, ...] = tuple(TOOL_REGISTRY)
 TOOL_NAMES = {tool.name: tool for tool in ALL_TOOLS}
@@ -144,6 +147,7 @@ def build_graph(checkpointer=None):
         - Do not ask the user follow up questions unless absolutely necessary. 
         - Do not do more than what the user requests.
         - Do not suggest next steps for the user unless they ask for them.
+        - For downloading DICOM Series or histopathology tiles, always download one patient at a time. If the user requests multiple patients, call the download tool multiple times, once per patient.
         - When using llm based tools which generate code, be as concise as possible in your instructions, unless an error occurs, then be as specific as possible to fix the issue.
         - Assume that tools cannot see each other's output or the conversation history. You must pass information between tools yourself.
         ---

app_idc.py

@@ -37,6 +37,9 @@
 import tools.idc_query as dq_mod
 import tools.dicom_to_nifti as d2n_mod
 import tools.idc_download as idc_dl_mod
+import tools.idc_web_qa as webqa_mod
+import tools.pathology_download as path_mod
+import tools.clinical_data as clin_mod
 from tools.shared import TOOL_REGISTRY
 
 '''
@@ -68,20 +71,34 @@ def oauth_callback(
     system_prompt=(_P("prompts/agent_systems/idc_query.txt").read_text()),
 )
 idc_dl_mod.configure_idc_download_tool()
+clin_mod.configure_clinical_data_tool()
+webqa_mod.configure_idc_web_qa_tool()
+path_mod.configure_pathology_download_tool()
 
 _ = dq_mod.idc_query_runner
 _ = d2n_mod.dicom2nifti_runner
 _ = idc_dl_mod.idc_download_runner
+_ = webqa_mod.idc_web_qa_runner
+_ = clin_mod.clinical_data_download_runner
+_ = path_mod.pathology_download_runner
 
 ALL_TOOLS: tuple[BaseTool, ...] = tuple(TOOL_REGISTRY)
 
 def build_graph(checkpointer=None):
     policy = SystemMessage(content=(
         f"""
-        You are **VoxelInsight IDC**, an AI assistant focused on IDC metadata, series downloads, and DICOM→NIfTI conversion.
+        You are **VoxelInsight IDC**, a multi-agent assistant for IDC: metadata Q&A, web-grounded answers, radiology downloads,
+        histopathology tiles via DICOMweb, clinical data exports (idc_index), and DICOM→NIfTI conversion.
 
         Core behavior
         - Only answer what the user asked; request clarifications solely when required to complete a tool call.
+        - Only when asked about VoxelInsight, answer yourself otherwise always use tools. YOU ARE NOT ALLOWED TO ANSWER DIRECTLY.
+        - When the user asks questions about IDC documentation, use the `idc_web_qa` tool to answer them based. These are questions like "What is the purpose of IDC?", "How to access IDC data?", "What collections are available in IDC?", etc.
+        - Primarily if the user's question is a How to or what is, use the `idc_web_qa` tool to answer them based on IDC documentation.
+        - When the user asks for IDC data (metadata, images, clinical data), use the idc_query tool. These include questions like "How many patients are in IDC?", "List all SeriesInstanceUIDs for CT scans in collection X", "Show me a summary of the IDC metadata tables", etc.
+        - When the user requests downloads of DICOM series, histopathology tiles, or clinical data, use the respective download tools (`idc_download`, `pathology_download`, `clinical_data_download`).
+        - For downloading DICOM Series or histopathology tiles, always download one patient at a time. If the user requests multiple patients, call the download tool multiple times, once per patient.
+        - When the user requests DICOM to NIfTI conversion, use the `
         - Tools cannot see each other’s outputs—pass important values (SeriesInstanceUIDs, directories, etc.) yourself.
         - Keep tool instructions brief unless retrying an error. Retry at most 3 times (when it seems reasonable/necessary) with progressively clearer directions.
         - Before each tool call, tell the user what you are about to do in one concise sentence.
@@ -94,7 +111,10 @@ def build_graph(checkpointer=None):
             - For instance do not ask the tool for notes which you could have surmised. You will receive the tools code output and code itself so you can interpret it directly.
             - Aim to get the result in as few tool calls as possible. Do not split into multiple calls unless absolutely necessary.
             - If the user wants to view or visualize the radiology imaging data without downloading, the idc_query tool can provide links to online viewers.
+        - `idc_web_qa`: answer general IDC questions grounded in learn.canceridc.dev (or a provided IDC doc URL). Use when the user asks doc questions.
         - `idc_download`: download DICOM series by UID. Use exactly the IDs produced by `idc_query` and respect user cancellations.
+        - `pathology_download`: download histopathology tiles via DICOMweb. Default size 512x512; honor user-specified size. Needs study/series/sop instance UIDs.
+        - `clinical_data_download`: download IDC clinical data by collection using idc_index (no BigQuery). Optionally select fields and/or filter on a field value.
         - `dicom2nifti`: convert downloaded DICOM folders to NIfTI files. Only run it after confirming the directory exists.
             - Automatically returns downloaded NIfTI files as download links in the UI.
 
@@ -289,6 +309,9 @@ def __init__(self):
             "midrc_download": "MIDRC Download Tool",
             "tcia_download": "TCIA Download Tool",
             "universeg": "Universeg Segmentation",
+            "idc_web_qa": "IDC Web Q&A",
+            "pathology_download": "Histopathology Download",
+            "clinical_data_download": "Clinical Data Download",
         }
 
     async def _rename_root(self, name: str):

idc_index/default__vector_store.json

@@ -0,0 +1 @@
+{"graph_dict": {}}

idc_index/docstore.json

@@ -0,0 +1 @@
+{"embedding_dict": {}, "text_id_to_ref_doc_id": {}, "metadata_dict": {}}

idc_index/graph_store.json

@@ -0,0 +1,128 @@
+from __future__ import annotations
+
+import tempfile
+from pathlib import Path
+from typing import List, Optional
+
+import pandas as pd
+from idc_index import IDCClient
+from pydantic import BaseModel, Field
+
+from core.state import TaskResult
+from tools.shared import toolify_agent
+
+
+class ClinicalDataArgs(BaseModel):
+    collection_id: str = Field(..., description="IDC collection ID (e.g., tcga_brca).")
+    fields: Optional[List[str]] = Field(
+        None,
+        description="Optional list of columns to keep. If omitted, all columns are returned.",
+    )
+    filter_field: Optional[str] = Field(
+        None,
+        description="Optional column to filter on (exact match).",
+    )
+    filter_value: Optional[str] = Field(
+        None,
+        description="Value to filter the filter_field by.",
+    )
+    limit_rows: int = Field(
+        5000,
+        ge=1,
+        le=50000,
+        description="Maximum rows to return (safety cap). Default 5000.",
+    )
+
+
+_CONFIGURED = False
+_CLIENT: Optional[IDCClient] = None
+
+
+def configure_clinical_data_tool():
+    """Initialize the IDC client once."""
+    global _CONFIGURED, _CLIENT
+    if _CONFIGURED and _CLIENT is not None:
+        return
+    _CLIENT = IDCClient()
+    _CLIENT.fetch_index("clinical_index")
+    _CONFIGURED = True
+
+
+def _available_tables_for_collection(collection_id: str) -> List[str]:
+    if _CLIENT is None:
+        raise RuntimeError("IDC client not initialized.")
+    df = _CLIENT.clinical_index
+    if "collection_id" not in df.columns:
+        return []
+    subset = df[df["collection_id"] == collection_id]
+    if subset.empty:
+        return []
+    if "short_table_name" in subset.columns:
+        tables = subset["short_table_name"].dropna().unique().tolist()
+    elif "table_name" in subset.columns:
+        tables = subset["table_name"].dropna().unique().tolist()
+    else:
+        tables = []
+    return [t for t in tables if t]
+
+
+@toolify_agent(
+    name="clinical_data_download",
+    description="Download IDC clinical data by collection using idc_index (no BigQuery). Can limit columns and apply an equality filter.",
+    args_schema=ClinicalDataArgs,
+    timeout_s=180,
+)
+async def clinical_data_download_runner(
+    collection_id: str,
+    fields: Optional[List[str]] = None,
+    filter_field: Optional[str] = None,
+    filter_value: Optional[str] = None,
+    limit_rows: int = 5000,
+):
+    if not _CONFIGURED or _CLIENT is None:
+        configure_clinical_data_tool()
+
+    tables = _available_tables_for_collection(collection_id)
+    if not tables:
+        raise ValueError(f"No clinical tables found for collection '{collection_id}'.")
+
+    frames: List[pd.DataFrame] = []
+    for tbl in tables:
+        try:
+            df_tbl = _CLIENT.get_clinical_table(tbl)
+            df_tbl["__source_table"] = tbl
+            frames.append(df_tbl)
+        except Exception as e:
+            raise RuntimeError(f"Failed to load clinical table '{tbl}': {e}")
+
+    if not frames:
+        raise RuntimeError(f"Clinical tables for '{collection_id}' could not be loaded.")
+
+    df = pd.concat(frames, ignore_index=True)
+
+    if filter_field:
+        if filter_field not in df.columns:
+            raise ValueError(f"Field '{filter_field}' not found in clinical data.")
+        if filter_value is not None:
+            df = df[df[filter_field] == filter_value]
+
+    if fields:
+        missing = [f for f in fields if f not in df.columns]
+        if missing:
+            raise ValueError(f"Requested fields missing: {', '.join(missing)}")
+        df = df[fields]
+
+    df = df.head(limit_rows)
+
+    tmp_dir = Path(tempfile.mkdtemp(prefix="clinical_"))
+    csv_path = tmp_dir / f"{collection_id}_clinical.csv"
+    df.to_csv(csv_path, index=False)
+
+    summary = f"Clinical data downloaded via idc_index: collection={collection_id}, rows={len(df)}, columns={len(df.columns)}"
+    outputs = {
+        "text": summary,
+        "tool": "clinical_data_download",
+        "df_preview": {"rows": df.head(50).to_dict("records"), "nrows": len(df)},
+    }
+    artifacts = {"files": [str(csv_path)]}
+    return TaskResult(output=outputs, artifacts=artifacts)