Upload 15 files

cellemetry/__init__.py

@@ -0,0 +1,18 @@
+"""
+Cellemetry: Google ADK Agent for Microscopy Image Analysis
+"""
+from .agents import root_agent, analyst_agent, manager_agent
+from .config import AnalysisDeps, AnalystResult, ManagerSummary, ComponentRequest, BoundingBox
+from .tools import ANALYST_TOOLS
+
+__all__ = [
+    "root_agent",
+    "analyst_agent", 
+    "manager_agent",
+    "AnalysisDeps",
+    "AnalystResult",
+    "ManagerSummary",
+    "ComponentRequest",
+    "BoundingBox",
+    "ANALYST_TOOLS",
+]

cellemetry/agent.py

@@ -0,0 +1,8 @@
+"""
+Agent definition file for ADK CLI (adk web / adk run).
+Place this at the package root for: adk web bio_agent
+"""
+from cellemetry.agents import root_agent
+
+# ADK CLI looks for 'root_agent' or 'agent' at module level
+agent = root_agent

cellemetry/agents/__init__.py

@@ -0,0 +1,15 @@
+"""
+Agents package for bio_agent.
+Exports the agent hierarchy with manager as root.
+"""
+from .analyst import analyst_agent
+from .manager import manager_agent
+
+# The root agent for ADK runner
+root_agent = manager_agent
+
+__all__ = [
+    "root_agent",
+    "manager_agent",
+    "analyst_agent",
+]

cellemetry/agents/analyst.py

@@ -0,0 +1,66 @@
+"""
+Analyst Agent - Expert microscopy image analyst.
+Segments biological components and computes statistics.
+"""
+from google.adk.agents import LlmAgent
+from google.adk.tools.agent_tool import AgentTool
+
+from ..tools import ANALYST_TOOLS
+
+
+ANALYST_INSTRUCTION = """
+You are an expert microscopy image analyst.
+
+**Your Goal:** Identify major biological components, segment them using SAM3, analyze the segmentations, and provide a report.
+
+**Step 1: Resolution Parsing:**
+Look for physical resolution info (e.g., "0.27 microns/px", "0.5 um per pixel"). 
+If found, note it for reference. If not found, proceed without physical units.
+
+**Step 2: Visual Analysis**
+Identify distinct structures (e.g., Nuclei, Cells) in the image.
+
+**Step 3: Define Tool Inputs**
+Decompose each structure into three words:
+- `color`: ONE adjective (e.g., "green")
+- `morphology`: ONE adjective (e.g., "irregular")
+- `entity`: ONE noun (e.g., "cell" - singular!)
+
+**Step 4: Box Selection**
+Select 1-3 representative bounding boxes per structure (0-1000 normalized).
+Ensure boxes cover the full object.
+
+**Step 5: Execution**
+Call `apply_sam3_tool` for each structure type.
+
+**Step 6: CRITICAL - Use Exact Filenames**
+The segmentation tool returns a result containing "MASK_FILE=/tmp/data_xxx.npz".
+You MUST extract and use this EXACT filename when calling statistics tools.
+
+Example:
+- Segmentation returns: "SUCCESS: Found 15 'green irregular cell' objects. MASK_FILE=/tmp/data_green_cell.npz"
+- When calling get_basic_stats, use filename="/tmp/data_green_cell.npz" (the EXACT path from MASK_FILE)
+
+**Step 7: Quantification**
+- Call `get_basic_stats` with the EXACT filename from segmentation for every structure found.
+- Call `get_spatial_stats` with the EXACT filename specifically for Cells.
+- Call `get_relationship_stats` with BOTH exact filenames ONLY if both Cells and Nuclei were found.
+
+**Step 8: Save Results**
+Save all data using `save_excel_tool`.
+
+Return your findings as structured data including:
+- pixel_size_used (if applicable)
+- components_found (list of segmented components)
+- excel_path
+- stats objects
+"""
+
+analyst_agent = LlmAgent(
+    name="analyst",
+    model="gemini-3-pro-preview",
+    description="Expert microscopy analyst that segments and quantifies biological structures.",
+    instruction=ANALYST_INSTRUCTION,
+    tools=ANALYST_TOOLS,
+    output_key="analyst_result",
+)

