datagoat 1.0.0__tar.gz

datagoat-1.0.0/PKG-INFO

@@ -0,0 +1,35 @@
+Metadata-Version: 2.4
+Name: datagoat
+Version: 1.0.0
+Summary: Ask yes/no, score, choice and rank questions about cases. Datagoat answers from what happened to cases like them: deterministic, with reasons, signed.
+License: Apache-2.0
+Project-URL: Homepage, https://datagoat.io
+Project-URL: Documentation, https://datagoat.io/docs
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.3; extra == "langchain"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pydantic; extra == "test"
+
+# datagoat
+
+Ask yes/no, score, choice and rank questions about cases. Datagoat answers from what happened to
+cases like them: deterministic, with reasons, and a signed Verdict. It refuses rather than guess.
+
+```bash
+pip install datagoat
+datagoat signup      # a free test key for the sample datasets
+datagoat sample      # ask about sample:saas_churn and verify the answer
+```
+
+```python
+from datagoat import Client, yesno, score
+dg = Client()        # reads DATAGOAT_API_KEY, or the key `datagoat signup` saved
+out = dg.ask({"churn": yesno("churned", outcome_is_desirable=False)},
+             dataset_id="sample:saas_churn", entity_column="customer_id",
+             subject_kind="org", cases={"ids": ["cust_0001"]})
+```
+
+Docs: https://datagoat.io/docs

datagoat-1.0.0/README.md

@@ -0,0 +1,20 @@
+# datagoat
+
+Ask yes/no, score, choice and rank questions about cases. Datagoat answers from what happened to
+cases like them: deterministic, with reasons, and a signed Verdict. It refuses rather than guess.
+
+```bash
+pip install datagoat
+datagoat signup      # a free test key for the sample datasets
+datagoat sample      # ask about sample:saas_churn and verify the answer
+```
+
+```python
+from datagoat import Client, yesno, score
+dg = Client()        # reads DATAGOAT_API_KEY, or the key `datagoat signup` saved
+out = dg.ask({"churn": yesno("churned", outcome_is_desirable=False)},
+             dataset_id="sample:saas_churn", entity_column="customer_id",
+             subject_kind="org", cases={"ids": ["cust_0001"]})
+```
+
+Docs: https://datagoat.io/docs

datagoat-1.0.0/datagoat/__init__.py

@@ -0,0 +1,17 @@
+"""datagoat: ask yes/no, score, choice and rank questions about cases.
+
+    from datagoat import Client, yesno, score, choice, rank
+    dg = Client()
+    out = dg.ask({"churn": yesno("churned", outcome_is_desirable=False)},
+                 dataset_id="sample:saas_churn", entity_column="customer_id",
+                 subject_kind="org", cases={"ids": ["cust_0001"]})
+    out["answers"]["churn"]["cases"][0]["p"]         # the chance, with reasons and a signed Verdict
+
+A record that is not one row per case takes a shape: events, series, panel, signals or traces.
+"""
+from ._version import __version__
+from .client import Client, DatagoatError, Problem, register
+from .questions import choice, events, panel, rank, score, series, signals, traces, yesno
+
+__all__ = ["Client", "DatagoatError", "Problem", "register", "yesno", "score", "choice", "rank",
+           "events", "series", "panel", "signals", "traces", "__version__"]

datagoat-1.0.0/datagoat/_version.py

@@ -0,0 +1 @@
+__version__ = "1.0.0"

datagoat-1.0.0/datagoat/cli.py

