Skip to content

Installation

Requirements

  • Python 3.10 or higher
  • pip or uv package manager

Basic Installation

Using pip

pip install ondine

uv is a fast Python package installer and resolver:

# Install uv if you don't have it
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install ondine
uv pip install ondine

Optional Dependencies

Ondine provides optional dependency groups for specific features:

MLX (Apple Silicon Local Inference)

For running models locally on Apple Silicon (M1/M2/M3/M4) with MLX:

pip install ondine[mlx]

Requirements: - macOS with Apple Silicon (M1/M2/M3/M4) - 16GB+ RAM recommended

Supported models: - Qwen-2.5 series - Llama models - Mistral models - Any MLX-compatible model from Hugging Face

Observability

For OpenTelemetry-based observability and tracing:

pip install ondine[observability]

Features: - Distributed tracing with Jaeger - Custom metrics export - Performance monitoring

Development Tools

For contributing or development:

pip install ondine[dev]

Includes: - pytest and test utilities - ruff for linting - mypy for type checking - pre-commit hooks - Security scanners (bandit, pip-audit)

Install All Optional Dependencies

pip install ondine[mlx,observability,dev]

Verify Installation

Check that Ondine is installed correctly:

import ondine

print(ondine.__version__)
print("Ondine installed successfully!")

Or use the CLI:

ondine --version

API Keys Setup

Ondine requires API keys for LLM providers. Set them as environment variables:

OpenAI

export OPENAI_API_KEY="sk-..."

Azure OpenAI

export AZURE_OPENAI_API_KEY="..."
export AZURE_OPENAI_ENDPOINT="https://..."
export AZURE_OPENAI_API_VERSION="2024-02-15-preview"

Anthropic Claude

export ANTHROPIC_API_KEY="sk-ant-..."

Groq

export GROQ_API_KEY="gsk_..."

Environment File

For convenience, create a .env file in your project root:

# .env
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GROQ_API_KEY=gsk_...

Ondine automatically loads .env files using python-dotenv.

Upgrade

To upgrade to the latest version:

pip install --upgrade ondine

Troubleshooting

Import Error: No module named 'ondine'

Make sure you're in the correct Python environment:

python -c "import sys; print(sys.executable)"
pip list | grep ondine

MLX Installation Issues

MLX only works on Apple Silicon. If you get import errors:

  1. Verify you're on Apple Silicon: uname -m should show arm64
  2. Install Xcode Command Line Tools: xcode-select --install
  3. Try reinstalling: pip uninstall mlx mlx-lm && pip install ondine[mlx]

API Key Not Found

If you get authentication errors:

  1. Check environment variables: echo $OPENAI_API_KEY
  2. Verify .env file is in the correct directory
  3. Restart your Python session after setting environment variables

Next Steps