How 567-labs/instructor works
Project Type and Purpose
• Instructor is an open-source Python library (not a deployed application) that provides a unified, Pydantic-based API for generating and validating structured outputs from LLMs.
• It wraps many provider SDKs (OpenAI, Anthropic, Google Gemini, Mistral, Cohere, etc.), offering features like retries, hooks, streaming, and type inference.
High-Level Architectural Components
A. Core Library (instructor/)
• Client factory (from_provider, from_openai, etc.)
• Provider adapters (client_openai.py, client_anthropic.py, etc.)
• DSL & templating modules (instructor/dsl, templating.py)
• Response processing (validation via Pydantic, retry logic, streaming partials/iterables)
• Hooks subsystem (hook registration and event dispatch)
• Utility modules (utils.py, process_response.py, retry.py, patch.py)
B. Command-Line Interface (instructor/cli/)
• CLI entrypoints (“instructor jobs”, “instructor files”, “instructor usage”)
• Job management, file uploads, usage metrics wrappers around core client
C. Examples & Documentation
• examples/ – Cookbook‐style scripts demonstrating various use cases
• docs/ + mkdocs.yml – MkDocs static site for API reference, tutorials, concept guides
• Build scripts (build_mkdocs.sh, make_sitemap.py)
D. Testing & CI
• tests/ – Unit tests and eval suites across providers
• .github/workflows – CI pipelines for linting (ruff), type checking (pyright), tests, docs validation
Relationships and Data Flows
• User code (or CLI) invokes Instructor client →
• Client factory selects appropriate provider adapter →
• Adapter calls underlying LLM SDK (e.g., OpenAI.ChatCompletion) →
• Responses streamed or batched back →
• Instructor applies retry policies, Pydantic validation, hooks →
• Final structured models returned to user
Key Architectural Patterns
• Adapter pattern for provider integrations
• Decorator/Monkey-patching for injecting type inference into underlying SDKs
• Strategy pattern for retries and validation strategies
• Event dispatcher for hooks
• Modular layering: Core → Adapters → External services
Technologies and Frameworks
• Python 3, Pydantic for models/validation
• Underlying SDKs: openai, anthropic, google-generativeai, cohere, etc.
• CLI: click or argparse (instructor/cli)
• Documentation: MkDocs with YAML config, pre-commit hooks for docs checks
• Testing: pytest, uv for dependency management, ruff for linting, pyright for type checking