1. Scopo e confini

config è il componente trasversale che legge, valida, espone la configurazione a tutto il resto del sistema. Definisce una unica fonte di verità tipata (Settings) costruita per layering da file TOML, variabili d'ambiente e secret store. Questo doc non è il luogo dei valori: è il luogo del meccanismo.

Cosa copre

• Distinzione fra parametri configurabili e nuclei non-configurabili (Costituzione).
• Ordine di precedenza fra file, env, defaults, secret.
• Schema pydantic-settings (struttura e regole di validazione).
• Gestione dei secrets e relazione con observability.
• Hot reload sicuro e comandi CLI.

Cosa non copre

• La Costituzione (SOUL.md) → constitution. Non passa da config.
• I manifest dei neuroni → neuron. Non passano da config.
• Il contenuto di USER.md/IDENTITY.md → workspace.

2. Configurabile vs non configurabile

Tre categorie disgiunte. La distinzione è di design, non di comodo: spostare qualcosa da "non configurabile" a "configurabile" richiede un cambiamento nella Costituzione o un bump di versione del contratto.

3. Layering delle sorgenti

La configurazione finale è costruita per merge a strati: ogni strato successivo può aggiungere o sovrascrivere valori degli strati precedenti, mai toglierli. La validazione tipata avviene dopo il merge.

4. Schema pydantic-settings

Lo schema è una gerarchia di BaseSettings annidati, con env_prefix e supporto TOML via pydantic-settings 2.x.

from pydantic import BaseModel, SecretStr, Field, HttpUrl
from pydantic_settings import BaseSettings, SettingsConfigDict
from pathlib import Path

class GatewaySettings(BaseModel):
    bind_host: str = "127.0.0.1"
    bind_port: int = Field(8810, ge=1024, le=65535)
    public_base_url: HttpUrl | None = None

class LLMProviderSettings(BaseModel):
    name: str                          # "anthropic" | "openai" | "local-vllm"
    api_key: SecretStr | None = None
    base_url: HttpUrl | None = None
    model: str                         # es. "claude-sonnet-4-6"
    max_tokens: int = 4096

class CostTierSettings(BaseModel):
    local_fast: LLMProviderSettings
    frontier:   LLMProviderSettings
    budget_soft_eur: float = 2.0
    budget_hard_eur: float = 5.0

class MemorySettings(BaseModel):
    workspace_path: Path = Path("~/.myclaw/workspace").expanduser()
    episodic_retention_days: int = 60
    semantic_budget_kb: int = 2
    reflection_cron: str = "0 3 * * *"
    tau_days: int = 30                 # Ebbinghaus decay

class SynapseSettings(BaseModel):
    retrieval_epsilon: float = Field(0.05, ge=0, le=0.5)
    strike_threshold: int = 3
    dormant_days: int = 90
    quarantine_grace_days: int = 30

class ObservabilitySettings(BaseModel):
    audit_path: Path = Path(".audit")
    log_level: str = "INFO"
    metrics_enabled: bool = True

class Settings(BaseSettings):
    model_config = SettingsConfigDict(
        env_prefix="MYCLAW_",
        env_nested_delimiter="__",
        toml_file=("/etc/myclaw/config.toml",
                   "~/.config/myclaw/local.toml"),
        secrets_dir="/run/secrets/myclaw",   # file-per-secret, 0600
        extra="forbid",
        frozen=True,
    )

    gateway: GatewaySettings = GatewaySettings()
    llm:     CostTierSettings
    memory:  MemorySettings = MemorySettings()
    synapse: SynapseSettings = SynapseSettings()
    obs:     ObservabilitySettings = ObservabilitySettings()

Regole di validazione non negoziabili

• extra="forbid": chiavi sconosciute in un TOML → errore di avvio (tipografia catturata subito).
• frozen=True: Settings è immutabile dopo il load; nessun ramo di codice può "correggere runtime" la config.
• Tutti i SecretStr sono esclusi da model_dump_json() default (richiedono opt-in esplicito).
• Budget e soglie tunabili sono tutti esposti: niente magic number hardcoded in altri moduli.

5. Secrets: dove vivono, come si leggono

Un secret non è una variabile di configurazione. I segreti abitano un proprio canale e vengono letti come SecretStr, il cui valore è accessibile solo con .get_secret_value(). Ogni logger normale li stampa come **********.

Sorgenti permesse (in ordine di preferenza)

1. File-per-secret in /run/secrets/myclaw/, uno per chiave (es. llm__frontier__api_key), mode 0600, owner myclaw. Letti via secrets_dir di pydantic-settings. Preferita.
2. Variabili d'ambiente MYCLAW_LLM__FRONTIER__API_KEY=.... Accettate ma l'environment è visibile in /proc/<pid>/environ: meno robusto.
3. File TOML: NON permesso per secrets. Il loader rifiuta un SecretStr che venga popolato da config.toml/local.toml (ValueError all'avvio).

Regole di gestione

• I secrets non appaiono nei log di obs anche a DEBUG.
• L'audit event di caricamento config include un digest (sha256 prefisso) del secret, non il valore.
• Rotazione: cambio del file + systemctl kill -s HUP myclaw → hot reload (vedi §6).
• I secrets sono esclusi da snapshot di diagnostica (myclaw diag li redige automaticamente).

6. Hot reload

Non tutta la config può essere ricaricata a caldo senza rischio. La separo in tre classi:

Il loader mantiene una classificazione per campo: un campo marcato restart_required=True che cambia tra due load non applica il nuovo valore ma logga la differenza come evento config.restart_pending.

7. CLI operativa

Una manciata di comandi per trasparenza e ops. Tutti rispettano la regola secrets-redatti.

8. Contratto Python

from typing import Protocol, Literal
from pathlib import Path

class ConfigLoader(Protocol):
    def load(self) -> "Settings":
        """Merge dei 5 strati + validazione. Solleva ValidationError con
        path del campo offensore."""
        ...

    def reload(self, signal: Literal["SIGHUP"] | None = None) -> "ConfigDiff":
        """Esegue load, confronta con la corrente, applica solo i campi
        hot-reloadable. Ritorna il diff."""
        ...

    def provenance(self, field_path: str) -> Literal["default", "toml", "local", "env", "secret"]:
        """Dice da quale strato viene l'attuale valore di un campo."""
        ...

@dataclass
class ConfigDiff:
    applied: list[str]              # campi hot-reloadable cambiati e applicati
    restart_pending: list[str]      # campi cambiati ma non applicati
    unchanged: int
    new_hash: str                   # sha256 del dump redacted

# Errori
class ConfigValidationError(Exception): ...
class SecretInTomlError(Exception): ...  # secret letto da TOML: rifiutato
class UnknownConfigKeyError(Exception): ...  # extra="forbid"

9. Alternative considerate

10. Test di conformità

11. Riferimenti

Continua a leggere

myclaw — config microprogettazione v1.0 — 2026-04-22
Ultimo doc dell'ordine canonico. La tabella di microprogettazione è completa.