# 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.io/api/mcp): Remote MCP server over Streamable HTTP, OAuth 2.1. - [MCP server card](https://hunter-seeker.io/.well-known/mcp.json): Machine-readable tool list, transport, endpoint, and trust contract. - [For AI agents](https://hunter-seeker.io/for-agents): Per-client connect snippets and their quirks, the tool catalog, the free sample datasets, and the trust contract on the wire. - [llms-full.txt](https://hunter-seeker.io/llms-full.txt): Every tool's FULL description, verbatim as your client receives it. - [AGENTS.md](https://hunter-seeker.io/AGENTS.md): How to connect and invoke the tools, with the honest-empty and honest-null contracts. ## What you can give it The engine ranks ONE binary outcome per entity. A `reading` tells it what shape your data is in and reduces it to one leak-safe row per entity as of a cutoff — you supply the outcome, or a reading derives it from your events; the engine never guesses which token means the outcome occurred. Free text in any column is engineered into signals on every run. | `reading.kind` | what you hand it, and what comes back | |---|---| | `as-is@1` | a row per entity already — no reduction, and no cost to saying so | | `sequential@1` | an event log → per-entity counts, tenure, top event types and transitions | | `trace@1` | agent/job runs → each run gains its prior failure rate over STRICTLY EARLIER runs | | `windowed@1` | a metric history → trailing-window aggregates, row count preserved | | `panel@1` | entity × period → the outcome DERIVED by the engine, from a future window or a trend | | `stream@1` | a sensor stream + fault intervals → snapshots with trailing aggregates | Every kind states its own required roles (`—`, `identifier + time_axis`, `identifier + time_axis + outcome`, `identifier + time_axis + numeric_metric`, `identifier + time_axis`, `identifier + time_axis + signals` respectively) and its param bounds; `hs_describe_capabilities` publishes all of them, so a caller constructs a valid `reading` without guessing. ## Tools 15 tools. One costs a run; the rest are free or per-decision — each line says which. - `hs_describe_capabilities` — Describe capabilities. Free; no engine run. - `hs_provide_dataset` — Provide dataset. Free; no engine run. - `hs_rank_topk` — Rank top-k by outcome likelihood. Costs ONE RUN from quota — the only tool that does. - `hs_poll_task` — Poll ranking task. Free to call; the run it polls is the billable one. - `hs_explain_levers` — Explain counterfactual levers. Free; no engine run. - `hs_explain_drivers` — Explain outcome drivers. Free; no engine run. - `hs_model_quality` — Model quality diagnostics. Free; no engine run. - `hs_context_brief` — Portable context brief. Free; no engine run. - `hs_score_entity` — Score one entity at decision time. Costs ONE DECISION from your quota (never a run). - `hs_score_batch` — Score many rows against one scorecard. Costs ONE DECISION PER ROW that is not refused. - `hs_verify_verdict` — Verify a Verdict's signature. Free; no engine run. - `hs_report_outcome` — Report observed outcomes. Free; writes YOUR observed outcomes (never fires an action, never retrains). - `hs_attest_action` — Attest that a lever was pulled. Free; records that you acted on a lever. - `hs_action_evidence` — Did acting on this pattern work? Free; no engine run. - `hs_drift_status` — Has the pattern moved? Free; no engine run. ## Free samples 6 free sample datasets. They cost nothing, they are synthetic, and they clear the bar — so an agent can see a real result before asking anyone for real data. - `sample:saas_churn` — 800 synthetic SaaS accounts with tenure, support tickets, logins, plan and seats. Which accounts are most likely to churn? `outcome_column: "churned"`, `entity_column: "customer_id"`, `subject_kind: "org"`, `outcome_is_desirable: false` · 800 rows · **synthetic** · free — a sample run never takes a reserve from your quota. Clears at lift 4.4776, top-decile lift 4.444444. - `sample:b2b_leads` — 800 synthetic B2B leads with pages viewed, demo requests, company size and touch latency. Which leads are most likely to convert? `outcome_column: "converted"`, `entity_column: "lead_id"`, `subject_kind: "org"`, `outcome_is_desirable: true` · 800 rows · **synthetic** · free — a sample run never takes a reserve from your quota. Clears at lift 7.3469, top-decile lift 5.263158. - `sample:telco_churn` — 800 synthetic telecom accounts with contract type, tech support, tenure and charges. Which accounts are most likely to churn? `outcome_column: "churned"`, `entity_column: "account_id"`, `subject_kind: "org"`, `outcome_is_desirable: false` · 800 rows · **synthetic** · free — a sample run never takes a reserve from your quota. Clears at lift 3.9216, top-decile lift 6.190476. - `sample:agent_traces` — 800 synthetic AI-agent runs (agent, task, tool, 0/1 failed) with a tool that degrades mid-window. Built for reading {kind: "trace", version: 1} — ranked raw it returns an honest non-finding; reduced, the per-group prior failure rates clear high-tier. Which runs are most likely to fail? `outcome_column: "failed"`, `entity_column: "run_id"`, `subject_kind: "event"`, `outcome_is_desirable: false` · 800 rows · **synthetic** · free — a sample run never takes a reserve from your quota. Ranked RAW this one is an honest non-finding, on purpose. Pass `reading: {"kind":"trace","version":1,"roles":{"identifier":"run_id","time_axis":"ts","outcome":"failed","agent":"agent","task":"task","tool":"tool"}}` and it clears at lift 4.1026, top-decile lift 4.285714. - `sample:usage_panel` — 9,600 rows: 800 synthetic SaaS accounts observed over 12 monthly periods, with usage, logins, feature adoption, support tickets and seats. The `usage_declining` column is a noisy per-period self-report and ranks to nothing on its own. Built for reading {kind: "panel", version: 1} with a `trend` label — the engine derives the real declining/not label from the shape of `usage` and clears. Which accounts are on their way out? `outcome_column: "usage_declining"`, `entity_column: "account_id"`, `subject_kind: "org"`, `outcome_is_desirable: false` · 9600 rows · **synthetic** · free — a sample run never takes a reserve from your quota. Ranked RAW this one is an honest non-finding, on purpose. Pass `reading: {"kind":"panel","version":1,"roles":{"identifier":"account_id","time_axis":"period"},"params":{"label_horizon":1,"label_agg":"max","min_observation":5,"trend_direction":"down","trend_alpha":0.1,"cutoff_rule":"last_minus_label","label":{"kind":"trend","column":"usage"}}}` and it clears at lift 2.5478, top-decile lift 2.539683. - `sample:sensor_stream` — 4,815 rows: four signals from 40 synthetic machines every six hours for 30 days, with the fault intervals in the same table (a row with an `event_type` is an interval, not a reading). The `maintenance_due` flag is noise and ranks to nothing. Built for reading {kind: "stream", version: 1} — reduced to daily snapshots with trailing window aggregates it clears high-tier. Which machines are about to fail? `outcome_column: "maintenance_due"`, `entity_column: "asset_id"`, `subject_kind: "object"`, `outcome_is_desirable: false` · 4815 rows · **synthetic** · free — a sample run never takes a reserve from your quota. Ranked RAW this one is an honest non-finding, on purpose. Pass `reading: {"kind":"stream","version":1,"roles":{"identifier":"asset_id","time_axis":"ts","signals":["vibration","temp_c","pressure_psi","current_a"],"event_type":"event_type","event_start":"event_start","event_end":"event_end","label_column":"maintenance_due"},"params":{"snapshot_period":"1d","windows":[1,3,7],"horizon":3,"min_observation":3}}` and it clears at lift 3.2448, top-decile lift 7.518539. ## Docs - [Docs](https://hunter-seeker.io/docs): Quickstart, MCP server, REST API, model quality, governance export, honest-empty, security. - [OpenAPI](https://hunter-seeker.io/docs/openapi.json): Full schema for the product REST API (`/api/v1`). - [Benchmarks](https://hunter-seeker.io/benchmarks): The Analyst Test — reproducible, seed-pinned, verifier-checked. - [Governance](https://hunter-seeker.io/governance): The per-run audit bundle and compliance posture. ## Notes - **Engine pin.** Every response carries `{engine_version, core_hash}`. Current: engine `0.3.5`, core `4d24e9fc…`. - **Reading contract.** A SEPARATE identity axis from the engine pin — it moves when the reading kinds change, which `core_hash` cannot see, so pin whichever you actually depend on. Current: `40498adb…`, grammar version 3. - 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. - Markdown mirror: every page under `## Optional` below is served both as HTML and as markdown — append `.md` to the URL, or send `Accept: text/markdown`. The same bytes either way. (The marketing pages at /docs, /governance and /benchmarks are HTML only; this line used to claim otherwise and nothing implemented it.) ## Optional - [The two loops](https://hunter-seeker.io/docs/two-loops): Loop A self-governs one decision (rank → quality → band → verify); Loop B asks whether acting changed anything (attest → report → evidence → drift). Every mechanism mapped to its established name, with citations. - [Refusal is a result](https://hunter-seeker.io/docs/refusal-is-a-result): What `{result:"none"}` and a `null` statistic each mean, why the run is refunded, and why retrying the same data is the mistake. - [How it's different](https://hunter-seeker.io/docs/how-its-different): Dated comparison against LLM-as-judge eval tools, guardrails, AutoML and agent memory — including where each of them is better. - [The randomized control arm](https://hunter-seeker.io/docs/control-arm): How to hold out a random slice of the acted cohort, and why `hs_action_evidence` is observational until you do. - [Status: served vs planned](https://hunter-seeker.io/docs/status): Served, specified-but-unserved, and proposed — rendered from the registry, never typed. - [Tool reference](https://hunter-seeker.io/docs/tools): Every served tool's full description, verbatim as your client receives it. - [Worked example — agentic GTM](https://hunter-seeker.io/docs/examples/agentic-gtm): Observe, Decide, Act, Learn across six outcomes and four agents. Runnable on the free samples; band gates in LangGraph and n8n. - [Worked example — self-improving agents](https://hunter-seeker.io/docs/examples/self-improving-agents): The same 800 agent-run traces answered twice — an honest non-finding raw, a cleared ranking once reduced by `trace@1`. Runnable, free.