@@ -0,0 +1,94 @@
+"""`datagoat` on the command line.
+
+  datagoat signup                 a free test key for the sample datasets, saved for later calls
+  datagoat sample                 ask about sample:saas_churn and verify every Verdict
+  datagoat describe               question types, prices and the samples
+  datagoat ask QUESTIONS --data DATASET_ID --entity COLUMN [--cases IDS] [--kind org]
+                                  e.g. datagoat ask '{"churn":{"type":"yesno","outcome_column":"churned"}}' \\
+                                       --data sample:saas_churn --entity customer_id --cases cust_0001,cust_0002
+  datagoat verify VERDICT.json SIGNATURE.json
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from typing import List, Optional
+
+from .client import CREDENTIALS, Client, DatagoatError, register, saved_key
+from .questions import score, yesno
+
+
+def _save(key: str) -> None:
+    CREDENTIALS.parent.mkdir(parents=True, exist_ok=True)
+    CREDENTIALS.write_text(key + "\n")
+    os.chmod(CREDENTIALS, 0o600)
+
+
+def _print_and_verify(dg: Client, out: dict) -> int:
+    print(json.dumps(out, indent=2))
+    ok = dg.verify_all(out)
+    print("verify:", "valid" if ok else "INVALID (do not act on an unverified Verdict)")
+    return 0 if ok else 1
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    p = argparse.ArgumentParser(prog="datagoat", description="Ask questions about cases.")
+    sub = p.add_subparsers(dest="cmd", required=True)
+    s = sub.add_parser("signup")
+    s.add_argument("--force", action="store_true", help="replace a saved key")
+    sub.add_parser("sample")
+    sub.add_parser("describe")
+    a = sub.add_parser("ask")
+    a.add_argument("questions")
+    a.add_argument("--data", required=True, help="a dataset_id or sample id")
+    a.add_argument("--entity", required=True, help="the column naming each case")
+    a.add_argument("--cases", help="comma-separated ids; omit to rank the record")
+    a.add_argument("--kind", default="org", choices=["person", "org", "object", "event", "other"])
+    v = sub.add_parser("verify")
+    v.add_argument("verdict")
+    v.add_argument("signature")
+    args = p.parse_args(argv)
+
+    try:
+        if args.cmd == "signup":
+            if saved_key() and not args.force:
+                print(f"A key is already saved in {CREDENTIALS}. Use --force to replace it.")
+                return 0
+            r = register()
+            _save(r["api_key"])
+            print(f"Saved a test key to {CREDENTIALS}. It works on the sample datasets only.")
+            print("For your own data, create a live key at https://datagoat.io/keys and set DATAGOAT_API_KEY.")
+            return 0
+        if args.cmd == "describe":
+            print(json.dumps(Client(api_key="dgk_test_none").describe(), indent=2))
+            return 0
+        if args.cmd == "verify":
+            with open(args.verdict) as f1, open(args.signature) as f2:
+                status = Client(api_key="dgk_test_none").verify(json.load(f1), json.load(f2))
+            print(status)
+            return 0 if status == "valid" else 1
+        dg = Client()
+        if args.cmd == "sample":
+            out = dg.ask({"churn": yesno("churned", outcome_is_desirable=False),
+                          "risk": score("churned", outcome_is_desirable=False)},
+                         dataset_id="sample:saas_churn", entity_column="customer_id",
+                         subject_kind="org", cases={"ids": ["cust_0001"]})
+            return _print_and_verify(dg, out)
+        if args.cmd == "ask":
+            cases = {"ids": [c.strip() for c in args.cases.split(",") if c.strip()]} if args.cases else None
+            out = dg.ask(json.loads(args.questions), dataset_id=args.data, entity_column=args.entity,
+                         subject_kind=args.kind, cases=cases)
+            return _print_and_verify(dg, out)
+    except DatagoatError as e:
+        print(f"{e.problem.code}: {e.problem.detail}\n{e.problem.remedy}", file=sys.stderr)
+        return 1
+    except ValueError as e:
+        print(str(e), file=sys.stderr)
+        return 2
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

datagoat-1.0.0/datagoat/client.py

@@ -0,0 +1,233 @@
+"""The Datagoat client. Standard library only.
+
+    from datagoat import Client, yesno
+    dg = Client()                     # DATAGOAT_API_KEY, else the key `datagoat signup` saved
+    dg.ask({"churn": yesno("churned", outcome_is_desirable=False)},
+           dataset_id="sample:saas_churn", entity_column="customer_id",
+           subject_kind="org", cases={"ids": ["cust_0001"]})
+"""
+from __future__ import annotations
+
+import json
+import os
+import time
+import urllib.error
+import urllib.request
+import uuid
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Callable, Dict, Mapping, Optional, Sequence
+
+from ._version import __version__
+
+DEFAULT_BASE = "https://api.datagoat.io"
+CREDENTIALS = Path(os.environ.get("DATAGOAT_CONFIG_DIR", Path.home() / ".config" / "datagoat")) / "credentials"
+
+
+@dataclass(frozen=True)
+class Problem:
+    status: int
+    code: str
+    detail: str
+    remedy: str
+    field: Optional[str] = None
+    request_id: Optional[str] = None
+
+
+class DatagoatError(Exception):
+    """A problem the API answered with. Read `problem.code` and `problem.remedy`."""
+
+    def __init__(self, p: Problem) -> None:
+        super().__init__(f"{p.code}: {p.detail} ({p.remedy})")
+        self.problem = p
+
+    @property
+    def retryable(self) -> bool:
+        return self.problem.status in (429, 502, 503, 504)
+
+
+def _json_default(o: Any) -> Any:
+    import datetime as _dt
+    if isinstance(o, _dt.date):
+        return o.isoformat()
+    raise TypeError(f"Object of type {type(o).__name__} is not JSON serializable")
+
+
+def saved_key() -> Optional[str]:
+    try:
+        return CREDENTIALS.read_text().strip() or None
+    except OSError:
+        return None
+
+
+def _source(dataset_id, rows, csv, fetch_url, fetch_headers) -> 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 is not None}
+    if len(data) != 1:
+        raise ValueError("pass exactly one of dataset_id, rows, csv, fetch_url")
+    if fetch_headers:
+        if "fetch_url" not in data:
+            raise ValueError("fetch_headers needs fetch_url")
+        data["fetch_headers"] = dict(fetch_headers)
+    return data
+
+
+class Client:
+    #: The longest Datagoat keeps a first fit running. `ask` never waits longer than this.
+    RUN_TIMEOUT_S = 900.0
+
+    def __init__(self, api_key: Optional[str] = None, *, base_url: Optional[str] = None, timeout: float = 320.0) -> None:
+        key = api_key or os.environ.get("DATAGOAT_API_KEY") or saved_key()
+        if not key:
+            raise ValueError("no API key: pass api_key, set DATAGOAT_API_KEY, or run `datagoat signup`")
+        self._auth = f"Bearer {key}"
+        self.base = (base_url or os.environ.get("DATAGOAT_BASE_URL") or DEFAULT_BASE).rstrip("/")
+        self.timeout = timeout
+        self.test_mode = key.startswith("dgk_test_")
+
+    # -- transport ------------------------------------------------------------ #
+    @staticmethod
+    def _request(url: str, body: Optional[Mapping[str, Any]], headers: Mapping[str, str], timeout: float) -> Dict[str, Any]:
+        data = json.dumps(body or {}, default=_json_default, allow_nan=False).encode()
+        req = urllib.request.Request(url, data=data, method="POST", headers={
+            "content-type": "application/json", "user-agent": f"datagoat-python/{__version__}", **headers})
+        try:
+            with urllib.request.urlopen(req, timeout=timeout) as r:  # noqa: S310 - fixed https base
+                return json.load(r)
+        except urllib.error.HTTPError as e:
+            try:
+                p = json.load(e)
+            except Exception:  # noqa: BLE001
+                p = {}
+            raise DatagoatError(Problem(e.code, p.get("code", "http_error"), p.get("detail", str(e.reason)),
+                                        p.get("remedy", "see https://datagoat.io/docs"), p.get("field"),
+                                        p.get("request_id") or e.headers.get("x-request-id"))) from None
+
+    def _call(self, op: str, body: Optional[Mapping[str, Any]] = None, *, keyless: bool = False) -> Dict[str, Any]:
+        return self._request(f"{self.base}/v1/{op}", body, {} if keyless else {"authorization": self._auth}, self.timeout)
+
+    def _follow(self, out: Dict[str, Any], *, wait: bool, timeout_s: Optional[float],
+                on_progress: Optional[Callable[[Dict[str, Any]], None]]) -> Dict[str, Any]:
+        """Follow a pending task to its answer, bounded. Never re-submits: that would fit twice."""
+        deadline = time.monotonic() + (self.RUN_TIMEOUT_S if timeout_s is None else timeout_s)
+        while wait and out.get("status") == "pending":
+            if on_progress is not None:
+                on_progress(out)
+            task_id = out["task_id"]
+            if time.monotonic() >= deadline:
+                raise DatagoatError(Problem(504, "poll_timeout", "the task is still running",
+                                            f"poll({task_id!r}) later; do not re-submit (that would fit twice)"))
+            time.sleep(max(0.5, out.get("retry_after_ms", 2000) / 1000))
+            out = self.poll(task_id)
+        return out
+
+    # -- the one call ----------------------------------------------------------- #
+    def ask(self, questions: Mapping[str, Mapping[str, Any]], *, entity_column: str, subject_kind: str,
+            dataset_id: Optional[str] = None, rows: Optional[Sequence[Mapping[str, Any]]] = None,
+            csv: Optional[str] = None, fetch_url: Optional[str] = None, fetch_headers: Optional[Mapping[str, str]] = None,
+            cases: Optional[Mapping[str, Any]] = None, time_column: Optional[str] = None,
+            shape: Optional[Mapping[str, Any]] = None, band: bool = False,
+            acknowledge_decision_support: bool = False, idempotency_key: Optional[str] = None,
+            wait: bool = True, timeout_s: Optional[float] = None,
+            on_progress: Optional[Callable[[Dict[str, Any]], None]] = None) -> Dict[str, Any]:
+        """Ask typed questions about cases, answered from a record of past outcomes.
+
+        Build questions with `yesno`, `score`, `choice`, `rank`. `cases` is {"ids": [...]} or
+        {"rows": [...]}; omit it to rank the whole record. When the record is not one row per case,
+        pass `shape` (build it with `events`, `series`, `panel`, `signals` or `traces`) and
+        `time_column`. Each answer's `state` is answered, refused or not_yet; a refusal is an
+        answer, and retrying returns the same one.
+        """
+        if not questions:
+            raise ValueError("ask needs at least one question")
+        for name, q in questions.items():
+            if not isinstance(q, Mapping) or "type" not in q:
+                raise ValueError(f"question {name!r} needs a type: yesno | score | choice | rank")
+        body: Dict[str, Any] = {
+            "data": _source(dataset_id, list(rows) if rows is not None else None, csv, fetch_url, fetch_headers),
+            "entity_column": entity_column, "subject_kind": subject_kind,
+            "questions": {n: dict(q) for n, q in questions.items()},
+            "idempotency_key": idempotency_key or str(uuid.uuid4()),
+        }
+        if cases is not None:
+            body["cases"] = dict(cases)
+        if time_column:
+            body["time_column"] = time_column
+        if shape is not None:
+            body["shape"] = dict(shape)
+        if band:
+            body["band"] = True
+        if acknowledge_decision_support:
+            body["acknowledge_decision_support"] = True
+        return self._follow(self._call("ask", body), wait=wait, timeout_s=timeout_s, on_progress=on_progress)
+
+    # -- supporting operations ----------------------------------------------------- #
+    def add_dataset(self, *, rows: Optional[Sequence[Mapping[str, Any]]] = None, csv: Optional[str] = None,
+                    fetch_url: Optional[str] = None, fetch_headers: Optional[Mapping[str, str]] = None,
+                    upload: bool = False, dataset_id: Optional[str] = None, filename: Optional[str] = None) -> Dict[str, Any]:
+        """Store a table once and ask about it by dataset_id. Pass dataset_id with rows to append a piece."""
+        body = {k: v for k, v in {"rows": list(rows) if rows is not None else None, "csv": csv, "fetch_url": fetch_url,
+                                   "fetch_headers": dict(fetch_headers) if fetch_headers else None,
+                                   "upload": True if upload else None, "dataset_id": dataset_id, "filename": filename}.items() if v is not None}
+        return self._call("add-dataset", body)
+
+    def upload_rows(self, rows: Sequence[Mapping[str, Any]], *, chunk_size: int = 5000) -> str:
+        """Send a large table in pieces and return its dataset_id."""
+        rows = list(rows)
+        if not rows:
+            raise ValueError("no rows")
+        first = self.add_dataset(rows=rows[:chunk_size])
+        for i in range(chunk_size, len(rows), chunk_size):
+            self.add_dataset(dataset_id=first["dataset_id"], rows=rows[i:i + chunk_size])
+        return first["dataset_id"]
+
+    def upload_file(self, path: str) -> str:
+        """Upload a CSV file of any size through a presigned URL and return its dataset_id."""
+        d = self.add_dataset(upload=True, filename=os.path.basename(path))
+        with open(path, "rb") as f:
+            req = urllib.request.Request(d["upload_url"], data=f.read(), method="PUT", headers={"content-type": "text/csv"})
+            with urllib.request.urlopen(req, timeout=self.timeout):  # noqa: S310 - presigned URL we were given
+                pass
+        return d["dataset_id"]
+
+    def delete_dataset(self, dataset_id: str) -> Dict[str, Any]:
+        """Delete a stored dataset now. Otherwise it is deleted 24 hours after its last use."""
+        return self._call("delete-dataset", {"dataset_id": dataset_id})
+
+    def poll(self, task_id: str) -> Dict[str, Any]:
+        return self._call("poll", {"task_id": task_id})
+
+    def preflight(self, dataset_id: str, *, outcome_column: Optional[str] = None,
+                  predictors: Optional[Sequence[str]] = None) -> Dict[str, Any]:
+        body: Dict[str, Any] = {"dataset_id": dataset_id}
+        if outcome_column:
+            body["outcome_column"] = outcome_column
+        if predictors:
+            body["predictors"] = list(predictors)
+        return self._call("preflight", body)
+
+    def report_outcomes(self, model_ref: str, outcomes: Sequence[Mapping[str, Any]]) -> Dict[str, Any]:
+        """Record what really happened: [{entity_id, outcome, observed_at, event_id?}]."""
+        return self._call("report-outcomes", {"model_ref": model_ref, "outcomes": [dict(o) for o in outcomes]})
+
+    def drift(self, model_ref: str) -> Dict[str, Any]:
+        return self._call("drift", {"model_ref": model_ref})
+
+    def verify(self, verdict: Mapping[str, Any], signature: Optional[Mapping[str, Any]]) -> str:
+        """valid | invalid_signature | expired | unknown_key. Needs no key. Never act on anything but valid."""
+        if not signature:
+            return "invalid_signature"
+        return self._call("verify", {"verdict": dict(verdict), "signature": dict(signature)}, keyless=True)["status"]
+
+    def verify_all(self, answer: Mapping[str, Any]) -> bool:
+        """True when every Verdict in an ask answer is valid."""
+        return all(self.verify(v["verdict"], v.get("signature")) == "valid"
+                   for a in (answer.get("answers") or {}).values() for v in a.get("verdicts", []))
+
+    def describe(self) -> Dict[str, Any]:
+        return self._call("describe", {}, keyless=True)
+
+
+def register(base_url: Optional[str] = None, timeout: float = 30.0) -> Dict[str, Any]:
+    """Get a free test key (sample datasets only). No account, no key needed."""
+    base = (base_url or os.environ.get("DATAGOAT_BASE_URL") or DEFAULT_BASE).rstrip("/")
+    return Client._request(f"{base}/v1/agents/register", {}, {}, timeout)

datagoat-1.0.0/datagoat/langchain.py

@@ -0,0 +1,37 @@
+"""LangChain tools: `from datagoat.langchain import datagoat_tools` then give them to an agent."""
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from .client import Client
+
+
+def datagoat_tools(dg: Client) -> List[Any]:
+    from langchain_core.tools import tool
+
+    @tool
+    def dg_ask(questions: Dict[str, Any], entity_column: str, subject_kind: str, dataset_id: Optional[str] = None,
+               rows: Optional[List[Dict[str, Any]]] = None, cases: Optional[Dict[str, Any]] = None,
+               acknowledge_decision_support: bool = False) -> Dict[str, Any]:
+        """Ask yes/no, score, choice and rank questions about cases, answered from a table of past outcomes.
+        Read answers[name].state first: answered, refused (do not retry) or not_yet. choice needs
+        outcome_is_desirable. Never state a number the answer does not contain."""
+        return dg.ask(questions, entity_column=entity_column, subject_kind=subject_kind, dataset_id=dataset_id,
+                      rows=rows, cases=cases, acknowledge_decision_support=acknowledge_decision_support)
+
+    @tool
+    def dg_verify(verdict: Dict[str, Any], signature: Dict[str, Any]) -> str:
+        """Check a Verdict is genuine and unaltered: valid | invalid_signature | expired | unknown_key."""
+        return dg.verify(verdict, signature)
+
+    @tool
+    def dg_report_outcomes(model_ref: str, outcomes: List[Dict[str, Any]]) -> Dict[str, Any]:
+        """Record what really happened for cases answered under model_ref: [{entity_id, outcome, observed_at, event_id}]."""
+        return dg.report_outcomes(model_ref, outcomes)
+
+    @tool
+    def dg_describe() -> Dict[str, Any]:
+        """Question types, prices, limits and the free sample datasets with ready-to-run asks."""
+        return dg.describe()
+
+    return [dg_ask, dg_verify, dg_report_outcomes, dg_describe]

datagoat-1.0.0/datagoat/questions.py

@@ -0,0 +1,112 @@
+"""Question and shape builders for `Client.ask`, as plain dicts.
+
+Each builder sends only what you state. `outcome_is_desirable` is never filled in for you: it says
+whether the outcome is one you want, and a default would decide that for you. It is optional
+everywhere except `choice`, where "the best option" means nothing without it.
+
+    yesno   the chance the outcome happens for each case
+    score   that chance as a level: unlikely | possible | likely | very_likely by default
+    choice  the best option: the likeliest to give an outcome you want, the least likely to give
+            one you avoid; each answer also carries most_likely and least_likely
+    rank    cases in order of the chance
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, Mapping, Optional, Sequence
+
+
+def _stated(**kw: Any) -> Dict[str, Any]:
+    return {k: (list(v) if isinstance(v, tuple) else v) for k, v in kw.items() if v is not None}
+
+
+def yesno(outcome_column: str, *, outcome_is_desirable: Optional[bool] = None,
+          positive_values: Optional[Sequence[str]] = None, refit_of: Optional[str] = None) -> Dict[str, Any]:
+    """The chance `outcome_column` comes out yes for each case."""
+    return {"type": "yesno", **_stated(outcome_column=outcome_column, outcome_is_desirable=outcome_is_desirable,
+                                       positive_values=positive_values, refit_of=refit_of)}
+
+
+def score(outcome_column: str, *, levels: Optional[Sequence[str]] = None, cuts: Optional[Sequence[float]] = None,
+          outcome_is_desirable: Optional[bool] = None, positive_values: Optional[Sequence[str]] = None,
+          refit_of: Optional[str] = None) -> Dict[str, Any]:
+    """The chance as a named level. `levels` lowest first; `cuts` one fewer, ascending, in (0, 1).
+    Omit both for unlikely < 0.25 <= possible < 0.50 <= likely < 0.75 <= very_likely."""
+    return {"type": "score", **_stated(outcome_column=outcome_column, levels=levels, cuts=cuts,
+                                       outcome_is_desirable=outcome_is_desirable,
+                                       positive_values=positive_values, refit_of=refit_of)}
+
+
+def choice(*, outcome_is_desirable: bool, option_column: Optional[str] = None, options: Optional[Sequence[str]] = None,
+           outcome_column: Optional[str] = None, option_outcomes: Optional[Mapping[str, str]] = None,
+           positive_values: Optional[Sequence[str]] = None) -> Dict[str, Any]:
+    """The best option for each case. Two forms:
+
+    - `option_column` + `options` + `outcome_column`: which value of a column you control (a
+      contract, a team, a channel) is best for this case. Refused as `option_not_in_pattern` when
+      the record shows the column makes no difference.
+    - `option_outcomes`: {option: outcome_column}, one learned outcome per option.
+
+    `outcome_is_desirable` is required: the best option is the likeliest to give an outcome you
+    want and the least likely to give one you avoid."""
+    if not isinstance(outcome_is_desirable, bool):
+        raise TypeError("choice needs outcome_is_desirable=True or False")
+    if (option_outcomes is None) == (option_column is None):
+        raise ValueError("choice takes EITHER option_column + options + outcome_column, OR option_outcomes")
+    return {"type": "choice", **_stated(option_column=option_column, options=options,
+                                        outcome_column=outcome_column,
+                                        option_outcomes=dict(option_outcomes) if option_outcomes else None,
+                                        outcome_is_desirable=outcome_is_desirable,
+                                        positive_values=positive_values)}
+
+
+def rank(outcome_column: str, *, top_k: Optional[int] = None, outcome_is_desirable: Optional[bool] = None,
+         positive_values: Optional[Sequence[str]] = None, refit_of: Optional[str] = None) -> Dict[str, Any]:
+    """The cases (or, with no cases, the whole record) in order of the chance, highest first."""
+    return {"type": "rank", **_stated(outcome_column=outcome_column, top_k=top_k,
+                                      outcome_is_desirable=outcome_is_desirable,
+                                      positive_values=positive_values, refit_of=refit_of)}
+
+
+# -- record shapes ------------------------------------------------------------------ #
+# Pass one of these as `shape=` (with `time_column=`) when the record is not one row per case.
+
+def _shape(kind: str, **fields: Any) -> Dict[str, Any]:
+    return {"kind": kind, **{k: v for k, v in fields.items() if v is not None}}
+
+
+def events(*, label: Mapping[str, Any], event_column: Optional[str] = None, value_columns: Optional[Sequence[str]] = None,
+           horizon_days: Optional[int] = None, lookback_days: Optional[Sequence[int]] = None, as_of: Optional[str] = None) -> Dict[str, Any]:
+    """An event log. label is {"lapsed": True} (outcome lapsed_{horizon_days}d) or {"name": ..., "when": predicate}
+    (outcome {name}_next_{horizon_days}d)."""
+    return _shape("events", label=dict(label), event_column=event_column, value_columns=list(value_columns) if value_columns else None,
+                  horizon_days=horizon_days, lookback_days=list(lookback_days) if lookback_days else None, as_of=as_of)
+
+
+def series(*, value_columns: Sequence[str], windows: Sequence[int]) -> Dict[str, Any]:
+    """A time series with an outcome on each row. windows: [3, 6], [7, 30] or [4, 12] periods."""
+    return _shape("series", value_columns=list(value_columns), windows=list(windows))
+
+
+def panel(*, trend_of: Optional[str] = None, window_of: Optional[str] = None, direction: Optional[str] = None,
+          alpha: Optional[float] = None, periods: Optional[int] = None, agg: Optional[str] = None,
+          min_history: Optional[int] = None) -> Dict[str, Any]:
+    """Periods per case. The outcome is a significant trend in `trend_of`, or `window_of` over the final periods."""
+    if (trend_of is None) == (window_of is None):
+        raise ValueError("a panel reads its outcome from trend_of OR window_of")
+    label = ({"trend_of": trend_of, "direction": direction, "alpha": alpha} if trend_of
+             else {"window_of": window_of, "periods": periods, "agg": agg})
+    return _shape("panel", label={k: v for k, v in label.items() if v is not None}, min_history=min_history)
+
+
+def signals(*, signal_columns: Sequence[str], windows: Sequence[int], snapshot_every: str, horizon: int,
+            event_column: Optional[str] = None, event_start_column: Optional[str] = None, event_end_column: Optional[str] = None,
+            min_history: Optional[int] = None, as_of: Optional[str] = None) -> Dict[str, Any]:
+    """Sensor readings with event intervals in the same table. The outcome: an event starts within `horizon` snapshots."""
+    return _shape("signals", signal_columns=list(signal_columns), windows=list(windows), snapshot_every=snapshot_every, horizon=horizon,
+                  event_column=event_column, event_start_column=event_start_column, event_end_column=event_end_column,
+                  min_history=min_history, as_of=as_of)
+
+
+def traces(*, agent_column: Optional[str] = None, task_column: Optional[str] = None, tool_column: Optional[str] = None) -> Dict[str, Any]:
+    """A log of runs, one row per run, with a yes/no outcome column."""
+    return _shape("traces", agent_column=agent_column, task_column=task_column, tool_column=tool_column)

