cleveragents-core/docs/api/config.md

cleveragents.config — Configuration System

The config package provides application runtime configuration backed by environment variables, structured logging, metrics processing, and security scanning.

See ADR-024 for design rationale.

---

Settings

from cleveragents.config.settings import Settings

settings = Settings()
print(settings.provider)   # auto-detected from env
print(settings.model)      # default model for provider

Pydantic BaseSettings model. All fields are configurable via environment variables prefixed with CLEVERAGENTS_ (case-insensitive).

Key Fields

Field	Env Var	Description
provider	CLEVERAGENTS_PROVIDER	AI provider (openai, anthropic, …)
model	CLEVERAGENTS_MODEL	Model name
openai_api_key	OPENAI_API_KEY	OpenAI API key
anthropic_api_key	ANTHROPIC_API_KEY	Anthropic API key
google_api_key	GOOGLE_API_KEY	Google API key
azure_api_key	AZURE_OPENAI_API_KEY	Azure OpenAI API key
openrouter_api_key	OPENROUTER_API_KEY	OpenRouter API key
budget_per_plan	CLEVERAGENTS_BUDGET_PER_PLAN	Per-plan token budget
budget_per_day	CLEVERAGENTS_BUDGET_PER_DAY	Daily token budget
fallback_providers	CLEVERAGENTS_FALLBACK_PROVIDERS	Ordered fallback list
actor.default.estimation	CLEVERAGENTS_ACTOR__DEFAULT__ESTIMATION	Estimation actor name

Provider Auto-Detection

If no provider is explicitly set, Settings inspects the environment for known API keys in the following priority order:

openai → anthropic → google → azure → openrouter →
groq → together → cohere → gemini

Default Models

Provider	Default Model
openai	gpt-4o
anthropic	claude-sonnet-4-20250514
google / gemini	gemini-2.0-flash
azure	gpt-4o
openrouter	anthropic/claude-sonnet-4-20250514
cohere	command-r-plus

---

Logging

Module: cleveragents.config.logging

Configures structured logging (structlog or stdlib) based on the CLEVERAGENTS_LOG_LEVEL and CLEVERAGENTS_LOG_FORMAT environment variables.

from cleveragents.config.logging import configure_logging

configure_logging(level="INFO", format="json")

---

Metrics Processor

Module: cleveragents.config.metrics_processor

Processes and aggregates token usage and cost metrics from plan execution. Integrates with the cost/budget service.

---

Security Scanner

Module: cleveragents.config.security_scanner

Scans configuration values for accidentally included secrets (API keys, tokens, passwords) and redacts them before logging or serialization.

from cleveragents.config.security_scanner import scan_for_secrets

issues = scan_for_secrets({"db_url": "postgresql://user:password@host/db"})
# → [SecretIssue(field="db_url", pattern="password_in_url")]

---

Complete Environment Variable Reference

All CLEVERAGENTS_* environment variables recognised by the settings system. Variables marked secret are redacted from logs and CLI output.

Provider and Model Selection

Environment Variable	Type	Default	Description
CLEVERAGENTS_DEFAULT_PROVIDER	str	auto-detected	Pin the global LLM provider (openai, anthropic, google, azure, openrouter, groq, together, cohere, gemini)
CLEVERAGENTS_DEFAULT_MODEL	str	provider default	Pin the global model ID
CLEVERAGENTS_FALLBACK_PROVIDERS	str	""	Comma-separated ordered list of fallback providers (e.g. anthropic,openrouter)

Provider API Keys

Environment Variable	Provider	Secret
OPENAI_API_KEY	OpenAI	✓
ANTHROPIC_API_KEY	Anthropic	✓
GOOGLE_API_KEY	Google	✓
GOOGLE_GENAI_API_KEY	Google (alias)	✓
GEMINI_API_KEY	Gemini	✓
GOOGLE_GEMINI_API_KEY	Gemini (alias)	✓
AZURE_OPENAI_API_KEY	Azure OpenAI	✓
AZURE_OPENAI_ENDPOINT	Azure OpenAI	—
AZURE_OPENAI_DEPLOYMENT	Azure OpenAI	—
OPENROUTER_API_KEY	OpenRouter	✓
CLEVERAGENTS_OPENROUTER_ORGANIZATION	OpenRouter	—
GROQ_API_KEY	Groq	✓
TOGETHER_API_KEY	Together	✓
COHERE_API_KEY	Cohere	✓
HF_TOKEN	Hugging Face	✓

Paths and Storage

Environment Variable	Type	Default	Description
CLEVERAGENTS_DATA_DIR	path	~/.local/share/cleveragents	Root directory for database, logs, and runtime data
CLEVERAGENTS_CONFIG_PATH	path	~/.config/cleveragents/config.toml	Path to the TOML configuration file
CLEVERAGENTS_ACTOR_PATH	path	~/.config/cleveragents/actors	Directory scanned for custom actor YAML files
CLEVERAGENTS_DB_URL	str	SQLite in CLEVERAGENTS_DATA_DIR	Database URL (SQLite, PostgreSQL, MySQL, or DuckDB)

Budget and Cost Controls

Environment Variable	Type	Default	Description
CLEVERAGENTS_BUDGET_PER_PLAN	int	unlimited	Maximum tokens consumed per plan execution
CLEVERAGENTS_BUDGET_PER_DAY	int	unlimited	Maximum tokens consumed per calendar day