cellemetry/agents/manager.py

@@ -0,0 +1,39 @@
+"""
+Manager Agent - Workflow orchestrator.
+Coordinates analysis tasks and synthesizes user-facing reports.
+"""
+from google.adk.agents import LlmAgent
+from google.adk.tools.agent_tool import AgentTool
+
+from .analyst import analyst_agent
+
+
+MANAGER_INSTRUCTION = """
+You are the Cellemetry Workflow Manager.
+
+**Goal**: Orchestrate microscopy image analysis and deliver user-friendly summaries.
+
+**Workflow:**
+1. Receive the user's request and image context.
+2. Extract resolution info (e.g., "0.27 microns/px") if present in the request.
+3. Delegate analysis to the `analyst` tool - pass the original request along with any extracted metadata.
+4. Receive the structured analysis results.
+5. Synthesize a human-readable summary:
+   - Write a clear executive summary
+   - Highlight key biological findings (density, size, relationships)
+   - List where output files were saved
+
+**Important**: When calling the analyst tool, pass the full user request so the analyst has all context about what to analyze.
+"""
+
+# Wrap analyst as a tool for the manager
+analyst_tool = AgentTool(agent=analyst_agent)
+
+manager_agent = LlmAgent(
+    name="manager",
+    model="gemini-2.5-pro",
+    description="Orchestrates microscopy analysis workflows and synthesizes reports.",
+    instruction=MANAGER_INSTRUCTION,
+    tools=[analyst_tool],
+    output_key="manager_summary",
+)

cellemetry/config/__init__.py

@@ -0,0 +1,19 @@
+"""
+Config package - schemas and dependency definitions.
+"""
+from .schemas import (
+    AnalystResult,
+    ManagerSummary,
+    ComponentRequest,
+    BoundingBox,
+)
+from .dependencies import AnalysisDeps, get_deps_from_state
+
+__all__ = [
+    "AnalystResult",
+    "ManagerSummary",
+    "ComponentRequest",
+    "BoundingBox",
+    "AnalysisDeps",
+    "get_deps_from_state",
+]

cellemetry/config/dependencies.py

@@ -0,0 +1,36 @@
+"""
+Dependency management using ADK session state.
+SAM models and shared resources are stored in state for tool access.
+"""
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional, Any
+
+@dataclass
+class AnalysisDeps:
+    """Container for analysis dependencies - stored in session state."""
+    sam_model: Any
+    sam_processor: Any
+    image_path: Path
+    device: str
+    pixel_size_microns: Optional[float] = None
+
+    def to_state_dict(self) -> dict:
+        """Convert to dict for session state storage."""
+        return {
+            "app:sam_model": self.sam_model,
+            "app:sam_processor": self.sam_processor,
+            "app:image_path": str(self.image_path),
+            "app:device": self.device,
+            "app:pixel_size_microns": self.pixel_size_microns,
+        }
+
+def get_deps_from_state(state: dict) -> AnalysisDeps:
+    """Reconstruct AnalysisDeps from session state."""
+    return AnalysisDeps(
+        sam_model=state.get("app:sam_model"),
+        sam_processor=state.get("app:sam_processor"),
+        image_path=Path(state.get("app:image_path")),
+        device=state.get("app:device", "cpu"),
+        pixel_size_microns=state.get("app:pixel_size_microns"),
+    )

cellemetry/config/schemas.py

