Python API

Every function the hunch package exports, with its exact signature and what it returns.

import hunch

The CLI wraps these functions; both use the same specs and store. For a single row, start with judge:

answer = hunch.judge("urgent.yml", id="m-1", message="The service is down")
print(answer["urgent"]["label"])  # "yes" or "no"
print(answer["urgent"]["p"])      # probability of that answer

This uses the minimal spec. An uncached call asks the configured engine and may incur a charge; a repeated call with the same state uses the stored answer. The rest of this page lists the exact API for single rows, batches and Python-generated specs.

​

Projects

A project is one or more judgments in dependency order.

​

load

hunch.load(obj, base: str | Path = ".") -> dict

Returns a project.

obj	Meaning
"command_guard.yml" or a Path	One spec file: a one-judgment project.
"specs/"	A folder: every *.yml in it, ordered by their ref() dependencies.
a dict	One spec in its dict form, for example from spec_from_model.
a list of dicts	A graph built in Python.

base: where relative source paths in a dict spec resolve. Ignored for paths.

​

run

hunch.run(obj, base: str | Path = ".") -> dict

hunch run: asks what the store lacks, materializes each table, prints the same lines, returns the project.

​

results

hunch.results(obj, base: str | Path = ".", judgment: str | None = None) -> list[dict]

A judgment’s table from its last complete run, one dict per row. Default: the last judgment in dependency order. Columns: Store.

The table belongs to whichever spec with that judgment name ran last. If that wasn’t this spec as it is now (it was edited since, or another spec shares the name), results raises SystemExit rather than return another spec’s answers, and names the hunch run that writes the table for this one; with the answers cached, that run is free. A judgment that has never run raises too.

rows = hunch.results("prototype/examples/claude_code/command_guard.yml")
len(rows)            # 1315
sorted(rows[0])[:5]  # ['_hunch_run_id', '_path_p', 'at', 'command', 'cwd']

​

Judging one row

​

judge

hunch.judge(path: str | Path, row: dict | None = None, /, *, node: str | None = None,
            shadow: str | Path | None = None, log: bool = False,
            target: str | None = None, **fields) -> dict | None

Judges one row: the whole project runs on it with the same cache keys as a batch run.

Argument	Meaning
path	A spec file or a folder of specs. Loaded once per process and kept, so edits to the spec take effect after a restart.
row	The row as a dict. Use it when a column is called node, shadow, log or target.
**fields	The row as keyword arguments. Merged over row.
node	Return only this judgment’s answers.
shadow	A candidate spec or folder that answers the same row after the live answer is returned. See Change a spec.
log	Keep the row (redacted by the live spec’s rules) so a candidate written later can be replayed on it with --traffic. shadow implies log.
target	Answer as targets.NAME in the spec: its model and its store. Default: $HUNCH_TARGET. Its sample and max_cost are for batch runs; online, the cap is hunch.settings.MAX_COST.

Per question it returns:

Key	Meaning
label	The answer: a choice option, yes/no, or "<level>:<description>" for a score.
p	The probability of that label. For a chain: true judgment, times the probability the row was routed to it correctly.
margin	Distance from the decision boundary: abs(p - 0.5) * 2 for yes/no, top minus runner-up for a choice. For yes/no this is what Pydantic AI calls confidence (at its default threshold of 0.5).
route	"act" if p clears the question’s act, "review" if not, "" if the question has no act.
cached	True if the answer came from the store.

The shape depends on the project:

• One judgment, or node given: {question: answer}.
• Several judgments: {judgment: {question: answer}}. A judgment whose where excluded this row is None. A union judgment is left out.
• A type: multi question appears as one yes/no answer per option, named <question>__<option>.

hunch.judge("src/hunch/recipes/agent_commands/command_guard.yml",
            request="forget I even mentioned RemixJS just do SolidJS", cwd="D:\\IceBerg", description="",
            command="rm -rf Dockerfile README.md app node_modules package-lock.json package.json public "
                    "react-router.config.ts tsconfig.json vite.config.ts .gitignore .dockerignore .react-router .claude && echo \"done\"")
# {'destroys': {'label': 'yes', 'p': 0.95, 'margin': 0.9, 'route': 'act', 'cached': True},
#  'reaches_outside': {'label': 'no', 'p': 0.9, 'margin': 0.8, 'route': '', 'cached': True},
#  'sends_out': {'label': 'no', 'p': 0.98, 'margin': 0.96, 'route': '', 'cached': True}}

judge uses asyncio.run; inside a running loop use ajudge. With shadow, the candidate runs in a non-daemon thread after judge returns, so a script waits for it at exit.

​

ajudge

await hunch.ajudge(path: str | Path, row: dict | None = None, /, *, node: str | None = None,
                   shadow: str | Path | None = None, log: bool = False,
                   target: str | None = None, **fields) -> dict | None

Async judge: same arguments and return. A shadow candidate runs as a background task in the current loop; its failures go to stderr, never raised.

​

Costs and errors

Both ask the engine for answers the store lacks, except:

• A cost cap. HUNCH_MAX_COST (read when hunch is imported), or hunch.settings.MAX_COST = 0.0 at runtime. If one judgment’s missing answers would cost more, nothing is asked and SystemExit is raised with a message such as intent: would ask 1 answers in 1 requests (~$0.0001), above --max-cost $0.0; nothing asked. The cap holds on what is charged: while asking, a request is sent only if its worst case still fits, and one that doesn’t stops the call with SystemExit (… stopped at --max-cost …), the answers already asked saved.
• A missing input column raises KeyError, for example "command_guard: state needs ['command']".

