CONTRIBUTING.md

Setting up the environment

With uv

We use uv to manage dependencies. To set it up, run:

$ uv sync --group dev --all-extras

You can then run scripts using uv run python script.py or by activating the virtual environment:

# Activate the virtual environment - https://docs.python.org/3/library/venv.html#how-venvs-work
$ source .venv/bin/activate

# now you can omit the `uv run` prefix
$ python script.py

Modifying/Adding code

Most of the SDK is generated by tools/sdkgen from the OpenAPI spec; generated files carry a header saying so and are overwritten on regeneration. Hand-written code lives in src/mixedbread/lib/ and examples/, which the generator never touches.

Adding and running examples

All files in the examples/ directory are not modified by the generator and can be freely edited or added to.

# add an example to examples/<your-example>.py

#!/usr/bin/env -S rye run python
…

$ chmod +x examples/<your-example>.py
# run the example against your api
$ ./examples/<your-example>.py

Using the repository from source

If you’d like to use the repository from source, you can either install from git or link to a cloned repository:

To install via git:

$ pip install git+ssh://git@github.com/mixedbread-ai/mixedbread-python.git

Alternatively, you can build from source and install the wheel file:

Building this package will create two files in the dist/ directory, a .tar.gz containing the source files and a .whl that can be used to install the package efficiently.

To create a distributable version of the library, all you have to do is run this command:

$ rye build
# or
$ python -m build

Then to install:

$ pip install ./path-to-wheel-file.whl

Running tests

Most tests require you to set up a mock server against the OpenAPI spec to run the tests.

$ ./scripts/mock

$ ./scripts/test

Linting and formatting

This repository uses ruff and black to format the code in the repository.

To lint:

$ ./scripts/lint

To format and fix all ruff issues automatically:

$ ./scripts/format

Publishing and releases

Changes made to this repository via the automated release PR pipeline should publish to PyPI automatically. If the changes aren't made through the automated pipeline, you may want to make releases manually.

Publish with a GitHub workflow

You can release to package managers by using the Publish PyPI GitHub action. This requires a setup organization or repository secret to be set up.

Publish manually

If you need to manually release a package, you can run the bin/publish-pypi script with a PYPI_TOKEN set on the environment.