Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
109 lines (77 loc) · 3.4 KB

CONTRIBUTING.md

File metadata and controls

109 lines (77 loc) · 3.4 KB

Contributing to oMLX

Thank you for your interest in contributing to oMLX! This guide will help you get started.

Getting Started

  1. Fork the repository on GitHub
  2. Clone your fork:
git clone https://github.com/<your-username>/omlx.git
cd omlx
  1. Install development dependencies:
pip install -e ".[dev]"

Note: oMLX requires Apple Silicon (M1/M2/M3/M4) and Python 3.10+.

Development Workflow

Testing

Run tests with:

# Fast tests only (recommended during development)
pytest -m "not slow"

# Run a specific test file
pytest tests/test_config.py -v

# Run slow tests (requires model files)
pytest -m slow

Test markers:

Marker Description
@pytest.mark.slow Tests that require loading models
@pytest.mark.integration Tests that require a running server

Test file naming: For a source file omlx/<module>.py, the test file should be tests/test_<module>.py.

When modifying source code, always check if existing tests are affected and update them accordingly. New code should include corresponding tests.

License Header

All source files should include the Apache 2.0 license identifier:

# SPDX-License-Identifier: Apache-2.0

Project Structure

omlx/
├── omlx/                 # Main package
│   ├── api/              # API models and adapters (OpenAI, Anthropic)
│   ├── cache/            # KV cache management (paged, prefix, SSD)
│   ├── engine/           # Inference engines (simple, batched, embedding)
│   ├── mcp/              # Model Context Protocol integration
│   ├── models/           # Model wrappers (LLM, embedding)
│   ├── utils/            # Utilities
│   ├── server.py         # FastAPI server
│   ├── scheduler.py      # Request scheduling with mlx-lm BatchGenerator
│   ├── engine_core.py    # Core async inference engine
│   ├── paged_cache.py    # Block-based KV cache with LRU eviction
│   └── cli.py            # CLI entry point
├── packaging/            # macOS menubar app (PyObjC)
├── tests/                # Test suite
└── docs/                 # Documentation

For a more detailed architecture overview, see the Architecture section in the README.

Areas for Contribution

  • Bug fixes — Check open issues for reported bugs
  • Performance — Inference speed, memory efficiency, cache hit rates
  • New features — API endpoints, model format support, admin dashboard improvements
  • Documentation — Guides, examples, API references
  • Model support — Testing and fixing compatibility with new MLX models
  • macOS app — UI improvements, new settings, system integration

Pull Request Process

  1. Fork & branch — Create a feature branch from main:

    git checkout -b feature/your-feature

  2. Make changes — Write code and tests following the style guidelines above.

  3. Test — Ensure all related tests pass:

    pytest tests/test_<affected_module>.py -v

  4. Submit — Push your branch and open a pull request against main. Describe what changed and why.

Support

If you have questions or run into issues, please open an issue on GitHub Issues.