datagoat-1.0.0/datagoat.egg-info/PKG-INFO

@@ -0,0 +1,35 @@
+Metadata-Version: 2.4
+Name: datagoat
+Version: 1.0.0
+Summary: Ask yes/no, score, choice and rank questions about cases. Datagoat answers from what happened to cases like them: deterministic, with reasons, signed.
+License: Apache-2.0
+Project-URL: Homepage, https://datagoat.io
+Project-URL: Documentation, https://datagoat.io/docs
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.3; extra == "langchain"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pydantic; extra == "test"
+
+# datagoat
+
+Ask yes/no, score, choice and rank questions about cases. Datagoat answers from what happened to
+cases like them: deterministic, with reasons, and a signed Verdict. It refuses rather than guess.
+
+```bash
+pip install datagoat
+datagoat signup      # a free test key for the sample datasets
+datagoat sample      # ask about sample:saas_churn and verify the answer
+```
+
+```python
+from datagoat import Client, yesno, score
+dg = Client()        # reads DATAGOAT_API_KEY, or the key `datagoat signup` saved
+out = dg.ask({"churn": yesno("churned", outcome_is_desirable=False)},
+             dataset_id="sample:saas_churn", entity_column="customer_id",
+             subject_kind="org", cases={"ids": ["cust_0001"]})
+```
+
+Docs: https://datagoat.io/docs

