OpenDataSciConfig¶

OpenDataSciConfig is the single configuration object accepted by create_agent and Agent. Every field can be set via:

Direct constructor argument
Environment variable (see the alias column below)
.env file in the current working directory (loaded automatically)
A YAML config file via OpenDataSciConfig.from_yaml(path)

TUI flags always take precedence over all of the above.

Quick reference¶

from opendatasci import OpenDataSciConfig

# Defaults — uses Anthropic with claude-sonnet-5
config = OpenDataSciConfig()

# OpenAI with custom temperature
config = OpenDataSciConfig(
    provider="openai",
    model="gpt-5.6-sol",
    openai_api_key="sk-...",
    temperature=0.2,
)

# Mixed providers — Anthropic for the primary model, OpenAI for summarisation
config = OpenDataSciConfig(
    provider="anthropic",
    secondary_provider="openai",
    secondary_model="gpt-5.6-luna",
    openai_api_key="sk-...",
)

# Load from YAML
config = OpenDataSciConfig.from_yaml("opendatasci_config.yaml")

Field reference¶

Model selection¶

Field	Env var	Default	Description
`provider`	`PROVIDER`	`"anthropic"`	LLM provider for the primary model
`model`	`MODEL`	(provider default)	Primary model identifier
`secondary_provider`	`SECONDARY_PROVIDER`	`"anthropic"`	Provider for the secondary model
`secondary_model`	`SECONDARY_MODEL`	(provider default)	Secondary model for lightweight tasks

API keys¶

Field	Env var	Description
`anthropic_api_key`	`ANTHROPIC_API_KEY`	Anthropic API key
`openai_api_key`	`OPENAI_API_KEY`	OpenAI / vLLM API key
`google_api_key`	`GOOGLE_API_KEY`	Google Gemini API key
`azure_api_key`	`AZURE_OPENAI_API_KEY`	Azure OpenAI API key

Cloud / endpoint settings¶

Field	Env var	Description
`aws_region`	`REGION`	AWS region for Bedrock
`google_cloud_project`	`GOOGLE_CLOUD_PROJECT`	GCP project ID for Vertex AI
`google_cloud_location`	`GOOGLE_CLOUD_LOCATION`	Vertex AI region
`azure_endpoint`	`AZURE_OPENAI_ENDPOINT`	Azure OpenAI resource endpoint URL
`azure_api_version`	`AZURE_OPENAI_API_VERSION`	Azure API version (default: `2025-01-01-preview`)
`llm_server_base_url`	`LLM_SERVER_BASE_URL`	Custom endpoint for Ollama / OpenAI-compatible server

Sampling & reasoning¶

Field	Env var	Default	Description
`temperature`	`TEMPERATURE`	`0.0`	LLM sampling temperature (not sent to Claude 4.6+ / Sonnet 5 models)

Agent behaviour¶

Field	Env var	Default	Description
`name`	`NAME`	`"Sai"`	Agent display name, injected into all system prompts
`midturn_compaction_threshold`	`MIDTURN_COMPACTION_THRESHOLD`	`96000`	Token count after which the agent's context is compacted mid-turn
`worker_timeout_seconds`	`WORKER_TIMEOUT_SECONDS`	`300.0`	Max seconds for all spawned workers to finish (`null` = no timeout)

Web access¶

Field	Env var	Default	Description
`extra_web_domains`	`EXTRA_FETCH_DOMAINS`	`[]`	Additional hostnames the `fetch_url` tool may access
`override_web_domains`		`None`	Replaces the built-in domain allowlist entirely when set

Skills¶

Field	Env var	Default	Description
`skills_directory`	`SKILLS_DIRECTORY`	`None`	Path to a user-defined skills directory
`builtin_skills_directory`	`BUILTIN_SKILLS_DIRECTORY`	(bundled)	Path to the built-in skills directory

Sandbox¶

Field	Env var	Default	Description
`local_code_exec_timeout`	`CODE_EXEC_TIMEOUT`	`1800`	Max seconds for a single local sandbox execution

MCP¶

Field	Env var	Default	Description
`mcp_servers`	`MCP_SERVERS`	`[]`	MCP tool server URLs

Default models per provider¶

Provider	Primary model	Secondary model
`anthropic`	`claude-sonnet-5`	`claude-haiku-4-5`
`openai`	`gpt-5.6-sol`	`gpt-5.6-luna`
`bedrock`	`us.anthropic.claude-sonnet-5`	`us.anthropic.claude-haiku-4-5-20251001-v1:0`
`gemini`	`gemini-3.5-flash`	`gemini-3.1-flash-lite`
`vertexai`	`gemini-3.5-flash`	`gemini-3.1-flash-lite`
`azure`	`gpt-5.6-sol`	`gpt-5.6-luna`
`ollama`	`qwen3.5:9b`	`qwen3.5:9b`
`openai_compatible_server`	`Qwen/Qwen3.5-4B`	`Qwen/Qwen3.5-4B`

YAML config file¶

# opendatasci_config.yaml
provider: anthropic
model: claude-sonnet-5

secondary_provider: openai
secondary_model: gpt-5.6-luna

temperature: 0.1

name: Sai

extra_web_domains:
  - arxiv.org
  - huggingface.co

worker_timeout_seconds: 600
midturn_compaction_threshold: 80000

config = OpenDataSciConfig.from_yaml("opendatasci_config.yaml")

Unknown keys in the YAML file are ignored, so config files written for other versions keep loading.

API reference¶

OpenDataSciConfig ¶

Bases: BaseSettings

Configuration for OpenDataSci.

All fields can be set via environment variables (names shown in parentheses) or a .env file. Pass an instance to :func:create_agent or :class:Agent to apply custom settings.

Attributes:

