How to Run the Test Suite and Contribute Code to mlx-omni-server

To run the test suite and contribute code to mlx-omni-server, clone the repository, install dependencies in editable mode with uv pip install -e ., execute tests via uv run pytest, and submit pull requests following the Black/Isort formatting standards and pre-commit hooks defined in the project documentation.

MLX Omni Server is a FastAPI-based inference server that delivers OpenAI- and Anthropic-compatible endpoints for local AI models on Apple Silicon. Understanding how to run the test suite and contribute code properly ensures your modifications align with the existing architecture and maintain API compatibility across chat, audio, image, and embedding endpoints.

Setting Up the Development Environment

Before running tests or submitting changes, configure a local development environment using the project's preferred package manager, uv.

Clone the repository and install the package in editable mode:

git clone https://github.com/madroidmaq/mlx-omni-server.git
cd mlx-omni-server
uv pip install -e .

This command installs mlx-omni-server along with its development dependencies, allowing you to modify source code in src/mlx_omni_server/ without reinstallation.

To verify your setup, launch the server in development mode with hot-reloading enabled:

uvicorn mlx_omni_server.main:app --reload --host 0.0.0.0 --port 10240

The --reload flag monitors file changes automatically, which accelerates iteration when working on features in src/mlx_omni_server/routers.py or endpoint handlers.

Running the mlx-omni-server Test Suite

The repository includes a comprehensive pytest suite that exercises every public API through FastAPI's TestClient, ensuring endpoint contracts match OpenAI and Anthropic specifications.

Execute the full test suite with:

uv run pytest

Target specific API implementations using directory paths:

uv run pytest tests/chat/openai/     # OpenAI-compatible endpoints

uv run pytest tests/chat/anthropic/  # Anthropic-compatible endpoints

Test Coverage Details

The suite validates functionality across multiple modules:

• Chat completions – Non-streaming and streaming responses, body parameter handling, and draft model integration (tests/chat/openai/test_chat_completions.py)
• Multimodal endpoints – Audio transcription, image generation, and text embeddings (tests/audio_test.py, tests/images_test.py, tests/embedding_test.py)
• MLX-specific features – Tool calling and structured output wrappers (tests/chat/mlx/*)

Tests instantiate an in-process TestClient that mimics downstream consumer behavior, validating the exact JSON schemas defined in src/mlx_omni_server/chat/openai/ and related modules.

Contributing Code to mlx-omni-server

Contributions follow a standard Git workflow with strict code quality enforcement via CI pipelines.

Contribution Workflow

1. Fork and branch – Create a feature branch: git checkout -b feature/<description>
2. Implement changes – Modify relevant files in src/mlx_omni_server/ following the existing architecture
3. Format code – Run black . && isort . to ensure consistent style
4. Install pre-commit hooks – Execute pre-commit install then pre-commit run --all-files to catch linting errors before submission
5. Validate locally – Run uv run pytest to confirm all tests pass
6. Commit – Follow the conventional commit standards documented in docs/git-commit-conventions.md
7. Submit PR – Push to your fork and open a Pull Request against the main branch

GitHub Actions automatically run the full test suite, formatting checks, and type validation on every pull request.

Key Source Files for Contributors

Understanding the repository structure helps orient new contributions:

• src/mlx_omni_server/main.py – CLI entry point, CORS configuration, logging setup, and Uvicorn server initialization
• src/mlx_omni_server/routers.py – Central registration of all API routers (/v1/*, /anthropic/*)
• src/mlx_omni_server/chat/openai/ – OpenAI-compatible adapters, request parsing, and streaming response logic
• src/mlx_omni_server/chat/mlx/ – Core MLX implementation for tool calling and structured outputs
• docs/development_guide.md – Detailed environment setup and contribution guidelines

Summary

• Environment Setup – Clone the repository and run uv pip install -e . to install dependencies in editable mode
• Test Execution – Use uv run pytest for full validation, or target specific directories like tests/chat/openai/ for focused testing
• Contribution Standards – Follow the fork-branch-PR workflow, enforce code style with Black and Isort, install pre-commit hooks, and adhere to commit conventions documented in docs/git-commit-conventions.md

Frequently Asked Questions

How do I run only specific tests in mlx-omni-server?

Target specific test directories or files using pytest's path selector. For example, uv run pytest tests/chat/openai/ executes only OpenAI-compatible chat tests, while uv run pytest tests/audio_test.py runs audio endpoint validation exclusively.

What code formatting standards does mlx-omni-server require?

The project mandates Black for code formatting and Isort for import sorting. Run black . && isort . before committing, or install pre-commit hooks with pre-commit install to automate these checks.

How do I set up pre-commit hooks for mlx-omni-server?

Execute pre-commit install after cloning to register git hooks locally. Then run pre-commit run --all-files to validate your changes against the repository's linting rules before submitting a pull request.

Where are the chat completion tests located?

Chat completion tests reside in tests/chat/openai/test_chat_completions.py for OpenAI-compatible endpoints and tests/chat/anthropic/ for Anthropic-compatible implementations. MLX-specific chat features are tested in tests/chat/mlx/.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}