Skip to content

Installation

Lumen works with Python 3.11+ on Linux, Windows, and Mac.

Already installed?

Jump to the Quick Start to start chatting with your data.

Using conda?

Lumen is on conda-forge, and the plain install is all you need for OpenAI and every OpenAI-compatible provider:

conda install -c conda-forge lumen

Providers with their own client library, such as Anthropic or Google, need that package too, for example conda install -c conda-forge anthropic.

Bring Your Own LLM

Lumen works with any LLM provider. Choose the approach that fits your needs:

  • ☁️ Cloud providers — OpenAI, Anthropic, Google, Mistral, Azure, Groq (easiest to get started)
  • 🖥️ Locally hosted — Ollama, Llama.cpp, MLX (free, runs on your machine, no API keys)
  • 🔀 Router/Multi-provider — Kilo, OpenRouter, LiteLLM, AWS Bedrock (unified interface, many providers and models)
  • 💻 Coding CLIs — Codex, Claude Code, GitHub Copilot, Antigravity (use a CLI you are already signed in to, no API key)

pip install lumen is all you need for OpenAI, every OpenAI-compatible provider (OpenRouter, Kilo, Groq, Ollama, AI Navigator, AI Catalyst) and the coding CLIs. Anthropic, Google, Mistral, AWS Bedrock, Llama.cpp and LiteLLM need their client library, which the matching extra below installs.

Cloud Service Providers

Use hosted LLM APIs from major providers. Fastest to set up, pay-per-use pricing.

pip install lumen
export OPENAI_API_KEY=sk-...

Get your API key:

  1. Visit platform.openai.com/api-keys
  2. Click "Create new secret key"
  3. Copy the key (starts with sk-)
  4. Set environment variable:
# macOS/Linux
export OPENAI_API_KEY='sk-your-key-here'

# Windows PowerShell
$env:OPENAI_API_KEY='sk-your-key-here'

# Windows CMD
set OPENAI_API_KEY=sk-your-key-here

pip install 'lumen[ai-anthropic]'
export ANTHROPIC_API_KEY=sk-ant-...

Get your API key:

  1. Visit console.anthropic.com/settings/keys
  2. Click "Create Key"
  3. Copy the key (starts with sk-ant-)
  4. Set environment variable:
# macOS/Linux
export ANTHROPIC_API_KEY='sk-ant-your-key-here'

# Windows PowerShell
$env:ANTHROPIC_API_KEY='sk-ant-your-key-here'

# Windows CMD
set ANTHROPIC_API_KEY=sk-ant-your-key-here

pip install 'lumen[ai-google]'
export GEMINI_API_KEY=your-key

Get your API key:

  1. Visit aistudio.google.com/apikey
  2. Click "Create API key"
  3. Choose "Create API key in new project" or select existing project
  4. Copy the key (starts with AIza)
  5. Set environment variable:
# macOS/Linux
export GEMINI_API_KEY='your-key-here'

# Windows PowerShell
$env:GEMINI_API_KEY='your-key-here'

# Windows CMD
set GEMINI_API_KEY=your-key-here

Alternative: You can also use GOOGLE_API_KEY instead of GEMINI_API_KEY.

pip install 'lumen[ai-mistralai]'
export MISTRAL_API_KEY=your-key

Get your API key:

  1. Visit console.mistral.ai/api-keys
  2. Click "Create new key"
  3. Copy the key
  4. Set environment variable:
# macOS/Linux
export MISTRAL_API_KEY='your-key-here'

# Windows PowerShell
$env:MISTRAL_API_KEY='your-key-here'

# Windows CMD
set MISTRAL_API_KEY=your-key-here

pip install lumen
export AZUREAI_ENDPOINT_KEY=your-key
export AZUREAI_ENDPOINT_URL=https://your-resource.openai.azure.com/

