[ { "path": ".coveragerc", "content": "[run]\nsource =\n instructor/\nomit =\n instructor/cli/*\n" }, { "path": ".cursor/rules/documentation-sync.mdc", "content": "---\ndescription: when making code changes or adding documentation\nglobs: [\"*.py\", \"*.md\"]\nalwaysApply: true\n---\n\n- When making code changes:\n - Update related documentation files to reflect the changes\n - Check docstrings and type hints are up to date\n - Update any example code in markdown files\n - Review README.md if the changes affect installation or usage\n\n- When creating new markdown files:\n - Add the file to mkdocs.yml under the appropriate section\n - Follow the existing hierarchy and indentation\n - Use descriptive nav titles\n - Example:\n ```yaml\n nav:\n - Home: index.md\n - Guides:\n - Getting Started: guides/getting-started.md\n - Your New File: guides/your-new-file.md\n ```\n\n- For API documentation:\n - Ensure new functions/classes are documented\n - Include type hints and docstrings\n - Add usage examples\n - Update API reference docs if auto-generated\n\n- Documentation Quality:\n - Write at grade 10 reading level (see simple-language.mdc)\n - Include working code examples\n - Add links to related documentation\n - Use consistent formatting and style " }, { "path": ".cursor/rules/followups.mdc", "content": "---\ndescription: when AI agents are collaborating on code\nglobs: \"*\"\nalwaysApply: true\n---\nMake sure to come up with follow-up hot keys. They should be thoughtful and actionable and result in small additional code changes based on the context that you have available.\n\nusing [J], [K], [L]\n" }, { "path": ".cursor/rules/new-features-planning.mdc", "content": "---\ndescription: when asked to implement new features or clients\nglobs: *.py\nalwaysApply: true\n---\n\n- When being asked to make new features, make sure that you check out from main a new branch and make incremental commits\n - Use conventional commit format: `(): `\n - Types: feat, fix, docs, style, refactor, perf, test, chore\n - Example: `feat(validation): add email validation function` \n - Keep commits focused on a single change\n - Write descriptive commit messages in imperative mood\n - Use `git commit -m \"type(scope): subject\" -m \"body\" -m \"footer\"` for multiline commits\n- If the feature is very large, create a temporary `todo.md`\n- And start a pull request using `gh`\n - Create PRs with multiline bodies using:\n ```bash\n gh pr create --title \"feat(component): add new feature\" --body \"$(cat < --add-reviewer jxnl,ivanleomk`\n - Or include `-r jxnl,ivanleomk` when creating the PR\n- use `gh pr view --comments | cat` to view all the comments\n- For PR updates:\n - Do not directly commit to an existing PR branch\n - Instead, create a new PR that builds on top of the original PR's branch\n - This creates a \"stacked PR\" pattern where:\n 1. The original PR (base) contains the initial changes\n 2. The new PR (stack) contains only the review-related updates\n 3. Once the base PR is merged, the stack can be rebased onto main \n" }, { "path": ".cursor/rules/readme.md", "content": "# Cursor Rules\n\nCursor rules are configuration files that help guide AI-assisted development in the Cursor IDE. They provide structured instructions for how the AI should behave in specific contexts or when working with certain types of files.\n\n## What is Cursor?\n\n[Cursor](https://cursor.sh) is an AI-powered IDE that helps developers write, understand, and maintain code more efficiently. It integrates AI capabilities directly into the development workflow, providing features like:\n\n- AI-assisted code completion\n- Natural language code generation\n- Intelligent code explanations\n- Automated refactoring suggestions\n\n## Understanding Cursor Rules\n\nCursor rules are defined in `.mdc` files within the `.cursor/rules` directory. Each rule file follows a specific naming convention: lowercase names with the `.mdc` extension (e.g., `simple-language.mdc`).\n\nEach rule file contains:\n\n1. **Metadata Header**: YAML frontmatter that defines:\n ```yaml\n ---\n description: when to apply this rule\n globs: file patterns to match (e.g., \"*.py\", \"*.md\", or \"*\" for all files)\n alwaysApply: true/false # whether to apply automatically\n ---\n ```\n\n2. **Rule Content**: Markdown-formatted instructions that guide the AI's behavior\n\n## Available Rules\n\nCurrently, the following rules are defined:\n\n### `simple-language.mdc`\n- **Purpose**: Ensures documentation is written at a grade 10 reading level\n- **Applies to**: Markdown files (*.md)\n- **Auto Apply**: No\n- **Key Requirements**: \n - Write at grade 10 reading level\n - Ensure code blocks are self-contained with complete imports\n\n### `new-features-planning.mdc`\n- **Purpose**: Guides feature implementation workflow\n- **Applies to**: Python files (*.py)\n- **Auto Apply**: Yes\n- **Key Requirements**:\n - Create new branch from main\n - Make incremental commits\n - Create todo.md for large features\n - Start pull requests using GitHub CLI (`gh`)\n - Include \"This PR was written by [Cursor](https://cursor.sh)\" in PRs\n\n### `followups.mdc`\n- **Purpose**: Ensures thoughtful follow-up suggestions\n- **Applies to**: All files\n- **Auto Apply**: Yes\n- **Key Requirements**:\n - Generate actionable hotkey suggestions using:\n - [J]: First follow-up action\n - [K]: Second follow-up action\n - [L]: Third follow-up action\n - Focus on small, contextual code changes\n - Suggestions should be thoughtful and actionable\n\n### `documentation-sync.mdc`\n- **Purpose**: Maintains documentation consistency with code changes\n- **Applies to**: Python and Markdown files (*.py, *.md)\n- **Auto Apply**: Yes\n- **Key Requirements**:\n - Update docs when code changes\n - Add new markdown files to mkdocs.yml\n - Keep API documentation current\n - Maintain documentation quality standards\n\n## Creating New Rules\n\nTo create a new rule:\n\n1. Create a `.mdc` file in `.cursor/rules/` using lowercase naming\n2. Add YAML frontmatter with required metadata:\n ```yaml\n ---\n description: when to apply this rule\n globs: file patterns to match\n alwaysApply: true/false\n ---\n ```\n3. Write clear, specific instructions in Markdown\n4. Test the rule with relevant file types\n\n## Best Practices\n\n- Keep rules focused and specific\n- Use clear, actionable language\n- Test rules thoroughly before committing\n- Document any special requirements or dependencies\n- Update rules as project needs evolve\n- Use consistent file naming (lowercase with .mdc extension)\n- Ensure globs patterns are explicit and documented\n" }, { "path": ".cursor/rules/simple-language.mdc", "content": "---\ndescription: when writing documentation\nglobs: *.md\nalwaysApply: false\n---\n\n- When writing documents and concepts make sure that you write at a grade 10 reading level \n- make sure every code block has complete imports and makes no references to previous code blocks, each one needs to be self contained\n" }, { "path": ".cursorignore", "content": "# Add directories or file patterns to ignore during indexing (e.g. foo/ or *.csv)\n" }, { "path": ".github/FUNDING.yml", "content": "github: jxnl" }, { "path": ".github/ISSUE_TEMPLATE/bug_report.md", "content": "---\nname: Bug report\nabout: Create a report to help us improve\n---\n\n- [ ] This is actually a bug report.\n- [ ] I am not getting good LLM Results\n- [ ] I have tried asking for help in the community on discord or discussions and have not received a response.\n- [ ] I have tried searching the documentation and have not found an answer.\n\n**What Model are you using?**\n\n- [ ] gpt-3.5-turbo\n- [ ] gpt-4-turbo\n- [ ] gpt-4\n- [ ] Other (please specify)\n\n**Describe the bug**\nA clear and concise description of what the bug is.\n\n**To Reproduce**\nSteps to reproduce the behavior, including code snippets of the model and the input data and openai response.\n\n**Expected behavior**\nA clear and concise description of what you expected to happen.\n\n**Screenshots**\nIf applicable, add screenshots to help explain your problem.\n" }, { "path": ".github/ISSUE_TEMPLATE/feature_request.md", "content": "---\nname: Feature request\nabout: Suggest an idea for this project\n---\n\n**Is your feature request related to a problem? Please describe.**\nA clear and concise description of what the problem is. Ex. I'm always frustrated when [...]\n\n**Describe the solution you'd like**\nA clear and concise description of what you want to happen.\n\n**Describe alternatives you've considered**\nA clear and concise description of any alternative solutions or features you've considered.\n\n**Additional context**\nAdd any other context or screenshots about the feature request here.\n" }, { "path": ".github/PULL_REQUEST_TEMPLATE/pull_request_template.md", "content": "> Please use conventional commits to describe your changes. For example, `feat: add new feature` or `fix: fix a bug`. If you are unsure, leave the title as `...` and AI will handle it.\n\n## Describe your changes\n\n...\n\n## Issue ticket number and link\n\n## Checklist before requesting a review\n\n- [ ] I have performed a self-review of my code\n- [ ] If it is a core feature, I have added thorough tests.\n- [ ] If it is a core feature, I have added documentation.\n" }, { "path": ".github/dependabot.yml", "content": "# To get started with Dependabot version updates, you'll need to specify which\n# package ecosystems to update and where the package manifests are located.\n# Please see the documentation for all configuration options:\n# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates\n\nversion: 2\nupdates:\n - package-ecosystem: \"pip\" # See documentation for possible values\n directory: \"/\" # Location of package manifests\n schedule:\n interval: \"daily\"\n groups:\n poetry:\n patterns: [\"*\"]\n" }, { "path": ".github/workflows/ai-label.yml", "content": "name: AI Labeler\n\non:\n issues:\n types: [opened, reopened]\n pull_request:\n types: [opened, reopened]\n\njobs:\n ai-labeler:\n runs-on: ubuntu-latest\n permissions:\n contents: read\n issues: write\n pull-requests: write\n steps:\n - uses: actions/checkout@v4\n - uses: jlowin/ai-labeler@v0.4.0\n with:\n include-repo-labels: true\n openai-api-key: ${{ secrets.OPENAI_API_KEY }}\n" }, { "path": ".github/workflows/evals.yml", "content": "name: Weekly Tests\n\non:\n workflow_dispatch:\n schedule:\n - cron: \"0 0 * * 0\" # Runs at 00:00 UTC every Sunday\n push:\n branches: [main]\n paths-ignore:\n - \"**\" # Ignore all paths to ensure it only triggers on schedule\n\njobs:\n weekly-tests:\n runs-on: ubuntu-latest\n\n steps:\n - uses: actions/checkout@v2\n\n - name: Install uv\n uses: astral-sh/setup-uv@v4\n with:\n enable-cache: true\n\n - name: Set up Python\n run: uv python install 3.11\n\n - name: Install dependencies\n run: uv sync --all-extras --dev\n\n - name: Run all tests\n run: uv run pytest tests/ --asyncio-mode=auto\n env:\n OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}\n" }, { "path": ".github/workflows/python-publish.yml", "content": "# This workflow will upload a Python Package using Twine when a release is created\n# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python#publishing-to-package-registries\n\n# This workflow uses actions that are not certified by GitHub.\n# They are provided by a third-party and are governed by\n# separate terms of service, privacy policy, and support\n# documentation.\n\nname: Upload Python Package\n\non:\n release:\n types: [published]\n\npermissions:\n contents: read\n\njobs:\n release:\n runs-on: ubuntu-latest\n\n steps:\n - uses: actions/checkout@v2\n - name: Install uv\n uses: astral-sh/setup-uv@v4\n with:\n enable-cache: true\n - name: Set up Python\n run: uv python install 3.10\n - name: Install the project\n run: uv sync --all-extras\n - name: Build the project\n run: uv build\n - name: Build and publish Python package\n run: uv publish\n env:\n UV_PUBLISH_TOKEN: ${{ secrets.PYPI_TOKEN }}\n" }, { "path": ".github/workflows/ruff.yml", "content": "name: Ruff\n\non:\n push:\n pull_request:\n branches: [main]\n\nenv:\n WORKING_DIRECTORY: \".\"\n CUSTOM_PACKAGES: \"instructor examples tests\"\n\njobs:\n Ruff:\n runs-on: ubuntu-latest\n steps:\n - name: Checkout code\n uses: actions/checkout@v3\n - name: Install uv\n uses: astral-sh/setup-uv@v4\n with:\n enable-cache: true\n - name: Set up Python\n run: uv python install 3.9\n - name: Install the project\n run: uv sync --all-extras\n - name: Ruff lint\n run: uv run ruff check ${{ env.CUSTOM_PACKAGES }}\n - name: Ruff format\n run: uv run ruff format --check ${{ env.CUSTOM_PACKAGES }}\n" }, { "path": ".github/workflows/scheduled-release.yml", "content": "name: Scheduled Release\n\non:\n schedule:\n # Every 2 weeks on Monday at 9 AM UTC\n - cron: '0 9 * * 1/2'\n workflow_dispatch: # Allow manual trigger\n inputs:\n skip_tests:\n description: 'Skip LLM tests (use for testing workflow)'\n required: false\n default: false\n type: boolean\n dry_run:\n description: 'Dry run - dont push changes or create release'\n required: false\n default: false\n type: boolean\n\njobs:\n test-and-release:\n runs-on: ubuntu-latest\n if: github.ref == 'refs/heads/main'\n \n steps:\n - uses: actions/checkout@v4\n with:\n fetch-depth: 0\n token: ${{ secrets.GITHUB_TOKEN }}\n \n - name: Setup UV\n uses: astral-sh/setup-uv@v3\n \n - name: Install dependencies\n run: |\n uv sync --all-extras --dev\n \n - name: Run linting\n run: |\n uv run ruff check instructor examples tests\n \n - name: Run type checking\n run: |\n uv run pyright\n \n - name: Run core tests (no LLM)\n run: |\n uv run pytest tests/ -k \"not openai and not llm and not anthropic and not gemini and not cohere and not mistral and not groq and not vertexai and not xai and not cerebras and not fireworks and not writer and not bedrock and not perplexity and not genai\" --tb=short -v --maxfail=10\n \n # Optional: Run LLM tests if you have API keys in secrets\n - name: Run LLM tests\n if: github.event.inputs.skip_tests != 'true'\n env:\n OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}\n ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}\n GOOGLE_API_KEY: ${{ secrets.GOOGLE_API_KEY }}\n COHERE_API_KEY: ${{ secrets.COHERE_API_KEY }}\n GROQ_API_KEY: ${{ secrets.GROQ_API_KEY }}\n MISTRAL_API_KEY: ${{ secrets.MISTRAL_API_KEY }}\n run: |\n echo \"Running basic LLM tests if API keys are available...\"\n # Run a subset of LLM tests to verify basic functionality\n if [ ! -z \"$OPENAI_API_KEY\" ]; then\n echo \"Testing OpenAI integration...\"\n uv run pytest tests/llm/test_openai/test_basics.py --tb=short -v --maxfail=1 || echo \"OpenAI tests failed\"\n fi\n if [ ! -z \"$ANTHROPIC_API_KEY\" ]; then\n echo \"Testing Anthropic integration...\"\n uv run pytest tests/llm/test_anthropic/test_basics.py --tb=short -v --maxfail=1 || echo \"Anthropic tests failed\"\n fi\n echo \"LLM tests completed (non-blocking)\"\n \n - name: Check for changes since last release\n id: changes\n run: |\n LAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo \"\")\n if [ -z \"$LAST_TAG\" ]; then\n echo \"has_changes=true\" >> $GITHUB_OUTPUT\n echo \"last_tag=none\" >> $GITHUB_OUTPUT\n echo \"change_count=initial\" >> $GITHUB_OUTPUT\n else\n CHANGES=$(git rev-list $LAST_TAG..HEAD --count)\n echo \"has_changes=$([[ $CHANGES -gt 0 ]] && echo true || echo false)\" >> $GITHUB_OUTPUT\n echo \"change_count=$CHANGES\" >> $GITHUB_OUTPUT\n echo \"last_tag=$LAST_TAG\" >> $GITHUB_OUTPUT\n fi\n \n echo \"Last tag: $LAST_TAG\"\n echo \"Changes since last tag: $(git rev-list $LAST_TAG..HEAD --count 2>/dev/null || echo 'N/A')\"\n \n # Only proceed with release if tests passed AND there are changes\n - name: Get current version\n if: steps.changes.outputs.has_changes == 'true'\n id: current_version\n run: |\n VERSION=$(uv run python -c \"import tomllib; print(tomllib.load(open('pyproject.toml', 'rb'))['project']['version'])\")\n echo \"version=$VERSION\" >> $GITHUB_OUTPUT\n echo \"Current version: $VERSION\"\n \n - name: Determine version bump type\n if: steps.changes.outputs.has_changes == 'true'\n id: version_type\n run: |\n # Check commit messages since last tag to determine bump type\n LAST_TAG=\"${{ steps.changes.outputs.last_tag }}\"\n if [ \"$LAST_TAG\" = \"none\" ]; then\n COMMITS=$(git log --oneline HEAD~20..HEAD)\n else\n COMMITS=$(git log --oneline $LAST_TAG..HEAD)\n fi\n \n echo \"Recent commits:\"\n echo \"$COMMITS\"\n \n # Look for breaking changes or major features\n if echo \"$COMMITS\" | grep -qE \"(BREAKING|feat!|fix!)\"; then\n echo \"bump_type=minor\" >> $GITHUB_OUTPUT\n echo \"Detected breaking changes - using minor bump\"\n elif echo \"$COMMITS\" | grep -qE \"feat:\"; then\n echo \"bump_type=minor\" >> $GITHUB_OUTPUT\n echo \"Detected new features - using minor bump\"\n else\n echo \"bump_type=patch\" >> $GITHUB_OUTPUT\n echo \"Using patch bump for bug fixes and chores\"\n fi\n \n - name: Bump version\n if: steps.changes.outputs.has_changes == 'true'\n id: bump_version\n run: |\n CURRENT=\"${{ steps.current_version.outputs.version }}\"\n BUMP_TYPE=\"${{ steps.version_type.outputs.bump_type }}\"\n \n IFS='.' read -r major minor patch <<< \"$CURRENT\"\n \n case $BUMP_TYPE in\n major)\n major=$((major + 1))\n minor=0\n patch=0\n ;;\n minor)\n minor=$((minor + 1))\n patch=0\n ;;\n patch)\n patch=$((patch + 1))\n ;;\n esac\n \n NEW_VERSION=\"$major.$minor.$patch\"\n echo \"new_version=$NEW_VERSION\" >> $GITHUB_OUTPUT\n echo \"Bumping from $CURRENT to $NEW_VERSION ($BUMP_TYPE)\"\n \n # Update pyproject.toml\n sed -i \"s/version = \\\"$CURRENT\\\"/version = \\\"$NEW_VERSION\\\"/\" pyproject.toml\n \n - name: Update lockfile\n if: steps.changes.outputs.has_changes == 'true'\n run: |\n uv lock\n \n # Run tests again after version bump to make sure nothing broke\n - name: Final test run\n if: steps.changes.outputs.has_changes == 'true'\n run: |\n uv sync\n uv run pytest tests/ -k \"not openai and not llm and not anthropic and not gemini and not cohere and not mistral and not groq and not vertexai and not xai and not cerebras and not fireworks and not writer and not bedrock and not perplexity and not genai\" --tb=short --maxfail=5\n \n - name: Generate changelog\n if: steps.changes.outputs.has_changes == 'true'\n id: changelog\n run: |\n LAST_TAG=\"${{ steps.changes.outputs.last_tag }}\"\n NEW_VERSION=\"${{ steps.bump_version.outputs.new_version }}\"\n \n if [ \"$LAST_TAG\" = \"none\" ]; then\n CHANGELOG=$(git log --oneline HEAD~30..HEAD --pretty=format:\"- %s\" | head -20)\n else\n CHANGELOG=$(git log --oneline $LAST_TAG..HEAD --pretty=format:\"- %s\")\n fi\n \n # Save changelog to file for GitHub release\n cat > CHANGELOG.md << EOF\n ## 🚀 What's Changed\n \n $CHANGELOG\n \n ## 🔗 Links\n **Full Changelog**: https://github.com/${{ github.repository }}/compare/$LAST_TAG...v$NEW_VERSION\n \n ---\n 🤖 *This release was automatically generated every 2 weeks*\n EOF\n \n echo \"changelog_file=CHANGELOG.md\" >> $GITHUB_OUTPUT\n \n - name: Create release commit\n if: steps.changes.outputs.has_changes == 'true'\n run: |\n git config --local user.email \"action@github.com\"\n git config --local user.name \"GitHub Action\"\n git add pyproject.toml uv.lock\n git commit -m \"chore: automated release v${{ steps.bump_version.outputs.new_version }}\n\n 🤖 Generated with [Claude Code](https://claude.ai/code)\n\n Co-Authored-By: GitHub Action \"\n git tag \"v${{ steps.bump_version.outputs.new_version }}\"\n \n - name: Push changes\n if: steps.changes.outputs.has_changes == 'true' && github.event.inputs.dry_run != 'true'\n run: |\n git push origin main\n git push origin \"v${{ steps.bump_version.outputs.new_version }}\"\n \n - name: Create GitHub Release\n if: steps.changes.outputs.has_changes == 'true' && github.event.inputs.dry_run != 'true'\n uses: ncipollo/release-action@v1\n with:\n tag: \"v${{ steps.bump_version.outputs.new_version }}\"\n name: \"🚀 Release v${{ steps.bump_version.outputs.new_version }}\"\n bodyFile: \"CHANGELOG.md\"\n draft: false\n prerelease: false\n \n - name: Dry run summary\n if: steps.changes.outputs.has_changes == 'true' && github.event.inputs.dry_run == 'true'\n run: |\n echo \"🧪 DRY RUN MODE - No changes pushed\"\n echo \"Would have released: v${{ steps.bump_version.outputs.new_version }}\"\n cat CHANGELOG.md\n \n # Optional: Publish to PyPI (uncomment if you want automatic PyPI releases)\n # - name: Build and publish to PyPI\n # if: steps.changes.outputs.has_changes == 'true' && secrets.PYPI_TOKEN != ''\n # env:\n # PYPI_TOKEN: ${{ secrets.PYPI_TOKEN }}\n # run: |\n # uv build\n # uv publish --token $PYPI_TOKEN\n \n # Summary outputs\n - name: Summary\n if: always()\n run: |\n echo \"## 📊 Scheduled Release Summary\" >> $GITHUB_STEP_SUMMARY\n echo \"- **Branch**: ${{ github.ref }}\" >> $GITHUB_STEP_SUMMARY\n echo \"- **Has Changes**: ${{ steps.changes.outputs.has_changes }}\" >> $GITHUB_STEP_SUMMARY\n echo \"- **Change Count**: ${{ steps.changes.outputs.change_count }}\" >> $GITHUB_STEP_SUMMARY\n if [ \"${{ steps.changes.outputs.has_changes }}\" = \"true\" ]; then\n echo \"- **Version**: ${{ steps.current_version.outputs.version }} → ${{ steps.bump_version.outputs.new_version }}\" >> $GITHUB_STEP_SUMMARY\n echo \"- **Bump Type**: ${{ steps.version_type.outputs.bump_type }}\" >> $GITHUB_STEP_SUMMARY\n echo \"- **Status**: ✅ Released\" >> $GITHUB_STEP_SUMMARY\n else\n echo \"- **Status**: ⏭️ Skipped (no changes)\" >> $GITHUB_STEP_SUMMARY\n fi\n \n - name: Notify on failure\n if: failure()\n run: |\n echo \"❌ Scheduled release failed - check the logs above\"\n echo \"Common issues:\"\n echo \"- Tests failed\"\n echo \"- Linting issues\" \n echo \"- Type checking errors\"\n echo \"- Git push permissions\"" }, { "path": ".github/workflows/test.yml", "content": "name: Test\non:\n pull_request:\n push:\n branches:\n - main\n\njobs:\n # Core tests without LLM providers\n core-tests:\n name: Core Tests\n runs-on: ubuntu-latest\n\n steps:\n - uses: actions/checkout@v2\n - name: Install uv\n uses: astral-sh/setup-uv@v4\n with:\n enable-cache: true\n - name: Set up Python\n run: uv python install 3.11\n - name: Install the project\n run: uv sync --all-extras\n - name: Run core tests\n run: >-\n uv run pytest tests/ --asyncio-mode=auto -n auto\n -k 'not test_core_providers and not test_openai and not test_anthropic\n and not test_gemini and not test_genai and not test_writer and not\n test_vertexai and not docs'\n env:\n INSTRUCTOR_ENV: CI\n OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}\n ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}\n COHERE_API_KEY: ${{ secrets.COHERE_API_KEY }}\n XAI_API_KEY: ${{ secrets.XAI_API_KEY }}\n GOOGLE_API_KEY: ${{ secrets.GOOGLE_API_KEY }}\n\n # Core provider tests for OpenAI\n core-openai:\n name: Core Provider Tests (OpenAI)\n runs-on: ubuntu-latest\n needs: core-tests\n env:\n OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}\n\n steps:\n - uses: actions/checkout@v2\n - name: Install uv\n uses: astral-sh/setup-uv@v4\n with:\n enable-cache: true\n - name: Set up Python\n run: uv python install 3.11\n - name: Install the project\n run: uv sync --all-extras\n - name: Skip core provider tests (OpenAI)\n if: ${{ env.OPENAI_API_KEY == '' }}\n run: echo \"Skipping OpenAI core provider tests (missing OPENAI_API_KEY).\"\n - name: Run core provider tests (OpenAI)\n if: ${{ env.OPENAI_API_KEY != '' }}\n run: |\n set +e\n uv run pytest tests/llm/test_core_providers -v --asyncio-mode=auto -n auto -k \"openai\"\n status=$?\n set -e\n if [ $status -eq 5 ]; then\n echo \"No tests collected; treating as success.\"\n exit 0\n fi\n exit $status\n env:\n INSTRUCTOR_ENV: CI\n OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}\n\n # Core provider tests for Anthropic\n core-anthropic:\n name: Core Provider Tests (Anthropic)\n runs-on: ubuntu-latest\n needs: core-tests\n env:\n ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}\n\n steps:\n - uses: actions/checkout@v2\n - name: Install uv\n uses: astral-sh/setup-uv@v4\n with:\n enable-cache: true\n - name: Set up Python\n run: uv python install 3.11\n - name: Install the project\n run: uv sync --all-extras\n - name: Skip core provider tests (Anthropic)\n if: ${{ env.ANTHROPIC_API_KEY == '' }}\n run: echo \"Skipping Anthropic core provider tests (missing ANTHROPIC_API_KEY).\"\n - name: Run core provider tests (Anthropic)\n if: ${{ env.ANTHROPIC_API_KEY != '' }}\n run: |\n set +e\n uv run pytest tests/llm/test_core_providers -v --asyncio-mode=auto -n auto -k \"anthropic\"\n status=$?\n set -e\n if [ $status -eq 5 ]; then\n echo \"No tests collected; treating as success.\"\n exit 0\n fi\n exit $status\n env:\n INSTRUCTOR_ENV: CI\n ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}\n\n # Core provider tests for Google\n core-google:\n name: Core Provider Tests (Google)\n runs-on: ubuntu-latest\n needs: core-tests\n env:\n GOOGLE_API_KEY: ${{ secrets.GOOGLE_API_KEY }}\n GOOGLE_GENAI_MODEL: ${{ secrets.GOOGLE_GENAI_MODEL }}\n\n steps:\n - uses: actions/checkout@v2\n - name: Install uv\n uses: astral-sh/setup-uv@v4\n with:\n enable-cache: true\n - name: Set up Python\n run: uv python install 3.11\n - name: Install the project\n run: uv sync --all-extras\n - name: Skip core provider tests (Google)\n if: ${{ env.GOOGLE_API_KEY == '' || env.GOOGLE_GENAI_MODEL == '' }}\n run: echo \"Skipping Google core provider tests (missing GOOGLE_API_KEY or GOOGLE_GENAI_MODEL).\"\n - name: Run core provider tests (Google)\n if: ${{ env.GOOGLE_API_KEY != '' && env.GOOGLE_GENAI_MODEL != '' }}\n run: |\n set +e\n uv run pytest tests/llm/test_core_providers -v --asyncio-mode=auto -n auto -k \"google\"\n status=$?\n set -e\n if [ $status -eq 5 ]; then\n echo \"No tests collected; treating as success.\"\n exit 0\n fi\n exit $status\n env:\n INSTRUCTOR_ENV: CI\n GOOGLE_API_KEY: ${{ secrets.GOOGLE_API_KEY }}\n\n # Core provider tests for other providers\n core-other:\n name: Core Provider Tests (Other)\n runs-on: ubuntu-latest\n needs: core-tests\n env:\n COHERE_API_KEY: ${{ secrets.COHERE_API_KEY }}\n XAI_API_KEY: ${{ secrets.XAI_API_KEY }}\n MISTRAL_API_KEY: ${{ secrets.MISTRAL_API_KEY }}\n CEREBRAS_API_KEY: ${{ secrets.CEREBRAS_API_KEY }}\n FIREWORKS_API_KEY: ${{ secrets.FIREWORKS_API_KEY }}\n WRITER_API_KEY: ${{ secrets.WRITER_API_KEY }}\n PERPLEXITY_API_KEY: ${{ secrets.PERPLEXITY_API_KEY }}\n\n steps:\n - uses: actions/checkout@v2\n - name: Install uv\n uses: astral-sh/setup-uv@v4\n with:\n enable-cache: true\n - name: Set up Python\n run: uv python install 3.11\n - name: Install the project\n run: uv sync --all-extras\n - name: Skip core provider tests (Other)\n if: >-\n ${{ env.COHERE_API_KEY == '' && env.XAI_API_KEY == ''\n && env.MISTRAL_API_KEY == '' && env.CEREBRAS_API_KEY == ''\n && env.FIREWORKS_API_KEY == '' && env.WRITER_API_KEY == ''\n && env.PERPLEXITY_API_KEY == '' }}\n run: echo \"Skipping core provider tests (Other) (missing provider secrets).\"\n - name: Run core provider tests (Cohere, xAI, Mistral, etc)\n if: >-\n ${{ env.COHERE_API_KEY != '' || env.XAI_API_KEY != ''\n || env.MISTRAL_API_KEY != '' || env.CEREBRAS_API_KEY != ''\n || env.FIREWORKS_API_KEY != '' || env.WRITER_API_KEY != ''\n || env.PERPLEXITY_API_KEY != '' }}\n run: |\n set +e\n uv run pytest tests/llm/test_core_providers -v --asyncio-mode=auto -n auto -k \"cohere or xai or mistral or cerebras or fireworks or writer or perplexity\"\n status=$?\n set -e\n if [ $status -eq 5 ]; then\n echo \"No tests collected; treating as success.\"\n exit 0\n fi\n exit $status\n env:\n INSTRUCTOR_ENV: CI\n COHERE_API_KEY: ${{ secrets.COHERE_API_KEY }}\n XAI_API_KEY: ${{ secrets.XAI_API_KEY }}\n MISTRAL_API_KEY: ${{ secrets.MISTRAL_API_KEY }}\n CEREBRAS_API_KEY: ${{ secrets.CEREBRAS_API_KEY }}\n FIREWORKS_API_KEY: ${{ secrets.FIREWORKS_API_KEY }}\n WRITER_API_KEY: ${{ secrets.WRITER_API_KEY }}\n PERPLEXITY_API_KEY: ${{ secrets.PERPLEXITY_API_KEY }}\n\n # Provider tests run in parallel\n provider-tests:\n name: ${{ matrix.provider.name }} Tests\n runs-on: ubuntu-latest\n needs: [core-openai, core-anthropic, core-google, core-other]\n env:\n PROVIDER_API_KEY: ${{ secrets[matrix.provider.env_key] }}\n GOOGLE_GENAI_MODEL: ${{ secrets.GOOGLE_GENAI_MODEL }}\n strategy:\n fail-fast: false\n matrix:\n provider:\n - name: OpenAI\n env_key: OPENAI_API_KEY\n test_path: tests/llm/test_openai\n - name: Anthropic\n env_key: ANTHROPIC_API_KEY\n test_path: tests/llm/test_anthropic\n - name: Gemini\n env_key: GOOGLE_API_KEY\n test_path: tests/llm/test_gemini\n - name: Google GenAI\n env_key: GOOGLE_API_KEY\n test_path: tests/llm/test_genai\n - name: Vertex AI\n env_key: GOOGLE_API_KEY\n test_path: tests/llm/test_vertexai\n - name: Writer\n env_key: WRITER_API_KEY\n test_path: tests/llm/test_writer\n\n steps:\n - uses: actions/checkout@v2\n - name: Install uv\n uses: astral-sh/setup-uv@v4\n with:\n enable-cache: true\n - name: Set up Python\n run: uv python install 3.11\n - name: Install the project\n run: uv sync --all-extras\n - name: Skip ${{ matrix.provider.name }} tests\n if: >-\n ${{ env.PROVIDER_API_KEY == '' ||\n ((matrix.provider.name == 'Gemini' || matrix.provider.name == 'Google GenAI'\n || matrix.provider.name == 'Vertex AI') && env.GOOGLE_GENAI_MODEL == '') }}\n run: >-\n echo \"Skipping ${{ matrix.provider.name }} tests\n (missing ${{ matrix.provider.env_key }} or GOOGLE_GENAI_MODEL).\"\n - name: Run ${{ matrix.provider.name }} tests\n if: >-\n ${{ env.PROVIDER_API_KEY != '' &&\n ((matrix.provider.name != 'Gemini' && matrix.provider.name != 'Google GenAI'\n && matrix.provider.name != 'Vertex AI') || env.GOOGLE_GENAI_MODEL != '') }}\n run: |\n set +e\n uv run pytest ${{ matrix.provider.test_path }} --asyncio-mode=auto -n auto\n status=$?\n set -e\n if [ $status -eq 5 ]; then\n echo \"No tests collected; treating as success.\"\n exit 0\n fi\n exit $status\n env:\n INSTRUCTOR_ENV: CI\n ${{ matrix.provider.env_key }}: ${{ secrets[matrix.provider.env_key] }}\n\n # Auto client needs multiple providers\n auto-client-test:\n name: Auto Client Tests\n runs-on: ubuntu-latest\n needs: [core-openai, core-anthropic, core-google, core-other]\n env:\n OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}\n GOOGLE_API_KEY: ${{ secrets.GOOGLE_API_KEY }}\n COHERE_API_KEY: ${{ secrets.COHERE_API_KEY }}\n ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}\n XAI_API_KEY: ${{ secrets.XAI_API_KEY }}\n\n steps:\n - uses: actions/checkout@v2\n - name: Install uv\n uses: astral-sh/setup-uv@v4\n with:\n enable-cache: true\n - name: Set up Python\n run: uv python install 3.11\n - name: Install the project\n run: uv sync --all-extras\n - name: Skip Auto Client tests\n if: >-\n ${{ env.OPENAI_API_KEY == '' || env.GOOGLE_API_KEY == ''\n || env.COHERE_API_KEY == '' || env.ANTHROPIC_API_KEY == ''\n || env.XAI_API_KEY == '' }}\n run: echo \"Skipping Auto Client tests (missing one or more provider secrets).\"\n - name: Run Auto Client tests\n if: >-\n ${{ env.OPENAI_API_KEY != '' && env.GOOGLE_API_KEY != ''\n && env.COHERE_API_KEY != '' && env.ANTHROPIC_API_KEY != ''\n && env.XAI_API_KEY != '' }}\n run: |\n set +e\n uv run pytest tests/test_auto_client.py --asyncio-mode=auto -n auto\n status=$?\n set -e\n if [ $status -eq 5 ]; then\n echo \"No tests collected; treating as success.\"\n exit 0\n fi\n exit $status\n env:\n INSTRUCTOR_ENV: CI\n OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}\n GOOGLE_API_KEY: ${{ secrets.GOOGLE_API_KEY }}\n COHERE_API_KEY: ${{ secrets.COHERE_API_KEY }}\n ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}\n XAI_API_KEY: ${{ secrets.XAI_API_KEY }}\n" }, { "path": ".github/workflows/test_docs.yml", "content": "name: Test Docs\non:\n schedule:\n - cron: '0 0 1 * *' # Runs at 00:00 on the 1st of every month\njobs:\n release:\n runs-on: ubuntu-latest\n\n strategy:\n matrix:\n python-version: [\"3.11\"]\n\n steps:\n - uses: actions/checkout@v2\n\n - name: Install system dependencies\n run: |\n sudo apt-get update\n sudo apt-get install -y graphviz libcairo2-dev xdg-utils\n\n - name: Install Poetry\n uses: snok/install-poetry@v1.3.1\n\n - name: Set up Python ${{ matrix.python-version }}\n uses: actions/setup-python@v4\n with:\n python-version: ${{ matrix.python-version }}\n cache: \"poetry\"\n - name: Install uv\n uses: astral-sh/setup-uv@v4\n - name: Install the project\n run: uv sync --all-extras\n - name: Run tests\n run: uv run pytest tests/docs --asyncio-mode=auto\n env:\n OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}\n" }, { "path": ".github/workflows/ty.yml", "content": "name: ty\n\non:\n pull_request:\n branches: [main]\n push:\n branches: [main]\n\nenv:\n WORKING_DIRECTORY: \".\"\n\njobs:\n type-check:\n runs-on: ubuntu-latest\n steps:\n - name: Checkout code\n uses: actions/checkout@v3\n - name: Install uv\n uses: astral-sh/setup-uv@v4\n with:\n enable-cache: true\n - name: Set up Python\n run: uv python install 3.11\n - name: Install the project\n run: uv sync --all-extras\n - name: Run type check with ty\n run: uv run ty check instructor/\n - name: Run type check with ty (tests)\n run: uv run ty check --config-file ty-tests.toml tests\n" }, { "path": ".gitignore", "content": ".DS_Store\n# Byte-compiled / optimized / DLL files\n__pycache__/\n*.py[cod]\n*$py.class\n\n# C extensions\n*.so\n\n\n# Distribution / packaging\n.Python\nbuild/\ndevelop-eggs/\ndist/\ndownloads/\neggs/\n.eggs/\nlib/\nlib64/\nparts/\nsdist/\nvar/\nwheels/\nshare/python-wheels/\n*.egg-info/\n.installed.cfg\n*.egg\nMANIFEST\n\n# PyInstaller\n# Usually these files are written by a python script from a template\n# before PyInstaller builds the exe, so as to inject date/other infos into it.\n*.manifest\n*.spec\n\n# Installer logs\npip-log.txt\npip-delete-this-directory.txt\n\n# Unit test / coverage reports\nhtmlcov/\n.tox/\n.nox/\n.coverage\n.coverage.*\n.cache\nnosetests.xml\ncoverage.xml\n*.cover\n*.py,cover\n.hypothesis/\n.pytest_cache/\ncover/\n\n# Translations\n*.mo\n*.pot\n\n# Django stuff:\n*.log\nlocal_settings.py\ndb.sqlite3\ndb.sqlite3-journal\n\n# Flask stuff:\ninstance/\n.webassets-cache\n\n# Scrapy stuff:\n.scrapy\n\n# Sphinx documentation\ndocs/_build/\n\n# PyBuilder\n.pybuilder/\ntarget/\n\n# Jupyter Notebook\n.ipynb_checkpoints\n\n# IPython\nprofile_default/\nipython_config.py\n\n# pyenv\n# For a library or package, you might want to ignore these files since the code is\n# intended to run in multiple environments; otherwise, check them in:\n# .python-version\n\n# pipenv\n# According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.\n# However, in case of collaboration, if having platform-specific dependencies or dependencies\n# having no cross-platform support, pipenv may install dependencies that don't work, or not\n# install all needed dependencies.\n#Pipfile.lock\n\n# poetry\n# Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.\n# This is especially recommended for binary packages to ensure reproducibility, and is more\n# commonly ignored for libraries.\n# https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control\n#poetry.lock\n\n# pdm\n# Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.\n#pdm.lock\n# pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it\n# in version control.\n# https://pdm.fming.dev/#use-with-ide\n.pdm.toml\n\n# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm\n__pypackages__/\n\n# Celery stuff\ncelerybeat-schedule\ncelerybeat.pid\n\n# SageMath parsed files\n*.sage.py\n\n# Environments\n.env\n.venv\nenv/\nvenv/\nENV/\nenv.bak/\nvenv.bak/\n.envrc\n\n# Spyder project settings\n.spyderproject\n.spyproject\n\n# Rope project settings\n.ropeproject\n\n# mkdocs documentation\n/site\n\n# mypy\n.mypy_cache/\n.dmypy.json\ndmypy.json\n\n# Pyre type checker\n.pyre/\n\n# pytype static type analyzer\n.pytype/\n\n# Cython debug symbols\ncython_debug/\n\n# PyCharm\n# JetBrains specific template is maintained in a separate JetBrains.gitignore that can\n# be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore\n# and can be added to the global gitignore or merged into this file. For a more nuclear\n# option (not recommended) you can uncomment the following to ignore the entire idea folder.\n.idea/\n\n.vscode/\n\nexamples/citation_with_extraction/fly.toml\nmy_cache_directory/\ntutorials/wandb/*\ntutorials/results.csv\ntutorials/results.jsonl\ntutorials/results.jsonlines\ntutorials/schema.json\nwandb/settings\nmath_finetunes.jsonl\n\npr_body.md\n\ncheck_zero_width_chars.py\n\n# Suggestion files from architectural analysis\n*_SUGGESTIONS.md\nORGANIZED_SUGGESTIONS.md\n" }, { "path": ".grit/.gitignore", "content": ".gritmodules\n*.log\n" }, { "path": ".grit/grit.yaml", "content": "version: 0.0.1\npatterns:\n - name: github.com/getgrit/python#openai\n level: info\n" }, { "path": ".pre-commit-config.yaml", "content": "repos:\n - repo: https://github.com/astral-sh/ruff-pre-commit\n rev: v0.9.9 # Ruff version\n hooks:\n - id: ruff # Run the linter.\n name: Run Linter Check (Ruff)\n args: [ --fix, --unsafe-fixes ]\n files: ^(instructor|tests|examples)/\n - id: ruff-format # Run the formatter.\n name: Run Formatter (Ruff)\n\n - repo: local\n hooks:\n - id: uv-lock-check\n name: Check uv.lock is up-to-date\n entry: uv\n args: [lock, --check]\n language: system\n files: ^(pyproject\\.toml|uv\\.lock)$\n pass_filenames: false\n \n - id: uv-sync-check\n name: Verify dependencies can be installed\n entry: uv\n args: [sync, --check]\n language: system\n files: ^(pyproject\\.toml|uv\\.lock)$\n pass_filenames: false\n\n - id: uv-export-requirements\n name: Export requirements.txt from pyproject.toml\n entry: bash -c 'uv pip compile pyproject.toml -o requirements.txt && git add requirements.txt'\n language: system\n files: ^pyproject\\.toml$\n pass_filenames: false\n\n - id: ty-check\n name: Run Type Check (ty)\n entry: uv\n args: [run, ty, check, --ignore, unresolved-import]\n language: system\n files: ^instructor/\n pass_filenames: false\n" }, { "path": ".ruff.toml", "content": "# Exclude a variety of commonly ignored directories.\nexclude = [\n \".bzr\",\n \".direnv\",\n \".eggs\",\n \".git\",\n \".git-rewrite\",\n \".hg\",\n \".mypy_cache\",\n \".nox\",\n \".pants.d\",\n \".pytype\",\n \".ruff_cache\",\n \".svn\",\n \".tox\",\n \".venv\",\n \"__pypackages__\",\n \"_build\",\n \"buck-out\",\n \"build\",\n \"dist\",\n \"node_modules\",\n \"venv\",\n]\n\n# Same as Black.\nline-length = 88\noutput-format = \"grouped\"\n\ntarget-version = \"py39\"\n\n[lint]\nselect = [\n # bugbear rules\n \"B\",\n # remove unused imports\n \"F401\",\n # bare except statements\n \"E722\",\n # unused arguments\n \"ARG\",\n # pyupgrade\n \"UP\",\n]\nignore = [\n # mutable defaults\n \"B006\",\n \"B018\",\n]\n\nunfixable = [\n # disable auto fix for print statements\n \"T201\",\n \"T203\",\n]\n\n[lint.extend-per-file-ignores]\n\"instructor/distil.py\" = [\"ARG002\"]\n\"tests/test_distil.py\" = [\"ARG001\"]\n\"tests/test_patch.py\" = [\"ARG001\"]\n\"examples/task_planner/task_planner_topological_sort.py\" = [\"ARG002\"]\n\"examples/citation_with_extraction/main.py\" = [\"ARG001\"]\n" }, { "path": "AGENT.md", "content": "# AGENT.md\n\n## Commands\n- Install: `uv pip install -e \".[dev]\"` or `poetry install --with dev`\n- Run tests: `uv run pytest tests/`\n- Run single test: `uv run pytest tests/path_to_test.py::test_name`\n- Skip LLM tests: `uv run pytest tests/ -k 'not llm and not openai'`\n- Temp deps for a run: `uv run --with [==version] ` (example: `uv run --with pytest-asyncio --with anthropic pytest tests/...`)\n- Type check: `uv run ty check`\n- Lint: `uv run ruff check instructor examples tests`\n- Format: `uv run ruff format instructor examples tests`\n- Build docs: `uv run mkdocs serve` (local) or `./build_mkdocs.sh` (production)\n- Waiting: use `sleep ` for explicit pauses (e.g., CI waits) or to let external processes finish\n\n## Architecture\n- **Core**: `instructor/` - Pydantic-based structured outputs for LLMs\n- **Base classes**: `Instructor` and `AsyncInstructor` in `client.py`\n- **Providers**: Client files (`client_*.py`) for OpenAI, Anthropic, Gemini, Cohere, etc.\n- **Factory pattern**: `from_provider()` for automatic provider detection\n- **DSL**: `dsl/` directory with Partial, Iterable, Maybe, Citation extensions\n- **Key modules**: `patch.py` (patching), `process_response.py` (parsing), `function_calls.py` (schemas)\n\n## Code Style\n- **Typing**: Strict type annotations, use `BaseModel` for structured outputs\n- **Imports**: Standard lib → third-party → local\n- **Formatting**: Ruff with Black conventions\n- **Error handling**: Custom exceptions from `exceptions.py`, Pydantic validation\n- **Naming**: `snake_case` functions/variables, `PascalCase` classes\n- **No mocking**: Tests use real API calls\n- **Client creation**: Always use `instructor.from_provider(\"provider_name/model_name\")` instead of provider-specific methods like `from_openai()`, `from_anthropic()`, etc.\n\n## Pull Request (PR) Formatting\n\nUse **Conventional Commits** formatting for PR titles. Treat the PR title as the message we would use for a squash merge commit.\n\n### PR Title Format\n\nUse:\n\n`(): `\n\nRules:\n- Keep it under ~70 characters when you can.\n- Use the imperative mood (for example, “add”, “fix”, “update”).\n- Do not end with a period.\n- If it includes a breaking change, add `!` after the type or scope (for example, `feat(api)!:`).\n\nGood examples:\n- `fix(openai): handle empty tool_calls in streaming`\n- `feat(retry): add backoff for JSON parse failures`\n- `docs(agents): add conventional commit PR title guidelines`\n- `test(schema): cover nested union edge cases`\n- `ci(ruff): enforce formatting in pre-commit`\n\nCommon types:\n- `feat`: new feature\n- `fix`: bug fix\n- `docs`: documentation-only changes\n- `refactor`: code change that is not a fix or feature\n- `perf`: performance improvement\n- `test`: add or update tests\n- `build`: build system or dependency changes\n- `ci`: CI pipeline changes\n- `chore`: maintenance work\n\nSuggested scopes (pick the closest match):\n- Providers: `openai`, `anthropic`, `gemini`, `vertexai`, `bedrock`, `mistral`, `groq`, `writer`\n- Core: `core`, `patch`, `process_response`, `function_calls`, `retry`, `dsl`\n- Repo: `docs`, `examples`, `tests`, `ci`, `build`\n\n### PR Description Guidelines\n\nKeep PR descriptions short and easy to review:\n- **What**: What changed, in 1–3 sentences.\n- **Why**: Why this change is needed (link issues when possible).\n- **Changes**: 3–7 bullet points with the main edits.\n- **Testing**: What you ran (or why you did not run anything).\n\nIf the PR was authored by Cursor, include:\n- `This PR was written by [Cursor](https://cursor.com)`\n" }, { "path": "CHANGELOG.md", "content": "# Changelog\n\nAll notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).\n\n## [Unreleased]\n\n\n\n## [1.14.4] - 2026-01-16\n\n### Changed\n- Simplified `JsonCompleteness` by using `jiter` parsing and a sibling-based completeness heuristic (#2000)\n\n### Fixed\n\n- Fixed Google GenAI `safety_settings` causing `400 INVALID_ARGUMENT` when requests include image content by using image-specific harm categories when needed (#1773)\n- Fixed `create_with_completion()` crashing for `list[T]` response models (where `T` is a Pydantic model) by preserving `_raw_response` on list outputs (#1303)\n- Fixed Responses API retries crashing on reasoning items by skipping non-tool-call items in `reask_responses_tools` (#2002)\n- Fixed Google GenAI dict-style `config` handling to preserve `labels` and other settings like `cached_content` and `thinking_config` (#2005)\n\n\n## [1.14.3] - 2026-01-13\n\n### Added\n- Completeness-based validation for Partial streaming - only validates JSON structures that are structurally complete (#1999)\n- New `JsonCompleteness` class in `instructor/dsl/json_tracker.py` for tracking JSON completeness during streaming (#1999)\n\n### Fixed\n- Fixed Stream objects crashing reask handlers when using streaming with `max_retries > 1` (#1992)\n- Field constraints (`min_length`, `max_length`, `ge`, `le`, etc.) now work correctly during streaming (#1999)\n\n### Deprecated\n- `PartialLiteralMixin` is now deprecated - completeness-based validation handles Literal/Enum types automatically (#1999)\n\n## [1.14.2] - 2026-01-13\n\n### Fixed\n- Fixed model validators crashing during partial streaming by skipping them until streaming completes (#1994)\n- Fixed infinite recursion with self-referential models in Partial (e.g., TreeNode with children: List[\"TreeNode\"]) (#1997)\n\n### Added\n- Added `PartialLiteralMixin` documentation for handling Literal/Enum types during streaming (#1994)\n- Added final validation against original model after streaming completes to enforce required fields (#1994)\n- Added tests for recursive Partial models (#1997)\n\n## [1.14.1] - 2026-01-08\n\n### Fixed\n- Added support for cached_content in Google Gemini context caching (#1987)\n\n## [1.14.0] - 2026-01-08\n\n### Added\n- Pre-commit hook to auto-export requirements.txt for build consistency\n\n### Changed\n- Standardized provider factory methods across codebase for improved consistency\n- Standardized provider imports throughout documentation\n- Audited and standardized exception handling throughout the instructor library\n\n### Fixed\n- Fixed build issues with requirements.txt regeneration from pyproject.toml\n- Fixed provider functionality issue (#1914)\n\n### Documentation\n- Comprehensive documentation audit and SEO optimization improvements (#1944)\n- Updated documentation for responses API mode (#1946)\n- Enhanced README with PydanticAI promotion and clear feature distinctions\n- Removed incorrect model reference in client.create extraction example (#1951)\n- Fixed image base URLs in Jupyter notebook tutorials (#1922)\n\n## [1.13.0] - Previous Release\n\nFor changes in earlier versions, see the [git history](https://github.com/instructor-ai/instructor/releases).\n" }, { "path": "CLAUDE.md", "content": "# CLAUDE.md\n\nThis file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.\n\n# Instructor Development Guide\n\n## Commands\n- Install deps: `uv pip install -e \".[dev,anthropic]\"` or `poetry install --with dev,anthropic`\n- Run tests: `uv run pytest tests/ -n auto`\n- Run specific test: `uv run pytest tests/path_to_test.py::test_name`\n- Skip LLM tests: `uv run pytest tests/ -k 'not llm and not openai'`\n- Type check: `uv run ty check`\n- Lint: `uv run ruff check instructor examples tests`\n- Format: `uv run ruff format instructor examples tests`\n- Generate coverage: `uv run coverage run -m pytest tests/ -k \"not docs\"` then `uv run coverage report`\n- Build documentation: `uv run mkdocs serve` (for local preview) or `./build_mkdocs.sh` (for production)\n- Waiting: use `sleep ` for explicit pauses (e.g., CI waits) or to let external processes finish\n\n## Installation & Setup\n- Fork the repository and clone your fork\n- Install UV: `pip install uv`\n- Create virtual environment: `uv venv`\n- Install dependencies: `uv pip install -e \".[dev]\"`\n- Install pre-commit: `uv run pre-commit install`\n- Run tests to verify: `uv run pytest tests/ -k \"not openai\"`\n\n## Code Style Guidelines\n- **Typing**: Use strict typing with annotations for all functions and variables\n- **Imports**: Standard lib → third-party → local imports\n- **Formatting**: Follow Black's formatting conventions (enforced by Ruff)\n- **Models**: Define structured outputs as Pydantic BaseModel subclasses\n- **Naming**: snake_case for functions/variables, PascalCase for classes\n- **Error Handling**: Use custom exceptions from exceptions.py, validate with Pydantic\n- **Comments**: Docstrings for public functions, inline comments for complex logic\n\n## Conventional Commits\n- **Format**: `type(scope): description`\n- **Types**: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert\n- **Examples**:\n - `feat(anthropic): add support for Claude 3.5`\n - `fix(openai): correct response parsing for streaming`\n - `docs(README): update installation instructions`\n - `test(gemini): add validation tests for JSON mode`\n\n## Core Architecture\n- **Base Classes**: `Instructor` and `AsyncInstructor` in client.py are the foundation\n- **Factory Pattern**: Provider-specific factory functions (`from_openai`, `from_anthropic`, etc.)\n- **Unified Access**: `from_provider()` function in auto_client.py for automatic provider detection\n- **Mode System**: `Mode` enum categorizes different provider capabilities (tools vs JSON output)\n- **Patching Mechanism**: Uses Python's dynamic nature to patch provider clients for structured outputs\n- **Response Processing**: Transforms raw API responses into validated Pydantic models\n- **DSL Components**: Special types like Partial, Iterable, Maybe extend the core functionality\n\n## Provider Architecture\n- **Supported Providers**: OpenAI, Anthropic, Gemini, Cohere, Mistral, Groq, VertexAI, Fireworks, Cerebras, Writer, Databricks, Anyscale, Together, LiteLLM, Bedrock, Perplexity\n- **Provider Implementation**: Each provider has a dedicated client file (e.g., `client_anthropic.py`) with factory functions\n- **Modes**: Different providers support specific modes (`Mode` enum): `ANTHROPIC_TOOLS`, `GEMINI_JSON`, etc.\n- **Common Pattern**: Factory functions (e.g., `from_anthropic`) take a native client and return patched `Instructor` instances\n- **Provider Testing**: Tests in `tests/llm/` directory, define Pydantic models, make API calls, verify structured outputs\n- **Provider Detection**: `get_provider` function analyzes base URL to detect which provider is being used\n\n## Key Components\n- **process_response.py**: Handles parsing and converting LLM outputs to Pydantic models\n- **patch.py**: Contains the core patching logic for modifying provider clients\n- **function_calls.py**: Handles generating function/tool schemas from Pydantic models\n- **hooks.py**: Provides event hooks for intercepting various stages of the LLM request/response cycle\n- **dsl/**: Domain-specific language extensions for specialized model types\n- **retry.py**: Implements retry logic for handling validation failures\n- **validators.py**: Custom validation mechanisms for structured outputs\n\n## Testing Guidelines\n- Tests are organized by provider under `tests/llm/`\n- Each provider has its own conftest.py with fixtures\n- Standard tests cover: basic extraction, streaming, validation, retries\n- Evaluation tests in `tests/llm/test_provider/evals/` assess model capabilities\n- Use parametrized tests when testing similar functionality across variants\n- **IMPORTANT**: No mocking in tests - tests make real API calls\n\n## Documentation Guidelines\n- Every provider needs documentation in `docs/integrations/` following standard format\n- Provider docs should include: installation, basic example, modes supported, special features\n- When adding a new provider, update `mkdocs.yml` navigation and redirects\n- Example code should include complete imports and environment setup\n- Tutorials should progress from simple to complex concepts\n- New features should include conceptual explanation in `docs/concepts/`\n- **Writing Style**: Grade 10 reading level, all examples must be working code\n\n## Branch and Development Workflow\n1. Fork and clone the repository\n2. Create feature branch: `git checkout -b feat/your-feature`\n3. Make changes and add tests\n4. Run tests and linting\n5. Commit with conventional commit message\n6. Push to your fork and create PR\n7. Use stacked PRs for complex features\n\n## Adding New Providers\n\n### Step-by-Step Guide\n1. **Update Provider Enum** in `instructor/utils.py`:\n ```python\n class Provider(Enum):\n YOUR_PROVIDER = \"your_provider\"\n ```\n\n2. **Add Provider Modes** in `instructor/mode.py`:\n ```python\n class Mode(enum.Enum):\n YOUR_PROVIDER_TOOLS = \"your_provider_tools\"\n YOUR_PROVIDER_JSON = \"your_provider_json\"\n ```\n\n3. **Create Client Implementation** `instructor/client_your_provider.py`:\n - Use overloads for sync/async variants\n - Validate mode compatibility\n - Return appropriate Instructor/AsyncInstructor instance\n - Handle provider-specific edge cases\n\n4. **Add Conditional Import** in `instructor/__init__.py`:\n ```python\n if importlib.util.find_spec(\"your_provider_sdk\") is not None:\n from .client_your_provider import from_your_provider\n __all__ += [\"from_your_provider\"]\n ```\n\n5. **Update Auto Client** in `instructor/auto_client.py`:\n - Add to `supported_providers` list\n - Implement provider handling in `from_provider()`\n - Update `get_provider()` function if URL-detectable\n\n6. **Create Tests** in `tests/llm/test_your_provider/`:\n - `conftest.py` with client fixtures\n - Basic extraction tests\n - Streaming tests\n - Validation/retry tests\n - No mocking - use real API calls\n\n7. **Add Documentation** in `docs/integrations/your_provider.md`:\n - Installation instructions\n - Basic usage examples\n - Supported modes\n - Provider-specific features\n\n8. **Update Navigation** in `mkdocs.yml`:\n - Add to integrations section\n - Include redirects if needed\n\n## Contributing to Evals\n- Standard evals for each provider test model capabilities\n- Create new evals following existing patterns\n- Run evals as part of integration test suite\n- Performance tracking and comparison\n\n## Pull Request Guidelines\n- Keep PRs small and focused\n- Include tests for all changes\n- Update documentation as needed\n- Follow PR template\n- Link to relevant issues\n\n## Type System and Best Practices\n\n### Type Checking with ty\n- **Type Checker**: Using `ty` for fast, incremental type checking\n- **Python Version**: 3.9+ for compatibility\n- **Configuration**: Uses `pyproject.toml` settings for type checking\n- Run `uv run ty check` before committing - aim for zero errors\n\n### Code Quality Checks Before Committing\nAlways run these checks before committing code:\n1. **Ruff linting**: `uv run ruff check .` - Fix all errors\n2. **Ruff formatting**: `uv run ruff format .` - Apply consistent formatting\n3. **Type checking**: `uv run ty check` - Aim for zero type errors\n4. **Tests**: Run relevant tests to ensure changes don't break functionality\n\n### Type Patterns\n- **Bounded TypeVars**: Use `T = TypeVar(\"T\", bound=Union[BaseModel, ...])` for constraints\n- **Version Compatibility**: Handle Python 3.9 vs 3.10+ typing differences explicitly\n- **Union Type Syntax**: Use `from __future__ import annotations` to enable Python 3.10+ union syntax (`|`) in Python 3.9\n- **Simple Type Detection**: Special handling for `list[Union[int, str]]` patterns\n- **Runtime Type Handling**: Graceful fallbacks for compatibility\n\n### Pydantic Integration\n- Heavy use of `BaseModel` for structured outputs\n- `TypeAdapter` used internally for JSON schema generation\n- Field validators and custom types\n- Models serve dual purpose: validation and documentation\n\n## Building Documentation\n\n### Setup\n```bash\n# Install documentation dependencies\npip install -r requirements-doc.txt\n```\n\n### Local Development\n```bash\n# Serve documentation locally with hot reload\nuv run mkdocs serve\n\n# Build documentation for production\n./build_mkdocs.sh\n```\n\n### Documentation Features\n- **Material Theme**: Modern UI with extensive customization\n- **Plugins**:\n - `mkdocstrings` - API documentation from docstrings\n - `mkdocs-jupyter` - Notebook integration\n - `mkdocs-redirects` - URL management\n - Custom hooks for code processing\n- **Custom Processing**: `hide_lines.py` removes code marked with `# <%hide%>`\n- **Redirect Management**: Comprehensive redirect maps for moved content\n\n### Writing Documentation\n- Follow templates in `docs/templates/` for consistency\n- Grade 10 reading level for accessibility\n- All code examples must be runnable\n- Include complete imports and environment setup\n- Progressive complexity: simple → advanced\n\n## Project Structure\n- `instructor/` - Core library code\n - Base classes (`client.py`): `Instructor` and `AsyncInstructor`\n - Provider clients (`client_*.py`): Factory functions for each provider\n - DSL components (`dsl/`): Partial, Iterable, Maybe, Citation extensions\n - Core logic: `patch.py`, `process_response.py`, `function_calls.py`\n - CLI tools (`cli/`): Batch processing, file management, usage tracking\n- `tests/` - Test suite organized by provider\n - Provider-specific tests in `tests/llm/test_/`\n - Evaluation tests for model capabilities\n - No mocking - all tests use real API calls\n- `docs/` - MkDocs documentation\n - `concepts/` - Core concepts and features\n - `integrations/` - Provider-specific guides\n - `examples/` - Practical examples and cookbooks\n - `learning/` - Progressive tutorial path\n - `blog/posts/` - Technical articles and announcements\n - `templates/` - Templates for new docs (provider, concept, cookbook)\n- `examples/` - Runnable code examples\n - Feature demos: caching, streaming, validation, parallel processing\n - Use cases: classification, extraction, knowledge graphs\n - Provider examples: anthropic, openai, groq, mistral\n - Each example has `run.py` as the main entry point\n- `typings/` - Type stubs for untyped dependencies\n\n## Documentation Structure\n- **Getting Started Path**: Installation → First Extraction → Response Models → Structured Outputs\n- **Learning Patterns**: Simple Objects → Lists → Nested Structures → Validation → Streaming\n- **Example Organization**: Self-contained directories with runnable code demonstrating specific features\n- **Blog Posts**: Technical deep-dives with code examples in `docs/blog/posts/`\n\n## Example Patterns\nWhen creating examples:\n- Use `run.py` as the main file name\n- Include clear imports: stdlib → third-party → instructor\n- Define Pydantic models with descriptive fields\n- Show expected output in comments\n- Handle errors appropriately\n- Make examples self-contained and runnable\n\n## Dependency Management\n\n### Core Dependencies\n- **Minimal core**: `openai`, `pydantic`, `docstring-parser`, `typer`, `rich`\n- **Python requirement**: `<4.0,>=3.9`\n- **Pydantic version**: `<3.0.0,>=2.8.0` (constrained for stability)\n\n### Optional Dependencies\nProvider-specific packages as extras:\n```bash\n# Install with specific provider\npip install \"instructor[anthropic]\"\npip install \"instructor[google-generativeai]\"\npip install \"instructor[groq]\"\n```\n\n### Development Dependencies\n```bash\n# Install all development dependencies\nuv pip install -e \".[dev]\"\n```\nIncludes:\n- ty \n- `pytest` and `pytest-asyncio` - Testing\n- `ruff` - Linting and formatting\n- `coverage` - Test coverage\n- `mkdocs` and plugins - Documentation\n\n### Version Constraints\n- **Upper bounds on all dependencies** for stability\n- **Provider SDK versions** pinned to tested versions\n- **Test dependencies** include evaluation frameworks\n\n### Managing Dependencies\n- Update `pyproject.toml` for new dependencies\n- Test with multiple Python versions (3.9-3.12)\n- Run full test suite after dependency updates\n- Document any provider-specific version requirements\n\nThe library enables structured LLM outputs using Pydantic models across multiple providers with type safety.\n" }, { "path": "CONTRIBUTING.md", "content": "# Contributing to Instructor\n\nThank you for considering contributing to Instructor! This document provides guidelines and instructions to help you contribute effectively.\n\n## Table of Contents\n\n- [Contributing to Instructor](#contributing-to-instructor)\n - [Table of Contents](#table-of-contents)\n - [Code of Conduct](#code-of-conduct)\n - [Getting Started](#getting-started)\n - [Environment Setup](#environment-setup)\n - [Development Workflow](#development-workflow)\n - [Dependency Management](#dependency-management)\n - [Using UV](#using-uv)\n - [Using Poetry](#using-poetry)\n - [Working with Optional Dependencies](#working-with-optional-dependencies)\n - [How to Contribute](#how-to-contribute)\n - [Reporting Bugs](#reporting-bugs)\n - [Feature Requests](#feature-requests)\n - [Pull Requests](#pull-requests)\n - [Writing Documentation](#writing-documentation)\n - [Contributing to Evals](#contributing-to-evals)\n - [Code Style Guidelines](#code-style-guidelines)\n - [Conventional Comments](#conventional-comments)\n - [Conventional Commits](#conventional-commits)\n - [Types](#types)\n - [Examples](#examples)\n - [Testing](#testing)\n - [Branch and Release Process](#branch-and-release-process)\n - [Using Cursor for PR Creation](#using-cursor-for-pr-creation)\n - [License](#license)\n\n## Code of Conduct\n\nBy participating in this project, you agree to abide by our code of conduct: treat everyone with respect, be constructive in your communication, and focus on the technical aspects of the contributions.\n\n## Getting Started\n\n### Environment Setup\n\n1. **Fork the Repository**: Click the \"Fork\" button at the top right of the [repository page](https://github.com/instructor-ai/instructor).\n\n2. **Clone Your Fork**:\n ```bash\n git clone https://github.com/YOUR-USERNAME/instructor.git\n cd instructor\n ```\n\n3. **Set up Remote**:\n ```bash\n git remote add upstream https://github.com/instructor-ai/instructor.git\n ```\n\n4. **Install UV** (recommended):\n ```bash\n # macOS/Linux\n curl -LsSf https://astral.sh/uv/install.sh | sh\n\n # Windows PowerShell\n powershell -ExecutionPolicy ByPass -c \"irm https://astral.sh/uv/install.ps1 | iex\"\n ```\n\n5. **Install Dependencies**:\n ```bash\n # Using uv (recommended)\n uv pip install -e \".[dev,docs,test-docs]\"\n \n # Using poetry\n poetry install --with dev,docs,test-docs\n \n # For specific providers, add the provider name as an extra\n # Example: uv pip install -e \".[dev,docs,test-docs,anthropic]\"\n ```\n\n6. **Set up Pre-commit**:\n ```bash\n pip install pre-commit\n pre-commit install\n ```\n\n### Development Workflow\n\n1. **Create a Branch**:\n ```bash\n git checkout -b feature/your-feature-name\n ```\n\n2. **Make Your Changes and Commit**:\n ```bash\n git add .\n git commit -m \"Your descriptive commit message\"\n ```\n\n3. **Keep Your Branch Updated**:\n ```bash\n git fetch upstream\n git rebase upstream/main\n ```\n\n4. **Push Changes**:\n ```bash\n git push origin feature/your-feature-name\n ```\n\n### Dependency Management\n\nWe support both UV and Poetry for dependency management. Choose the tool that works best for you:\n\n#### Using UV\n\nUV is a fast Python package installer and resolver. It's recommended for day-to-day development in Instructor.\n\n```bash\n# Install uv\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# Install project and development dependencies\nuv pip install -e \".[dev,docs]\"\n\n# Adding a new dependency (example)\nuv pip install new-package\n```\n\nKey UV commands:\n- `uv pip install -e .` - Install the project in editable mode\n- `uv pip install -e \".[dev]\"` - Install with development extras\n- `uv pip freeze > requirements.txt` - Generate requirements file\n- `uv self update` - Update UV to the latest version\n\n#### Using Poetry\n\nPoetry provides more comprehensive dependency management and packaging.\n\n```bash\n# Install Poetry\ncurl -sSL https://install.python-poetry.org | python3 -\n\n# Install dependencies including development deps\npoetry install --with dev,docs\n\n# Add a new dependency\npoetry add package-name\n\n# Add a new development dependency\npoetry add --group dev package-name\n```\n\nKey Poetry commands:\n- `poetry shell` - Activate the virtual environment\n- `poetry run python -m pytest` - Run commands within the virtual environment\n- `poetry update` - Update dependencies to their latest versions\n\n### Working with Optional Dependencies\n\nInstructor uses optional dependencies to support different LLM providers. Provider-specific utilities live under `instructor/utils`. When adding integration for a new provider:\n\n1. **Update pyproject.toml**: Add your provider's dependencies to both `[project.optional-dependencies]` and `[dependency-groups]`:\n\n ```toml\n [project.optional-dependencies]\n # Add your provider here\n my-provider = [\"my-provider-sdk>=1.0.0,<2.0.0\"]\n \n [dependency-groups]\n # Also add to dependency groups\n my-provider = [\"my-provider-sdk>=1.0.0,<2.0.0\"]\n ```\n\n2. **Create Provider Client**: Implement your provider client in `instructor/clients/client_myprovider.py`\n\n3. **Add Tests**: Create tests in `tests/llm/test_myprovider/`\n\n4. **Document Installation**: Update the documentation to include installation instructions:\n ```\n # Install with your provider support\n uv pip install \"instructor[my-provider]\"\n # or\n poetry install --with my-provider\n ```\n\n5. **Create Provider Utilities and Handlers**:\n - Add a new module at `instructor/utils/myprovider.py`\n - Implement `reask` functions for validation errors and `handle_*` functions\n for formatting requests\n - Define `MYPROVIDER_HANDLERS` mapping `Mode` values to these functions\n\n6. **Register the Provider**:\n - Add a value in `instructor/utils/providers.py` to the `Provider` enum\n - Extend `get_provider` with detection logic for your base URL\n\n7. **Update `process_response.py`**:\n - Import your handler functions and include them in the `mode_handlers`\n dictionary so the library can route requests to your provider\n - `process_response.py` relies on these handlers to format arguments and\n parse results for each `Mode`\n\n## How to Contribute\n\n### Reporting Bugs\n\nIf you find a bug, please create an issue on [our issue tracker](https://github.com/instructor-ai/instructor/issues) with:\n\n1. A clear, descriptive title\n2. A detailed description including:\n - The `response_model` you are using\n - The `messages` you are using\n - The `model` you are using\n - Steps to reproduce the bug\n - The expected behavior and what went wrong\n - Your environment (Python version, OS, package versions)\n\n### Feature Requests\n\nFor feature requests, please create an issue describing:\n\n1. The problem your feature would solve\n2. How your solution would work\n3. Alternatives you've considered\n4. Examples of how the feature would be used\n\n### Pull Requests\n\n1. **Create a Pull Request** from your fork to the main repository.\n2. **Fill out the PR template** with details about your changes.\n3. **Address review feedback** and make requested changes.\n4. **Wait for CI checks** to pass.\n5. Once approved, a maintainer will merge your PR.\n\n### Writing Documentation\n\nDocumentation improvements are always welcome! Follow these guidelines:\n\n1. Documentation is written in Markdown format in the `docs/` directory\n2. When creating new markdown files, add them to `mkdocs.yml` under the appropriate section\n3. Follow the existing hierarchy and structure\n4. Use a grade 10 reading level (simple, clear language)\n5. Include working code examples\n6. Add links to related documentation\n\n### Contributing to Evals\n\nWe encourage contributions to our evaluation tests:\n\n1. Explore existing evals in the [evals directory](https://github.com/instructor-ai/instructor/tree/main/tests/llm)\n2. Contribute new evals as pytest tests\n3. Evals should test specific capabilities or edge cases of the library or models\n4. Follow the existing patterns for structuring eval tests\n\n## Code Style Guidelines\n\nWe use automated tools to maintain consistent code style:\n\n- **Ruff**: For linting and formatting\n- **ty**: For type checking\n- **Black**: For code formatting (enforced by Ruff)\n\nGeneral guidelines:\n\n- **Typing**: Use strict typing with annotations for all functions and variables\n- **Imports**: Standard lib → third-party → local imports\n- **Models**: Define structured outputs as Pydantic BaseModel subclasses\n- **Naming**: snake_case for functions/variables, PascalCase for classes\n- **Error Handling**: Use custom exceptions from exceptions.py, validate with Pydantic\n- **Comments**: Docstrings for public functions, inline comments for complex logic\n\n### Conventional Comments\n\nWe use conventional comments in code reviews and commit messages. This helps make feedback clearer and more actionable:\n\n```\n