Skip to content

config

diapason.core.config

Configuration loading, hardware detection, and engine recommendation.

User configuration lives at ~/.diapason/config.toml. load_config() detects hardware, fills sensible defaults, then overlays any user overrides found in the TOML file.

A2AConfig dataclass

Agent-to-Agent protocol settings.

ACEOptimizerConfig dataclass

ACE agent optimizer config. Maps to [learning.agent.ace].

ACE (Agentic Context Engineering) evolves a playbook — annotated natural-language strategies that get prepended to the agent's context — using a Generator / Reflector / Curator triad. Unlike DSPy (few-shot bootstrapping) or GEPA (Pareto-evolutionary prompt mutation), ACE writes a textual playbook that the agent reads at inference time.

See https://github.com/ace-agent/ace for the upstream reference. Install via pip install -e diapason[learning-ace] once the optional dep is available (ACE is not on PyPI as of v1.0.1; the extra installs from the upstream git repo).

AgentConfig dataclass

Agent harness settings — orchestration, tools, system prompt.

default_tools property writable

Deprecated: use agent.tools.

AgentLearningConfig dataclass

Agent sub-policy config within Learning.

AgentManagerConfig dataclass

Persistent agent manager settings.

AnalyticsConfig dataclass

External anonymous usage analytics (PostHog).

Separate concern from :class:TelemetryConfig, which stores local FLOPs/energy/inference metrics in SQLite. This controls anonymized usage events sent to the Diapason team's PostHog instance to measure setup success, retention, feature usage, and churn.

No chat content, prompts, model outputs, file paths, emails, IPs, or hardware identifiers are ever sent. See docs/telemetry.md.

AppleFmEngineConfig dataclass

Per-engine config for Apple Foundation Models.

BlueBubblesChannelConfig dataclass

Per-channel config for BlueBubbles (iMessage bridge).

BrowserConfig dataclass

Browser automation settings (Playwright).

CapabilitiesConfig dataclass

RBAC capability system settings.

ChannelConfig dataclass

Channel messaging settings.

CompressionConfig dataclass

Configuration for context compression.

ConfigurationError

Bases: RuntimeError

Raised when the resolved home directory would violate isolation guarantees.

DSPyOptimizerConfig dataclass

DSPy agent optimizer config. Maps to [learning.agent.dspy].

DeepResearchConfig dataclass

Planner settings for the web Deep Research endpoint.

DesktopConfig dataclass

Desktop automation / vision settings.

DesktopLightningConfig dataclass

Fast deterministic desktop execution before any model call.

DesktopVisionConfig dataclass

Screen capture / share → vision model (opt-in).

DiapasonConfig dataclass

Top-level configuration for Diapason.

memory property writable

Backward-compatible accessor — canonical location is tools.storage.

DictationConfig dataclass

Push-to-talk dictation polish + dictionary (Diapason-style).

DigestConfig dataclass

Configuration for the morning digest feature.

DigestSectionConfig dataclass

Configuration for a single digest section.

DiscordChannelConfig dataclass

Per-channel config for Discord.

EmailChannelConfig dataclass

Per-channel config for email (SMTP/IMAP).

EngineConfig dataclass

Inference engine settings with nested per-engine configs.

apple_fm_host property writable

Deprecated: use engine.apple_fm.host.

exo_host property writable

Deprecated: use engine.exo.host.

lemonade_host property writable

Deprecated: use engine.lemonade.host.

llamacpp_host property writable

Deprecated: use engine.llamacpp.host.

llamacpp_path property writable

Deprecated: use engine.llamacpp.binary_path.

lmstudio_host property writable

Deprecated: use engine.lmstudio.host.

mlx_host property writable

Deprecated: use engine.mlx.host.

nexa_host property writable

Deprecated: use engine.nexa.host.

ollama_host property writable

Deprecated: use engine.ollama.host.

sglang_host property writable

Deprecated: use engine.sglang.host.

uzu_host property writable

Deprecated: use engine.uzu.host.

vllm_host property writable

Deprecated: use engine.vllm.host.

ExoEngineConfig dataclass

Per-engine config for Exo.

FeishuChannelConfig dataclass

Per-channel config for Feishu (Lark).

GEPAOptimizerConfig dataclass

GEPA agent optimizer config. Maps to [learning.agent.gepa].

GRPOConfig dataclass

General-purpose GRPO training config. Maps to [learning.intelligence.grpo].

GemmaCppEngineConfig dataclass

Per-engine config for gemma.cpp.

GoogleChatChannelConfig dataclass

Per-channel config for Google Chat webhooks.

