Hunter-Seeker

Free; no engine run. For a ranking already produced by hs_rank_topk (pass its ranking_ref), return a PORTABLE BRIEF you can drop straight into your own agent's context - the whole analysis as one compact artifact instead of three separate calls. Returns: provenance (engine version, core hash, the ranking_ref, the analysis identity, and when the analysis was computed), outcome.label, trust (top-decile lift, calibration error, validation scheme, and any columns the leak guard quarantined), driver_group (the drivers the engine found, each with a direction, to be read as ONE combination), and limits. Best for: handing an analysis to another agent, filing an analysis in your own store so you can recognise the same analysis later, or building a domain expert on top of Hunter-Seeker - we supply the governed prediction, you supply the domain. Set format to "markdown" for prose instead of JSON; both carry identical numbers. It reuses the analysis behind the ranking_ref, so it costs nothing and can be called as often as you like - only hs_rank_topk consumes a run. Drivers are ASSOCIATIONS, not causes, and are only meaningful together: never re-order them, never rank one above another, never report one on its own. Common mistakes: passing a ranking_ref older than an hour (the analysis is cached for one hour, then you must re-run hs_rank_topk); treating a null statistic as zero - null means the engine did not report it; and inventing drivers when the brief returns an empty driver group, which is a real result and not a gap. Never restate a number this brief does not contain, and never compute change over time by comparing two briefs - that is you authoring a direction the engine never gave. If change over time matters, re-run.

Free; no engine run. Return Hunter-Seeker's input contract, supported problem shapes, the trust guarantees (determinism, provenance, honest-empty; plus leak-guard, which is LIVE as of engine 0.1.1: it quarantines columns that predict the outcome too well (likely target leakage), each named with a plain-English reason, and is null on a non-finding (honest-null), not "pending"), limits (inline row/column/byte caps, k max), and worked examples across several domains (customer churn, machine failure, sports prospects, job applications). Call this first if you are unsure whether a user's problem is a top-k prediction problem or how to format inputs.

Free; no engine run. For a ranking already produced by hs_rank_topk (pass its ranking_ref), return THE PATTERN the engine found - the core of what Hunter-Seeker does: it discovers a COMBINATION of feature-conditions that, TOGETHER, predict the outcome (not independent per-feature effects). Returns pattern.conditions[] - read as ONE joint profile - plus pattern.coverage (exact share of entities matching the full pattern) and pattern.lift. A NUMERIC condition is a feature + direction (higher / lower) + the threshold where it turns (e.g. months_supply lower than 2.1), and it carries the exact predicate alongside: operator ("<=" or ">") and missing_values ("included" or "excluded"). BUILD YOUR FILTER FROM operator AND missing_values, NOT FROM THE DIRECTION WORD - the boundary is ASYMMETRIC and the English reading of "lower" is wrong. "lower" means operator "<=" with missing_values "included": it holds AT the threshold as well as below it, and also covers rows where that value is MISSING. "higher" means operator ">" with missing_values "excluded": strictly above, missing rows out. So "lower than t" names a WIDER cohort than a naive "< t" filter, and coverage counts those extra rows. This is not a rounding detail: on a dataset whose threshold lands on a common value, reading "lower than 168" as "< 168" selects ZERO rows while coverage reports 0.279 - a gate that fires on nothing while the envelope looks healthy. Both fields are absent on a categorical condition, whose cohort is defined by the set below instead. A CATEGORICAL condition has direction "different" (set membership has no high/low) and instead carries categories (the values involved) plus category_match, either "is_one_of" or "is_not_one_of" - take it LITERALLY and never drop the negation, because "is_not_one_of" ["annual"] is the opposite cohort from "is_one_of" ["annual"]. Both fields are absent on numeric conditions. This is what takes your agent from generalist to expert on THIS dataset - the structured pa…

Free; no engine run. For one or more entities already ranked by hs_rank_topk, compute the minimal set of feature changes (counterfactual levers) that would move the entity out of the high-risk / high-likelihood pattern. Best for: "what would have to change for this customer not to churn", "what's driving this risk", "how do I intervene". Not recommended for: entities not present in a prior ranking; guarantees of real-world causal effect (these are minimal model-based flips, not proven interventions). Returns: per-entity minimal feature changes (each a feature label + a direction: increase / decrease / change), a coarse magnitude (substantial / notable / slight), and likelihood_direction (lower / higher / unchanged) - which way the change moves PREDICTED LIKELIHOOD of the outcome - plus provenance; every lever is labeled association_not_causal. likelihood_direction is a FACT, not a recommendation, and it is NOT fixed to "lower" - READ IT PER LEVER. Which way it reads follows the polarity the engine resolved for this outcome: on an ADVERSE outcome (churn, default, failure) the levers move an entity OUT of the high-likelihood pattern and read "lower"; on a DESIRABLE outcome (converted, renewed, closed) the engine returns COMPLETION levers that move an entity INTO it, and those read "higher". Assuming "lower" on a desirable outcome inverts every lever you present. Whether the direction you get is the direction you want depends on whether the outcome is desirable (converted, renewed, closed) or adverse (churn, default, failure) - you know which, and Hunter-Seeker does not infer it. Decide the good/bad reading yourself, or ask the user, before presenting a lever as an improvement. No raw scores, score deltas, thresholds, or weights are returned - these are coarse, model-associated flips, not causal guarantees. Common mistakes: interpreting levers as causal guarantees - present them as "what the model associates with a different outcome", especially in regulated or person…

