152 lines
8.5 KiB
Markdown
152 lines
8.5 KiB
Markdown
# Configuration Resolution Chain
|
|
|
|
CleverAgents uses a multi-level configuration resolution chain that determines
|
|
the effective value for each configuration key. This document describes the
|
|
resolution order, all registered configuration keys, their types, defaults,
|
|
and environment variable mappings.
|
|
|
|
## Resolution Order
|
|
|
|
Values are resolved from **highest to lowest** priority. The first level that
|
|
provides a non-`None` value wins:
|
|
|
|
| Priority | Level | Description |
|
|
|----------|------------------|------------------------------------------------------|
|
|
| 1 | **CLI flag** | Value passed explicitly via `--key=value` on the CLI |
|
|
| 2 | **Env var** | Environment variable (`CLEVERAGENTS_<SECTION>_<KEY>`) |
|
|
| 3 | **Project scope**| Per-project override in `[project."<name>"]` TOML table |
|
|
| 4 | **Global config**| Value in `~/.cleveragents/config.toml` |
|
|
| 5 | **Default** | Built-in default from the key registry |
|
|
|
|
### Example
|
|
|
|
```
|
|
$ export CLEVERAGENTS_CORE_LOG_LEVEL=WARNING
|
|
$ agents config set core.log_level DEBUG # writes to global config
|
|
$ agents config get core.log_level
|
|
# -> WARNING (env var wins over global config)
|
|
```
|
|
|
|
## Environment Variable Convention
|
|
|
|
All registered keys map to environment variables following the pattern:
|
|
|
|
```
|
|
CLEVERAGENTS_<SECTION>_<KEY>
|
|
```
|
|
|
|
Where `<SECTION>` and `<KEY>` are uppercased. For example:
|
|
|
|
- `core.log_level` -> `CLEVERAGENTS_CORE_LOG_LEVEL`
|
|
- `plan.max_retries` -> `CLEVERAGENTS_PLAN_MAX_RETRIES`
|
|
- `provider.temperature` -> `CLEVERAGENTS_PROVIDER_TEMPERATURE`
|
|
|
|
## Configuration Keys
|
|
|
|
### `core.*` — Core Runtime
|
|
|
|
| Key | Type | Default | Env Var | Project-Scopable | Description |
|
|
|----------------------|--------|------------------------------|------------------------------------|-------------------|-------------------------------|
|
|
| `core.log_level` | `str` | `INFO` | `CLEVERAGENTS_CORE_LOG_LEVEL` | Yes | Logging verbosity level |
|
|
| `core.debug_enabled` | `bool` | `false` | `CLEVERAGENTS_CORE_DEBUG_ENABLED` | Yes | Enable debug mode |
|
|
| `core.env` | `str` | `development` | `CLEVERAGENTS_CORE_ENV` | Yes | Runtime environment name |
|
|
| `core.data_dir` | `str` | `data` | `CLEVERAGENTS_CORE_DATA_DIR` | Yes | Base data directory path |
|
|
| `core.database_url` | `str` | `sqlite:///cleveragents.db` | `CLEVERAGENTS_CORE_DATABASE_URL` | No | Primary database URL |
|
|
| `core.server_host` | `str` | `0.0.0.0` | `CLEVERAGENTS_CORE_SERVER_HOST` | No | Server bind host |
|
|
| `core.server_port` | `int` | `8080` | `CLEVERAGENTS_CORE_SERVER_PORT` | No | Server bind port |
|
|
|
|
### `plan.*` — Plan Execution
|
|
|
|
| Key | Type | Default | Env Var | Project-Scopable | Description |
|
|
|------------------------|--------|---------|--------------------------------------|-------------------|---------------------------------------|
|
|
| `plan.auto_apply` | `bool` | `false` | `CLEVERAGENTS_PLAN_AUTO_APPLY` | Yes | Auto-apply plans on completion |
|
|
| `plan.max_retries` | `int` | `3` | `CLEVERAGENTS_PLAN_MAX_RETRIES` | Yes | Maximum plan retry count |
|
|
| `plan.timeout_seconds` | `int` | `300` | `CLEVERAGENTS_PLAN_TIMEOUT_SECONDS` | Yes | Plan execution timeout in seconds |
|
|
|
|
### `provider.*` — LLM Provider
|
|
|
|
| Key | Type | Default | Env Var | Project-Scopable | Description |
|
|
|--------------------------|---------|---------|----------------------------------------|-------------------|-------------------------------|
|
|
| `provider.default_provider` | `str` | `""` | `CLEVERAGENTS_PROVIDER_DEFAULT_PROVIDER` | No | Default LLM provider name |
|
|
| `provider.default_model` | `str` | `""` | `CLEVERAGENTS_PROVIDER_DEFAULT_MODEL` | No | Default LLM model name |
|
|
| `provider.temperature` | `float` | `0.7` | `CLEVERAGENTS_PROVIDER_TEMPERATURE` | Yes | LLM sampling temperature |
|
|
| `provider.max_tokens` | `int` | `4096` | `CLEVERAGENTS_PROVIDER_MAX_TOKENS` | Yes | Max tokens per LLM response |
|
|
|
|
### `sandbox.*` — Sandbox Isolation
|
|
|
|
| Key | Type | Default | Env Var | Project-Scopable | Description |
|
|
|------------------------|--------|----------------|--------------------------------------|-------------------|---------------------------------------|
|
|
| `sandbox.strategy` | `str` | `git_worktree` | `CLEVERAGENTS_SANDBOX_STRATEGY` | Yes | Default sandbox strategy |
|
|
| `sandbox.auto_cleanup` | `bool` | `true` | `CLEVERAGENTS_SANDBOX_AUTO_CLEANUP` | Yes | Auto-clean sandbox after use |
|
|
| `sandbox.max_age_hours`| `int` | `48` | `CLEVERAGENTS_SANDBOX_MAX_AGE_HOURS` | Yes | Max sandbox age before cleanup |
|
|
|
|
### `context.*` — Context Management
|
|
|
|
| Key | Type | Default | Env Var | Project-Scopable | Description |
|
|
|--------------------------------|--------|----------|-------------------------------------------------|-------------------|--------------------------------------------|
|
|
| `context.max_files` | `int` | `100` | `CLEVERAGENTS_CONTEXT_MAX_FILES` | Yes | Maximum context files per session |
|
|
| `context.max_tokens` | `int` | `128000` | `CLEVERAGENTS_CONTEXT_MAX_TOKENS` | Yes | Maximum context token window |
|
|
| `context.auto_include_gitignore` | `bool` | `true` | `CLEVERAGENTS_CONTEXT_AUTO_INCLUDE_GITIGNORE` | Yes | Auto-include gitignore in context filtering |
|
|
|
|
### `index.*` — Vector Store Indexing
|
|
|
|
| Key | Type | Default | Env Var | Project-Scopable | Description |
|
|
|--------------------------|--------|---------|------------------------------------------|-------------------|---------------------------------|
|
|
| `index.enabled` | `bool` | `false` | `CLEVERAGENTS_INDEX_ENABLED` | Yes | Enable vector-store indexing |
|
|
| `index.backend` | `str` | `faiss` | `CLEVERAGENTS_INDEX_BACKEND` | Yes | Vector store backend name |
|
|
| `index.embedding_model` | `str` | `fake` | `CLEVERAGENTS_INDEX_EMBEDDING_MODEL` | Yes | Embedding model for indexing |
|
|
| `index.embedding_dimension` | `int` | `1536` | `CLEVERAGENTS_INDEX_EMBEDDING_DIMENSION` | Yes | Embedding vector dimension |
|
|
|
|
## Validation Rules
|
|
|
|
### Unknown Keys
|
|
|
|
Attempting to get or set an unregistered key will produce an actionable error:
|
|
|
|
```
|
|
ValueError: Unknown configuration key: 'bogus.key'.
|
|
Valid keys include: context.auto_include_gitignore, context.max_files, ...
|
|
```
|
|
|
|
### Type Mismatches
|
|
|
|
Values are coerced to the registered type. If coercion fails, an actionable
|
|
error is raised:
|
|
|
|
```
|
|
TypeError: Type mismatch for key 'core.server_port': expected int,
|
|
got str with value 'not_a_number'.
|
|
```
|
|
|
|
Boolean coercion accepts: `true`/`false`, `1`/`0`, `yes`/`no` (case-insensitive).
|
|
|
|
## TOML File Location
|
|
|
|
The global configuration file is stored at:
|
|
|
|
```
|
|
~/.cleveragents/config.toml
|
|
```
|
|
|
|
Parent directories are created automatically on first write. Project-scoped
|
|
overrides live under `[project."<name>"]` tables within the same file.
|
|
|
|
## Verbose Mode
|
|
|
|
When `--verbose` is passed to `config get`, the full resolution chain is
|
|
displayed, showing which level provided (or could provide) the value:
|
|
|
|
```
|
|
$ agents config get core.log_level --verbose
|
|
Key: core.log_level
|
|
Value: INFO
|
|
Source: default
|
|
|
|
Resolution chain (highest -> lowest priority):
|
|
cli_flag -> (not set)
|
|
env_var -> (not set) [CLEVERAGENTS_CORE_LOG_LEVEL]
|
|
project -> (not set)
|
|
global -> (not set) [~/.cleveragents/config.toml]
|
|
default -> INFO <-- active
|
|
```
|