GpuInfo dataclass

Detected GPU metadata.

HardwareInfo dataclass

Detected system hardware.

HeartbeatConfig dataclass

Ambient HEARTBEAT.md queue drain (Diapason-style).

IRCChannelConfig dataclass

Per-channel config for IRC.

IntelligenceConfig dataclass

The model — identity, paths, quantization, and generation defaults.

IntelligenceLearningConfig dataclass

Intelligence sub-policy config within Learning.

LMStudioEngineConfig dataclass

Per-engine config for LM Studio.

LearningConfig dataclass

Learning system settings with per-primitive sub-policies.

agent_policy property writable

Deprecated: use learning.agent.policy.

default_policy property writable

Deprecated: use learning.routing.policy.

intelligence_policy property writable

Deprecated: use learning.intelligence.policy.

reward_weights property writable

Deprecated: use learning.metrics.*.

LemonadeEngineConfig dataclass

Per-engine config for Lemonade.

LlamaCppEngineConfig dataclass

Per-engine config for llama.cpp.

MCPConfig dataclass

MCP (Model Context Protocol) settings.

MLXEngineConfig dataclass

Per-engine config for MLX.

MatrixChannelConfig dataclass

Per-channel config for Matrix.

MattermostChannelConfig dataclass

Per-channel config for Mattermost.

MemoryFilesConfig dataclass

Persistent memory-file paths and nudge settings.

MeshConfig dataclass

Le maillage d'appareils, et ce qu'il chiffre.

chiffrement gouverne l'ÉMISSION seulement, et cette asymétrie est voulue :

  • opportuniste (défaut) — on scelle vers un pair dont on détient une clé fraîche, et l'on part en clair vers les autres. C'est ce qui laisse le client mobile fonctionner : il ne publie aucune clé.
  • exige — on refuse d'envoyer à un pair sans clé fraîche. Cela rend le téléphone injoignable, et il faut le savoir avant de le choisir.
  • jamais — le comportement d'avant le 26 août 2026, pour revenir en arrière sans rien désinstaller.

EN RÉCEPTION, le clair est accepté quel que soit ce réglage. Non par négligence : /v1/mesh/commands/deliver est l'une des cinq portes du téléphone, et le client figé y poste une enveloppe claire. Rendre exige symétrique casserait net un appareil déjà déployé. Sans cette phrase, quelqu'un croirait raisonnablement que sa machine n'accepte plus de clair.

MetricsConfig dataclass

Reward / optimization metric weights.

NexaEngineConfig dataclass

Per-engine config for Nexa.

OllamaEngineConfig dataclass

Per-engine config for Ollama.

OperatorsConfig dataclass

Operator lifecycle settings.

OptimizeConfig dataclass

Configuration optimization settings.

PrivacyConfig dataclass

The single, authoritative answer to "may this leave the machine?".

Before this section existed the question was asked in three unrelated places, each covering one path and none covering the rest:

  • speech.wakeword.require_local_only — declared, never read anywhere.
  • desktop.vision.allow_cloud — vision only.
  • nothing at all for speech-to-text or for LLM polish, which is how a failing local Whisper silently reached OpenAI and how dictation polish reached a cloud engine.

A promise that is enforced on some paths and not others is not a promise. local_only is therefore checked by every outbound path, and the per-domain switches may only ever be more restrictive than it — never less. Turning local_only on cannot be overridden by any of them.

New installations default to True. Existing cloud setups can opt in explicitly by setting local_only = false under [privacy].

ProactiveConfig dataclass

Proactive agent — autonomous action scheduling and approval routing.

ReflexionConfig dataclass

Le brouillon-critique des questions analytiques (server/reflexion.py).

model vide = le modèle du tour se relit lui-même ; un nom de modèle ("qwen3:14b") fait monter ces tours-là en gamme. Choisir un modèle qui COHABITE en mémoire avec celui du quotidien, sinon chaque question analytique évince le modèle de la voix et tout le monde attend.

RoutinesConfig dataclass

Named cron routines catalog (ROUTINES.json).

RoutingLearningConfig dataclass

Routing sub-policy config within Learning.

SFTConfig dataclass

General-purpose SFT training config. Maps to [learning.intelligence.sft].

SGLangEngineConfig dataclass

Per-engine config for SGLang.

SandboxConfig dataclass

Container sandbox settings.

SchedulerConfig dataclass

Task scheduler settings.

SecurityConfig dataclass

Security guardrails settings.

ServerConfig dataclass

API server settings.

SessionConfig dataclass

Cross-channel session settings.

SignalChannelConfig dataclass

