Models and authentication¶

ChemGraph selects a provider from the model identifier. Run chemgraph models to see the identifiers registered by your installed version.

Provider routes¶

Provider	Model form	Credential or setup
OpenAI	`gpt-4o-mini`	`OPENAI_API_KEY`
Anthropic	`claude-...`	`ANTHROPIC_API_KEY`
Google Gemini	`gemini-...`	`GEMINI_API_KEY`
Groq	`groq:<model-id>`	`GROQ_API_KEY`
OpenRouter	`openrouter:<model-id>`	`OPENROUTER_API_KEY`
Argo	`argo:<model-id>`	`ARGO_USER` or `argo_user` in config
ALCF endpoints	Listed by `chemgraph models`	`ALCF_ACCESS_TOKEN`
Ollama	Curated local ID such as `llama3.2`	Running Ollama server; no key
vLLM/custom	Custom ID plus a configured base URL	`VLLM_API_KEY` or placeholder
Codex	`codex:<model-id>`	Experimental subscription setup

Only set credentials for providers you use. Do not commit secrets to config.toml, shell scripts, notebooks, or Git history.

Select and test a model¶

The default is gpt-4o-mini. Override it per command:

chemgraph run --model gpt-4o-mini -q "What is the formula of caffeine?"

Inspect the registry and validate configured credentials without starting a workflow:

chemgraph models
chemgraph run --model gpt-4o-mini --check-keys

Public API providers¶

Set the provider's environment variable before launching ChemGraph:

export OPENAI_API_KEY="..."
# or ANTHROPIC_API_KEY, GEMINI_API_KEY, or GROQ_API_KEY

Use the prefix shown by chemgraph models where one is required. Provider model catalogs change more frequently than ChemGraph releases; the CLI registry is the source of truth for identifiers supported by the installed version.

Argonne routes¶

Argo routes use the argo: prefix and an Argonne username:

export ARGO_USER="<anl-username>"
chemgraph run --model argo:gpt-4o -q "Summarize the water molecule."

For every argo: model, ChemGraph resolves the identity from an explicit or configured argo_user, then ARGO_USER, and finally the internal chemgraph placeholder required by the client libraries. Argo routes do not read an explicit api_key or OPENAI_API_KEY, so OpenAI credentials are never sent to an Argo endpoint.

ALCF-hosted inference routes use ALCF_ACCESS_TOKEN. Available endpoints and access policies are facility-managed, so use chemgraph models and the current ALCF service instructions rather than copying an old model name.

Local Ollama models¶

Start Ollama, pull a model supported by ChemGraph, then select it:

ollama pull llama3.2
chemgraph run --model llama3.2 -q "What is the formula of water?"

Local models vary substantially in tool-calling reliability. See Local models for limitations and advanced endpoints.

Configuration file¶

Non-secret endpoint settings and [api.argo].argo_user can be placed in config.toml. Use [api.vllm].base_url for an otherwise unknown custom model; leaving that canonical value empty prevents the direct OpenAI URL from becoming an accidental custom-model fallback. Choose the CLI model with --model; Streamlit reads its model default from the configuration file. Environment variables remain the recommended place for tokens. See Configuration for supported sections and interface-specific behavior.

Experimental Codex route¶

The Codex subscription integration has separate dependencies and authentication and is not an OpenAI API-key replacement for every workflow. See Codex subscription before using a codex: model.