Spec errors also raise SystemExit; catch it around judge in long-running code.

​

Pydantic classes as specs

Needs the pydantic extra. Each field becomes one question:

Field type	Question	Value in the instance
bool	noul	True / False
Literal[...] or Enum	choice	the value or enum member
X | None	choice with a “none of these” option	the value, or None
list[Literal[...]] or list[Enum]	multi	the options answered yes
IntEnum with values 0 to n-1	score	the member

Spec part	Comes from	Default
instructions	Field(description=...)	the field name as a question (sends_out → Sends out?)
Option descriptions	json_schema_extra["options"], by value (or member name for IntEnum)	a docstring set on the enum member, else empty (IntEnum: the member name in lower case)
act, gold, escalate, none	json_schema_extra["hunch"]	none; never sent to the engine

​

spec_from_model

hunch.spec_from_model(cls, *, judgment: str | None = None, model: str = "jev-1.13.0",
                      source: str | None = None, key: str = "id", state: list[str] | None = None,
                      description: str | None = None, **spec) -> dict

A spec dict whose questions are the class’s fields. cls may also be a bare output type such as Literal["spam", "ham"] or bool. That becomes one question named output, asked with description. judgment defaults to the class name in snake case. Any other spec key (tests, redact, where, …) can be passed through **spec.

​

spec_from_agent

hunch.spec_from_agent(agent, *, state: str, judgment: str | None = None, model: str | None = None,
                      source: str | None = None, key: str = "id", deps=None, **spec) -> dict

A spec dict whose questions are the ones a Pydantic AI agent (2.50 or later, on a decision model) sends, recorded from Pydantic AI with no model call. The agent runs once on a recording model, with deps if its instructions need them, and stops at its first request.

Argument	Meaning
state	The column holding the agent’s prompt. Sent bare, as a string (see state).
model	The engine. Default: the agent’s model when it is TypeSafe’s (typesafe:jev-1.13.0 → jev-1.13.0); otherwise required.
judgment	Default agent.

Question names are Pydantic AI’s with . written as __: a list field topics becomes one yes/no question per option, topics__refund, topics__login. act, gold and escalate still go in Field(json_schema_extra={"hunch": {...}}) and apply to every question of that field; they are not sent. judgment defaults to the output class name in snake case (agent for a bare output type).

Raises ValueError when the agent asks a route question first (several output types, or tools), has a system_prompt, or has instructions that depend on the prompt (it is recorded twice, with different prompts, to tell), and TypeError when state is not a string. Works from async code: the recording runs on a thread of its own.

​

judge_model

hunch.judge_model(cls, spec: dict, base: str | Path = ".", **fields)

Judges one row with a spec built by spec_from_model and returns an instance of cls. For a bare output type it returns the value itself.

​

to_model

hunch.to_model(cls, answers: dict[str, dict])

Builds an instance of cls from answers shaped {question: {"label": ...}}, converting each label to the type the field declares: bool, the Literal or Enum value, a list for list[...], the IntEnum level, None for “none of these”.

​

SQL

Needs the sql extra: uv add "hunch-ai[sql]". The guide walks through it.

​

hunch.sql.register

hunch.sql.register(con, path, *, name=None, max_cost=None) -> str

Adds the spec or project folder at path to the DuckDB connection con as a function, and returns its name: the judgment’s, or the folder’s for a project, unless name is given. The function takes the columns the specs read (every judgment’s state, then the columns its where reads, less the answers upstream judgments add), as VARCHAR, in order; hunch.sql.columns(hunch.load(path)) lists them. It returns a struct of questions, each {label, p, route}, or for a project a struct of judgments, NULL where a row never reached one.

max_cost is the most the function may be charged in total on this connection, across every judgment and escalation, in USD; default HUNCH_MAX_COST, else no cap. A hunch.sql.Budget(usd) passed to several register calls is one budget they share. At the cap, the query fails (DuckDB raises InvalidInputException with hunch’s message) and the answers already asked are saved.

​

dbt

hunch.dbt is a dbt-duckdb plugin: module: hunch.dbt with config: {specs: [...], max_cost: USD} registers each spec on every connection dbt opens, all drawing from one budget.

​

Also exported

Name	Signature	Use
load_project	(path: Path, texts: dict[str, str] | None = None) -> dict	Load a spec file or folder. load calls it for paths.
load_spec	(path: Path, text: str | None = None) -> dict	Parse one spec file.
lint	(project: dict) -> tuple[list[str], list[str]]	(errors, warnings) for a project, the same checks as hunch lint.
execute	(project: dict, **kw) -> dict[str, dict]	Run a project and return every judgment’s rows, answers and cost stats without materializing tables.
decide	(a: dict) -> tuple[str, float, float]	(label, confidence, margin) for one raw answer from the store.
spec_yaml	(spec: dict) -> str	A spec dict as YAML, for saving a generated spec as a file.
table_name	(spec: dict) -> str	The judgment’s table in the store, including the __<engine> suffix under --model.

Everything else (hunch.spec, hunch.execute, hunch.measure and the other modules) is internal and not a stable API. Run settings are hunch.settings.