title: Contribute to Instructor: Evals, Issues, and Pull Requests description: Join us in enhancing the Instructor library with evals, report issues, and submit pull requests on GitHub. Collaborate and contribute!

Contributing to Instructor¶

We welcome contributions to Instructor! This page covers the different ways you can help improve the library.

Ways to Contribute¶

Evaluation Tests (Evals)¶

Evals help us monitor the quality of both the OpenAI models and the Instructor library. To contribute:

Explore Existing Evals: Check out our evals directory
Create a New Eval: Add new pytest tests that evaluate specific capabilities or edge cases
Follow the Pattern: Structure your eval similar to existing ones
Submit a PR: We'll review and incorporate your eval

Evals are run weekly, and results are tracked to monitor performance over time.

Reporting Issues¶

If you encounter a bug or problem, please file an issue on GitHub with:

A clear, descriptive title
Detailed information including:
The response_model you're using
The messages you sent
The model you're using
Steps to reproduce the issue
Expected vs. actual behavior
Your environment details (Python version, OS, package versions)

Contributing Code¶

We welcome pull requests! Here's the process:

For Small Changes: Feel free to submit a PR directly
For Larger Changes: Start with an issue to discuss approach
Looking for Ideas? Check issues labeled help wanted or good first issue

Setting Up Your Development Environment¶

Using UV (Recommended)¶

UV is a fast Python package installer and resolver that makes development easier.

Install UV (official method):

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows PowerShell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Install Project in Development Mode:

# Clone the repository
git clone https://github.com/YOUR-USERNAME/instructor.git
cd instructor

# Install with development dependencies 
uv pip install -e ".[dev,docs]"

Adding New Dependencies:

# Add a regular dependency
uv pip install some-package

# Install a specific version
uv pip install "some-package>=1.0.0,<2.0.0"

Common UV Commands:

# Update UV itself
uv self update

# Create a requirements file
uv pip freeze > requirements.txt

Using Poetry¶

Poetry provides comprehensive dependency management and packaging.

Install Poetry:

curl -sSL https://install.python-poetry.org | python3 -

Install Dependencies:

# Clone the repository
git clone https://github.com/YOUR-USERNAME/instructor.git
cd instructor

# Install with development dependencies
poetry install --with dev,docs

Working with Poetry:

# Activate virtual environment
poetry shell

# Run a command in the virtual environment
poetry run pytest

# Add a dependency
poetry add package-name

# Add a development dependency
poetry add --group dev package-name

Adding Support for New LLM Providers¶

Instructor uses optional dependencies to support different LLM providers. To add a new provider:

Add Dependencies to pyproject.toml:

[project.optional-dependencies]
# Add your provider
my-provider = ["my-provider-sdk>=1.0.0,<2.0.0"]

[dependency-groups]
# Mirror in dependency groups
my-provider = ["my-provider-sdk>=1.0.0,<2.0.0"]

Create Provider Client:
Create a new file at instructor/clients/client_myprovider.py
Implement from_myprovider function that patches the provider's client
Add Tests: Create tests in tests/llm/test_myprovider/

Document Installation:

# Installation command for your provider
uv pip install "instructor[my-provider]"
# or with poetry
poetry install --with my-provider

Write Documentation:
Add a new markdown file in docs/integrations/ for your provider
Update mkdocs.yml to include your new page
Make sure to include a complete example

Development Workflow¶

Fork the Repository: Create your own fork of the project

Clone and Set Up:

git clone https://github.com/YOUR-USERNAME/instructor.git
cd instructor
git remote add upstream https://github.com/instructor-ai/instructor.git

Create a Branch:

git checkout -b feature/your-feature-name

Make Changes, Test, and Commit:

# Run tests
pytest tests/ -k 'not llm and not openai'  # Skip LLM tests for faster local dev

# Commit changes
git add .
git commit -m "Your descriptive commit message"

Keep Updated and Push:

git fetch upstream
git rebase upstream/main
git push origin feature/your-feature-name

Create a Pull Request: Submit your PR with a clear description of changes

Using Cursor to Build PRs¶

Cursor is an AI-powered code editor that can help you contribute to Instructor.

