instructor_skill

Overview

This skill extracts structured data from LLM responses with Pydantic validation, automatic retries, and streaming support. It provides type-safe parsing of complex JSON, nested models, enums, unions, and dynamic runtime models. The library works across providers and includes battle-tested patterns for reliable production use.

How this skill works

Define Pydantic response models that describe the expected output shape and validation rules. Send prompts through the client tied to your LLM provider; the skill validates responses with Pydantic, automatically retries with feedback when validation fails, and can stream partial or iterable objects during generation. It supports provider modes for native structured outputs or JSON fallbacks and exposes hooks for custom validators and model-level checks.

When to use it

• When you need reliable extraction of fields, lists, or nested objects from LLM text.
• When outputs must conform to strict types, ranges, email/URL formats, or enums.
• When you want automatic retry and error feedback instead of ad-hoc parsing logic.
• When you need to stream partial results for real-time UIs or incremental processing.
• When you must support multiple LLM providers with a consistent API.

Best practices

• Design clear Pydantic models with Field descriptions and sensible defaults to guide the LLM.
• Use constrained types (EmailStr, HttpUrl, Field validations) to catch format issues early.
• Provide model-level and field validators for domain-specific rules (dates, ranges).
• Set a reasonable max_retries and inspect ValidationError details to refine prompts.
• Prefer streaming for long outputs or when UI responsiveness matters.

Example use cases

• Extract user profiles (name, age, email) from unstructured text into typed objects.
• Classify articles into enums with confidence scores and keyword lists.
• Parse multi-entity outputs (people, organizations, locations) into nested models.
• Stream a partially generated story or a list of tasks to update a UI in real time.
• Batch-process dozens of documents into validated records with automatic retry.