Configuration¶

A TOML file can hold repeatable non-secret endpoint, MCP, logging, evaluation, and execution settings. For a first run, CLI flags and provider environment variables are usually simpler.

chemgraph run --config config.toml -q "What is the SMILES string for water?"

General settings and interface behavior¶

[general]
model = "gpt-4o-mini"
workflow = "single_agent"
output = "last_message"
structured = false
report = false
recursion_limit = 20
human_supervised = false

[logging]
level = "WARNING"

Streamlit consumes the [general] model, workflow, output, structured, report, and supervision defaults. On the CLI, use explicit flags for those settings:

chemgraph run --model gpt-4o-mini --workflow single_agent \
  --output last_message -q "What is the SMILES string for water?"

The CLI currently honors selected general/config values such as recursion_limit, enable_deepagent, and checkpoint_db, but its parser has concrete defaults for several other fields. Therefore a historical [general] value may not override a CLI default. The CLI flag is the reliable source for model/workflow/output behavior.

Provider endpoints¶

Environment variables are the recommended place for API keys and access tokens. TOML provider sections configure endpoints and an optional Argo username:

[api.openai]
base_url = "https://api.openai.com/v1"

[api.argo]
base_url = "https://apps.inside.anl.gov/argoapi/v1"
argo_user = ""

[api.vllm]
# Set this for custom OpenAI-compatible model IDs. An explicit empty value
# disables the one-release [api.openai] custom-endpoint fallback.
base_url = ""

[api.anthropic]
base_url = "https://api.anthropic.com"

[api.google]
base_url = "https://generativelanguage.googleapis.com/v1beta"

[api.alcf]
base_url = "https://inference-api.alcf.anl.gov/resource_server/sophia/vllm/v1"

[api.local]
base_url = "http://localhost:11434"

The selected model determines which section is consulted. See Models and authentication.

Base URLs resolve in this order: an explicit CLI/Python argument, the selected endpoint's canonical section, a supported legacy section, its environment variable, and finally its built-in default. For one release, argo: and custom model routes can read a legacy [api.openai].base_url when their canonical section is absent; ChemGraph logs migration guidance whenever it does so.

[api.argo].argo_user is the canonical Argo identity setting. The historical [api.openai].argo_user spelling remains supported for one release with a warning. Keep API keys and access tokens in endpoint-specific environment variables rather than TOML.

MCP connection¶

Configure either streamable HTTP:

[mcp]
url = "http://localhost:9003/mcp/"
server_name = "ChemGraph General Tools"

or a stdio launch command:

[mcp]
command = "python -m chemgraph.mcp.mcp_tools"
server_name = "ChemGraph General Tools"

Do not set both unless the consuming interface explicitly supports multiple definitions. See MCP servers.

Durable main-agent state¶

[general]
workflow = "main_agent"
checkpoint_db = "~/.chemgraph/checkpoints.db"
enable_deepagent = false
deepagent_discover_skills = true
# deepagent_skills = ["../external/AtomisticSkills/.agents/skills/"]

main_agent still requires interactive CLI mode. enable_deepagent controls only its optional deepagent subagent. To call the graph directly, select workflow = "deep_agent"; deepagent_workspace applies to either entry point. Deep Agent is a development-only capability with broad local access, so leave it disabled unless you understand the security boundary.

The headless-only --deepagent-dangerously-skip-approvals switch is intentionally not configurable through TOML. It must be typed explicitly for each run together with --deepagent-workspace.

deepagent_discover_skills defaults to true and controls personal/project skill discovery for local workspaces. Bundled skills are always available. The matching CLI boolean flag overrides TOML. See skills.

deepagent_skills is an ordered list of additional host skill directories. Relative paths resolve against the CLI invocation directory, not the workspace or TOML file directory. Absolute paths, ~, and .. are supported. It applies to a direct deep_agent or to an enabled main_agent worker. Later sources override earlier sources with the same skill name. A repeated --deepagent-skill CLI option replaces the TOML list for that run; explicitly disabling the worker with --no-deepagent also clears its configured skills. Omitting the list still loads bundled skills and any enabled automatic sources.

Evaluation profiles¶

[eval]
default_profile = "standard"

[eval.profiles.standard]
dataset = "./evaluation/questions.json"
workflow_types = ["single_agent"]
judge_type = "structured"
structured_output = true
recursion_limit = 50
max_queries = 0

Profile fields may be overridden by chemgraph eval flags. See Evaluation for dataset formats and judge modes.

Execution backend¶

Distributed execution reads the [execution] hierarchy and may also accept backend-specific environment variables. A minimal local choice is:

[execution]
backend = "local"

Parsl, Ensemble Launcher, Globus Compute, and transfer settings are deployment specific. Start from the runnable examples linked in HPC and Academy rather than copying credentials or endpoint IDs into documentation.

Which interface reads what?¶

Setting area	CLI run	Streamlit	Evaluation	Execution layer
`[general]`	Partial; prefer explicit run flags	Yes	No	No
`[api.*]`	Yes	Yes	Yes	No
`[mcp]`	Yes	Not the primary UI control	No	No
`[logging]`	Yes	Application-dependent	Yes	Yes
`[eval]`, `[eval.profiles.*]`	No	No	Yes	No
`[execution]`	Through backend tools	Through backend tools	No	Yes

Security¶

Never commit API keys, bearer tokens, endpoint secrets, or private paths. Pass secrets through environment variables or an approved secret manager. Sanitize configuration files before attaching them to bug reports.