Actor Defaults

Environment Variable	Type	Default	Description
CLEVERAGENTS_ACTOR__DEFAULT__ESTIMATION	str	""	Name of the actor used for cost/effort estimation
CLEVERAGENTS_ACTOR__DEFAULT__INVARIANT	str	""	Name of the actor used for invariant reconciliation

Logging and Observability

Environment Variable	Type	Default	Description
CLEVERAGENTS_LOG_LEVEL	str	WARNING	Log level: DEBUG, INFO, WARNING, ERROR, CRITICAL
CLEVERAGENTS_LOG_FORMAT	str	text	Log format: text or json
CLEVERAGENTS_LANGSMITH_ENABLED	bool	false	Enable LangSmith tracing
CLEVERAGENTS_LANGSMITH_PROJECT	str	""	LangSmith project name
CLEVERAGENTS_LANGSMITH_API_KEY	str	""	LangSmith API key (secret)
CLEVERAGENTS_LANGSMITH_ENDPOINT	str	LangSmith default	LangSmith endpoint URL
CLEVERAGENTS_LANGSMITH_USER_ID	str	""	LangSmith user ID for trace attribution
CLEVERAGENTS_LANGSMITH_TAGS	str	""	Comma-separated tags added to all LangSmith traces

Testing

Environment Variable	Type	Default	Description
CLEVERAGENTS_TESTING_USE_MOCK_AI	bool	false	Force the in-repo mock provider; disables all real API calls

TUI

Environment Variable	Type	Default	Description
CLEVERAGENTS_TUI_ANIMATIONS	bool	true	Enable/disable TUI animations

---

Configuration File

CleverAgents reads a TOML configuration file from ~/.config/cleveragents/config.toml (or the path set by CLEVERAGENTS_CONFIG_PATH). Environment variables always take precedence over file values.

# ~/.config/cleveragents/config.toml

[defaults]
provider = "anthropic"
model = "claude-sonnet-4-20250514"
fallback_providers = ["openrouter", "openai"]

[budget]
per_plan = 100000
per_day = 1000000

[actor.default]
estimation = "local/my-estimator"
invariant = "local/my-invariant-checker"

[logging]
level = "INFO"
format = "json"

[langsmith]
enabled = true
project = "my-project"

---

Actor Configuration YAML Format

Custom actors are defined as YAML files placed in ~/.config/cleveragents/actors/ (or the path set by CLEVERAGENTS_ACTOR_PATH).

Minimal LLM Actor

name: local/my-assistant   # Required — must be namespace/identifier
type: llm                  # Required — llm | tool | graph
description: My assistant  # Required
model: gpt-4o              # Required for llm and graph types
version: "1.0"             # Optional

LLM Actor with Skills

name: local/code-assistant
type: llm
description: Code-focused assistant with file and git tools
model: claude-sonnet-4-20250514
version: "1.0"

skills:
  - local/file-ops
  - local/git-ops

Graph Actor (Multi-Node Workflow)

name: local/dev-pipeline
type: graph
description: Multi-step development pipeline
model: gpt-4o
version: "1.0"

skills:
  - local/file-ops

route:
  entry_node: planner
  exit_nodes:
    - reviewer

  nodes:
    - id: planner
      type: agent
      name: Planner
      description: Plans the implementation
      config:
        model: gpt-4o
        prompt: "Analyze requirements and create a plan."

    - id: implementer
      type: agent
      name: Implementer
      description: Implements the plan
      config:
        model: gpt-4o
        prompt: "Implement the changes per the plan."

    - id: gate
      type: conditional
      name: Quality Gate
      description: Routes based on lint result
      config:
        conditions:
          - check: "state.get('lint_ok') == True"
            route_to: reviewer
          - check: "state.get('lint_ok') == False"
            route_to: planner

    - id: reviewer
      type: agent
      name: Reviewer
      description: Reviews the implementation
      config:
        model: gpt-4o
        prompt: "Review the implementation for correctness."

  edges:
    - from_node: planner
      to_node: implementer
    - from_node: implementer
      to_node: gate
    - from_node: gate
      to_node: planner
    - from_node: gate
      to_node: reviewer

See Actor Configuration Reference for the full field listing and validation rules.

---

Action Configuration YAML Format

Actions define high-level tasks. They are typically created via the CLI (agents action create) but can also be written as YAML files.

name: local/refactor-auth
description: Refactor the authentication module to use async patterns
version: "1.0"

# Actor to use for this action
actor: local/dev-pipeline

# Automation profile (manual | review | supervised | cautious | trusted | autonomous | ci | full-auto)
automation_profile: trusted

# Resources this action operates on
resources:
  - type: git-checkout
    path: /path/to/repo
    name: main-repo

# Invariants enforced for every plan spawned from this action
invariants:
  - "All API changes must maintain backward compatibility"
  - "Test coverage must not decrease"

# Definition of Done
definition_of_done:
  must:
    - "All existing tests pass"
    - "New tests cover the changed code"
  should:
    - "Cyclomatic complexity does not increase"

---

Related Documentation

• ADR-024 Configuration System — design rationale
• ADR-025 Observability & Logging — LangSmith integration details
• Actor Configuration Reference — full actor YAML schema
• Diagnostics Check List — agents diagnostics checks
• Troubleshooting Guide — common configuration problems and fixes