# Hunter-Seeker

> Governed predictive top-k engine. Give it any table with a yes/no outcome column and it ranks the rows by likelihood of that outcome — with calibrated scores, top-decile lift, counterfactual levers, a provenance hash on every response, and a structured honest "no" when the signal isn't there. Built for decisions that must survive an audit: byte-identical replay, leak-guard, and SR 26-2 / EU-AI-Act-shaped governance export. The engine owns every fact; nothing above it may author or alter a number.

Agents connect over MCP; applications call the REST API. Both front the product layer only — the engine is never exposed. Identical inputs return byte-identical envelopes carrying `engine_version` + `core_hash`.

## For AI agents (MCP)

- [MCP endpoint](https://hunter-seeker.net/api/mcp): Remote MCP server over Streamable HTTP, OAuth 2.1.
- [MCP server card](https://hunter-seeker.net/.well-known/mcp.json): Machine-readable tool list, transport, endpoint, and trust contract.
- [For AI agents](https://hunter-seeker.net/for-agents): Connect snippets (Claude, Cursor, VS Code, LangChain, CrewAI), the eight-tool catalog, and the trust contract on the wire.
- [AGENTS.md](https://hunter-seeker.net/AGENTS.md): How to connect and invoke the tools, with the honest-empty and honest-null contracts.

## Tools

- `hs_describe_capabilities`: Input contract, problem shapes, trust guarantees, and worked multi-domain examples. Call first when unsure.
- `hs_provide_dataset`: Register data past the inline cap (~4.4 MB of JSON; at most 2,000 rows / 64 columns) via a direct-to-storage PUT (the default — no size or row cap, ~1M rows is routine) or a guarded https fetch; `direct_upload: false` falls back to the ~4.5 MB proxied upload.
- `hs_rank_topk`: Rank rows by likelihood of a yes/no outcome; returns top-k entities with calibrated scores, tiers, and the trust contract. Honest-empty below a validated lift of 1.5. Its `data` takes **exactly one** of five sources: `rows` (inline JSON, synchronous) | `csv` (inline CSV text, synchronous) | `fetch_url` (a public https URL the server fetches + ranks in one async call) | `dataset_id` (a registered dataset, async) | `direct_upload: true` (returns an upload_url + dataset_id, no run starts — PUT your CSV, then call again with the dataset_id). Inline is capped ~4.4 MB / 2,000 rows / 64 columns, but your client's tool-payload budget (Claude Code ~25k tokens, Claude Desktop ~150k chars) usually binds first, so keep inline to a few hundred rows and route anything larger to fetch_url / dataset_id / direct_upload. Any async mode accepts an `idempotency_key` so a retried submission returns the same task, never a duplicate; async pending responses may carry a signed `status_url` — a short-TTL live status page (SSE) a human can open to watch leak-firewalled staged progress.
- `hs_poll_task`: Poll a long-running ranking started from a `dataset_id` or `fetch_url`; its only parameter is `task_id`. Pending responses may include a `stage` + append-only `facts_so_far` (leak-firewalled progress, never a partial ranking) and the optional live `status_url`.
- `hs_explain_levers`: For already-ranked entities, the minimal feature changes associated with leaving the risk pattern (association, not causation).
- `hs_explain_drivers`: For a prior ranking (its `ranking_ref`), THE PATTERN the engine found — a combination of conditions (feature + direction + the threshold where it turns) that together predict the outcome, plus its exact coverage and lift. Reuses the analysis, no re-run. association_not_causal.
- `hs_model_quality`: For a prior ranking (its `ranking_ref`), the model diagnostics — top-decile lift, calibration error, out-of-time/holdout validation, a relative lift curve, and leak_guard. Validation statistics only, no method internals.
- `hs_context_brief`: For a prior ranking (its `ranking_ref`), a portable brief you can drop into another agent's context: provenance, outcome, trust, and the driver group as one combination. `format: markdown` for prose. Free reuse — no engine run.

## Docs

- [Docs](https://hunter-seeker.net/docs): Quickstart, MCP server, REST API, model quality, governance export, honest-empty, security.
- [OpenAPI](https://hunter-seeker.net/docs/openapi.json): Full schema for the product REST API (`/api/v1`).
- [Benchmarks](https://hunter-seeker.net/benchmarks): The Analyst Test — reproducible, seed-pinned, verifier-checked.
- [Governance](https://hunter-seeker.net/governance): The per-run audit bundle and compliance posture.

## Notes

- Provenance: every response carries `{engine_version, core_hash}`. Current pin: engine `0.2.2`, core `4d24e9fc…`.
- Honest-null: `top_decile_lift`, `validation`, `leak_guard`, and ranking-level `top_factors` are populated by the model-quality engine (live as of engine `0.1.1`) on a cleared finding, and returned as `null` on a non-finding — never fabricated. A `null` means no finding, not pending or zero.
- Honest-empty: below the published lift ≥ 1.5 bar, you get `{result:"none", reasons[], gate_verdicts[], retry:"unproductive"}` — a terminal result, not an error. Do not retry; relay the reasons or improve the input.
- Regulated use: person-level outcomes in regulated domains (hiring, credit, education, insurance, benefits, justice, healthcare (e.g. readmission, triage, diagnosis), immigration (visa, asylum)) require `acknowledge_decision_support: true` and are decision-support only. Social-scoring, emotion-recognition, biometric-categorization, and predictive-policing framings are refused with no acknowledgment path.
- Everything under /docs is mirrored in markdown — append `.md` to a URL or send `Accept: text/markdown`.