hunter-seeker 2.0.0__tar.gz

hunter_seeker-2.0.0/PKG-INFO

@@ -0,0 +1,47 @@
+Metadata-Version: 2.4
+Name: hunter-seeker
+Version: 2.0.0
+Summary: Python client and framework tools for the Hunter-Seeker Verdict layer: deterministic, signed, refusable decisions for agents.
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/dmilstein-match/hunter-seeker-sdk
+Project-URL: Source, https://github.com/dmilstein-match/hunter-seeker-sdk
+Project-URL: Documentation, https://hunter-seeker.net/docs
+Project-URL: Changelog, https://github.com/dmilstein-match/hunter-seeker-sdk/blob/main/CHANGELOG.md
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: hs-verify>=0.1
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.3; extra == "langchain"
+Provides-Extra: crewai
+Requires-Dist: crewai>=0.100; extra == "crewai"
+Requires-Dist: crewai-tools>=0.40; extra == "crewai"
+
+# hunter-seeker
+
+Python client, `hs` CLI and framework adapters for the **Hunter-Seeker Verdict layer** —
+deterministic, signed, refusable decisions for AI agents.
+
+> Agents may generate copy. They may not invent the score.
+
+```bash
+pip install hunter-seeker
+export HS_API_KEY=hsk_test_...
+hs sample                    # ranks a sample dataset and verifies the Verdict
+```
+```python
+from hunter_seeker import Client
+hs = Client()
+out = hs.score_entity(model_ref=ref, row=row, subject_kind="org")
+out["entity"]["band"]                       # act | escalate | refuse
+hs.verify(out["verdict"], out["signature"]) # valid | invalid_signature | expired | unknown_key
+```
+
+Extras: `hunter-seeker[langchain]`, `hunter-seeker[crewai]`.
+
+The client refuses to call an unsigned Verdict valid — a missing signature reports
+`invalid_signature`, because production engines will not serve one.
+
+**Pre-release:** the hosted service is not serving yet. Full docs, the OpenAPI contract, the
+n8n node and Agent Skills: https://github.com/dmilstein-match/hunter-seeker-sdk
+
+Apache-2.0.

hunter_seeker-2.0.0/README.md

@@ -0,0 +1,29 @@
+# hunter-seeker
+
+Python client, `hs` CLI and framework adapters for the **Hunter-Seeker Verdict layer** —
+deterministic, signed, refusable decisions for AI agents.
+
+> Agents may generate copy. They may not invent the score.
+
+```bash
+pip install hunter-seeker
+export HS_API_KEY=hsk_test_...
+hs sample                    # ranks a sample dataset and verifies the Verdict
+```
+```python
+from hunter_seeker import Client
+hs = Client()
+out = hs.score_entity(model_ref=ref, row=row, subject_kind="org")
+out["entity"]["band"]                       # act | escalate | refuse
+hs.verify(out["verdict"], out["signature"]) # valid | invalid_signature | expired | unknown_key
+```
+
+Extras: `hunter-seeker[langchain]`, `hunter-seeker[crewai]`.
+
+The client refuses to call an unsigned Verdict valid — a missing signature reports
+`invalid_signature`, because production engines will not serve one.
+
+**Pre-release:** the hosted service is not serving yet. Full docs, the OpenAPI contract, the
+n8n node and Agent Skills: https://github.com/dmilstein-match/hunter-seeker-sdk
+
+Apache-2.0.

hunter_seeker-2.0.0/hunter_seeker/__init__.py

@@ -0,0 +1,16 @@
+"""hunter-seeker — Python client for the Hunter-Seeker Verdict layer.
+
+    from hunter_seeker import Client
+    hs = Client(api_key="hsk_test_...")             # or oauth token
+    caps = hs.describe_capabilities()
+    run  = hs.rank_topk(dataset_id="sample:saas_churn", entity_column="customer_id",
+                        outcome_column="churned", subject_kind="org")
+    v    = hs.score_entity(run["model_ref"], {"tenure": 14, "seats": 3}, subject_kind="org")
+    hs.verify(v["verdict"], v["signature"])          # -> "valid"
+
+Framework adapters: hunter_seeker.langchain, hunter_seeker.crewai. CLI: `hs`.
+"""
+from .client import Client, HunterSeekerError, ProblemDetails
+
+__all__ = ["Client", "HunterSeekerError", "ProblemDetails"]
+__version__ = "2.0.0"

