feat: add Flow Cytometry Referee agent

agents/flow-cytometry-referee/README.md

@@ -0,0 +1,66 @@
+# Flow Cytometry Referee
+
+Flow Cytometry Referee reviews standard FCS flow-cytometry files and supporting analysis material for technical
+quality and reproducibility. It reports observed measurement and metadata evidence, missing controls, and gating
+documentation gaps. It is designed for research QC and is not a clinical, diagnostic, regulatory, or assay-validation tool.
+
+## Overview
+
+Researchers often receive event files, a gating figure, and partial panel documentation from different systems. This
+agent makes the technical review explicit: it inventories evidence, measures file-level QC facts, and identifies what
+must be supplied before a gating workflow can be considered reproducible.
+
+## Architecture
+
+The prompt agent uses a parameterized Foundry chat model and the `flow-qc` Python environment. The environment reads
+FCS events with `flowio`, calculates deterministic channel and acquisition summaries, validates the shape and channel
+names of a stored spillover matrix when present, and can calculate an optional exploratory Isolation Forest outlier
+fraction. The agent combines those results with supplied SOPs, gating plans, and control inventories. The outlier
+score flags unusual measurement events only; it does not classify cells or samples or establish a QC threshold.
+
+## Prerequisites
+
+- An Azure subscription with Microsoft Discovery deployment permissions.
+- An Azure AI Foundry project and a chat-model deployment for `{{CHAT-MODEL}}`.
+- A container image built from `tools/flow-qc/Dockerfile` and published to the deployment ACR.
+- Standard FCS files and, for a complete review, the acquisition template, panel specification, gating plan, and
+  single-stain, FMO, viability, and relevant biological controls.
+
+## Configuration
+
+| Parameter | Description | Example |
+| --- | --- | --- |
+| `{{CHAT-MODEL}}` | Foundry chat-model deployment | `gpt-4o-deployment` |
+| `{{flowQcToolId}}` | Deployed Discovery tool ARM resource ID | `/subscriptions/.../tools/flow-qc` |
+
+## Usage
+
+1. Deploy the agent and the `flow-qc` tool through Discovery.
+2. Supply one or more FCS files and the available supporting documents.
+3. Ask for a technical review, for example: “Review this FCS file and gating plan for compensation evidence, control
+   coverage, acquisition integrity, and reproducibility gaps.”
+4. Review PASS, WARN, NEEDS EVIDENCE, and FAIL findings with a qualified flow-cytometry scientist.
+
+## Tools
+
+`flow-qc` provides a Python code environment with `flowio`, NumPy, pandas, scikit-learn, and `flow_qc_utils`.
+It can read standard FCS files, summarize event and channel values, inspect and validate stored compensation-related
+metadata, evaluate acquisition-time continuity, calculate an exploratory event-outlier fraction, and create a
+technical QC dashboard. A declared-range-limit fraction is a measurement-range check, not proof of detector
+saturation. Derived reports belong in the configured output directory.
+
+## Known Limitations
+
+- It does not inspect microscopy images or imaging flow-cytometry imagery.
+- It cannot prove compensation is correct from FCS metadata alone.
+- It does not create, validate, or optimize gates without a documented gating plan and appropriate controls.
+- It must not be used for diagnosis, treatment, patient triage, or regulatory release decisions.
+- The unsupervised outlier metric is sensitive to panel design and batch effects and is not a trained classifier.
+
+## Support
+
+For issues or questions, open an issue at https://github.com/AzizMuminov/discovery/issues.
+
+## Contributing
+
+See [CONTRIBUTING.md](../../CONTRIBUTING.md) for the catalog contribution workflow.

agents/flow-cytometry-referee/agent.yaml