@@ -0,0 +1,76 @@
+"""
+Pydantic schemas for structured inputs/outputs.
+ADK supports Pydantic models for structured output via output_schema.
+"""
+from pydantic import BaseModel, Field
+from typing import List, Optional, Dict
+
+
+# --- SAM3 Inputs ---
+class BoundingBox(BaseModel):
+    ymin: int = Field(description="Top Y (0-1000)")
+    xmin: int = Field(description="Left X (0-1000)")
+    ymax: int = Field(description="Bottom Y (0-1000)")
+    xmax: int = Field(description="Right X (0-1000)")
+
+
+class ComponentRequest(BaseModel):
+    entity: str = Field(description="Generic object name (e.g., 'cell'). 1 word.")
+    color: str = Field(description="Dominant color adjective (e.g., 'green').")
+    morphology: str = Field(description="Dominant shape adjective (e.g., 'irregular').")
+    bboxes: List[BoundingBox]
+
+
+# --- Stats Schemas ---
+class BasicStats(BaseModel):
+    count: int
+    area_mean: float
+    area_std: float
+    unit: str = "px²"
+
+
+class SpatialStats(BaseModel):
+    avg_nnd: float
+    std_nnd: float
+    density: float
+    avg_neighbor_count: float
+    std_neighbor_count: float
+    dist_unit: str = "px"
+    density_unit: str = "N/A"
+
+
+class RelationalStats(BaseModel):
+    matched_pairs: int
+    avg_ratio: float
+    std_ratio: float
+
+
+# --- Analyst Output ---
+class SegmentedComponent(BaseModel):
+    label: str
+    description: str
+    mask_filename: str
+    data_filename: str
+    count: int
+
+
+class AnalystResult(BaseModel):
+    """Structured output from the Analyst agent."""
+    pixel_size_used: Optional[float] = None
+    components_found: List[SegmentedComponent] = Field(default_factory=list)
+    excel_path: str = ""
+    cell_stats: Optional[BasicStats] = None
+    nuclei_stats: Optional[BasicStats] = None
+    spatial_stats: Optional[SpatialStats] = None
+    relational_stats: Optional[RelationalStats] = None
+
+
+# --- Manager Output ---
+class ManagerSummary(BaseModel):
+    """Final user-facing summary from the Manager."""
+    executive_summary: str
+    key_findings: List[str]
+    file_locations: Dict[str, str] = Field(
+        default_factory=dict,
+        description="Map of 'description' to 'filepath'"
+    )

cellemetry/services/__init__.py

@@ -0,0 +1,7 @@
+"""
+Services package - core processing logic.
+"""
+from . import sam
+from . import analysis
+
+__all__ = ["sam", "analysis"]

cellemetry/services/analysis.py

