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.

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. 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”.

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.