datagoat-1.0.0/datagoat.egg-info/SOURCES.txt

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

datagoat-1.0.0/datagoat.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

datagoat-1.0.0/datagoat.egg-info/entry_points.txt

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

datagoat-1.0.0/datagoat.egg-info/requires.txt

@@ -0,0 +1,7 @@
+
+[langchain]
+langchain-core>=0.3
+
+[test]
+pytest
+pydantic

datagoat-1.0.0/datagoat.egg-info/top_level.txt

@@ -0,0 +1 @@
+datagoat

datagoat-1.0.0/pyproject.toml

@@ -0,0 +1,26 @@
+[project]
+name = "datagoat"
+version = "1.0.0"
+description = "Ask yes/no, score, choice and rank questions about cases. Datagoat answers from what happened to cases like them: deterministic, with reasons, signed."
+requires-python = ">=3.9"
+dependencies = []
+license = {text = "Apache-2.0"}
+readme = "README.md"
+
+[project.urls]
+Homepage = "https://datagoat.io"
+Documentation = "https://datagoat.io/docs"
+
+[project.optional-dependencies]
+langchain = ["langchain-core>=0.3"]
+test = ["pytest", "pydantic"]
+
+[project.scripts]
+datagoat = "datagoat.cli:main"
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+include = ["datagoat*"]

