license: relicense AGPL-3.0; bring SAF docs online; keep CLAUDE.md + docs/ local
SAF (souveraine architecture files) is now the in-repo doc set. working notes (CLAUDE.md, docs/) stay on disk, gitignored.
This commit is contained in:
Fimeg
parent
d35370b9c9
commit
3ff6ffaa7f
22 changed files with 2732 additions and 200 deletions
164
saf/config.md
Normal file
164
saf/config.md
Normal file
|
|
@ -0,0 +1,164 @@
|
|||
# SAF: Config Reference
|
||||
|
||||
> Every config option, its default, where it's read, and what it controls.
|
||||
> **Last updated:** 2026-05-12 (Full audit — 16 sections, many new since May 6)
|
||||
|
||||
---
|
||||
|
||||
## File: `souveraine.toml` (or `souveraine.yaml`)
|
||||
|
||||
Loaded by `ConsciousnessConfig::load()` in `src/core/config.rs`.
|
||||
|
||||
### `[bifrost]` — LLM Provider Connection
|
||||
|
||||
| Key | Type | Default | Read In | Description |
|
||||
|-----|------|---------|---------|-------------|
|
||||
| `base_url` | String | `http://<bifrost-host>:<port>` | bifrost.rs | Bifrost API endpoint |
|
||||
| `api_key` | String | (OS keyring or env) | bifrost.rs | Bearer token for auth. Falls back to `credentials::get_bifrost_key()` which checks env `BIFROST_KEY` then OS keyring |
|
||||
| `primary_model` | String | `fireworks/.../kimi-k2p5-turbo` | local.rs, server.rs | Default model for conversations |
|
||||
| `virtual_key` | String | (env `BIFROST_VIRTUAL_KEY`) | bifrost.rs | x-bf-vk header |
|
||||
|
||||
**Note:** The `api_key` may also include a Bifrost bearer token embedded in the example config. In-memory fallbacks read from env vars before the keyring.
|
||||
|
||||
### `[models.<name>]` — Per-Model Overrides
|
||||
|
||||
| Key | Type | Default | Description |
|
||||
|-----|------|---------|-------------|
|
||||
| `provider` | String | `"bifrost"` | Provider name |
|
||||
| `model` | String | — | Model path for provider |
|
||||
| `context_limit` | Uint | `128000` | Context window in tokens |
|
||||
| `output_limit` | Uint | `8192` | Max output tokens |
|
||||
| `archivist_threshold` | Float | `0.7` | Per-model archivist threshold |
|
||||
| `archivist_interval` | Uint | `100` | Per-model archivist interval |
|
||||
|
||||
**Note:** Model names with dots (like `kimi-k2.5-turbo`) must use quoted table headers: `[models."kimi-k2.5-turbo"]`. Built-in defaults for `kimi-k2p5-turbo` and `deepseek-v4-pro`.
|
||||
|
||||
### `[subconscious]` — N+1 / Aster Configuration
|
||||
|
||||
| Key | Type | Default | Description |
|
||||
|-----|------|---------|-------------|
|
||||
| `n1_enabled` | Bool | `true` | Enable N+1 subconscious pass |
|
||||
| `n1_trigger` | Enum | `every_response` | When to trigger: `every_response`, `every_n_responses(N)`, `time_based(S)`, `manual` |
|
||||
| `inbox_enabled` | Bool | `true` | Enable 3-box inbox system |
|
||||
| `model` | String (opt) | `None` | Model handle for Aster (e.g. `"openai/glm-5.1"`). None = use primary's model |
|
||||
| `max_tokens` | Uint (opt) | `None` | Max tokens for Aster's response. None = model default |
|
||||
|
||||
### `[reflection]` — N+25 Configuration
|
||||
|
||||
| Key | Type | Default | Description |
|
||||
|-----|------|---------|-------------|
|
||||
| `enabled` | Bool | `true` | Enable N+25 reflection |
|
||||
| `message_interval` | Uint | `25` | Messages between reflections |
|
||||
| `trigger` | Enum | `step_count` | `off`, `step_count`, `compaction_event` |
|
||||
|
||||
### `[archivist]` — N+100 Configuration (NOT WIRED)
|
||||
|
||||
| Key | Type | Default | Description |
|
||||
|-----|------|---------|-------------|
|
||||
| `enabled` | Bool | `true` | Enable N+100 compression |
|
||||
| `interval` | Uint | `100` | Messages between syntheses |
|
||||
| `threshold` | Float | `0.7` | Context pressure threshold (0.0-1.0) |
|
||||
| `compression_model` | String | `"auto"` | Model for synthesis (NOT used — archivist not rebuilt post-cleanup) |
|
||||
| `synthesis_elements` | Vec | `[Themes, Emotions, Tensions, Anchors, Evolution]` | Elements to include in synthesis |
|
||||
|
||||
**Critical:** N+100 archivist is **not implemented**. Config fields exist but nothing reads them. See gaps.md.
|
||||
|
||||
### `[compaction]` — In-Session Message Compaction
|
||||
|
||||
| Key | Type | Default | Description |
|
||||
|-----|------|---------|-------------|
|
||||
| `enabled` | Bool | `true` | Enable compaction engine |
|
||||
| `strategy` | Enum | `cull` | Default strategy: `microcompact`, `sliding_window`, `summary`, `cull` |
|
||||
| `warn_pressure` | Float | `0.80` | Tier-1 (warn) advisory threshold |
|
||||
| `urgent_pressure` | Float | `0.90` | Tier-2 (urgent) advisory threshold |
|
||||
| `critical_pressure` | Float | `0.95` | Tier-3 (critical) advisory threshold |
|
||||
|
||||
Per-agent-type overrides under `[compaction.per_type.<type>]` where type is `primary`, `subconscious`, or `subagent`. Each override has the same fields as above plus `max_summary_length`, `kv_target`, `min_messages`.
|
||||
|
||||
### `[subagent]` — Forked Agent Configuration
|
||||
|
||||
| Key | Type | Default | Description |
|
||||
|-----|------|---------|-------------|
|
||||
| `enabled` | Bool | `true` | Enable subagent spawning |
|
||||
| `max_concurrent` | Uint | `3` | Max concurrent forks |
|
||||
| `timeout` | Uint | `300` | Per-fork timeout in seconds |
|
||||
| `max_depth` | Uint | `3` | Max nesting depth |
|
||||
| `max_tool_rounds` | Uint | `50` | Max tool rounds per turn |
|
||||
| `warning_1_threshold` | Float | `0.80` | First "attention narrowing" warning |
|
||||
| `warning_2_threshold` | Float | `0.95` | Second "last chance" warning |
|
||||
| `inter_round_delay_ms` | Uint | `300` | Delay between subagent tool rounds |
|
||||
|
||||
### `[memory]` — Git-Backed Memory
|
||||
|
||||
| Key | Type | Default | Description |
|
||||
|-----|------|---------|-------------|
|
||||
| `git_enabled` | Bool | `true` | Enable git repo management |
|
||||
| `auto_commit` | Bool | `true` | Auto-commit on writes |
|
||||
| `auto_push` | Bool | `false` | Auto-push to remote (NOT used — push not implemented) |
|
||||
| `base_path` | Path (opt) | `None` → `~/.souveraine/` | Base path for memory & agents |
|
||||
|
||||
### `[server]` — HTTP Server Configuration
|
||||
|
||||
| Key | Type | Default | Description |
|
||||
|-----|------|---------|-------------|
|
||||
| `bind` | String | `127.0.0.1` | Server bind address |
|
||||
| `port` | Uint | `8484` | TCP port |
|
||||
| `url` | String | `http://127.0.0.1:8484` | Client-facing URL (env `SOUVERAINE_SERVER_URL` overrides) |
|
||||
|
||||
#### `[server.auth]`
|
||||
|
||||
| Key | Type | Default | Description |
|
||||
|-----|------|---------|-------------|
|
||||
| `required` | Bool | `true` | Require bearer token for memory routes |
|
||||
| `allow_loopback` | Bool | `true` | Allow 127.0.0.1/::1 to bypass auth |
|
||||
|
||||
### `[schedules]` — Cron Schedules
|
||||
|
||||
| Key | Type | Default | Description |
|
||||
|-----|------|---------|-------------|
|
||||
| `enabled` | Bool | `true` | Enable schedule system |
|
||||
| `schedules_dir` | Path (opt) | `None` | Custom schedules directory |
|
||||
|
||||
### `[events]` — Event Persistence (Firehose)
|
||||
|
||||
| Key | Type | Default | Description |
|
||||
|-----|------|---------|-------------|
|
||||
| `enabled` | Bool | `true` | Enable JSONL event log |
|
||||
| `events_dir` | Path (opt) | `None` | Custom events directory |
|
||||
| `retain_days` | Uint | `30` | Days to retain event logs |
|
||||
|
||||
### `[federation]` — Cross-Instance Sync
|
||||
|
||||
| Key | Type | Default | Description |
|
||||
|-----|------|---------|-------------|
|
||||
| `enabled` | Bool | `false` | Enable federation |
|
||||
| `instance_label` | String (opt) | `None` | Human-readable instance label |
|
||||
|
||||
### `[websocket]` — WebSocket Server
|
||||
|
||||
| Key | Type | Default | Description |
|
||||
|-----|------|---------|-------------|
|
||||
| `enabled` | Bool | `false` | Enable WebSocket listener |
|
||||
| `port` | Uint | `7373` | WebSocket port |
|
||||
|
||||
### `[sensorium]` — Interface Configuration (NOT WIRED)
|
||||
|
||||
| Key | Type | Default | Description |
|
||||
|-----|------|---------|-------------|
|
||||
| `primary_bandwidth` | Enum | `high` | Bandwidth class: `high`, `medium`, `low`, `minimal` |
|
||||
|
||||
---
|
||||
|
||||
## Environment Variables
|
||||
|
||||
| Variable | Overrides | Default |
|
||||
|----------|-----------|---------|
|
||||
| `SOUVERAINE_CONFIG_DIR` | Config search path | `~/.config/souveraine/` |
|
||||
| `SOUVERAINE_SERVER_URL` | Server client URL | `http://127.0.0.1:8484` |
|
||||
| `SOUVERAINE_SERVER_BIND` | Server bind address | Config value or `127.0.0.1:8484` |
|
||||
| `SOUVERAINE_API_KEY` | API bearer token | `""` |
|
||||
| `BIFROST_KEY` | Bifrost bearer token | (OS keyring) |
|
||||
| `BIFROST_VIRTUAL_KEY` | x-bf-vk header | `""` |
|
||||
| `SOUVERAINE_GITEA_URL` | Gitea API URL | (none) |
|
||||
| `SOUVERAINE_AGENT` | Default agent ID for memory tool | `"default"` |
|
||||
| `AGENT_ID` | Alternative agent ID env var | `"default"` |
|
||||
Loading…
Reference in a new issue