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