Free; no engine run. For a ranking already produced by hs_rank_topk (pass its ranking_ref), return the model DIAGNOSTICS so you can judge how much to trust it BEFORE acting on it. Returns: top_decile_lift (how concentrated the outcome is in the top-ranked group), calibration_error (ECE - lower is better-calibrated), validation (scheme: out-of-time, holdout, or none when no rows could be held back; n_holdout is null when nothing was held back; plus n_train and a plain-English reason), lift_curve (relative cumulative lift per decile), and leak_guard (columns quarantined as likely target leakage, each with a plain-English reason). These are validation statistics - never a threshold, weight, score, or arm. Best for: due diligence before acting, a governance / trust check, or a model-quality section in a report. A low top_decile_lift, a high calibration_error, or a populated leak_guard is a signal to be cautious. It reuses the analysis behind the ranking_ref - no new engine run. Common mistakes: passing an expired or never-cleared ranking_ref (call hs_rank_topk first); treating a null field as zero - it means there was no finding.

Free to call; the run it polls is the billable one. Check a long-running ranking started by hs_rank_topk in an async mode (a dataset_id or fetch_url run). Returns status "pending" (poll again after the suggested interval; do not tight-loop) or the completed ranking envelope. A pending response may also carry a stage + append-only facts_so_far (leak-firewalled progress — never a partial ranking) and an optional status_url: a short-TTL signed link to a live status page a human can open to watch staged progress in real time. Common mistakes: polling in a tight loop - respect retry_after_ms; treating "pending" as failure.

Free; no engine run. Register a dataset too large to inline in hs_rank_topk, then run it by dataset_id. RECOMMENDED for any real dataset (bigger than a small paste). Two ways to get the bytes in, no manual step needed from the user: - upload (best for a file you have): call it with no arguments to receive { dataset_id, upload_url, method: "PUT" }, then upload the file YOURSELF with a shell/code tool: curl -X PUT --data-binary @<file.csv> "<upload_url>" - the bytes stream straight to object storage, so there is NO size or row cap on this path (~1M rows is routine). Then hs_rank_topk({ data: { dataset_id } }). Send CSV: the engine reads the object as-is. - fetch_url (best when the data is already at a public https URL): call with { fetch_url: "https://..." } and the SERVER downloads it - no upload on your side. A comma-delimited CSV goes to storage byte-for-byte, so it has no row cap either. Then hs_rank_topk({ data: { dataset_id } }). (direct_upload: false opts back into a proxied upload_url, which converts a JSON body to CSV for you but is capped at the ~4.5MB serverless body limit. Only worth it for JSON you cannot convert.) Dataset runs are ASYNC: hs_rank_topk returns { status: "pending", task_id } - poll hs_poll_task. This tool stays useful for reuse (register once, rank many times) and for the direct_upload path, but you no longer NEED it as a separate step for the common cases: hs_rank_topk now accepts data.csv (inline CSV text, synchronous) and data.fetch_url (a public https URL the server fetches + ranks) directly, collapsing provide + rank into ONE call. Not recommended for: genuinely small tables (inline them in hs_rank_topk as data.rows or data.csv instead); non-https or private/internal URLs (blocked). Returns: dataset_id (+ upload_url in the upload modes). Common mistakes: passing localhost / private-network / cloud-metadata URLs (refused for safety); forgetting to actually PUT the file after direct_upload (the run has no data until you do); tig…

Costs one run from your monthly quota - the only tool that does. The run is refunded on honest-empty or error, so you are billed only for a ranking you actually received. Rank the rows of a table by their likelihood of a binary (yes/no) outcome, and return the top-k highest-likelihood entities with calibrated scores. Best for: any "which of these are most likely to [convert / churn / fail / default / win / succeed / respond / be approved]" or "who should I prioritize" question where the user has tabular data and one column represents a yes/no result. Works across any domain - business, operations, health-adjacent, education, sports, research, personal. Not recommended for: continuous-value forecasting (predicting a number, not a yes/no); questions with no historical outcome column to learn from; time-series-only problems; or when the user wants a causal guarantee rather than a ranked prediction. Returns: top-k ranked entities with per-entity calibrated scores; top-decile lift; calibration + validation records; provenance (engine version + core-hash); gate_verdicts with recorded reasons; and leak_guard results naming any quarantined post-outcome columns. Honest-null: top_decile_lift, validation, leak_guard, and top_factors are LIVE as of engine 0.1.1 - they populate on a cleared finding and are returned as null on a non-finding (never fabricated) - so a null means no finding, NOT that the field is pending. top_factors are human-readable strings ("higher/lower/different <feature>"); validation is { scheme, split_fraction, n_train, n_holdout, reason? }; scheme is "holdout", "out_of_time", or "none" when the dataset was too small to hold rows back - in which case n_holdout is null (not 0) and reason states why and what would fix it; leak_guard is a list of quarantined likely-leakage columns, each with a plain-English reason. If the data cannot clear the lift >= 1.5 bar, returns a structured honest-empty result with reasons instead of weak rankings. Common mistakes: cho…