@@ -0,0 +1,228 @@
+"""
+Statistical analysis functions for segmentation masks.
+Unchanged from original implementation.
+"""
+import os
+import xlsxwriter
+import numpy as np
+from scipy.spatial import KDTree
+from skimage.measure import regionprops
+from typing import Optional, Dict, Any
+
+
+def load_masks(filename: str) -> Optional[np.ndarray]:
+    """Load .npz mask stack from disk."""
+    try:
+        data = np.load(filename)
+        return data['masks'] if 'masks' in data else data[data.files[0]]
+    except Exception as e:
+        print(f"Error loading {filename}: {e}")
+        return None
+
+
+def get_basic_stats(filename: str, pixel_scale: Optional[float] = None) -> Dict[str, Any]:
+    """Calculate Count, Mean Area, and Std Dev Area."""
+    masks = load_masks(filename)
+    if masks is None or masks.size == 0:
+        return {"count": 0, "area_mean": 0.0, "area_std": 0.0, "unit": "px²"}
+
+    areas_px = np.sum(masks, axis=(1, 2))
+
+    if pixel_scale:
+        conversion_factor = pixel_scale ** 2
+        areas = areas_px * conversion_factor
+        unit = "µm²"
+    else:
+        areas = areas_px
+        unit = "px²"
+
+    return {
+        "count": int(len(areas)),
+        "area_mean": float(np.mean(areas)),
+        "area_std": float(np.std(areas)),
+        "unit": unit
+    }
+
+
+def get_spatial_stats(filename: str, pixel_scale: Optional[float] = None) -> Dict[str, Any]:
+    """Calculate spatial metrics including NND and density."""
+    masks = load_masks(filename)
+    defaults = {
+        "avg_nnd": 0.0, "std_nnd": 0.0,
+        "density": 0.0,
+        "avg_neighbor_count": 0.0, "std_neighbor_count": 0.0,
+        "dist_unit": "px", "density_unit": "N/A"
+    }
+
+    if masks is None or masks.size == 0:
+        return defaults
+
+    # Get centroids
+    centroids_px = []
+    for m in masks:
+        props = regionprops(m.astype(int))
+        if props:
+            centroids_px.append(props[0].centroid)
+
+    centroids_px = np.array(centroids_px)
+    n_objects = len(centroids_px)
+    image_pixel_area = masks[0].size
+
+    # Unit conversion
+    if pixel_scale:
+        dist_factor = pixel_scale
+        dist_unit = "µm"
+        image_phys_area = (image_pixel_area * (pixel_scale ** 2)) / (1000 ** 2)
+        density_unit = "cells/mm²"
+    else:
+        dist_factor = 1.0
+        dist_unit = "px"
+        image_phys_area = image_pixel_area / 10000.0
+        density_unit = "cells/10k px²"
+
+    if n_objects < 2:
+        res = defaults.copy()
+        res.update({
+            "density": float(n_objects / image_phys_area) if image_phys_area > 0 else 0,
+            "dist_unit": dist_unit,
+            "density_unit": density_unit
+        })
+        return res
+
+    # KDTree calculations
+    tree = KDTree(centroids_px)
+
+    # Nearest neighbor distance
+    dists_px, _ = tree.query(centroids_px, k=2)
+    valid_dists_px = dists_px[:, 1]
+
+    # Local crowding
+    neighbors = tree.query_ball_point(centroids_px, r=100)
+    neighbor_counts = [len(n) - 1 for n in neighbors]
+
+    return {
+        "avg_nnd": float(np.mean(valid_dists_px) * dist_factor),
+        "std_nnd": float(np.std(valid_dists_px) * dist_factor),
+        "density": float(n_objects / image_phys_area),
+        "avg_neighbor_count": float(np.mean(neighbor_counts)),
+        "std_neighbor_count": float(np.std(neighbor_counts)),
+        "dist_unit": dist_unit,
+        "density_unit": density_unit
+    }
+
+
+def analyze_relationships(cell_file: str, nuc_file: str) -> Dict[str, Any]:
+    """Calculate Cell/Nucleus overlap ratios."""
+    cells = load_masks(cell_file)
+    nuclei = load_masks(nuc_file)
+
+    if cells is None or nuclei is None or cells.size == 0 or nuclei.size == 0:
+        return {"matched_pairs": 0, "avg_ratio": 0.0, "std_ratio": 0.0}
+
+    H, W = cells[0].shape
+    cell_map = np.zeros((H, W), dtype=int)
+    for idx, mask in enumerate(cells):
+        cell_map[mask > 0] = idx + 1
+
+    ratios = []
+    for nuc_mask in nuclei:
+        props = regionprops(nuc_mask.astype(int))
+        if not props:
+            continue
+        cy, cx = map(int, props[0].centroid)
+        if 0 <= cy < H and 0 <= cx < W:
+            cell_id = cell_map[cy, cx]
+            if cell_id > 0:
+                cell_area = np.sum(cells[cell_id - 1])
+                nuc_area = np.sum(nuc_mask)
+                if nuc_area > 0:
+                    ratios.append(cell_area / nuc_area)
+
+    if not ratios:
+        return {"matched_pairs": 0, "avg_ratio": 0.0, "std_ratio": 0.0}
+
+    return {
+        "matched_pairs": len(ratios),
+        "avg_ratio": float(np.mean(ratios)),
+        "std_ratio": float(np.std(ratios))
+    }
+
+
+def save_stats_to_excel(
+    base_filename: str,
+    cell_stats: Optional[Dict] = None,
+    nuc_stats: Optional[Dict] = None,
+    spatial_stats: Optional[Dict] = None,
+    rel_stats: Optional[Dict] = None
+) -> str:
+    """Write statistics to a multi-sheet Excel file."""
+    filename = os.path.splitext(base_filename)[0] + ".xlsx"
+
+    try:
+        workbook = xlsxwriter.Workbook(filename)
+        header_fmt = workbook.add_format({'bold': True, 'bg_color': '#D3D3D3', 'border': 1})
+        num_fmt = workbook.add_format({'num_format': '0.00'})
+
+        # Morphology sheet
+        ws_morph = workbook.add_worksheet("Morphology")
+        headers = ["Structure", "Count", "Mean Area", "StdDev Area", "Unit"]
+        ws_morph.write_row(0, 0, headers, header_fmt)
+
+        row = 1
+        if cell_stats and cell_stats.get("count", 0) > 0:
+            ws_morph.write(row, 0, "Cells")
+            ws_morph.write(row, 1, cell_stats.get('count', 0))
+            ws_morph.write(row, 2, cell_stats.get('area_mean', 0), num_fmt)
+            ws_morph.write(row, 3, cell_stats.get('area_std', 0), num_fmt)
+            ws_morph.write(row, 4, cell_stats.get('unit', 'px²'))
+            row += 1
+
+        if nuc_stats and nuc_stats.get("count", 0) > 0:
+            ws_morph.write(row, 0, "Nuclei")
+            ws_morph.write(row, 1, nuc_stats.get('count', 0))
+            ws_morph.write(row, 2, nuc_stats.get('area_mean', 0), num_fmt)
+            ws_morph.write(row, 3, nuc_stats.get('area_std', 0), num_fmt)
+            ws_morph.write(row, 4, nuc_stats.get('unit', 'px²'))
+
+        ws_morph.set_column(0, 4, 15)
+
+        # Spatial sheet
+        if spatial_stats and spatial_stats.get("density", 0) > 0:
+            ws_spat = workbook.add_worksheet("Spatial")
+            headers = [
+                "Structure", "Global Density", "Density Unit",
+                "Mean NND", "StdDev NND", "Dist Unit",
+                "Mean Neighbors (r=100)", "StdDev Neighbors"
+            ]
+            ws_spat.write_row(0, 0, headers, header_fmt)
+
+            ws_spat.write(1, 0, "Cells")
+            ws_spat.write(1, 1, spatial_stats.get('density', 0), num_fmt)
+            ws_spat.write(1, 2, spatial_stats.get('density_unit', 'N/A'))
+            ws_spat.write(1, 3, spatial_stats.get('avg_nnd', 0), num_fmt)
+            ws_spat.write(1, 4, spatial_stats.get('std_nnd', 0), num_fmt)
+            ws_spat.write(1, 5, spatial_stats.get('dist_unit', 'px'))
+            ws_spat.write(1, 6, spatial_stats.get('avg_neighbor_count', 0), num_fmt)
+            ws_spat.write(1, 7, spatial_stats.get('std_neighbor_count', 0), num_fmt)
+
+            ws_spat.set_column(0, 7, 18)
+
+        # Relational sheet
+        if rel_stats and rel_stats.get("matched_pairs", 0) > 0:
+            ws_rel = workbook.add_worksheet("Relational")
+            headers = ["Relationship", "Matched Pairs", "Mean Area Ratio", "StdDev Ratio"]
+            ws_rel.write_row(0, 0, headers, header_fmt)
+
+            ws_rel.write(1, 0, "Cell_to_Nucleus")
+            ws_rel.write(1, 1, rel_stats.get('matched_pairs', 0))
+            ws_rel.write(1, 2, rel_stats.get('avg_ratio', 0), num_fmt)
+            ws_rel.write(1, 3, rel_stats.get('std_ratio', 0), num_fmt)
+
+            ws_rel.set_column(0, 3, 20)
+
+        workbook.close()
+        return filename
+
+    except Exception as e:
+        print(f"Error creating Excel file: {e}")
+        return f"Error: {e}"