hunter_seeker-2.0.0/hunter_seeker/cli.py

@@ -0,0 +1,91 @@
+"""`hs` — the command line.
+
+  hs init leads.csv           propose entity/outcome columns (propose-and-gate), write hs.yaml
+  hs rank                     run hs.yaml (one billed run) and print model_ref + verdict id
+  hs score '{"tenure":14}'    score one row against the model_ref in hs.yaml
+  hs verify v.json s.json     keyless verification
+  hs sample                   rank a hosted sample dataset (free) — the five-minute test
+"""
+from __future__ import annotations
+
+import csv
+import json
+import os
+import sys
+from pathlib import Path
+
+from .client import Client, HunterSeekerError
+
+
+def _client() -> Client:
+    key = os.environ.get("HS_API_KEY")
+    if not key:
+        sys.exit("set HS_API_KEY (hsk_test_... reaches the free sample datasets)")
+    return Client(api_key=key, base_url=os.environ.get("HS_BASE_URL", "https://hunter-seeker.net/api"))
+
+
+def _propose(path: Path) -> dict:
+    """Local first pass: enumerate binary-looking and id-looking columns. The server-side
+    /resolve-spec gate is authoritative; this only writes candidates for the human to confirm."""
+    with path.open(newline="") as f:
+        rows = list(csv.DictReader(f))
+    cols = rows[0].keys() if rows else []
+    n = len(rows)
+    ids, outs = [], []
+    for c in cols:
+        vals = [r[c] for r in rows if r.get(c) not in (None, "")]
+        distinct = set(vals)
+        if n and len(distinct) == n:
+            ids.append(c)
+        low = {v.strip().lower() for v in distinct}
+        if low and low <= {"0", "1", "true", "false", "yes", "no", "y", "n"}:
+            outs.append(c)
+    return {"rows": n, "entity_candidates": ids, "outcome_candidates": outs}
+
+
+def main(argv=None) -> int:
+    a = list(argv or sys.argv[1:])
+    if not a or a[0] in ("-h", "--help"):
+        print(__doc__); return 0
+    cmd, rest = a[0], a[1:]
+    try:
+        if cmd == "init":
+            p = Path(rest[0]); prop = _propose(p)
+            def pick(kind, cands):
+                if len(cands) == 1: return cands[0]
+                if not cands: return None
+                print(f"{kind}: choose one of {cands}"); return None  # ≥2 → surface a choice, never guess
+            spec = {"dataset": str(p), "entity_column": pick("entity", prop["entity_candidates"]),
+                    "outcome_column": pick("outcome", prop["outcome_candidates"]), "subject_kind": "org", "k": 20}
+            Path("hs.yaml").write_text("".join(f"{k}: {json.dumps(v)}\n" for k, v in spec.items()))
+            print(json.dumps({"proposed": prop, "wrote": "hs.yaml"}, indent=2)); return 0
+        hs = _client()
+        if cmd == "sample":
+            out = hs.rank_topk(dataset_id="sample:saas_churn", entity_column="customer_id", outcome_column="churned", subject_kind="org")
+            print(json.dumps({k: out.get(k) for k in ("ranking_ref", "model_ref", "honest_empty")}, indent=2))
+            if out.get("verdict"):
+                print("verify:", hs.verify(out["verdict"], out["signature"]))
+            return 0
+        spec = {l.split(":")[0]: json.loads(l.split(":", 1)[1]) for l in Path("hs.yaml").read_text().splitlines() if l.strip()}
+        if cmd == "rank":
+            csv_text = Path(spec["dataset"]).read_text()
+            out = hs.rank_topk(csv=csv_text, entity_column=spec["entity_column"], outcome_column=spec["outcome_column"],
+                               subject_kind=spec["subject_kind"], k=spec.get("k", 20))
+            spec["model_ref"] = out.get("model_ref")
+            Path("hs.yaml").write_text("".join(f"{k}: {json.dumps(v)}\n" for k, v in spec.items()))
+            print(json.dumps({k: out.get(k) for k in ("ranking_ref", "model_ref", "honest_empty")}, indent=2)); return 0
+        if cmd == "score":
+            out = hs.score_entity(spec["model_ref"], json.loads(rest[0]), subject_kind=spec["subject_kind"])
+            print(json.dumps(out["entity"], indent=2))
+            st = hs.verify(out["verdict"], out.get("signature"))
+            print("verify:", st + ("" if st == "valid" else "  (do not act on an unverified Verdict)")); return 0
+        if cmd == "verify":
+            v, s = json.load(open(rest[0])), json.load(open(rest[1])); print(hs.verify(v, s)); return 0
+        print(__doc__); return 2
+    except HunterSeekerError as e:
+        print(json.dumps({"error": e.problem.code, "detail": e.problem.detail, "remedy": e.problem.remedy}), file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

hunter_seeker-2.0.0/hunter_seeker/client.py

@@ -0,0 +1,169 @@
+from __future__ import annotations
+
+import json
+import time
+import urllib.error
+import urllib.request
+import uuid
+from dataclasses import dataclass
+from typing import Any, Dict, Mapping, Optional
+
+DEFAULT_BASE = "https://hunter-seeker.net/api"
+
+
+@dataclass(frozen=True)
+class ProblemDetails:
+    status: int
+    code: str
+    detail: str
+    remedy: str
+    field: Optional[str]
+    request_id: Optional[str]
+
+
+class HunterSeekerError(Exception):
+    def __init__(self, p: ProblemDetails) -> None:
+        super().__init__(f"{p.code}: {p.detail} — {p.remedy}")
+        self.problem = p
+
+    @property
+    def retryable(self) -> bool:
+        return self.problem.status in (429, 503)
+
+
+class Client:
+    def __init__(self, api_key: Optional[str] = None, *, oauth_token: Optional[str] = None,
+                 base_url: str = DEFAULT_BASE, timeout: float = 60.0) -> None:
+        if not (api_key or oauth_token):
+            raise ValueError("provide api_key (hsk_...) or oauth_token")
+        self._auth = f"Bearer {oauth_token or api_key}"
+        self.base = base_url.rstrip("/")
+        self.timeout = timeout
+        self.test_mode = bool(api_key and api_key.startswith("hsk_test_"))
+
+    # -- transport ---------------------------------------------------------- #
+    def _call(self, path: str, body: Optional[Mapping[str, Any]] = None, *, method: str = "POST",
+              idempotency_key: Optional[str] = None) -> Dict[str, Any]:
+        data = json.dumps(body or {}).encode() if method == "POST" else None
+        req = urllib.request.Request(self.base + path, data=data, method=method, headers={
+            "authorization": self._auth, "content-type": "application/json",
+            "user-agent": "hunter-seeker-python/2.0.0",
+            **({"idempotency-key": idempotency_key} if idempotency_key else {}),
+        })
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as r:  # noqa: S310
+                return json.load(r)
+        except urllib.error.HTTPError as e:
+            try:
+                prob = json.load(e)
+                hs = prob.get("hs") or (prob.get("detail") or {}).get("hs") or {}
+                det = prob.get("detail") if isinstance(prob.get("detail"), str) else (prob.get("detail") or {}).get("detail", "")
+            except Exception:  # noqa: BLE001
+                hs, det = {}, e.reason
+            raise HunterSeekerError(ProblemDetails(e.code, hs.get("code", "http_error"), det or str(e.reason),
+                                                   hs.get("remedy", "see docs"), hs.get("field"),
+                                                   e.headers.get("x-request-id"))) from None
+
+    # -- existing surface --------------------------------------------------- #
+    def describe_capabilities(self) -> Dict[str, Any]:
+        return self._call("/v1/describe-capabilities")
+
+    def provide_dataset(self, *, fetch_url: Optional[str] = None, name: Optional[str] = None) -> Dict[str, Any]:
+        return self._call("/v1/provide-dataset", {k: v for k, v in {"fetch_url": fetch_url, "name": name}.items() if v})
+
+    def rank_topk(self, *, entity_column: str, outcome_column: str, subject_kind: str,
+                  dataset_id: Optional[str] = None, rows: Optional[list] = None, csv: Optional[str] = None,
+                  fetch_url: Optional[str] = None, k: int = 20, horizon: Optional[str] = None,
+                  acknowledge_decision_support: bool = False, reading: Optional[Mapping[str, Any]] = None,
+                  refit_of: Optional[str] = None, idempotency_key: Optional[str] = None,
+                  wait: bool = True, poll_s: float = 2.0) -> Dict[str, Any]:
+        data = {k_: v for k_, v in {"dataset_id": dataset_id, "rows": rows, "csv": csv, "fetch_url": fetch_url}.items() if v}
+        body: Dict[str, Any] = {"data": data, "entity_column": entity_column, "outcome_column": outcome_column,
+                                "subject_kind": subject_kind, "page": {"k": k},
+                                "acknowledge_decision_support": acknowledge_decision_support}
+        if horizon: body["horizon"] = horizon
+        if reading: body["reading"] = dict(reading)
+        if refit_of: body["refit_of"] = refit_of
+        key = idempotency_key or str(uuid.uuid4())
+        body["idempotency_key"] = key
+        out = self._call("/v1/rank-topk", body, idempotency_key=key)
+        while wait and out.get("status") == "pending":
+            time.sleep(max(poll_s, out.get("retry_after_ms", 0) / 1000))
+            out = self.poll_task(out["task_id"])
+        return out
+
+    def poll_task(self, task_id: str) -> Dict[str, Any]:
+        return self._call("/v1/poll-task", {"task_id": task_id})
+
+    def model_quality(self, ranking_ref: str) -> Dict[str, Any]:
+        return self._call("/v1/model-quality", {"ranking_ref": ranking_ref})
+
+    def explain_drivers(self, ranking_ref: str) -> Dict[str, Any]:
+        return self._call("/v1/explain-drivers", {"ranking_ref": ranking_ref})
+
+    def explain_levers(self, ranking_ref: str, entity_ids: list[str]) -> Dict[str, Any]:
+        return self._call("/v1/explain-levers", {"ranking_ref": ranking_ref, "entity_ids": entity_ids})
+
+    def context_brief(self, ranking_ref: str, fmt: str = "json") -> Dict[str, Any]:
+        return self._call("/v1/context-brief", {"ranking_ref": ranking_ref, "format": fmt})
+
+    # -- verdict layer ------------------------------------------------------- #
+    def score_entity(self, model_ref: str, row: Mapping[str, Any], *, subject_kind: str,
+                     entity_id: Optional[str] = None, acknowledge_decision_support: bool = False,
+                     on_behalf_of: Optional[Mapping[str, str]] = None) -> Dict[str, Any]:
+        body = {"model_ref": model_ref, "row": dict(row), "subject_kind": subject_kind,
+                "acknowledge_decision_support": acknowledge_decision_support}
+        if entity_id: body["entity_id"] = entity_id
+        if on_behalf_of: body["on_behalf_of"] = dict(on_behalf_of)
+        return self._call("/v1/score-entity", body)
+
+    def score_batch(self, model_ref: str, rows: list, *, subject_kind: str, entity_column: Optional[str] = None,
+                    acknowledge_decision_support: bool = False, as_of: Optional[str] = None) -> Dict[str, Any]:
+        body = {"model_ref": model_ref, "rows": rows, "subject_kind": subject_kind,
+                "acknowledge_decision_support": acknowledge_decision_support}
+        if entity_column: body["entity_column"] = entity_column
+        if as_of: body["as_of"] = as_of
+        return self._call("/v1/score-batch", body)
+
+    def verify(self, verdict: Mapping[str, Any], signature: Optional[Mapping[str, str]], *,
+               offline: bool = True, jwks: Optional[Mapping[str, Any]] = None) -> str:
+        """Offline by default via hs-verify. Pass ``jwks`` to avoid the network entirely.
+
+        A Verdict with no signature is UNVERIFIABLE and is reported as "invalid_signature":
+        production deployments always sign, so a missing signature means a misconfigured or
+        non-production server, never a valid decision.
+        """
+        if not signature or not signature.get("protected") or not signature.get("signature"):
+            return "invalid_signature"
+        if offline:
+            try:
+                from hs_verify import verify as _v  # type: ignore
+            except ImportError:
+                pass
+            else:
+                # `jwks` makes this genuinely offline. Without it hs_verify fetches the
+                # published keys, and an unreachable JWKS RAISES rather than reporting the
+                # Verdict as invalid — a network failure is not a forgery.
+                return _v(verdict, signature, jwks=jwks) if jwks is not None else _v(verdict, signature)
+        return self._call("/v1/verify-verdict", {"verdict": dict(verdict), "signature": dict(signature)})["status"]
+
+    def report_outcome(self, model_ref: str, outcomes: list[Mapping[str, Any]]) -> Dict[str, Any]:
+        return self._call("/v1/report-outcome", {"model_ref": model_ref, "outcomes": [dict(o) for o in outcomes]})
+
+    def attest_action(self, *, model_ref: str, entity_id: str, lever_token: str, post_value: Any,
+                      acted_at: str, event_id: Optional[str] = None) -> Dict[str, Any]:
+        body = {"model_ref": model_ref, "entity_id": entity_id, "lever_token": lever_token,
+                "post_value": post_value, "acted_at": acted_at}
+        if event_id: body["event_id"] = event_id
+        return self._call("/v1/attest-action", body)
+
+    def action_evidence(self, model_ref: str) -> Dict[str, Any]:
+        return self._call("/v1/action-evidence", {"model_ref": model_ref})
+
+    def drift_status(self, model_ref: str) -> Dict[str, Any]:
+        return self._call("/v1/drift-status", {"model_ref": model_ref})
+
+    def export_bundle(self, verdict_id: str, entity_id: Optional[str] = None) -> Dict[str, Any]:
+        body = {"verdict_id": verdict_id}
+        if entity_id: body["entity_id"] = entity_id
+        return self._call("/v1/export-bundle", body)

hunter_seeker-2.0.0/hunter_seeker/crewai.py

@@ -0,0 +1,33 @@
+"""CrewAI tools. `pip install hunter-seeker[crewai]`. Or point CrewAI at the MCP server:
+    Agent(..., mcps=["https://hunter-seeker.net/api/mcp#hs_score_entity"])
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, Type
+
+from .client import Client
+
+
+def score_entity_tool(hs: Client):
+    from crewai.tools import BaseTool  # type: ignore
+    from pydantic import BaseModel, Field
+
+    class Args(BaseModel):
+        model_ref: str = Field(description="model_ref from a cleared hs_rank_topk")
+        row: Dict[str, Any] = Field(description="one entity's feature values")
+        subject_kind: str = Field(description="person | org | object | event | other")
+        acknowledge_decision_support: bool = False
+
+    class HSScoreEntity(BaseTool):
+        name: str = "hs_score_entity"
+        description: str = ("Score one row against a fitted scorecard; costs one decision. Returns score, band "
+                            "(act|escalate|refuse), max_autonomy, principal_reasons, and a signed Verdict. Read band; "
+                            "never reconstruct thresholds. Person-level requires acknowledge_decision_support=True.")
+        args_schema: Type[BaseModel] = Args
+
+        def _run(self, model_ref: str, row: Dict[str, Any], subject_kind: str,
+                 acknowledge_decision_support: bool = False) -> Dict[str, Any]:
+            return hs.score_entity(model_ref, row, subject_kind=subject_kind,
+                                   acknowledge_decision_support=acknowledge_decision_support)
+
+    return HSScoreEntity()

hunter_seeker-2.0.0/hunter_seeker/langchain.py

@@ -0,0 +1,61 @@
+"""LangChain / LangGraph tools. `pip install hunter-seeker[langchain]`.
+
+    from hunter_seeker.langchain import verdict_tools
+    tools = verdict_tools(Client(api_key=...))
+
+The approval-gate pattern (LangGraph):
+
+    def gate(state):
+        v = hs.score_entity(state["model_ref"], state["row"], subject_kind="person",
+                            acknowledge_decision_support=True)
+        if v["entity"]["band"] != "act":
+            decision = interrupt({"verdict": v["verdict"], "signature": v["signature"],
+                                  "band": v["entity"]["band"], "reasons": v["entity"]["principal_reasons"]})
+        ...
+
+interrupt() re-runs the node on resume: pass the same idempotency_key to rank_topk, and
+score_entity is idempotent, so a resumed node never double-bills.
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, List
+
+from .client import Client
+
+
+def verdict_tools(hs: Client) -> List[Any]:
+    try:
+        from langchain_core.tools import tool
+    except ImportError as e:  # pragma: no cover
+        raise ImportError("pip install langchain-core") from e
+
+    @tool
+    def hs_score_entity(model_ref: str, row: Dict[str, Any], subject_kind: str,
+                        acknowledge_decision_support: bool = False, entity_id: str | None = None) -> Dict[str, Any]:
+        """Score ONE row against a fitted scorecard (model_ref from a cleared hs_rank_topk). Costs one decision. Returns score, band (act|escalate|refuse), max_autonomy (L0-L4), up to four principal_reasons, and a signed Verdict. Never reconstruct thresholds; read band. person-level requires acknowledge_decision_support=True."""
+        return hs.score_entity(model_ref, row, subject_kind=subject_kind, entity_id=entity_id,
+                               acknowledge_decision_support=acknowledge_decision_support)
+
+    @tool
+    def hs_verify_verdict(verdict: Dict[str, Any], signature: Dict[str, str]) -> str:
+        """Free, keyless. Returns valid | invalid_signature | expired | unknown_key. An expired verdict is re-scored, never reused."""
+        return hs.verify(verdict, signature)
+
+    @tool
+    def hs_report_outcome(model_ref: str, entity_id: str, outcome: bool, observed_at: str, event_id: str | None = None) -> Dict[str, Any]:
+        """Free. Report the REAL-WORLD binary outcome you observed for an entity you scored. Idempotent by event_id. Never changes the model."""
+        o: Dict[str, Any] = {"entity_id": entity_id, "outcome": outcome, "observed_at": observed_at}
+        if event_id: o["event_id"] = event_id
+        return hs.report_outcome(model_ref, [o])
+
+    @tool
+    def hs_action_evidence(model_ref: str) -> Dict[str, Any]:
+        """Free. Did acting on this pattern work? Returns holdout and live blocks (never merged); live is null below the statistical floor."""
+        return hs.action_evidence(model_ref)
+
+    @tool
+    def hs_drift_status(model_ref: str) -> Dict[str, Any]:
+        """Free. Has the pattern changed since the prior run? recommendation keep | refit | abandon. Never diff two briefs yourself."""
+        return hs.drift_status(model_ref)
+
+    return [hs_score_entity, hs_verify_verdict, hs_report_outcome, hs_action_evidence, hs_drift_status]

hunter_seeker-2.0.0/hunter_seeker.egg-info/PKG-INFO

@@ -0,0 +1,47 @@
+Metadata-Version: 2.4
+Name: hunter-seeker
+Version: 2.0.0
+Summary: Python client and framework tools for the Hunter-Seeker Verdict layer: deterministic, signed, refusable decisions for agents.
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/dmilstein-match/hunter-seeker-sdk
+Project-URL: Source, https://github.com/dmilstein-match/hunter-seeker-sdk
+Project-URL: Documentation, https://hunter-seeker.net/docs
+Project-URL: Changelog, https://github.com/dmilstein-match/hunter-seeker-sdk/blob/main/CHANGELOG.md
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: hs-verify>=0.1
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.3; extra == "langchain"
+Provides-Extra: crewai
+Requires-Dist: crewai>=0.100; extra == "crewai"
+Requires-Dist: crewai-tools>=0.40; extra == "crewai"
+
+# hunter-seeker
+
+Python client, `hs` CLI and framework adapters for the **Hunter-Seeker Verdict layer** —
+deterministic, signed, refusable decisions for AI agents.
+
+> Agents may generate copy. They may not invent the score.
+
+```bash
+pip install hunter-seeker
+export HS_API_KEY=hsk_test_...
+hs sample                    # ranks a sample dataset and verifies the Verdict
+```
+```python
+from hunter_seeker import Client
+hs = Client()
+out = hs.score_entity(model_ref=ref, row=row, subject_kind="org")
+out["entity"]["band"]                       # act | escalate | refuse
+hs.verify(out["verdict"], out["signature"]) # valid | invalid_signature | expired | unknown_key
+```
+
+Extras: `hunter-seeker[langchain]`, `hunter-seeker[crewai]`.
+
+The client refuses to call an unsigned Verdict valid — a missing signature reports
+`invalid_signature`, because production engines will not serve one.
+
+**Pre-release:** the hosted service is not serving yet. Full docs, the OpenAPI contract, the
+n8n node and Agent Skills: https://github.com/dmilstein-match/hunter-seeker-sdk
+
+Apache-2.0.

hunter_seeker-2.0.0/hunter_seeker.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+README.md
+pyproject.toml
+hunter_seeker/__init__.py
+hunter_seeker/cli.py
+hunter_seeker/client.py
+hunter_seeker/crewai.py
+hunter_seeker/langchain.py
+hunter_seeker.egg-info/PKG-INFO
+hunter_seeker.egg-info/SOURCES.txt
+hunter_seeker.egg-info/dependency_links.txt
+hunter_seeker.egg-info/entry_points.txt
+hunter_seeker.egg-info/requires.txt
+hunter_seeker.egg-info/top_level.txt
+tests/test_client.py

hunter_seeker-2.0.0/hunter_seeker.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

hunter_seeker-2.0.0/hunter_seeker.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+hs = hunter_seeker.cli:main

hunter_seeker-2.0.0/hunter_seeker.egg-info/requires.txt

@@ -0,0 +1,8 @@
+hs-verify>=0.1
+
+[crewai]
+crewai>=0.100
+crewai-tools>=0.40
+
+[langchain]
+langchain-core>=0.3

hunter_seeker-2.0.0/hunter_seeker.egg-info/top_level.txt

@@ -0,0 +1 @@
+hunter_seeker

hunter_seeker-2.0.0/pyproject.toml

@@ -0,0 +1,21 @@
+[project]
+name = "hunter-seeker"
+version = "2.0.0"
+description = "Python client and framework tools for the Hunter-Seeker Verdict layer: deterministic, signed, refusable decisions for agents."
+requires-python = ">=3.10"
+dependencies = ["hs-verify>=0.1"]
+license = {text = "Apache-2.0"}
+readme = "README.md"
+
+[project.urls]
+Homepage = "https://github.com/dmilstein-match/hunter-seeker-sdk"
+Source = "https://github.com/dmilstein-match/hunter-seeker-sdk"
+Documentation = "https://hunter-seeker.net/docs"
+Changelog = "https://github.com/dmilstein-match/hunter-seeker-sdk/blob/main/CHANGELOG.md"
+
+[project.optional-dependencies]
+langchain = ["langchain-core>=0.3"]
+crewai = ["crewai>=0.100", "crewai-tools>=0.40"]
+
+[project.scripts]
+hs = "hunter_seeker.cli:main"

hunter_seeker-2.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

hunter_seeker-2.0.0/tests/test_client.py

@@ -0,0 +1,41 @@
+import json, threading
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from hunter_seeker import Client, HunterSeekerError
+
+class H(BaseHTTPRequestHandler):
+    def log_message(self, *a): pass
+    def do_POST(self):
+        n = int(self.headers.get("content-length", 0)); body = json.loads(self.rfile.read(n) or b"{}")
+        if self.path == "/v1/score-entity":
+            out = {"entity": {"entity_id": "a", "score": 0.9, "band": "act", "max_autonomy": "L3", "principal_reasons": []}, "verdict": {"expires_at": "2099-01-01T00:00:00Z"}, "signature": {"protected": "x", "signature": "y"}, "billable_decisions": 1}
+            self.send_response(200)
+        else:
+            out = {"type": "https://hunter-seeker.net/problems/model_ref_expired", "title": "expired", "status": 404, "detail": "gone", "hs": {"code": "model_ref_expired", "remedy": "re-run", "field": "model_ref"}}
+            self.send_response(404)
+        self.send_header("content-type", "application/json"); self.end_headers(); self.wfile.write(json.dumps(out).encode())
+
+def test_client_roundtrip_and_problem_mapping():
+    srv = HTTPServer(("127.0.0.1", 0), H); threading.Thread(target=srv.serve_forever, daemon=True).start()
+    hs = Client(api_key="hsk_test_abc", base_url=f"http://127.0.0.1:{srv.server_port}")
+    assert hs.test_mode
+    r = hs.score_entity("mr1_x", {"tenure": 1}, subject_kind="org")
+    assert r["entity"]["band"] == "act"
+    try:
+        hs.drift_status("mr1_gone"); assert False
+    except HunterSeekerError as e:
+        assert e.problem.code == "model_ref_expired" and e.problem.remedy == "re-run" and not e.retryable
+    srv.shutdown()
+
+def test_init_proposes_and_never_guesses(tmp_path, monkeypatch):
+    from hunter_seeker.cli import main
+    (tmp_path / "leads.csv").write_text("id,churned,other,tenure\n1,1,1,5\n2,0,0,5\n3,1,1,2\n")
+    monkeypatch.chdir(tmp_path)
+    assert main(["init", "leads.csv"]) == 0
+    spec = (tmp_path / "hs.yaml").read_text()
+    assert 'entity_column: "id"' in spec and 'outcome_column: null' in spec  # two outcome candidates → a choice, not a guess
+
+
+def test_missing_signature_is_unverifiable_not_valid():
+    hs = Client(api_key="hsk_test_abc", base_url="http://127.0.0.1:1")
+    assert hs.verify({"expires_at": "2099-01-01T00:00:00Z"}, None) == "invalid_signature"
+    assert hs.verify({"expires_at": "2099-01-01T00:00:00Z"}, {}) == "invalid_signature"