Agentsop Structured Output Picker

Structured-Output-Picker — 在解码处约束，还是在校验处约束？

One-liner: Three local libraries (Outlines, Instructor, Guidance) plus provider-native structured outputs all "make the model emit valid structure", but they enforce at different points and fail differently. Pick by how costly a malformed output is and whether you control the decoder. Then pick the failure stance — Assert (hard-fail + retry) vs Suggest (soft nudge, degrade gracefully) — borrowed from DSPy's constraint primitives.

This is an ENHANCE overlay. The four enforcement mechanisms each have a working local skill; what no single one provides is the cross-library *which-one

• how-to-handle-failure* decision. That gap is hit every time an LM output is consumed by code. For what shape the content should take (code vs JSON vs prose), descend first to [[agentsop-output-format-by-model]] — this skill assumes the shape is already chosen and asks only how to enforce it.

1. 何时激活 (When to activate)

Activate after you have decided the output shape (via [[agentsop-output-format-by-model]]) and the answer was "a typed/validated object", and before you write the parsing code.

Anti-triggers (skip this skill):

• The content is code / multi-step reasoning / long prose — go back to [[agentsop-output-format-by-model]]; enforcing a JSON grammar on code is the headline anti-pattern there (Aider 61%→20%). Enforcement strength is the wrong question when the shape is wrong.
• No code consumes the output yet (one-shot exploration).
• The shape is one token / one number — any parser works; no library needed.

2. 核心心智模型 (Core mental model)

2.1 The axis: where is the constraint applied?

   PROMPT ──────► DECODE ──────► RAW TEXT ──────► VALIDATE ──────► TYPED OBJECT
     │              │                                │
     │         constraint at DECODE             constraint at VALIDATE
     │         (grammar masks tokens)           (parse, check, retry on fail)
     │              │                                │
  ask nicely    Outlines / Guidance /          Instructor / DSPy Suggest /
  (weakest)     provider strict-mode           hand-rolled retry loop
                  ↑                                  ↑
            CANNOT emit invalid               CAN emit invalid, then
            structure — masked at             catches it and re-asks
            the logit level                   with the error injected

The pick is governed by one question: how costly is a malformed output?

• A malformed output is cheap to recover from (one extra API round-trip is fine; the model is strong; failures are rare) → constrain at validate (Instructor-style retry). Simpler, model writes more naturally, no decoder access needed.
• A malformed output is expensive or impossible to recover from (no retry budget, hard real-time, the output must be in a fixed enum/grammar, a single bad token corrupts a batch job) → constrain at decode (Outlines / Guidance grammar, or provider strict-mode). The model cannot emit invalid structure.

2.2 Two prerequisites that gate the choice

1. Do you control the decoder? Grammar/token-masking (Outlines, Guidance) requires logit access — i.e. local/open weights (Transformers, vLLM, llama.cpp) [[outlines]] [[guidance]]. Closed API models (GPT, Claude) expose only their own native structured-output / tool_use; you cannot bolt Outlines onto them. Instructor works on top of the API by parse-and-retry [[instructor]].
2. Is the content code-shaped? If yes, stop — see §1 anti-triggers and [[agentsop-output-format-by-model]]. Grammar-constraining code yields valid JSON containing degraded code: enforcement cannot buy back content quality.

2.3 Failure stance is orthogonal — Assert vs Suggest

Independent of which library, you choose what happens on a constraint violation. DSPy names the two stances [dspy-sop-skill §Constraint primitives; arxiv.org/pdf/2312.13382]:

Decode-time grammar (Outlines/Guidance) is itself a hard guarantee on shape — but semantic checks (range, cross-field, business rules) still need an Assert/Suggest stance layered on top.

3. SOP 工作流 (Decision workflow)

Three ordered steps. Each presupposes [[agentsop-output-format-by-model]] already said "typed/validated object".

Step 1 — Decide enforcement strength (how costly is malformed?)

malformed output cost?
   │
   ├── cheap to recover (retry OK, strong model, rare failures)
   │        └──► VALIDATE-time enforcement   (weakest sufficient — prefer this)
   │
   ├── must never escape (enum/regex/grammar is a hard contract)
   │        └──► DECODE-time grammar          (only if you control the decoder)
   │
   └── no retry budget / hard real-time / batch where 1 bad token poisons many
            └──► DECODE-time grammar          (or provider strict-mode if API)

Heuristic: start at the weakest layer that meets the cost constraint. Validate

• retry is cheaper to build, keeps the model's generation natural, and needs no decoder access. Escalate to decode-time grammar only when retry is too costly or the contract is absolute.

Step 2 — Pick the library (gated by decoder access + provider)

Step 3 — Choose the failure stance (Assert vs Suggest)

• Default Suggest in production (degrade gracefully; log the violation).
• Use Assert in dev/test and on values whose corruption is unacceptable downstream (IDs that index a DB, money amounts, irreversible actions).
• Decode-time grammar covers shape for free; still wrap semantic checks in a stance. Set a finite retry cap on either stance — an unbounded retry loop is an outage.

4. 操作模型 (Picker table — task → mechanism + stance)

5. 困境决策案例 (Dilemma cases / worked examples)

Case A — "Instructor keeps retrying and burning tokens; should I switch to Outlines?"

Trigger: An extraction service on GPT-4o uses Instructor with max_retries=5. Latency p95 spiked; logs show 15% of calls retry ≥2× on the same nested schema.

Constraints:

• Closed API model — no decoder access, so Outlines is not available for GPT-4o [[outlines]] [[instructor]].
• The schema is deeply nested with several free-text fields.
• The cost being paid is retries, i.e. malformed output is currently expensive.

Decision steps:

1. Outlines is off the table for an API model (Step-1 prerequisite §2.2(1)). The real lever is reducing the validate-time failure rate.
2. Inspect what fails. If the model emits valid JSON but wrong content, no enforcement layer helps — that's a prompt/format problem; check whether a free-text field is being squeezed into JSON ([[agentsop-output-format-by-model]] mixed-content trap).
3. If the failure is shape (extra prose, truncation): switch the API call to provider native structured outputs / tool_use (strict-mode guarantees schema validity at the API), then keep Instructor only for the Pydantic typing layer. Retries collapse because shape is now guaranteed upstream.
4. Lower max_retries to 2 and flip the stance to Suggest with a logged fallback object, so a stubborn case degrades instead of inflating p95.

Outcome: Don't "switch to Outlines" (impossible here). Move shape-enforcement to the provider's native layer, keep Instructor for typing, cap retries, Suggest.