cellemetry/services/sam.py

@@ -0,0 +1,167 @@
+"""
+SAM3 segmentation execution.
+Core logic unchanged from original - just updated imports.
+"""
+import matplotlib
+matplotlib.use('Agg')
+import matplotlib.pyplot as plt
+import torch
+import torchvision
+import numpy as np
+from PIL import Image
+from skimage.measure import regionprops
+
+from ..config.schemas import ComponentRequest
+from ..config.dependencies import AnalysisDeps
+
+MIN_SOLIDITY = 0.50
+MIN_CIRCULARITY = 0.1
+
+# Use /tmp for all outputs (Cloud Run writable directory)
+OUTPUT_DIR = "/tmp"
+
+
+def execute_segmentation(deps: AnalysisDeps, request: ComponentRequest) -> str:
+    """
+    Execute SAM3 segmentation for the given component request.
+    
+    Args:
+        deps: Analysis dependencies with SAM model
+        request: Component request with color, morphology, entity, bboxes
+    
+    Returns:
+        String describing results and output filenames
+    """
+    text_prompt = f"{request.color} {request.morphology} {request.entity}"
+    print(f"\n[Engine] Segmenting: '{text_prompt}' ({len(request.bboxes)} boxes).")
+
+    # Load Image
+    try:
+        raw_image = Image.open(deps.image_path).convert("RGB")
+    except Exception as e:
+        return f"Error loading image: {e}"
+
+    width, height = raw_image.size
+
+    # Convert normalized coords (0-1000) to pixel coords
+    sam_input_boxes = []
+    for box in request.bboxes:
+        y_min = (box.ymin / 1000) * height
+        x_min = (box.xmin / 1000) * width
+        y_max = (box.ymax / 1000) * height
+        x_max = (box.xmax / 1000) * width
+        sam_input_boxes.append([x_min, y_min, x_max, y_max])
+
+    if not sam_input_boxes:
+        return "No valid boxes provided."
+
+    # Generate consistent filename from request
+    safe_label = f"{request.color}_{request.entity}".replace(" ", "_").lower()
+    plot_filename = f"/tmp/out_{safe_label}.png"
+    data_filename = f"/tmp/data_{safe_label}.npz"
+    
+    # Check if SAM model is available
+    if deps.sam_model is None or deps.sam_processor is None:
+        # Return mock result for testing
+        return f"[Mock] Would segment '{text_prompt}'. SAM model not loaded. Data file would be: {data_filename}"
+
+    # Prepare inputs
+    sam_input_labels = [[1] * len(sam_input_boxes)]
+    input_boxes_batch = [sam_input_boxes]
+
+    inputs = deps.sam_processor(
+        images=raw_image,
+        text=text_prompt,
+        input_boxes=input_boxes_batch,
+        input_boxes_labels=sam_input_labels,
+        return_tensors="pt"
+    ).to(deps.device)
+
+    with torch.no_grad():
+        outputs = deps.sam_model(**inputs)
+
+    results = deps.sam_processor.post_process_instance_segmentation(
+        outputs,
+        threshold=0.3,
+        target_sizes=inputs["original_sizes"].tolist()
+    )[0]
+
+    # Morphology filtering
+    keep_indices_morph = []
+    for i, mask_tensor in enumerate(results["masks"]):
+        mask_np = mask_tensor.cpu().numpy()
+        mask_np = np.squeeze(mask_np).astype(int)
+
+        if mask_np.ndim != 2:
+            keep_indices_morph.append(False)
+            continue
+
+        props = regionprops(mask_np)
+        if not props:
+            keep_indices_morph.append(False)
+            continue
+
+        prop = props[0]
+        perimeter = prop.perimeter
+        circularity = (4 * np.pi * prop.area) / (perimeter ** 2) if perimeter > 0 else 0
+
+        is_solid = prop.solidity > MIN_SOLIDITY
+        is_round_enough = circularity > MIN_CIRCULARITY
+        keep_indices_morph.append(is_solid and is_round_enough)
+
+    if any(keep_indices_morph):
+        keep_indices_tensor = torch.tensor(keep_indices_morph, device=results["masks"].device)
+        before_count = len(results["masks"])
+        results = _filter_results(results, keep_indices_tensor)
+        print(f"[Filter] Morphology: Dropped {before_count - len(results['masks'])} debris-like objects.")
+
+    # NMS
+    pred_boxes = results["boxes"]
+    pred_scores = results["scores"]
+
+    if len(pred_scores) > 1:
+        keep_indices_nms = torchvision.ops.nms(pred_boxes, pred_scores, iou_threshold=0.3)
+        results = _filter_results(results, keep_indices_nms)
+        print(f"[NMS] Reduced masks from {len(pred_scores)} to {len(keep_indices_nms)}")
+
+    # Save outputs
+    _save_plot(raw_image, results, sam_input_boxes, text_prompt, plot_filename)
+
+    mask_count = len(results['masks'])
+    if mask_count > 0:
+        masks_list = [m.cpu().numpy().squeeze() for m in results['masks']]
+        masks_array = np.array(masks_list)
+        np.savez_compressed(data_filename, masks=masks_array)
+    else:
+        np.savez_compressed(data_filename, masks=np.array([]))
+
+    print(f"[Engine] Saved {mask_count} masks to {data_filename}")
+    
+    # Return with EXACT filename for stats tools to use
+    return f"SUCCESS: Found {mask_count} '{text_prompt}' objects. MASK_FILE={data_filename} PLOT_FILE={plot_filename}"
+
+
+def _filter_results(results, keep_indices):
+    """Helper to slice all dictionary keys at once."""
+    results["masks"] = results["masks"][keep_indices]
+    results["scores"] = results["scores"][keep_indices]
+    results["boxes"] = results["boxes"][keep_indices]
+    return results
+
+
+def _save_plot(image, results, boxes, label, filename):
+    """Save visualization of segmentation results."""
+    fig, ax = plt.subplots(figsize=(10, 10))
+    ax.imshow(image)
+
+    for mask, score in zip(results['masks'], results['scores']):
+        if score > 0.3:
+            mask_np = mask.cpu().numpy()
+            color = np.concatenate([np.random.random(3), np.array([0.5])], axis=0)
+            h, w = mask_np.shape[-2:]
+            ax.imshow(mask_np.reshape(h, w, 1) * color.reshape(1, 1, -1))
+
+    ax.set_title(f"{label}")
+    ax.axis('off')
+    fig.savefig(filename)
+    plt.close(fig)