Name	Type	Description
`provider`	`Provider`	LLM provider for the primary model. One of `"anthropic"`, `"openai"`, `"bedrock"`, `"gemini"`, `"vertexai"`, `"azure"`, `"ollama"`, `"openai_compatible_server"` (any self-hosted OpenAI-compatible server, e.g. vLLM).
`model`	`str`	Provider-specific model identifier. Falls back to a sensible default per provider when not set.
`secondary_provider`	`Provider`	LLM provider for the secondary (auxiliary) model. Defaults to `provider` when not set. Set to a different provider to mix backends — e.g. Anthropic for the primary model and OpenAI for summarisation.
`secondary_model`	`str`	Model identifier for lightweight tasks such as memory summarisation. Falls back to a sensible default per provider when not set.
`anthropic_api_key`	`str \| None`	API key for Anthropic (`ANTHROPIC_API_KEY`).
`openai_api_key`	`str \| None`	API key for OpenAI and OpenAI-compatible servers (`OPENAI_API_KEY`).
`google_api_key`	`str \| None`	API key for Google Gemini (`GOOGLE_API_KEY`).
`azure_api_key`	`str \| None`	API key for Azure OpenAI (`AZURE_OPENAI_API_KEY`). Omit when using service-principal auth instead.
`aws_region`	`str`	AWS region for Bedrock (`REGION`). Defaults to `"us-east-1"` when not set.
`google_cloud_project`	`str \| None`	GCP project ID for Vertex AI (`GOOGLE_CLOUD_PROJECT`).
`google_cloud_location`	`str \| None`	Vertex AI region / location (`GOOGLE_CLOUD_LOCATION`).
`azure_endpoint`	`str \| None`	Azure OpenAI resource endpoint URL (`AZURE_OPENAI_ENDPOINT`). Required when `provider` is `"azure"`.
`azure_api_version`	`str`	Azure OpenAI API version (`AZURE_OPENAI_API_VERSION`). Defaults to `"2025-01-01-preview"`.
`llm_server_base_url`	`str \| None`	Base URL for self-hosted providers (`LLM_SERVER_BASE_URL`). Required for `"ollama"` and `"openai_compatible_server"`; falls back to `http://localhost:11434` and `http://localhost:8000/v1` respectively when not set.
`temperature`	`float`	LLM sampling temperature. Not sent to Anthropic and Bedrock models that use adaptive thinking (Claude 4.6+), which reject explicit sampling parameters.
`name`	`str`	Display name of the agent. Defaults to `"Sai"`.
`mcp_servers`	`List[str]`	List of MCP server URLs the agent may connect to (`MCP_SERVERS`).
`skills_directory`	`Path \| None`	Path to a directory of custom skill files (`SKILLS_DIRECTORY`). Loaded in addition to the built-in skills; custom skills override built-ins of the same name.
`builtin_skills_directory`	`Path`	Path to the built-in skills bundled with the package (`BUILTIN_SKILLS_DIRECTORY`). Override only if you need to replace the defaults entirely.
`skill_domains_directory`	`Path \| None`	Path to a directory of custom skill domains (`SKILL_DOMAINS_DIRECTORY`). Loaded in addition to the built-in skill domains; custom domains override built-ins of the same name.
`builtin_skill_domains_directory`	`Path`	Path to the built-in skill domains bundled with the package (`BUILTIN_SKILL_DOMAINS_DIRECTORY`). Override only if you need to replace the defaults entirely.
`extra_web_domains`	`List[str]`	Additional hostnames the `fetch_url` tool may retrieve, on top of the built-in allowlist. Example: `["internal.corp"]`.
`override_web_domains`	`List[str] \| None`	When set, replaces the built-in domain allowlist entirely. `extra_web_domains` is still applied on top. Use `[]` to block all domains.
`worker_timeout_seconds`	`float \| None`	Maximum seconds to wait for all spawned workers to finish. `None` disables the timeout. Defaults to `300.0` (5 minutes).
`midturn_compaction_threshold`	`int`	Token count after which the agent's context is compacted mid-turn (during a single turn's reasoning/acting loop). Must be strictly positive. Defaults to `96000`.
`local_code_exec_timeout`	`int`	Maximum seconds allowed for a single code-execution run in the local sandbox (`CODE_EXEC_TIMEOUT`). Defaults to `1800` (30 minutes).

Cloud authentication (environment variables read by the underlying SDKs):

AWS Bedrock — boto3 credential chain (pick one):

Long-lived IAM key: AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY
Temporary STS credentials: add AWS_SESSION_TOKEN to the above.
EC2 / ECS / Lambda: credentials are fetched automatically from the instance metadata service; no env vars required.

Google Vertex AI — Application Default Credentials chain (pick one):

Service account JSON key: set GOOGLE_APPLICATION_CREDENTIALS to the path of the key file; also set GOOGLE_CLOUD_PROJECT.
User credentials: run gcloud auth application-default login.
Cloud Run / GCE / GKE: credentials are fetched automatically; GOOGLE_CLOUD_PROJECT is still required.

Azure OpenAI — API key or service principal (not both):

API key: AZURE_OPENAI_API_KEY
Service principal (requires pip install 'open-data-sci[azure]'): set AZURE_TENANT_ID, AZURE_CLIENT_ID, and AZURE_CLIENT_SECRET.

from_yaml `classmethod` ¶

from_yaml(path: str | Path) -> OpenDataSciConfig

Load an OpenDataSciConfig from a YAML file.

The file must be a YAML mapping whose keys match OpenDataSciConfig field names. Unknown keys are ignored, so config files written for other versions keep loading. Environment variables are still applied for any field not present in the file.

Raises:

Type	Description
`ImportError`	If PyYAML is not installed.
`ValueError`	If the file does not contain a mapping.