Per-channel config for Signal (via signal-cli REST API).

SkillSourceConfig dataclass

Configuration for a single skill source (Hermes, OpenClaw, GitHub).

SkillsConfig dataclass

Configuration for agent-authored procedural skills.

SkillsLearningConfig dataclass

Configuration for the skills learning loop (Plan 2A).

SlackChannelConfig dataclass

Per-channel config for Slack.

SpecSearchCompositeRewardConfig dataclass

Composite reward weights for Intelligence-edit training (paper Eq. 1).

R(q, y) = alpha * R_acc - beta * E_hat - gamma * L_hat - delta * C_hat

SpecSearchLearningConfig dataclass

LLM-guided spec search config (paper §3.3, Algorithm 1).

Maps to [learning.spec_search] and is consumed by SpecSearchOrchestrator.from_config and SpecSearchLoop.

SpeechConfig dataclass

Speech-to-text settings.

StorageConfig dataclass

Storage (memory) backend settings.

Covers both the retrieval/document store (default_backend, db_path, chunking, context injection) and the automatic long-term memory service (enabled, backend, extraction_model, max_facts, facts_path) configured under [memory] in config.toml.

SystemPromptConfig dataclass

Limits and strategy for system-prompt assembly.

TeamsChannelConfig dataclass

Per-channel config for Microsoft Teams (Bot Framework).

TelegramChannelConfig dataclass

Per-channel config for Telegram.

TelemetryConfig dataclass

Telemetry persistence settings.

ToolsConfig dataclass

Tools primitive settings — wraps storage and MCP configuration.

TracesConfig dataclass

Trace system settings.

UzuEngineConfig dataclass

Per-engine config for Uzu.

VLLMEngineConfig dataclass

Per-engine config for vLLM.

VoiceRealtimeConfig dataclass

Duplex realtime voice (local pipeline / Gemini Live / OpenAI Realtime).

WakeWordConfig dataclass

Always-on / text-gate wake word (opt-in; local only).

WebChatChannelConfig dataclass

Per-channel config for in-memory webchat.

WebhookChannelConfig dataclass

Per-channel config for generic webhooks.

WhatsAppBaileysChannelConfig dataclass

Per-channel config for WhatsApp via Baileys protocol.

WhatsAppChannelConfig dataclass

Per-channel config for WhatsApp Cloud API.

WorkflowConfig dataclass

Workflow engine settings.

apply_security_profile(security_cfg, server_cfg, *, overrides=None)

Expand a named security profile into config fields.

Fields in overrides (explicitly set by the user in TOML) are not overwritten by the profile.

detect_hardware()

Auto-detect hardware capabilities with graceful fallbacks.

estimated_download_gb(parameter_count_b)

Estimate download size in GB for Q4_K_M quantized model.

generate_default_toml(hw, engine=None, *, host=None)

Render a commented TOML string suitable for ~/.diapason/config.toml.

generate_minimal_toml(hw, engine=None, *, host=None)

Render a minimal TOML config with only essential settings.

get_cache_dir()

Resolve the directory for regenerable caches (eval datasets, etc.).

Lives at <root>/cache so caches stay inside the single Diapason directory instead of scattering across ~/.cache.

get_config_dir()

Resolve Diapason' single root directory, honoring env overrides.

Precedence: $DIAPASON_HOME > $XDG_DATA_HOME/diapason > ~/.diapason. The result is always absolute and is rejected if it falls inside the Diapason source tree.

get_config_path()

Resolve the path to config.toml under the Diapason root.

get_data_dir()

Resolve the directory for persistent data (databases, blobs, …).

Consolidated under the single root; identical to :func:get_config_dir. Provided as a distinct name so call sites read intentionally.

load_config(path=None) cached

Detect hardware, build defaults, overlay TOML overrides.

Parameters

path: Explicit config file. If not set, uses DIAPASON_CONFIG when set, otherwise ~/.diapason/config.toml.

recommend_engine(hw)

Suggest the best inference engine for the detected hardware.

recommend_model(hw, engine)

Suggest a default model for the selected engine and hardware.

For Lemonade, prefer the validated Qwen3.6 35B A3B GGUF default. For other local engines, use the generic Qwen3.5 tier mapping.

validate_config_key(dotted_key)

Validate a dotted config key and return the leaf field's Python type.

Raises :class:ValueError when the key does not map to a known field. The function walks the DiapasonConfig dataclass hierarchy using dataclasses.fields().

Examples::

validate_config_key("engine.ollama.host")      # -> str
validate_config_key("intelligence.temperature") # -> float