datagoat-1.0.0/setup.cfg

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

datagoat-1.0.0/tests/test_client.py

@@ -0,0 +1,167 @@
+"""What the client puts on the wire, and how it waits."""
+import itertools
+import json
+import threading
+from http.server import BaseHTTPRequestHandler, HTTPServer
+
+import pytest
+
+from datagoat import Client, DatagoatError, choice, rank, score, yesno
+from datagoat import cli
+
+SEEN = []
+
+
+def serve(script, status=200):
+    it = iter(script)
+
+    class H(BaseHTTPRequestHandler):
+        def log_message(self, *a):
+            pass
+
+        def do_POST(self):
+            n = int(self.headers.get("content-length", 0))
+            SEEN.append((self.path, json.loads(self.rfile.read(n) or b"{}"), self.headers.get("authorization")))
+            body, code = next(it), status
+            if isinstance(body, tuple):
+                body, code = body
+            self.send_response(code)
+            self.send_header("content-type", "application/json")
+            self.end_headers()
+            self.wfile.write(json.dumps(body).encode())
+
+    srv = HTTPServer(("127.0.0.1", 0), H)
+    threading.Thread(target=srv.serve_forever, daemon=True).start()
+    return srv, f"http://127.0.0.1:{srv.server_port}"
+
+
+DONE = {"status": "done", "task_id": "tk_1", "answers": {"churn": {"type": "yesno", "state": "answered", "verdicts": []}}}
+
+
+def setup_function(_):
+    SEEN.clear()
+
+
+def test_ask_body_is_the_public_contract():
+    srv, url = serve([DONE])
+    out = Client(api_key="dgk_test_x", base_url=url).ask(
+        {"churn": yesno("churned", outcome_is_desirable=False)}, dataset_id="sample:saas_churn",
+        entity_column="customer_id", subject_kind="org", cases={"ids": ["cust_0001"]})
+    path, body, auth = SEEN[-1]
+    assert path == "/v1/ask" and out == DONE and auth == "Bearer dgk_test_x"
+    assert body["data"] == {"dataset_id": "sample:saas_churn"}
+    assert body["questions"] == {"churn": {"type": "yesno", "outcome_column": "churned", "outcome_is_desirable": False}}
+    assert body["idempotency_key"]
+    for k in ("band", "time_column", "acknowledge_decision_support"):
+        assert k not in body
+    srv.shutdown()
+
+
+def test_builders_send_only_what_is_stated_and_choice_demands_polarity():
+    assert yesno("y") == {"type": "yesno", "outcome_column": "y"}
+    assert "outcome_is_desirable" not in score("y") and "outcome_is_desirable" not in rank("y")
+    assert score("y", levels=("lo", "hi"), cuts=(0.4,))["levels"] == ["lo", "hi"]
+    c = choice(option_column="contract", options=["a", "b"], outcome_column="churned", outcome_is_desirable=False)
+    assert c["outcome_is_desirable"] is False
+    with pytest.raises(TypeError):
+        choice(option_column="contract", options=["a", "b"], outcome_column="churned")  # type: ignore[call-arg]
+    with pytest.raises(ValueError):
+        choice(outcome_is_desirable=True)
+
+
+def test_a_pending_fit_is_followed_and_bounded():
+    pending = {"status": "pending", "task_id": "tk_9", "retry_after_ms": 0}
+    srv, url = serve([pending, pending, DONE])
+    out = Client(api_key="dgk_test_x", base_url=url).ask({"q": yesno("y")}, rows=[{"a": 1}], entity_column="a",
+                                                          subject_kind="org", cases={"ids": ["1"]})
+    assert out == DONE
+    assert [p for p, _, _ in SEEN] == ["/v1/ask", "/v1/poll", "/v1/poll"]
+    assert SEEN[1][1] == {"task_id": "tk_9"}
+    srv.shutdown()
+    srv, url = serve(itertools.repeat(pending))
+    with pytest.raises(DatagoatError) as e:
+        Client(api_key="dgk_test_x", base_url=url).ask({"q": yesno("y")}, rows=[{"a": 1}], entity_column="a",
+                                                        subject_kind="org", cases={"ids": ["1"]}, timeout_s=0.1)
+    assert e.value.problem.code == "poll_timeout" and "do not re-submit" in e.value.problem.remedy
+    srv.shutdown()
+
+
+def test_problems_are_raised_with_code_remedy_and_field():
+    prob = {"type": "https://datagoat.io/problems/unknown_case_id", "title": "t", "status": 422, "detail": "not in the record",
+            "code": "unknown_case_id", "remedy": "send ids that appear", "field": "cases.ids", "request_id": "r1"}
+    srv, url = serve([(prob, 422)])
+    with pytest.raises(DatagoatError) as e:
+        Client(api_key="dgk_live_x", base_url=url).ask({"q": yesno("y")}, dataset_id="ds_x", entity_column="a",
+                                                        subject_kind="org", cases={"ids": ["nope"]})
+    assert (e.value.problem.code, e.value.problem.field, e.value.problem.request_id) == ("unknown_case_id", "cases.ids", "r1")
+    assert not e.value.retryable
+    srv.shutdown()
+
+
+def test_verify_sends_no_key(monkeypatch):
+    srv, url = serve([{"status": "valid"}])
+    assert Client(api_key="dgk_live_secret", base_url=url).verify({"verdict_id": "v", "kind": "k"}, {"protected": "p", "signature": "s"}) == "valid"
+    assert SEEN[-1][2] is None, "verification is keyless: the key is never sent"
+    srv.shutdown()
+
+
+def test_local_mistakes_fail_before_any_request():
+    dg = Client(api_key="dgk_test_x", base_url="http://127.0.0.1:9")
+    with pytest.raises(ValueError):
+        dg.ask({}, dataset_id="sample:saas_churn", entity_column="a", subject_kind="org")
+    with pytest.raises(ValueError):
+        dg.ask({"q": yesno("y")}, dataset_id="x", rows=[{"a": 1}], entity_column="a", subject_kind="org")
+    with pytest.raises(ValueError):
+        dg.ask({"q": {"outcome_column": "y"}}, dataset_id="x", entity_column="a", subject_kind="org")
+
+
+def test_the_key_comes_from_env_then_the_saved_file(monkeypatch, tmp_path):
+    import datagoat.client as c
+    monkeypatch.setattr(c, "CREDENTIALS", tmp_path / "credentials")
+    monkeypatch.delenv("DATAGOAT_API_KEY", raising=False)
+    with pytest.raises(ValueError, match="datagoat signup"):
+        Client()
+    (tmp_path / "credentials").write_text("dgk_test_saved\n")
+    assert Client().test_mode
+    monkeypatch.setenv("DATAGOAT_API_KEY", "dgk_live_env")
+    assert not Client().test_mode
+
+
+def test_cli_sample_asks_and_verifies(monkeypatch, capsys):
+    calls = []
+
+    class Fake:
+        def ask(self, questions, **kw):
+            calls.append((questions, kw))
+            return {"status": "done", "answers": {"churn": {"state": "answered", "verdicts": [{"verdict": {}, "signature": {}}]}}}
+
+        def verify_all(self, out):
+            return True
+
+    monkeypatch.setattr(cli, "Client", lambda *a, **k: Fake())
+    assert cli.main(["sample"]) == 0
+    (q, kw), = calls
+    assert kw["dataset_id"] == "sample:saas_churn" and q["churn"]["outcome_is_desirable"] is False
+    assert "verify: valid" in capsys.readouterr().out
+
+
+def test_shapes_are_sent_as_stated_and_delete_dataset_calls_its_route():
+    from datagoat import events, panel, series, signals, traces
+    SEEN.clear()
+    srv, base = serve([DONE, {"dataset_id": "ds_x", "deleted": True}])
+    dg = Client("dgk_live_x", base_url=base)
+    dg.ask({"quiet": yesno("lapsed_90d", outcome_is_desirable=False)}, dataset_id="sample:customer_events",
+           entity_column="customer_id", subject_kind="org", time_column="date", cases={"ids": ["cust_0001"]},
+           shape=events(label={"lapsed": True}, event_column="event", horizon_days=90))
+    body = SEEN[0][1]
+    assert body["shape"] == {"kind": "events", "label": {"lapsed": True}, "event_column": "event", "horizon_days": 90}
+    assert body["time_column"] == "date"
+    assert dg.delete_dataset("ds_x") == {"dataset_id": "ds_x", "deleted": True}
+    assert SEEN[1][0] == "/v1/delete-dataset"
+    assert series(value_columns=["sales"], windows=[4, 12]) == {"kind": "series", "value_columns": ["sales"], "windows": [4, 12]}
+    assert panel(trend_of="usage", direction="down") == {"kind": "panel", "label": {"trend_of": "usage", "direction": "down"}}
+    assert signals(signal_columns=["v"], windows=[1, 3, 7], snapshot_every="1d", horizon=3)["kind"] == "signals"
+    assert traces(tool_column="tool") == {"kind": "traces", "tool_column": "tool"}
+    with pytest.raises(ValueError):
+        panel()
+    srv.shutdown()