Get your credentials:

  1. Visit portal.azure.com
  2. Navigate to your Azure OpenAI resource
  3. Go to "Keys and Endpoint"
  4. Copy KEY 1 or KEY 2 and your endpoint URL
  5. Set environment variables:
# macOS/Linux
export AZUREAI_ENDPOINT_KEY='your-key-here'
export AZUREAI_ENDPOINT_URL='https://your-resource.openai.azure.com/'

# Windows PowerShell
$env:AZUREAI_ENDPOINT_KEY='your-key-here'
$env:AZUREAI_ENDPOINT_URL='https://your-resource.openai.azure.com/'

# Windows CMD
set AZUREAI_ENDPOINT_KEY=your-key-here
set AZUREAI_ENDPOINT_URL=https://your-resource.openai.azure.com/

pip install 'lumen[ai-mistralai]'
export AZUREAI_ENDPOINT_KEY=your-key
export AZUREAI_ENDPOINT_URL=https://your-resource-endpoint.com/

Get your credentials:

  1. Visit portal.azure.com
  2. Navigate to your Azure AI resource with Mistral deployment
  3. Go to "Keys and Endpoint"
  4. Copy KEY 1 or KEY 2 and your endpoint URL
  5. Set environment variables (same as Azure OpenAI above)
pip install lumen
export GROQ_API_KEY=gsk_...

Groq serves open models through an OpenAI-compatible API. Lumen uses openai/gpt-oss-120b by default.

Get your API key:

  1. Visit console.groq.com/keys
  2. Click "Create API Key"
  3. Set the GROQ_API_KEY environment variable, then start Lumen with --provider groq or let it auto-detect the key

Locally Hosted

Run open-source LLMs on your own machine. No API keys required, full privacy, free to use.

pip install lumen

Setup Ollama:

  1. Install Ollama from ollama.com
  2. Start the Ollama service (usually starts automatically)
  3. Pull a model:
ollama pull qwen3.5:9b
  1. (Optional) Point Lumen at an Ollama server that is not on localhost:11434:
export OLLAMA_HOST=your-server:11434

No additional environment variables needed! Ollama works out of the box.

pip install 'lumen[ai-llama]'

No setup required! The first time you use Llama.cpp, Lumen will automatically download the model you specify. No environment variables needed.

Optional: Set a custom model URL:

lumen-ai serve data.csv --provider llama-cpp \
  --llm-model-url 'https://huggingface.co/unsloth/Qwen2.5-7B-Instruct-GGUF/blob/main/Qwen2.5-7B-Instruct-Q4_K_M.gguf'

pip install lumen mlx-lm

Runs models natively on Apple Silicon, either in-process or through a local mlx_lm.server. Start Lumen with --provider mlx. See MLX for both modes.

pip install lumen

Anaconda AI Navigator runs models locally on your machine. No API key needed!

Setup AI Navigator:

  1. Open AI Navigator.
  2. Navigate to the API Server tab (⚡ icon).
  3. Select a model and click Start.

Default endpoint: http://localhost:8080/v1

Optional: Set custom endpoint:

export AINAVIGATOR_BASE_URL=http://localhost:8080/v1

pip install lumen
export AI_CATALYST_BASE_URL=https://...
export AI_CATALYST_API_KEY=...

Anaconda AI Catalyst provides enterprise-ready, governed models running on your private infrastructure.

Get your credentials:

  1. Log in to your AI Catalyst dashboard
  2. Go to Model Servers, launch or select a server, and copy the Server Address
  3. Go to your profile icon > API Keys and create/copy a key
  4. Set environment variables:
# macOS/Linux
export AI_CATALYST_BASE_URL='https://your-company.anacondaconnect.com/.../v1'
export AI_CATALYST_API_KEY='your-key-here'

# Windows PowerShell
$env:AI_CATALYST_BASE_URL='https://your-company.anacondaconnect.com/.../v1'
$env:AI_CATALYST_API_KEY='your-key-here'

