Hy3 MitoScope

Hy3 MitoScope is a lightweight, auditable research agent for microscopy TIFF analysis and evidence-bound multi-document scientific question answering. It is prepared for Tencent Rhino Bird 2026 Hy3 Issue #4.

Hy3's role

Hy3 is the repository's only external generative model. Every workflow uses the OpenAI-compatible Hy3 API for:

• research planning;
• function/tool calls;
• adaptive subgoal-DAG planning and evidence sufficiency checks;
• scientific synthesis with citation IDs;
• report writing;
• post-generation self-reflection.

Local deterministic code reads TIFF pixels, segments structures, computes morphology metrics, summarizes an optional precomputed FLIM lifetime-map channel, parses PDFs, retrieves passages, and writes artifacts. It does not train, fine-tune, or locally deploy Hy3. The server never sends the Hy3 API key to the browser. TIFF calibration and channel semantics are bound from trusted local metadata rather than model arguments. A final allowlist rejects unknown citations and rounded or derived numbers that are absent from structured facts.

Run

Requirements: Python 3.10+.

cp .env.example .env
# Fill HY3_API_KEY and HY3_BASE_URL. Keep HY3_MODEL=hy3 unless instructed otherwise.
chmod +x run.sh
./run.sh

Open http://127.0.0.1:8765.

Docker is also supported:

cp .env.example .env
docker compose up --build

End-to-end demos

Microscopy: load or upload a TIFF, then run:

Hy3 plan -> Hy3 analyze_microscopy tool call -> local Otsu segmentation + precomputed FLIM-map statistics -> metrics -> reviewed references -> Hy3 report -> Hy3 self-reflection

Papers: upload two or more PDF/TXT documents, then run:

Hy3 subgoal DAG -> local DAG validation -> adaptive 1/2-hop private search -> passage-level evidence checks -> at most one repair round -> cited Hy3 answer -> Hy3 self-reflection

The paper workflow permits at most three subgoals and two dependency levels. Simple fact questions remain single-hop. A dependent subgoal is blocked when its parent lacks evidence, and completed subgoals must bind exact passage IDs such as [D1:C0]. Knowledge-graph edges may expand a search query but are not treated as final evidence by themselves. See docs/ADAPTIVE_MULTIHOP_ZH.md.

The bundled demo files are synthetic, deterministic, and contain no patient, laboratory, unpublished, or private project data. See docs/DEMO_SCRIPT.md for the recording sequence. The committed 69-second demo video replays sanitized frames from real API responses; its second workflow also shows a subgoal remaining unsupported after the single allowed repair. The demo TIFF labels channel 0 as mitochondrial intensity and channel 1 as a synthetic lifetime map stored in picoseconds. Hy3 MitoScope does not fit raw TCSPC decays; uploaded lifetime maps must already be calibrated. Submission status is tracked in docs/RELEASE_CHECKLIST.md. Both workflows were also run against the real Hy3 activity API on 2026-07-29; see the sanitized live validation record.

Verify

.venv/bin/python -m pytest
.venv/bin/python scripts/check_hy3_only.py

The source audit rejects references to non-Hy3 model providers under app/ and demo/.

The current automated suite contains 27 tests. It covers adaptive hop limits, cycle/depth fallback, fabricated citation rejection, one-round repair, blocked dependencies, guest isolation, trusted TIFF metadata, tool-argument sanitization, cross-language recall fallback, numeric grounding, deterministic microscopy metrics, and the Hy3 request contract.

Configuration

Variable	Purpose
HY3_API_KEY	Activity API credential
HY3_BASE_URL	OpenAI-compatible activity endpoint
HY3_MODEL	Model ID, default hy3
DEMO_GUEST_ENABLED	Enables isolated in-memory guest sessions
MAX_UPLOAD_MB	Per-file upload cap, default 25 MB
HOST / PORT	Bind address and port

Uploaded data is isolated by a random HttpOnly guest-session cookie and stored under ignored var/sessions/. PDF excerpts are sent to Hy3 when extracting knowledge triples and composing answers, so do not upload sensitive material to an endpoint whose data policy you have not reviewed.

Attribution

AI-assisted work is recorded in docs/AI_ASSISTED_DEVELOPMENT.md. CodeBuddy / WorkBuddy work is currently marked not yet performed; no pre-existing code is mislabeled as its output. A real, separately evidenced CodeBuddy or WorkBuddy contribution remains required before the competition PR.

License

Apache-2.0. The three bibliographic records in demo/references.json are metadata links; no article text is redistributed.