# `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](../adr/ADR-024-configuration-system.md) for design rationale.

---

## `Settings`

```python
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.

```python
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.

```python
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")]
```