Getting Started with Cursor:
Download Cursor from cursor.sh
Open the Instructor project in Cursor
Cursor will automatically detect our rules in .cursor/rules/
Using Cursor Rules:
new-features-planning: Helps plan and structure new features
simple-language: Guidelines for writing clear documentation
documentation-sync: Ensures documentation stays in sync with code changes
Creating PRs with Cursor:
Use Cursor's Git integration to create a new branch
Make your changes with AI assistance

Create a PR with:

# Use GitHub CLI to create the PR
gh pr create -t "Your feature title" -b "Description of your changes" -r jxnl,ivanleomk

Add This PR was written by [Cursor](https://cursor.sh) to your PR description
Benefits of Using Cursor:
AI helps generate code that follows our style guidelines
Simplifies PR creation process
Helps maintain documentation standards

Code Style Guidelines¶

We use the following tools to maintain code quality:

Ruff: For linting and formatting
PyRight: For type checking
Pre-commit: For automatic checks before committing

# Install pre-commit hooks
pip install pre-commit
pre-commit install

Key style guidelines: - Use strict typing - Follow import order: standard lib → third-party → local - Use snake_case for functions/variables, PascalCase for classes - Write comprehensive docstrings for public API functions

Conventional Comments¶

When reviewing code or writing commit messages, we use conventional comments to make feedback clearer:

<label>: <subject>

<description>

Common labels: - praise: highlights something positive - suggestion: proposes a change or improvement - question: asks for clarification - issue: points out a problem that needs fixing - todo: notes something to be addressed later - fix: resolves an issue

Examples:

suggestion: use a validator for this field
This would ensure the value is always properly formatted.

question: why not use async processing here?
I'm curious if this would improve performance.

fix: correct the parameter type
It should be an OpenAI client instance, not a string.

This format helps everyone understand the purpose and importance of each comment. Visit conventionalcomments.org to learn more.

Conventional Commits¶

We use conventional commit messages to make our project history clear and generate automated changelogs. A conventional commit has this structure:

<type>[optional scope]: <description>

[optional body]

[optional footer]

Common Types¶

feat: New feature
fix: Bug fix
docs: Documentation changes
style: Formatting changes
refactor: Code change that neither fixes a bug nor adds a feature
test: Adding or fixing tests
chore: Maintenance tasks

Examples¶

feat(openai): add streaming response support

fix(anthropic): resolve tool calling response format

docs: update installation instructions

test(evals): add new recursive schema test cases

For breaking changes, add an exclamation mark before the colon:

feat(api)!: change return type of from_openai function

Using conventional commits helps automatically generate release notes and makes the project history easier to navigate.

For more details, see the Conventional Commits specification.

Documentation Contributions¶

Documentation improvements are highly valued:

Docs Structure: All documentation is in Markdown in the docs/ directory
Adding New Pages: When adding a new page, include it in mkdocs.yml in the right section
Local Preview: Run mkdocs serve to preview changes locally
Style Guidelines:
Write at a grade 10 reading level (simple, clear language)
Include working code examples
Add links to related documentation
Use consistent formatting
Make sure each code example is complete with imports

Example of a good documentation code block:

# Complete example with imports
import instructor
from openai import OpenAI
from pydantic import BaseModel

# Define your model
class Person(BaseModel):
    name: str
    age: int

# Create the patched client
client = instructor.from_openai(OpenAI())

# Use the model
person = client.chat.completions.create(
    model="gpt-3.5-turbo",
    response_model=Person,
    messages=[
        {"role": "user", "content": "Extract: John Doe is 25 years old"}
    ]
)

print(person.name)  # "John Doe"
print(person.age)   # 25

Contributors¶

Documentation Resources¶

When working on documentation, these resources may be helpful:

mkdocs serve: Preview documentation locally. Install dependencies from requirements-doc.txt first.

hl_lines in Code Blocks: Highlight specific lines in a code block to draw attention:

```python hl_lines="2 3"
def example():
    # This line is highlighted
    # This line is also highlighted
    return "normal line"
```

Admonitions: Create styled callout boxes for important information:

!!! note "Optional Title"
    This is a note admonition.

!!! warning
    This is a warning.

For more documentation features, check the MkDocs Material documentation.

Thank you for your contributions to Instructor!