Primitives

Three functions, all in bridle. Each returns a Call typed as the value it will resolve to.

step

bridle.step(
    prompt: str,
    *,
    schema: type[T],
    context: Any = None,
    tools: Sequence[Tool] = (),
    system: str | None = None,
    max_turns: int = 50,
    max_schema_retries: int = 3,
    label: str | None = None,
) -> T

Run one unit of judgment. The model is given the prompt (and optional context), the supplied tools, and a synthetic __bridle_return__ tool whose schema matches schema. The step ends when the model calls __bridle_return__ with arguments that satisfy the schema.

Parameter	Type	Description
`prompt`	`str`	The instruction the model receives.
`schema`	`type[T]`	Pydantic model, bare type, enum, or `Literal`.
`context`	`Any`	JSON-serializable extra context appended to the prompt.
`tools`	`Sequence[Tool]`	Tools the model may call during the step.
`system`	`str \| None`	System prompt override. Resolution: per-call > per-agent (`@agent(system=...)`) > the loop's built-in default.
`max_turns`	`int`	Caps total model turns. Default `50`.
`max_schema_retries`	`int`	Caps invalid structured-output attempts before `SchemaSatisfactionError`. Default `3`.
`label`	`str \| None`	Trace label. Defaults to the prompt.

Returns: a Call annotated as T. Resolves on first read to the typed value.

Raises during resolution:

SchemaSatisfactionError — model failed validation past max_schema_retries.
ToolExecutionError — a tool with raise_on_error=True raised.
ModelError — the provider failed, or max_turns exhausted.
ConfigurationError — no model client or no model resolution.
TokenBudgetExceededError — agent budget exhausted.

branch

bridle.branch(
    prompt: str,
    *,
    schema: type[T] = bool,
    context: Any = None,
    label: str | None = None,
) -> T

A step constrained to one typed decision — no tools.

Parameter	Type	Description
`prompt`	`str`	The decision to make.
`schema`	`type[T]`	Defaults to `bool`. Pass an `Enum` or `Literal[...]` for multi-way.
`context`	`Any`	JSON-serializable extra context.
`label`	`str \| None`	Trace label. Defaults to the prompt.

Returns: a Call annotated as T. Resolves on truthiness or read.

Raises during resolution: same as step, minus ToolExecutionError.

Notes: shares step's evaluator with Call.kind == "branch" so the trace records it distinctly.

loop

bridle.loop(
    prompt: str,
    *,
    schema: type[T],
    until: Callable[[list[T]], bool],
    context: Any = None,
    tools: Sequence[Tool] = (),
    max_iterations: int = 32,
    label: str | None = None,
) -> list[T]

Repeat an inner step until until(accumulator) returns True. Each iteration's context is {"original_context": context, "previous_results": [...], "iteration": N}.

Parameter	Type	Description
`prompt`	`str`	The instruction for each iteration.
`schema`	`type[T]`	The shape of each value produced.
`until`	`Callable[[list[T]], bool]`	Pure-Python predicate over the accumulator.
`context`	`Any`	JSON-serializable shared context.
`tools`	`Sequence[Tool]`	Tools available in each iteration.
`max_iterations`	`int`	Hard cap. Default 32. Must be positive.
`label`	`str \| None`	Trace label.

Returns: a Call annotated as list[T].

Raises during resolution:

LoopExhaustedError — predicate never returned True before max_iterations. Carries the partial accumulator.
Any error the inner step would raise.

Primitives

step

branch

loop

Steps guide

Branches guide

Loops guide

Errors

On this page

Primitives

step

branch

loop

Related

Steps guide

Branches guide

Loops guide

Errors

On this page