cellemetry/tools/__init__.py

@@ -0,0 +1,25 @@
+"""
+Tools package for bio_agent.
+Exports categorized tool collections.
+"""
+from .segmentation import apply_sam3_tool
+from .statistics import get_basic_stats, get_spatial_stats, get_relationship_stats
+from .export import save_excel_tool
+
+# All tools used by the analyst agent
+ANALYST_TOOLS = [
+    apply_sam3_tool,
+    get_basic_stats,
+    get_spatial_stats,
+    get_relationship_stats,
+    save_excel_tool,
+]
+
+__all__ = [
+    "ANALYST_TOOLS",
+    "apply_sam3_tool",
+    "get_basic_stats",
+    "get_spatial_stats",
+    "get_relationship_stats",
+    "save_excel_tool",
+]

cellemetry/tools/export.py

@@ -0,0 +1,35 @@
+"""
+Data export tools (Excel, CSV, etc.).
+"""
+from typing import Optional
+from google.adk.tools.tool_context import ToolContext
+
+from ..services import analysis
+
+
+def save_excel_tool(
+    filename: str,
+    cell_stats: Optional[dict] = None,
+    nuc_stats: Optional[dict] = None,
+    spatial_stats: Optional[dict] = None,
+    rel_stats: Optional[dict] = None,
+    tool_context: ToolContext = None
+) -> dict:
+    """
+    Save all statistics to a multi-sheet Excel file.
+    
+    Args:
+        filename: Base filename for the output Excel file
+        cell_stats: Optional cell morphology stats
+        nuc_stats: Optional nuclei morphology stats
+        spatial_stats: Optional spatial distribution stats
+        rel_stats: Optional relationship stats
+        tool_context: Automatically injected by ADK
+    
+    Returns:
+        dict with the output filepath
+    """
+    result = analysis.save_stats_to_excel(
+        filename, cell_stats, nuc_stats, spatial_stats, rel_stats
+    )
+    return {"excel_path": result}

