LLM Providers¶

Agentomics-ML supports multiple LLM providers out of the box.

Supported Providers¶

Provider	Environment Variable	Models
OpenRouter	`OPENROUTER_API_KEY`	100+ models
OpenAI	`OPENAI_API_KEY`	Use `--list-models` to see available models
Anthropic	`ANTHROPIC_API_KEY`	Claude models available to your account
OpenAI Codex	`codex login`	Uses your local Codex/ChatGPT login
Ollama	Local setup	Local models

OpenRouter¶

Recommended for beginners - Access to 100+ models with one API key.

Setup¶

export OPENROUTER_API_KEY="sk-or-v1-xxxxxxxxxxxx"
./run.sh

Available Models¶

./run.sh --list-models

Model availability depends on your provider and API plan. Use ./run.sh --list-models to see what is available.

Provisioning Key¶

For temporary access without your own key:

./run.sh --use-provisioning-key

This requires PROVISIONING_OPENROUTER_API_KEY in your .env.

OpenAI¶

Direct access to OpenAI models.

Setup¶

export OPENAI_API_KEY="sk-xxxxxxxxxxxx"
./run.sh

Available Models¶

Use ./run.sh --list-models to see what your API key can access.

Anthropic¶

Direct access to Anthropic models.

Setup¶

export ANTHROPIC_API_KEY="sk-ant-xxxxxxxxxxxx"
./run.sh --provider anthropic --list-models

Use --provider anthropic explicitly when other provider keys are also set.

Codex (ChatGPT OAuth)¶

Experimental support for the local Codex CLI login flow.

Setup¶

First, sign into Codex on the same machine:

codex login

Then run Agentomics with the codex provider:

./run.sh --provider codex --list-models
./run.sh --provider codex --model gpt-5.4 --dataset my_data

This provider reads your local Codex auth state from ~/.codex/auth.json and uses the ChatGPT Codex backend instead of OPENAI_API_KEY.

If you are also setting OPENAI_API_KEY or OPENROUTER_API_KEY, pass --provider codex explicitly for non-interactive runs.

Ollama (Local Models)¶

Run models locally for privacy or offline use.

Requirements¶

Install Ollama
Pull a model: ollama pull <model-name>

Docker Mode (Recommended)¶

Set OLLAMA_BASE_URL so Agentomics considers Ollama available, then run with:

export OLLAMA_BASE_URL=http://localhost:11434/v1
./run.sh --ollama --provider ollama --model <ollama-model> --dataset <dataset>

Docker mode connects to the Ollama base URL defined in src/utils/providers/configured_providers.yaml (default: http://localhost:11434/v1) and uses host networking when --ollama is passed. Ensure your Ollama server is reachable from the host at :11434.

Local Mode¶

For local mode, set the Ollama base URL in src/utils/providers/configured_providers.yaml to http://localhost:11434/v1, then run:

export OLLAMA_BASE_URL=http://localhost:11434/v1
./run.sh --local --provider ollama --model <ollama-model> --dataset <dataset>

Popular Models¶

Run ollama list to see available models.

Custom Providers¶

Add custom providers in src/utils/providers/configured_providers.yaml:

providers:
  - name: "MyProvider"
    base_url: "https://api.myprovider.com/v1"
    apikey: "${MY_PROVIDER_API_KEY}"

Then set the API key:

export MY_PROVIDER_API_KEY="your-key"

For custom providers, use --model explicitly:

./run.sh --model my-custom-model

Provider Selection¶

When multiple providers are configured, they're all available. Use --list-models to see all options:

./run.sh --list-models

The interactive mode groups models by provider for easy selection.

Model Recommendations¶

Use Case	Recommended Model
Default	Use `--list-models` to pick
Privacy/Offline	Ollama local models

Troubleshooting¶

"API key not found"¶

Ensure your key is set:

echo $OPENROUTER_API_KEY  # Should show your key

"Model not available"¶

Check available models:

./run.sh --list-models

"Rate limit exceeded"¶

Wait and retry
Use a different provider
Check your API plan limits

Ollama connection refused¶

Ensure Ollama is running:

ollama list  # Should show pulled models

For Docker mode, run with --ollama so the container uses host networking, and verify the configured Ollama URL is reachable on the host.