Router / Multi-Provider

Use a unified interface to access multiple LLM providers and models.

pip install lumen
export KILO_API_KEY=...

Kilo provides an OpenAI-compatible API for accessing models from multiple providers through a single API key or its free tier.

The free tier needs no API key: run lumen-ai serve --provider kilo and skip the steps below. Get a key to use paid models.

Get your API key:

  1. Visit app.kilo.ai/profile
  2. Scroll down and click copy API key
  3. Set environment variable:
# macOS/Linux
export KILO_API_KEY='your-key-here'

# Windows PowerShell
$env:KILO_API_KEY='your-key-here'

# Windows CMD
set KILO_API_KEY=your-key-here

Then use Kilo with any supported model:

import lumen.ai as lmai

llm = lmai.llm.Kilo(
    model_kwargs={
        "default": {"model": "kilo-auto/free"},
        "sql": {"model": "anthropic/claude-sonnet-4.6"},
        "vega_lite": {"model": "openai/gpt-5.4-mini"},
    }
)

ui = lmai.ExplorerUI(data='data.csv', llm=llm)
ui.servable()

pip install lumen
export OPENROUTER_API_KEY=sk-or-...

OpenRouter provides an OpenAI-compatible API for accessing models from multiple providers through a single API key.

Get your API key:

  1. Visit openrouter.ai/keys
  2. Create or copy an API key
  3. Set environment variable:
# macOS/Linux
export OPENROUTER_API_KEY='sk-or-your-key-here'

# Windows PowerShell
$env:OPENROUTER_API_KEY='sk-or-your-key-here'

# Windows CMD
set OPENROUTER_API_KEY=sk-or-your-key-here

Then use OpenRouter with any supported model:

import lumen.ai as lmai

llm = lmai.llm.OpenRouter(
    model_kwargs={
        "default": {"model": "openai/gpt-6-luna"},
        "edit": {"model": "deepseek/deepseek-v4-pro-0813"},
        "sql": {"model": "qwen/qwen3.8-flash"},
    }
)
ui = lmai.ExplorerUI(data='data.csv', llm=llm)
ui.servable()

pip install 'lumen[ai-litellm]'

Supports 100+ models across OpenAI, Anthropic, Google, Mistral, and more.

Set environment variables for providers you want to use:

export OPENAI_API_KEY='sk-...'

export ANTHROPIC_API_KEY='sk-ant-...'

export GEMINI_API_KEY='...'

export AZUREAI_ENDPOINT_KEY='...'
export AZUREAI_ENDPOINT_URL='https://...'

pip install aws-sso-util
aws-sso-util login --profile your-profile
# Credentials auto-exported!

aws sso login --profile your-profile
export AWS_PROFILE=your-profile
export AWS_DEFAULT_REGION=us-east-1

export AWS_ACCESS_KEY_ID='...'
export AWS_SECRET_ACCESS_KEY='...'
export AWS_DEFAULT_REGION='us-east-1'

Then use any supported model:

import lumen.ai as lmai

llm = lmai.llm.LiteLLM(
    model_kwargs={
        "default": {"model": "gpt-5.4-mini"},                    # OpenAI
        "edit": {"model": "anthropic/claude-sonnet-4-6"},        # Anthropic
        "sql": {"model": "gemini/gemini-3.8-flash"}             # Google
    }
)
ui = lmai.ExplorerUI(data='data.csv', llm=llm)
ui.servable()

AWS Bedrock is a managed gateway that provides access to foundation models from Anthropic, Meta, Mistral, Amazon, Cohere, and AI21 through a unified API.

pip install 'lumen[ai-anthropic,ai-bedrock]'  # For AnthropicBedrock
# OR
pip install 'lumen[ai-bedrock]'  # For Bedrock

Authentication:

pip install aws-sso-util
aws-sso-util login --profile your-profile
# Credentials auto-exported!