cellemetry/tools/segmentation.py

@@ -0,0 +1,99 @@
+"""
+Segmentation tools using SAM3.
+"""
+from typing import Optional, Union, List
+from google.adk.tools.tool_context import ToolContext
+
+from ..config.dependencies import get_deps_from_state
+from ..config.schemas import ComponentRequest, BoundingBox
+from ..services import sam
+
+
+def apply_sam3_tool(
+    entity: str,
+    color: str,
+    morphology: str,
+    bboxes: List[BoundingBox],
+    tool_context: ToolContext
+) -> dict:
+    """
+    Segment biological components using SAM3.
+    
+    Args:
+        entity: Object name (e.g., 'cell', 'nucleus') - use SINGULAR form
+        color: Color adjective (e.g., 'green', 'blue')
+        morphology: Shape adjective (e.g., 'irregular', 'round')
+        bboxes: Bounding boxes in one of these formats:
+                - List of dicts: [{"ymin": 0, "xmin": 0, "ymax": 100, "xmax": 100}, ...]
+                - List of lists: [[ymin, xmin, ymax, xmax], ...]
+                Values should be 0-1000 normalized coordinates.
+        tool_context: Automatically injected by ADK
+    
+    Returns:
+        dict with:
+        - result: Description of segmentation outcome
+        - mask_file: EXACT path to the .npz file containing masks
+        - plot_file: Path to visualization image
+        - count: Number of objects found
+    """
+    deps = get_deps_from_state(tool_context.state)
+    
+    # Convert bboxes to BoundingBox objects, handling multiple formats
+    bbox_objects = []
+    for b in bboxes:
+        if isinstance(b, dict):
+            # Format: {"ymin": 0, "xmin": 0, "ymax": 100, "xmax": 100}
+            bbox_objects.append(BoundingBox(**b))
+        elif isinstance(b, (list, tuple)):
+            # Format: [ymin, xmin, ymax, xmax] or [xmin, ymin, xmax, ymax]
+            if len(b) == 4:
+                # Assume [ymin, xmin, ymax, xmax] based on schema order
+                bbox_objects.append(BoundingBox(
+                    ymin=int(b[0]),
+                    xmin=int(b[1]),
+                    ymax=int(b[2]),
+                    xmax=int(b[3])
+                ))
+            else:
+                print(f"[Warning] Skipping invalid bbox: {b}")
+        else:
+            print(f"[Warning] Skipping unrecognized bbox format: {b}")
+    
+    if not bbox_objects:
+        return {
+            "result": "ERROR: No valid bounding boxes provided",
+            "mask_file": None,
+            "plot_file": None,
+            "count": 0,
+            "label": f"{color} {morphology} {entity}"
+        }
+    
+    request = ComponentRequest(
+        entity=entity,
+        color=color,
+        morphology=morphology,
+        bboxes=bbox_objects
+    )
+    
+    result_str = sam.execute_segmentation(deps, request)
+    
+    # Generate consistent filenames
+    safe_label = f"{color}_{entity}".replace(" ", "_").lower()
+    mask_file = f"/tmp/data_{safe_label}.npz"
+    plot_file = f"/tmp/out_{safe_label}.png"
+    
+    # Try to extract count from result
+    count = 0
+    if "Found" in result_str:
+        try:
+            count = int(result_str.split("Found")[1].split()[0])
+        except:
+            pass
+    
+    return {
+        "result": result_str,
+        "mask_file": mask_file,  # <-- USE THIS EXACT PATH for get_basic_stats, get_spatial_stats
+        "plot_file": plot_file,
+        "count": count,
+        "label": f"{color} {morphology} {entity}"
+    }

