Guidance

Agent tool protocols and ledger-bound records need generation that cannot emit invalid shapes. Guidance is the research pick when you want a programmable mix of free text and hard constraints at decode time. Prefer Instructor for pragmatic multi-provider Pydantic extraction in app code; prefer Outlines for grammar/schema-guided decoding especially on self-hosted backends; prefer LMQL for query-language + research constraint programming (check maintenance).

You build an immutable model session, append role blocks, and call generators that mask or constrain tokens. Captured named fields land on the model object for downstream Python use.

1. Load a local/API model backend.
2. Compose system/user/assistant blocks.
3. Constrain with gen/select/regex/gen_json.
4. Read named captures; validate further in app code if needed.

Related: instructor · lmql · outlines · topics/12-central-nervous-system

• Use when: you need programmable constrained generation (regex, choice, JSON schema) interleaved with prompt control flow.
• Skip when: simple chat+JSON mode + Pydantic retries suffice (instructor), or you already standardize on Outlines grammars.
• Prefer instead: Instructor for API extraction; Outlines for engine-level structured generation guarantees.

• Backend coupling: strength depends on local/logit-control backends vs thin API wrappers.
• Not the ledger: valid JSON ≠ authorized action.
• Maintenance check: confirm repo activity vs peers before production lock.
• Learning curve: DSL + grammar composition is heavier than Instructor’s one-liner.