Thank you for your interest in contributing to TensorZero!

TensorZero aims to power the next generation of AI applications. We'd love to collaborate with you to make this vision a reality.

TensorZero is licensed under the Apache 2.0 license. By contributing to this repository, you agree to license your contributions under the same license.

Join our community on Slack or Discord to chat with the team and other contributors.

We use GitHub Issues to track bugs and feature requests. For general questions, technical support, and conversations not directly related to code, please use GitHub Discussions.

For small changes (i.e. a few lines of code), feel free to open a PR directly.

For larger changes, please communicate with us first to avoid duplicate work or wasted effort. You can start a discussion (GitHub, Slack, or Discord) or open an issue as a starting point. The team will be happy to provide feedback and guidance.

At this time, we don't assign issues to new external contributors (in the past, most people we assigned issues to never submitted a PR). Please submit a PR directly once you're ready to start working on an issue.

The content for our documentation lives in the docs/ directory.

For small changes (e.g. typos), feel free to open a PR directly.

For larger changes, please communicate with us first to avoid duplicate work or wasted effort. You can start a discussion (GitHub, Slack, or Discord) or open an issue as a starting point.

We'd love to collaborate on examples, tutorials, and other content that showcases how to build AI applications with TensorZero.

For content contributed directly to our repository, please follow the same process as code contributions.

For external content (e.g. blog posts, videos, social media content), we're excited to support and amplify your work. Share your content in our community channels (Slack and Discord), tag us on social media, or reach out if you'd like technical review or feedback before publishing.

We're happy to provide guidance and support for both types of content to help you create high-quality resources for the TensorZero community.

We're open to exploring integrations with other projects and tools (both open-source and commercial). Reach out if you're interested in collaborating.

If you discover a security vulnerability, please email us at security@tensorzero.com.

Did you have something else in mind? Reach out on Slack or Discord and let us know.

• Install Rust (1.80+) →
• Install cargo-deny →
• Install cargo-nextest →
• Install pre-commit →
• Enable pre-commit in your repository: pre-commit install
• Install Docker →
• Install uv →
• Install Python (3.9+) (e.g. uv python install 3.9 + )
• Install Node.js (we use v24.13.0) and npm →
• Install pnpm npm install -g pnpm@10.15.0 →

macOS users: If you see Rust build errors about missing dynamic libraries for Python, set up a Python virtual environment at tensorzero/.venv (e.g. uv venv from the tensorzero directory) This ensures the correct Python libraries are available for the build.

We maintain optimization recipes as Jupyter notebooks in recipes/. These notebooks serve as manual workflows for optimizing (e.g. fine-tuning) TensorZero functions.

Jupyter notebooks are notoriously hard to test, maintain, and review. To address these issues, each notebook has an accompanying Python script ending in _nb.py that serves the same purpose. We automatically keep these two files in sync using Jupytext.

To convert a notebook to a script, run ci/compile-notebook-to-script.sh path/to/notebook.ipynb. To convert a script to a notebook, run ci/compile-script-to-notebook.sh path/to/script_nb.py.

In pre-commit and CI, we check that the notebooks match the relevant scripts using a script ci/compile-check-notebooks.sh.

cargo test-unit

1. Launch the test containers

   docker compose -f crates/tensorzero-core/tests/e2e/docker-compose.yml up --wait

2. Set the relevant environment variables (TENSORZERO_CLICKHOUSE_URL and model provider API keys like OPENAI_API_KEY, ANTHROPIC_API_KEY, etc.). See the credential docs for the full list.

3. Launch the gateway in testing mode

   cargo run-e2e

4. Run the E2E tests

   cargo test-e2e

1. Launch the test containers

   docker compose -f crates/tensorzero-core/tests/e2e/docker-compose.yml up --wait

2. Set the relevant environment variables (TENSORZERO_CLICKHOUSE_URL and model provider API keys like OPENAI_API_KEY, ANTHROPIC_API_KEY, etc.). See the credential docs for the full list.

3. Launch the gateway in testing mode

   cargo run-e2e-postgres

4. Run the E2E tests

   TENSORZERO_INTERNAL_TEST_OBSERVABILITY_BACKEND=postgres cargo test-e2e

1. Launch ClickHouse and the gateway in E2E testing mode (see above).

2. Go to the relevant directory (e.g. cd clients/python)

3. Install the Python dependencies. We recommend using uv.

   uv sync

4. Run the tests

   uv run pytest

5. Run the type checker

   uv pip install pyright
   uv run pyright

6. Run the formatter

   uv pip install ruff
   uv run ruff format --check .
   uv run ruff check --output-format=github --extend-select I .

The UI depends on ClickHouse and other TensorZero components. For development, we recommend running the TensorZero Gateway and ClickHouse as containers. We also provide fixtures in ui/fixtures/.

To set it up, follow these steps from the repository's root directory:

1. Install dependencies: pnpm install

2. Build the internal N-API client for TensorZero using pnpm -r build. If you have changed your Rust code, you may also have to run pnpm build-bindings.

3. Create a ui/fixtures/.env following the ui/fixtures/.env.example.

4. Create a ui/.env following the ui/.env.example, or set the environment variables from that file in your shell before running the dev script.

5. Launch the dependencies:

   # For local development without R2 credentials (downloads via public HTTP):
   TENSORZERO_DOWNLOAD_FIXTURES_WITHOUT_CREDENTIALS=1 docker compose -f ui/fixtures/docker-compose.yml up --build --force-recreate
   
   # With R2 credentials (faster S3 sync, used in CI):
   docker compose -f ui/fixtures/docker-compose.yml up --build --force-recreate

   You can omit the --build --force-recreate flags to skip the build step, but they ensure you're using the latest gateway.

6. Launch the development server: pnpm ui:dev

Separately, you can run headless tests with pnpm ui:test and Playwright tests with pnpm ui:test:e2e (the latter will require a pnpm exec playwright install).

We also maintain a Docker Compose for e2e tests ui/fixtures/docker-compose.e2e.yml that is used in CI for the Playwright tests. This file uses a different configuration that mandates credentials for image fetching.

For internal contributors with access to the autopilot repository, see ui/AGENTS.md for detailed instructions on running the autopilot development environment and tests.

• To test batch and optimization workflows without real provider APIs, spin up the mock-provider-api and set TENSORZERO_INTERNAL_MOCK_PROVIDER_API=http://localhost:3030 when running the gateway.
• If your code affects the serialization of stored data, batch tests might fail because they'll rely on an older serialization of the request. In such cases, you might need to clear the database and re-run the tests. The TensorZero Team can clean up the cache by running TRUNCATE TABLE tensorzero_e2e_tests.BatchModelInference; TRUNCATE TABLE tensorzero_e2e_tests.BatchRequest; in the ClickHouse Cloud cluster dev-tensorzero-e2e-tests.

Thanks again for your interest in contributing to TensorZero! We're excited to see what you build.