cellemetry/tools/statistics.py

@@ -0,0 +1,61 @@
+"""
+Statistical analysis tools for morphology and spatial metrics.
+"""
+from google.adk.tools.tool_context import ToolContext
+
+from ..services import analysis
+
+
+def get_basic_stats(
+    filename: str,
+    tool_context: ToolContext
+) -> dict:
+    """
+    Calculate basic morphology stats (count, area mean/std).
+    
+    Args:
+        filename: Path to the .npz mask file
+        tool_context: Automatically injected by ADK
+    
+    Returns:
+        dict with count, area_mean, area_std, unit
+    """
+    pixel_scale = tool_context.state.get("app:pixel_size_microns")
+    return analysis.get_basic_stats(filename, pixel_scale=pixel_scale)
+
+
+def get_spatial_stats(
+    filename: str,
+    tool_context: ToolContext
+) -> dict:
+    """
+    Calculate spatial distribution stats (NND, density, neighbor count).
+    
+    Args:
+        filename: Path to the .npz mask file
+        tool_context: Automatically injected by ADK
+    
+    Returns:
+        dict with spatial metrics
+    """
+    pixel_scale = tool_context.state.get("app:pixel_size_microns")
+    return analysis.get_spatial_stats(filename, pixel_scale=pixel_scale)
+
+
+def get_relationship_stats(
+    cell_file: str,
+    nuc_file: str,
+    tool_context: ToolContext
+) -> dict:
+    """
+    Analyze cell-nucleus relationships (overlap ratios).
+    
+    Args:
+        cell_file: Path to cell masks .npz
+        nuc_file: Path to nucleus masks .npz
+        tool_context: Automatically injected by ADK
+    
+    Returns:
+        dict with matched_pairs, avg_ratio, std_ratio
+    """
+    return analysis.analyze_relationships(cell_file, nuc_file)