Skip to content

Contributing to Kreuzberg

Thank you for contributing to Kreuzberg!

Setup

  1. Install uv (fast Python package manager):

    1
    curl -LsSf https://astral.sh/uv/install.sh | sh

  2. Clone and install:

    1
2
3
    git clone https://github.com/Goldziher/kreuzberg.git
cd kreuzberg
uv sync --all-extras --dev

  3. Install pre-commit hooks:

    1
    pre-commit install && pre-commit install --hook-type commit-msg

Development

Commands

All commands run through uv run:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
# Testing
uv run pytest                      # Run all tests
uv run pytest tests/foo_test.py    # Run specific test
uv run pytest --cov                # With coverage (must be ≥95%)

# Code quality
uv run ruff format                 # Format code
uv run ruff check                  # Lint
uv run ruff check --fix            # Auto-fix issues
uv run mypy                        # Type check

# Pre-commit
uv run pre-commit run --all-files  # Run all checks manually

# Documentation
uv run mkdocs serve                # Serve docs locally

Commit Messages

Use Conventional Commits:

  • feat: add new feature
  • fix: resolve issue with X
  • docs: update README
  • test: add tests for Y

Pull Requests

  1. Fork the repo
  2. Create a feature branch
  3. Make changes (tests, code, docs)
  4. Ensure all checks pass
  5. Submit PR with clear description

Notes

  • Python 3.10-3.13 supported
  • System dependencies (optional): Tesseract, Pandoc
  • Pre-commit runs automatically on commit
  • Join our Discord for help

License

Contributions are licensed under MIT.