aws sso login --profile your-profile
export AWS_PROFILE=your-profile
export AWS_DEFAULT_REGION=us-east-1

export AWS_ACCESS_KEY_ID='...'
export AWS_SECRET_ACCESS_KEY='...'
export AWS_DEFAULT_REGION='us-east-1'

Choose your Lumen provider:

Optimized for Claude models using Anthropic's SDK.

import lumen.ai as lmai

llm = lmai.llm.AnthropicBedrock()
ui = lmai.ExplorerUI(data='data.csv', llm=llm)
ui.servable()

Universal access to all Bedrock models using boto3.

import lumen.ai as lmai

llm = lmai.llm.Bedrock(
    model_kwargs={
        "default": {"model": "us.anthropic.claude-haiku-4-5-20251001-v1:0"},
    }
)
ui = lmai.ExplorerUI(data='data.csv', llm=llm)
ui.servable()

Available models:

  • Anthropic (Claude), Amazon (Nova), Qwen, DeepSeek, Mistral, Meta (Llama), and more
  • Model IDs: us.anthropic.claude-*, us.amazon.nova-*, qwen.*, deepseek.*, mistral.*
  • Full model list

IAM Permissions:

{
  "Effect": "Allow",
  "Action": ["bedrock:InvokeModel", "bedrock:InvokeModelWithResponseStream"],
  "Resource": "*"
}

Coding CLIs

Run Lumen through a command-line coding agent you are already signed in to, so no API key is needed. These providers are meant for local use, not shared deployments.

pip install lumen
lumen-ai serve penguins.csv --provider claude-code      # Claude Code
lumen-ai serve penguins.csv --provider codex-cli        # Codex CLI
lumen-ai serve penguins.csv --provider copilot-cli      # GitHub Copilot CLI, any plan
lumen-ai serve penguins.csv --provider antigravity-cli  # Antigravity CLI

Install and sign in to the CLI first; see Codex CLI and Claude Code, GitHub Copilot CLI and Antigravity CLI for setup and limits.

Optional extras

Add extras for data sources and features beyond the LLM provider:

Extra Adds
sql SQLAlchemy, for PostgreSQL, MySQL, SQLite, Oracle and SQL Server
snowflake Snowflake connector
bigquery Google BigQuery
xarray NetCDF, Zarr and HDF5 through xarray
xarray-grib GRIB files, on top of xarray
geo GeoJSON, WKT and shapefiles through GeoPandas
chromadb ChromaDB vector store
ai-transformers Local sentence-transformers embeddings
ai-monty Sandboxed Python calculations for agents
mcp MCPTool, to give agents tools from MCP servers 
pip install 'lumen[sql,xarray]'

Making Environment Variables Persistent

Set variables permanently so you don't have to export them every session:

Add to ~/.bashrc or ~/.bash_profile:

echo 'export OPENAI_API_KEY="sk-your-key-here"' >> ~/.bashrc
source ~/.bashrc

Add to ~/.zshrc:

echo 'export OPENAI_API_KEY="sk-your-key-here"' >> ~/.zshrc
source ~/.zshrc
  1. Search for "Environment Variables" in Start Menu
  2. Click "Edit the system environment variables"
  3. Click "Environment Variables"
  4. Under "User variables", click "New"
  5. Add variable name (e.g., OPENAI_API_KEY) and value
  6. Click OK
  7. Restart your terminal

Verify Installation

python -c "import lumen; print(lumen.__version__)"

Test your LLM connection:

# Test script
import lumen.ai as lmai

llm = lmai.llm.OpenAI()  # or Anthropic(), Google(), etc.
ui = lmai.ExplorerUI(data='test.csv', llm=llm)
ui.servable()

Next Steps

Ready to start? Head to the Quick Start guide to chat with your first dataset.

Missing Your Favorite LLM?

Missing your favorite LLM? Let us know by submitting a GitHub issue!