Handle errors

Every failure is a typed FabricError with a located report: category, loc, type, msg, hint and recoverable. There are no bare exceptions and no error strings to parse. Validators collect all errors before raising, so one run shows every problem.

examples/docs/handle_errors.py

"""Every failure is a typed ``FabricError``: a bad plan reports all its errors at once, each with ``loc`` and ``hint``."""

from __future__ import annotations

from agent_fabric import build_registry
from agent_fabric.errors import PlanValidationError
from agent_fabric.pipeline import parse_plan
from text_pack import register

registry = build_registry([register])
spec = registry.pipeline("document_digest")

try:
    parse_plan(spec.instantiate({"top_k": "three"}), registry)  # top_k must be an integer
except PlanValidationError as exc:
    print(exc.category, "recoverable" if exc.recoverable else "fatal")
    for detail in exc.details:  # all errors are collected before raising
        print(".".join(map(str, detail.loc)), detail.type, "->", detail.msg)
else:
    raise AssertionError("expected a PlanValidationError")

• loc points at the exact place (steps.1.params.top_k): a step, a parameter, a column.
• recoverable says whether a model can repair the problem; agents use it to retry with the report as feedback, and the budget bounds the retries.
• hint tells the author or the model how to fix it, when the toolkit knows.

The full list of categories and the rules for writing loc, type and hint is in the error model.