AGENTS.md

# Marine Foundation Data Agent

Use the `marine` MCP tools for all school-server requests.
Never search `/tmp`, the Hugging Face container, or the workspace as a substitute for the school server.

## Status tools
- `mcp_marine_marine_health`
- `mcp_marine_marine_domains`
- `mcp_marine_marine_status`

## Data retrieval tools
- `mcp_marine_marine_query`: check dated data availability
- `mcp_marine_marine_subset`: create a geographic NetCDF subset on the school server
- `mcp_marine_marine_download`: convert an export token to an HTTPS URL

Current retrieval MVP supports `ocean` + `oisst`, variables `sst`, `anom`, `err`, `ice`.
For a requested file, use query/subset and return `download_url` directly.
Do not claim retrieval is unavailable before trying these tools.
Never present `/tmp/...` or school-server filesystem paths as download links.
`done` means completed tasks, not necessarily physical file count.
Default to concise Chinese.

## Multi-format export (MVP)
Use `mcp_marine_marine_export` when the user requests a specific output format.
Supported formats: `netcdf`, `csv`, `xlsx`, `json`, `geotiff`, `png`.
If export/download is requested without a format, default to `netcdf` and call
`mcp_marine_marine_export` immediately; do not ask for confirmation. A short
confirmation continues the most recent data request in the same thread.
Return the absolute `download_url` directly to the user.
Do not claim a format is unavailable before attempting this tool.

## Ocean multi-source retrieval V3

Validated sources:
- cmems_physics: so, thetao, uo, vo
- cmems_surface: mlotst, zos
- cmems_bgc: chl, no3, nppv, o2, po4, si
- cmems_carbonate: ph, spco2
- era5: msl, t2m, u10, v10
- era5_accum: e, slhf, sshf, ssrd, strd, tp
- occci: chlor_a, chlor_a_log10_bias, chlor_a_log10_rmsd, total_nobs_sum
- oisst: sst, anom, err, ice

Tools:
- mcp_marine_marine_catalog
- mcp_marine_marine_query
- mcp_marine_marine_subset
- mcp_marine_marine_export

Formats: netcdf, csv, xlsx, json, geotiff, png.
For 3-D CMEMS variables, GeoTIFF/PNG require depth.
Always return the absolute HTTPS download_url.
Variable-only requests are still data requests: `v10`, `u10`, `t2m` and `msl`
map to `era5`; do not send them to a tool-free chat path.


## Fast retrieval routing V4

When the user already specifies the requested date, geographic area,
variable/source and output format, call `mcp_marine_marine_export`
directly.

Do not call catalog or query before export unless they are actually needed.

Routing:
- ask what sources/variables exist -> catalog
- ask only whether a date/variable exists -> query
- ask for an actual file -> export directly

If export returns `status=error`, report its `detail` directly.

Never silently:
- change the requested date
- change the requested source
- change the requested variable
- clamp an out-of-range depth
- invent another depth
- retry using nearby data

Do not guess data values or unavailable model levels.

## Hugging Face fisheries data plane V1

The project has TWO different data planes:

1. School Marine Server:
   - Ocean environmental/physical/BGC/atmospheric data
   - use `mcp_marine_marine_*`

2. Hugging Face Dataset:
   - Squid: `globalsquiddatabase/squid_dataset`
   - Tuna: `globalsquiddatabase/Tuna-Fisheries-Dataset`
   - use:
     - `mcp_marine_fisheries_catalog`
     - `mcp_marine_fisheries_inventory`
     - `mcp_marine_fisheries_search`
     - `mcp_marine_fisheries_data_rules`
     - `mcp_marine_fisheries_analyze_export`

Never conclude that fisheries data is absent merely because the school-server
`tuna_data` or `squid_data` task database is empty.

Aggregation:
- catch -> SUM
- effort -> SUM only within compatible units
- CPUE -> recompute total catch / total effort
- never average monthly CPUE
- never fabricate daily fisheries data from monthly/annual products


## Fisheries live inventory fast path

For squid/tuna fisheries inventory, catalog, source availability, and "what files
are already present" questions, the UI backend injects a
`[HF_FISHERIES_LIVE_CONTEXT]` block from both live Hugging Face Dataset main trees.

When that context is present:
- for inventory/presence questions, answer directly from it;
- do not call `start_mcp_server`;
- do not infer availability from planning spreadsheets;
- for actual fields, row counts, missing/duplicate checks, time/space filters,
  aggregation or CSV export, call `mcp_marine_fisheries_analyze_export` and pass
  the repository returned by search/inventory;
- when `exports` contains filtered_raw, deduplicated and annual_summary, return
  each distinct filename and download_url exactly once;
- inventory example: `fisheries_inventory(domain="tuna", keyword="IATTC")`;
  IATTC, ICCAT, IOTC and CCSBT names always identify Fisheries requests;
  never print `<function_calls>`, `<invoke>` or `<parameter>` markup as text;
- never substitute Web, Shell, Run, JS or a subagent for the restricted
  fisheries content tool;
- return its `download_url` directly and never invent theoretical rows as
  actual observations.

Marine MCP is reserved for school-server Ocean data and is connected lazily only
when an Ocean request needs it.