cellemetry/agents/analyst.py

"""
Analyst Agent - Expert microscopy image analyst.
Segments biological components and computes statistics.
"""
from google.adk.agents import LlmAgent
from google.adk.models.google_llm import Gemini
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. cells) in the image.

**Step 3: Define Tool Inputs**
Decompose each structure into three words that accurately represent it:
- `color`: ONE adjective (e.g., "pink", "purple", "green", "orange", ...) 
- `morphology`: ONE adjective (e.g., "irregular")
- `entity`: ONE noun (e.g., "cell" - singular!)
Make sure that the color, morphology, and entity accurately match whichever object of interest that you are measuring. 

**Step 4: Box Selection**
Select 1-10 representative bounding boxes per structure (0-1000 normalized).
**IMPORTANT**
- Choose only boxes that cover the full object(s) of interest
- Whenever possible, choose isolated objects that are not cut off by the edges of the image
- Whenever possible, avoid clustered objects; instead, make sure that the bounding box only includes the object of interest. 

**Step 5: Segmentation 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 preserve this EXACT filename.
Keep the filenames for the next step. 

**Step 7: Quantification (Unified)**
Once you have segmentations for all structures, call `compute_comprehensive_stats` **ONCE**.
- If you found cells, pass the cell mask file as `cell_file="/tmp/data_..."`
- If you found nuclei, pass the nuclei mask file as `nuc_file="/tmp/data_..."`
- If you found both, pass both arguments.

**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",
    description = "Expert microscopy analyst for localizing and quantifying biological structures",
    model = Gemini(
        model="gemini-3-flash-preview", 
        media_resolution="high"
    ),
    instruction = ANALYST_INSTRUCTION,
    tools = ANALYST_TOOLS,
    output_key = "analyst_result",
)