@@ -0,0 +1,70 @@
+kind: prompt
+name: FlowCytometryReferee
+displayName: Flow Cytometry Referee
+description: >
+  An evidence-based technical reviewer for FCS quality, compensation, controls, and proposed gating plans.
+model:
+  id: '{{CHAT-MODEL}}'
+  options:
+    temperature: 0
+    maxOutputTokens: 4096
+instructions: |
+  You are the Flow Cytometry Referee, a technical quality-control agent for research flow-cytometry analysis.
+
+  Your job is to evaluate the reproducibility and technical adequacy of an FCS dataset and, when supplied, a
+  gating plan, panel description, control inventory, or laboratory SOP. You do not diagnose disease, classify
+  patients, recommend treatment, or claim that a dataset is biologically valid. Your findings concern only the
+  supplied data and documented analysis process.
+
+  ## Operating rules
+  - Invoke only one tool at a time and wait for its result before the next tool call.
+  - For every FCS file, run the flow-qc Python environment before drawing conclusions about event count,
+    channels, compensation metadata, non-finite values, saturation, time ordering, or outlier score.
+  - Treat a missing document, control, or metadata field as missing evidence, never as proof of an error.
+  - Do not infer cell type, disease state, treatment effect, or sample identity from fluorescence values.
+  - Do not use the exploratory unsupervised outlier score as a classifier or a validated QC threshold. It identifies
+    unusual measurement events only.
+  - State panel- and instrument-specific assumptions explicitly. Ask for the acquisition template, gating plan,
+    and single-stain/FMO controls when their absence prevents a reliable review.
+
+  ## Review sequence
+  1. Inventory the supplied FCS files and supporting material.
+  2. Run a QC script with flow_qc_utils.load_fcs and flow_qc_utils.build_qc_report.
+  3. Compare available evidence with this minimum technical checklist:
+     - event count and acquisition-time integrity;
+     - compensation or spillover metadata and single-stain controls;
+     - viability, singlet, debris, and relevant fluorescence-minus-one controls;
+     - documented gate order, parent populations, thresholds, and counts;
+     - transformations, exclusions, and batch/sample identifiers;
+     - reproducible output files and analysis software/version.
+  4. Return findings grouped as PASS, WARN, NEEDS EVIDENCE, or FAIL. Use FAIL only for a directly observed,
+     technically invalid condition such as an unreadable FCS file, no events, or non-finite event values that
+     make the requested analysis impossible.
+  5. Produce a concise remediation plan ordered by impact. Preserve the original data; write any derived JSON,
+     CSV, and figures to the output directory. When FCS event data is available, create a technical QC dashboard
+     with scatter, fluorescence-distribution, acquisition-time, and declared-range-limit panels through
+     `write_qc_artifacts`.
+
+  ## Dashboard presentation
+  - Inspect the generated dashboard through the host's image viewer before finalizing the review.
+  - Treat dashboard, CSV, and JSON files as tool artifacts. Do not write Markdown image tags, `file:` URLs,
+    workspace-relative links, or guessed artifact paths: VS Code does not reliably resolve them in chat responses.
+  - If the host displays the dashboard as native image content, refer to that attached dashboard under a short
+    `## Dashboard` heading. Otherwise, report the artifact names without inventing a link.
+
+  ## Required response format
+  - Scope and supplied evidence
+  - QC metrics observed from the FCS file
+  - Findings, each with severity, evidence, and remediation
+  - Missing evidence and the exact document or control needed
+  - Reproducibility checklist
+  - Limitations
+
+  Never present this report as clinical, regulatory, or diagnostic validation.
+discoveryExtensions:
+  humanInTheLoop: Disabled
+  tools:
+    - toolId: '{{flowQcToolId}}'
+      confirmation: Disabled
+  disableDataHandlingTools: false
+  disableDiscoveryInjectedTools: false

agents/flow-cytometry-referee/metadata.yaml

@@ -0,0 +1,19 @@
+name: flow-cytometry-referee
+type: agent
+version: 1.0.0
+associated_tools:
+  - agents/flow-cytometry-referee/tools/flow-qc
+publisher:
+  name: Aziz Muminov
+  contact: azizbekmuminov52@gmail.com
+  support_url: https://github.com/AzizMuminov/discovery/issues
+  party: 3p
+description: >
+  Reviews flow-cytometry FCS data and proposed gating plans for technical quality, compensation evidence,
+  control coverage, and reproducibility. Produces an evidence-backed QC report; it does not diagnose disease
+  or make clinical decisions.
+tags:
+  - single-cell
+  - bioinformatics
+  - biomedical
+  - data-analysis

agents/flow-cytometry-referee/tools/flow-qc/Dockerfile

@@ -0,0 +1,36 @@
+FROM mcr.microsoft.com/azurelinux/base/python:3.12
+
+ENV PYTHONUNBUFFERED=1
+ENV PYTHONDONTWRITEBYTECODE=1
+ENV MPLBACKEND=Agg
+ENV MPLCONFIGDIR=/tmp/matplotlib
+ENV OMP_NUM_THREADS=1
+ENV MKL_NUM_THREADS=1
+ENV OPENBLAS_NUM_THREADS=1
+
+RUN tdnf -y update && \
+    tdnf -y install ca-certificates shadow-utils && \
+    update-ca-trust && \
+    tdnf clean all
+
+RUN pip3 install --no-cache-dir \
+    flowio \
+    matplotlib \
+    numpy \
+    pandas \
+    scikit-learn \
+    scipy
+
+RUN mkdir -p /app /workdir /input /output /tmp/matplotlib && \
+    chmod 755 /app /workdir /input /output
+
+COPY flow_qc_utils.py /app/flow_qc_utils.py
+
+RUN groupadd -r appuser && useradd -r -g appuser appuser && \
+    chown -R appuser:appuser /app /workdir /input /output /tmp/matplotlib
+
+USER appuser
+WORKDIR /workdir
+ENV PYTHONPATH=/app
+
+CMD ["/bin/bash"]