Python API

import hunch

The CLI wraps these functions; both use the same specs and store.

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.

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, **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` or `log`.
`**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`.

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.88, 'margin': 0.76, 'route': '', 'cached': True},
#  'sends_out': {'label': 'no', 'p': 0.97, 'margin': 0.94, '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, **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.core.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.
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”.

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 in hunch.core is internal and not a stable API.

Files and commands

Running hunch

Statistics

Projects

`load`

`run`

`results`

Judging one row

`judge`

`ajudge`

Costs and errors

Pydantic classes as specs

`spec_from_model`

`spec_from_agent`

`judge_model`

`to_model`

Also exported

​Projects

​load

​run

​results

​Judging one row

​judge

​ajudge

​Costs and errors

​Pydantic classes as specs

​spec_from_model

​spec_from_agent

​judge_model

​to_model

​Also exported

Projects

`load`

`run`

`results`

Judging one row

`judge`

`ajudge`

Costs and errors

Pydantic classes as specs

`spec_from_model`

`spec_from_agent`

`judge_model`

`to_model`

Also exported