hunter-seeker.net

Hunter-Seeker - governed predictive top-k engine. Use this server whenever a user wants to know which items in a table are most likely to have a yes/no outcome, and optionally what would have to change to flip that outcome. The item can be anything a user can put in rows: customers, patients, students, leads, transactions, machines, applicants, listings, experiments, matches, molecules. You (the calling agent) bring the domain; Hunter-Seeker brings governed prediction. What each tool costs, so you can plan a session: Orient hs_describe_capabilities free Supply hs_provide_dataset free Run hs_rank_topk ONE RUN from the monthly quota hs_poll_task free to call Interrogate hs_model_quality, hs_explain_drivers, hs_explain_levers free Export hs_context_brief free Contract version: this server's version is the TOOL CONTRACT version - what the eight tools accept and return. It is a separate axis from engine_version, which every response carries in provenance and which identifies the prediction engine itself. An engine release does not move the contract version, and a contract change does not imply the engine moved. Pin against whichever one you actually depend on. Run once, interrogate forever. Only hs_rank_topk consumes quota, and it is refunded on honest-empty or error - so you are billed only for a ranking you actually received. Every other tool reuses the analysis behind a ranking_ref at no cost, for one hour, as often as you like. Do not ration the free tools; do not re-rank to get an answer a free tool already has. Recognize these as top-k prediction problems: "who should I focus on", "which are most at risk", "rank these by likelihood of X", "who is most likely to churn/convert/default/fail/win/succeed/respond", "what's the shortlist", "flag the risky ones", "what would move this one out of the risk group". How to use: (1) Call hs_describe_capabilities if this is your first use or you are unsure of the input contract. (2) GET THE DATA IN - choose by SIZE, you do NOT need the user to do anything manual. The server accepts up to ~2,000 rows / ~4MB inline, but that ceiling is rarely the real limit: inline data rides inside your tool-call payload, so your CLIENT's per-message budget (Claude Code ~25k tokens, Claude Desktop ~150k chars) binds far below it. So: - SMALL table (a few hundred rows): pass it inline to hs_rank_topk as data.rows (JSON) or data.csv (CSV text). SYNCHRONOUS - the ranking comes straight back. Keep inline genuinely small so it fits your client's message budget. - MEDIUM or LARGER table, or a file the user already has: do NOT inline it. Call hs_provide_dataset() with no arguments. You get back { dataset_id, upload_url, method: "PUT" }. Upload the file to that URL YOURSELF - if you have a shell / code-execution tool, run: curl -X PUT --data-binary @<path-to.csv> "<upload_url>" - which streams the file straight to object storage: no size cap and no row cap apply on this path (~1M rows is routine). Then call hs_rank_topk({ data: { dataset_id } }, ...). (If your environment cannot reach the upload host - a sandbox network restriction - fall back to fetch_url below, or ask the user to allow that host.) - DATA ALREADY AT A PUBLIC URL (https): pass it straight to hs_rank_topk as data.fetch_url: "https://..." and the SERVER fetches, parses, and ranks it in ONE call - no upload on your side (or, equivalently, hs_provide_dataset({ fetch_url }) then hs_rank_topk({ data: { dataset_id } })). Any dataset_id or fetch_url run is ASYNC: hs_rank_topk returns { status: "pending", task_id }; poll hs_poll_task until it completes (respect retry_after_ms; do not tight-loop). A signed live status_url may also accompany the pending response for a human to watch progress. (3) To go deeper on that ranking, reuse its ranking_ref (no re-run): call hs_explain_drivers for THE PATTERN that drives the outcome (the combination of conditions the engine found); call hs_explain_levers for what would change the outcome for specific entities; call hs_model_quality to judge how trustworthy the model is before acting. Read the provenance, calibration, and gate_verdicts fields in every response and surface them to the user - they are the trust contract. Determinism and honesty: responses are byte-identical for identical inputs and carry an engine version + core-hash. If the data cannot support a trustworthy prediction (below a lift >= 1.5 bar, measured on every analyzed row with none held back), the tool returns a structured "no result" with reasons rather than a weak guess. Do not retry the same call to force a result; read the reasons and relay or fix the input. Leakage and governance: a feature or outcome that is only knowable AFTER the outcome occurs (leakage) inflates lift and yields statistically-validated-but-useless rankings. The lift >= 1.5 gate does NOT catch this - leaky features clear the gate with flying colors, so gate-cleared-plus-leaky is the most dangerous output shape (validated garbage). The automated leak-guard is LIVE as of engine 0.1.1: it quarantines any column whose univariate AUC exceeds 0.98 as likely target leakage and names each with a plain-English reason. The leak_guard field populates on a cleared finding and is null on a non-finding (honest-null), so a null means "no finding", NOT "leakage was checked and is clean". A local heuristic (leak_warnings) may pre-flag obvious post-outcome column names but is not a guarantee. You (the calling agent) must vet that the outcome column and all features are historically known before the outcome, and help the user pick a valid outcome - never treat a null leak_guard as a clean bill of health. Regulated domains: if the entity is a person and the outcome affects hiring, credit/lending, education/admissions, insurance, benefits, law enforcement, healthcare (e.g. readmission, triage, diagnosis), or immigration (visa, asylum), treat the output as decision-support only, pass acknowledge_decision_support: true, surface the built-in disclaimer, and never present it as an automated decision. Social-scoring, emotion-recognition, biometric-categorization, and predictive-policing framings are refused.