SDKs

Python and TypeScript clients for the Datagoat API. Both send the same requests the API reference describes, wait for pending fits, and raise problems as typed errors.

Python

pip install datagoat                  # Python 3.9+, no dependencies
pip install "datagoat[langchain]"     # adds LangChain tools

from datagoat import Client, yesno, score, choice, rank, events

dg = Client()      # DATAGOAT_API_KEY, or the key `datagoat signup` saved
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"]},
)
out["answers"]["churn"]["cases"][0]["p"]

Questions and shapes

Builders return plain dicts and send only what you state.

Builder	Makes
`yesno(outcome_column, *, outcome_is_desirable=None, positive_values=None, refit_of=None)`	a yesno question
`score(outcome_column, *, levels=None, cuts=None, …)`	a score question
`choice(, outcome_is_desirable, option_column=…, options=…, outcome_column=…)` or `choice(, outcome_is_desirable, option_outcomes=…)`	a choice question
`rank(outcome_column, *, top_k=None, …)`	a rank question
`events(…)`, `series(…)`, `panel(…)`, `signals(…)`, `traces(…)`	a shape, passed as `shape=` with `time_column=`

`Client`

Method
`Client(api_key=None, *, base_url=None, timeout=320.0)`	reads `DATAGOAT_API_KEY` when `api_key` is left out
`ask(questions, *, entity_column, subject_kind, dataset_id= \| rows= \| csv= \| fetch_url=, cases=None, time_column=None, shape=None, band=False, acknowledge_decision_support=False, idempotency_key=None, wait=True, timeout_s=None, on_progress=None)`	the one call. Waits for a pending fit unless `wait=False`. Sends a fresh `idempotency_key` if you don't.
`add_dataset(rows= \| csv= \| fetch_url= \| upload=True, dataset_id=None)`	store a record, or append a piece to one
`upload_rows(rows, chunk_size=5000)` / `upload_file(path)`	store a large record in pieces, or through a presigned upload; returns the `dataset_id`
`delete_dataset(dataset_id)`	delete a stored dataset now
`poll(task_id)`	the status of a pending ask
`preflight(dataset_id, outcome_column=None)`	check a table before the first ask
`report_outcomes(model_ref, outcomes)`	record what happened
`attest(model_ref, entity_id, lever_token, post_value, acted_at, event_id=None)`	record that a case was acted on through a lever
`evidence(model_ref)`	did acting work?
`drift(model_ref)`	has the pattern moved?
`verify(verdict, signature)` / `verify_all(answer)`	check Verdicts; `verify_all` is `True` when every Verdict in an answer is valid
`describe()`	question types, shapes, limits, prices and the samples

Errors

A problem raises DatagoatError. Its problem has status, code, detail, remedy, field and request_id. retryable is true for 429, 502, 503 and 504. A refusal is not an error: it is an answer with state: "refused".

CLI

datagoat signup                     # a free test key, saved locally
datagoat sample                     # ask about sample:saas_churn and verify the answer
datagoat describe
datagoat ask '{"churn": {"type": "yesno", "outcome_column": "churned"}}' \
  --data sample:saas_churn --entity customer_id --cases cust_0001
datagoat verify verdict.json signature.json

LangChain

from datagoat import Client
from datagoat.langchain import datagoat_tools
tools = datagoat_tools(Client())     # dg_ask, dg_verify, dg_report_outcomes, dg_attest, dg_evidence, dg_describe

TypeScript

npm install @datagoat/sdk            # Node 20+, no dependencies (uses fetch)

import { Datagoat, yesno, traces } from "@datagoat/sdk";

const dg = new Datagoat({ apiKey: process.env.DATAGOAT_API_KEY! });
const out = await dg.ask({ fail: yesno("failed", { outcome_is_desirable: false }) }, {
  data: { dataset_id: "sample:agent_traces" }, entity_column: "run_id", subject_kind: "event",
  time_column: "ts", shape: traces({ agent_column: "agent", task_column: "task", tool_column: "tool" }),
  cases: { ids: ["run_0001"] },
});

Export
`new Datagoat({ apiKey, baseUrl?, fetch? })`	the client
`ask(questions, { data, entity_column, subject_kind, cases?, time_column?, shape?, band?, acknowledge_decision_support?, idempotency_key?, wait?, timeoutMs? })`	the one call; waits for a pending fit by default (up to 15 minutes)
`addDataset`, `deleteDataset`, `poll`, `preflight`, `reportOutcomes`, `attest`, `evidence`, `drift`, `verify`, `verifyAll`, `describe`	the other operations (`attest` and `evidence` from 1.1.0)
`yesno`, `score`, `choice`, `rank`	question builders
`events`, `series`, `panel`, `signals`, `traces`	shape builders (1.1.0 and later)
`register(baseUrl?)`	a free test key
`DatagoatError`	`.problem` (`code`, `detail`, `remedy`, `field`, `request_id`) and `.retryable`