English for Instructor (Structured Outputs) Developers

Instructor conversations usually come up when a team needs to justify why raw LLM text output isn’t reliable enough for downstream code, so the vocabulary covers structured outputs, validation, and the automatic retry loop that pushes the model to correct malformed responses.

Key Vocabulary

Structured output — a model response constrained to match a predefined schema (typically a Pydantic model), rather than free-form text that has to be parsed with regex or manual string handling afterward. “Stop parsing the model’s text response with regex — define a structured output schema instead, and Instructor guarantees the response matches that shape or raises a clear error.”

Response model — the Pydantic model passed to Instructor that defines the exact fields, types, and validation rules the model’s output must satisfy before being accepted as valid. “Add an email: EmailStr field to the response model — Instructor will now enforce that the model actually returns a valid email format, not just any string.”

Validation-triggered retry — Instructor’s mechanism of automatically re-prompting the model with the validation error message when its output fails to match the response model, giving the model a chance to self-correct. “We don’t need custom retry logic here — validation-triggered retry already re-asks the model with the specific error, and it usually corrects itself within one or two attempts.”

Field-level validators — custom validation logic attached to individual fields in the response model, used to enforce business rules beyond basic type checking, such as a date being in the future or a value falling within a known range. “Add a field-level validator here that rejects a negative price — right now the schema accepts any float, so a hallucinated negative number would slip through.”

Partial streaming — Instructor’s support for incrementally receiving and validating a structured object as the model streams its response, allowing a UI to render fields as they arrive instead of waiting for the full response. “Use partial streaming for this — the summary field can render to the user as soon as it’s available, without waiting for the model to finish the entire structured object.”

Common Phrases

• “Are we relying on a structured output here, or still parsing free-form text with regex somewhere downstream?”
• “Does the response model actually constrain this field, or is it too permissive to catch a hallucinated value?”
• “Did validation-triggered retry already handle this failure, or did it exhaust its attempts and raise?”
• “Should we add a field-level validator here, or is basic type checking enough for this case?”

Example Sentences

Justifying a refactor away from manual parsing: “Instead of regex-matching the model’s text output, we’re defining a structured output — Instructor validates it against our schema and raises immediately if the model returns something malformed.”

Explaining reliability improvements to a stakeholder: “Validation-triggered retry means the model gets a second chance with the actual error message when its output doesn’t match our schema — we’re seeing far fewer manual fallback cases now.”

Reviewing a schema definition: “This field only checks that it’s a string — add a field-level validator to reject values outside the expected range, since the model can still hallucinate a plausible-looking but wrong number.”

Professional Tips

• Justify migrating to structured outputs with concrete examples of regex parsing failures — it’s a much stronger argument than a general preference for cleaner code.
• Design the response model as strictly as the use case allows — looser schemas let more hallucinated or malformed values pass silently.
• Rely on validation-triggered retry for recoverable schema mismatches, but still cap the retry count and handle the final failure case explicitly.
• Add field-level validators for business rules the type system alone can’t express, such as value ranges, cross-field consistency, or format constraints beyond basic types.

Practice Exercise

1. Explain what a structured output is and how it differs from parsing free-form text with regex.
2. Describe what validation-triggered retry does when a model’s response doesn’t match the schema.
3. Write a sentence explaining to a teammate why a field-level validator is needed even though a field’s type already looks correct.