from __future__ import annotations """Pure, validated application settings schema.""" from typing import Annotated from pydantic import ( BaseModel, BeforeValidator, ConfigDict, Field, StringConstraints, field_validator, model_validator, ) from .api_keys import ApiKeyList from .constants import ( DEFAULT_MODEL, HTTP_CONNECT_TIMEOUT_DEFAULT, PROVIDER_MAX_ATTEMPTS_DEFAULT, ) from .custom_providers import CustomProviderDefinition, decode_custom_providers from .model_refs import ModelFallback, ModelFallbacks from .provider_catalog import ( BEDROCK_DEFAULT_BASE, PROVIDER_CATALOG, SUPPORTED_PROVIDER_IDS, ) from .reasoning import ReasoningPreference def _empty_to_none(value: object) -> object: if isinstance(value, str) and not value.strip(): return None return value NonEmptyString = Annotated[ str, StringConstraints(strip_whitespace=True, min_length=1), ] OptionalNonEmptyString = Annotated[ NonEmptyString | None, BeforeValidator(_empty_to_none), ] def _validate_model_ref(value: str) -> str: provider, separator, model = value.partition("/") if not separator or not provider: raise ValueError( "Model must be prefixed with provider type. " f"Valid providers: {', '.join(SUPPORTED_PROVIDER_IDS)}. " "Format: provider_type/model/name" ) if not model: raise ValueError("Model reference must include a non-empty model suffix.") return value class Settings(BaseModel): """Validated application settings with no file or process I/O.""" model_config = ConfigDict( frozen=True, validate_default=True, populate_by_name=True, extra="ignore", hide_input_in_errors=True, ) custom_providers: Annotated[ tuple[CustomProviderDefinition, ...], BeforeValidator(decode_custom_providers) ] = Field(default=(), validation_alias="FCC_CUSTOM_PROVIDERS") @property def provider_ids(self) -> tuple[str, ...]: return ( *SUPPORTED_PROVIDER_IDS, *(item.provider_id for item in self.custom_providers), ) def custom_provider(self, provider_id: str) -> CustomProviderDefinition | None: return next( (item for item in self.custom_providers if item.provider_id == provider_id), None, ) @model_validator(mode="after") def validate_provider_references(self) -> Settings: ids = [item.provider_id for item in self.custom_providers] names = [item.display_name.casefold() for item in self.custom_providers] if len(ids) != len(set(ids)) or len(names) != len(set(names)): raise ValueError("Custom provider names and IDs must be unique") for field in ( "model", "model_fable", "model_opus", "model_sonnet", "model_haiku", "model_fallbacks", ): value = getattr(self, field) refs = value if isinstance(value, tuple) else (value,) if value else () for ref in refs: model_ref = ref.model if isinstance(ref, ModelFallback) else ref provider_id = model_ref.partition("/")[0] if provider_id not in self.provider_ids: raise ValueError( f"{field.upper()}: Invalid provider in model reference" ) if isinstance(ref, ModelFallback) and ref.api_key_number > 1: definition = self.custom_provider(provider_id) descriptor = PROVIDER_CATALOG.get(provider_id) if definition is not None: keys = definition.api_keys elif descriptor is not None and descriptor.credential_attr: keys = getattr(self, descriptor.credential_attr) else: raise ValueError( f"MODEL_FALLBACKS: {provider_id} has no API key list." ) if ref.api_key_number > len(keys): raise ValueError( f"MODEL_FALLBACKS: {ref.model} selects Key " f"{ref.api_key_number}, but only {len(keys)} keys are " "configured. Update the fallback selection first." ) return self # ==================== OpenAI Platform API ==================== openai_api_keys: ApiKeyList = Field(default=(), validation_alias="OPENAI_API_KEY") # ==================== Azure OpenAI ==================== azure_openai_api_keys: ApiKeyList = Field( default=(), validation_alias="AZURE_OPENAI_API_KEY" ) azure_openai_base_url: OptionalNonEmptyString = Field( default=None, validation_alias="AZURE_OPENAI_BASE_URL" ) # ==================== OpenRouter Config ==================== open_router_api_keys: ApiKeyList = Field( default=(), validation_alias="OPENROUTER_API_KEY" ) # ==================== Mistral La Plateforme ==================== mistral_api_keys: ApiKeyList = Field(default=(), validation_alias="MISTRAL_API_KEY") # ==================== Mistral Codestral (codestral.mistral.ai) ==================== codestral_api_keys: ApiKeyList = Field( default=(), validation_alias="CODESTRAL_API_KEY" ) # ==================== DeepSeek Config ==================== deepseek_api_keys: ApiKeyList = Field( default=(), validation_alias="DEEPSEEK_API_KEY" ) # ==================== Kimi Config ==================== kimi_api_keys: ApiKeyList = Field(default=(), validation_alias="KIMI_API_KEY") # ==================== Kimi Code Subscription ==================== kimi_code_api_keys: ApiKeyList = Field( default=(), validation_alias="KIMI_CODE_API_KEY" ) # ==================== Wafer Config ==================== wafer_api_keys: ApiKeyList = Field(default=(), validation_alias="WAFER_API_KEY") # ==================== MiniMax Config ==================== minimax_api_keys: ApiKeyList = Field(default=(), validation_alias="MINIMAX_API_KEY") # ==================== OpenCode Zen / OpenCode Go ==================== # Same key from opencode.ai/auth; Zen uses ``opencode_zen/``, Go uses ``opencode_go/``. opencode_api_keys: ApiKeyList = Field( default=(), validation_alias="OPENCODE_API_KEY" ) # ==================== Vercel AI Gateway ==================== vercel_ai_gateway_api_keys: ApiKeyList = Field( default=(), validation_alias="AI_GATEWAY_API_KEY" ) # ==================== Amazon Bedrock Mantle ==================== bedrock_api_keys: ApiKeyList = Field( default=(), validation_alias="AWS_BEARER_TOKEN_BEDROCK" ) bedrock_base_url: NonEmptyString = Field( default=BEDROCK_DEFAULT_BASE, validation_alias="BEDROCK_BASE_URL", ) # ==================== Hugging Face Inference Providers ==================== huggingface_api_keys: ApiKeyList = Field( default=(), validation_alias="HUGGINGFACE_API_KEY" ) # ==================== Cohere Compatibility API ==================== cohere_api_keys: ApiKeyList = Field(default=(), validation_alias="COHERE_API_KEY") # ==================== SambaNova Cloud ==================== sambanova_api_keys: ApiKeyList = Field( default=(), validation_alias="SAMBANOVA_API_KEY" ) # ==================== Kilo.ai Config ==================== kilo_api_keys: ApiKeyList = Field(default=(), validation_alias="KILO_API_KEY") # ==================== Z.ai Coding Plan / General API ==================== zai_api_keys: ApiKeyList = Field(default=(), validation_alias="ZAI_API_KEY") # ==================== TokenRouter Config ==================== tokenrouter_api_keys: ApiKeyList = Field( default=(), validation_alias="TOKENROUTER_API_KEY" ) # ==================== NaraRoute Config ==================== nararoute_api_keys: ApiKeyList = Field( default=(), validation_alias="NARAROUTE_API_KEY" ) # ==================== Poolside AI (OpenAI-compatible) ==================== poolside_api_keys: ApiKeyList = Field( default=(), validation_alias="POOLSIDE_API_KEY" ) # ==================== LLM7.io (OpenAI-compatible) ==================== llm7_api_keys: ApiKeyList = Field(default=(), validation_alias="LLM7_API_KEY") # ==================== Lightning AI (OpenAI-compatible) ==================== lightning_api_keys: ApiKeyList = Field( default=(), validation_alias="LIGHTNING_API_KEY" ) # ==================== Experiential Labs (OpenAI-compatible) ==================== experiential_api_keys: ApiKeyList = Field( default=(), validation_alias="EXPLABS_API_KEY" ) # ==================== Cheaper Inference (OpenAI-compatible) ==================== cheaperinference_api_keys: ApiKeyList = Field( default=(), validation_alias="CHEAPER_INFERENCE_API_KEY" ) # ==================== OrcaRouter (OpenAI-compatible gateway) ==================== orcarouter_api_keys: ApiKeyList = Field( default=(), validation_alias="ORCAROUTER_API_KEY" ) # ==================== Atlas Cloud (OpenAI-compatible gateway) ==================== atlascloud_api_keys: ApiKeyList = Field( default=(), validation_alias="ATLASCLOUD_API_KEY" ) # ==================== xKiro (OpenAI-compatible gateway) ==================== xkiro_api_keys: ApiKeyList = Field(default=(), validation_alias="XKIRO_API_KEY") # ==================== Opper (OpenAI-compatible) ==================== opper_api_keys: ApiKeyList = Field(default=(), validation_alias="OPPER_API_KEY") # ==================== Fireworks AI Config ==================== fireworks_api_keys: ApiKeyList = Field( default=(), validation_alias="FIREWORKS_API_KEY" ) # ==================== Novita AI Config ==================== novita_api_keys: ApiKeyList = Field(default=(), validation_alias="NOVITA_API_KEY") # ==================== Cloudflare Workers AI Config ==================== cloudflare_api_tokens: ApiKeyList = Field( default=(), validation_alias="CLOUDFLARE_API_TOKEN" ) cloudflare_account_id: OptionalNonEmptyString = Field( default=None, validation_alias="CLOUDFLARE_ACCOUNT_ID" ) # ==================== Google Gemini (Google AI Studio) ==================== gemini_api_keys: ApiKeyList = Field(default=(), validation_alias="GEMINI_API_KEY") # ==================== Google Vertex AI ==================== vertex_project_id: OptionalNonEmptyString = Field( default=None, validation_alias="VERTEX_PROJECT_ID" ) vertex_location: NonEmptyString = Field( default="global", validation_alias="VERTEX_LOCATION" ) # ==================== Groq (OpenAI-compatible) ==================== groq_api_keys: ApiKeyList = Field(default=(), validation_alias="GROQ_API_KEY") # ==================== ClinePass (OpenAI-compatible) ==================== cline_api_keys: ApiKeyList = Field(default=(), validation_alias="CLINE_API_KEY") # ==================== xAI / Grok (OpenAI-compatible) ==================== xai_api_keys: ApiKeyList = Field(default=(), validation_alias="XAI_API_KEY") # ==================== Alibaba Cloud Model Studio ==================== anthropic_api_keys: ApiKeyList = Field( default=(), validation_alias="ANTHROPIC_API_KEY" ) anthropic_workspace_id: OptionalNonEmptyString = Field( default=None, validation_alias="ANTHROPIC_WORKSPACE_ID" ) anthropic_proxy: OptionalNonEmptyString = Field( default=None, validation_alias="ANTHROPIC_PROXY" ) alibaba_cloud_api_keys: ApiKeyList = Field( default=(), validation_alias="ALIBABA_CLOUD_API_KEY" ) alibaba_cloud_base_url: OptionalNonEmptyString = Field( default=None, validation_alias="ALIBABA_CLOUD_BASE_URL" ) # ==================== QwenCloud Token Plan (OpenAI-compatible) ==================== qwencloud_api_keys: ApiKeyList = Field( default=(), validation_alias="QWENCLOUD_API_KEY" ) # ==================== QwenCloud Coding Plan (OpenAI-compatible) ==================== qwencloud_coding_api_keys: ApiKeyList = Field( default=(), validation_alias="QWENCLOUD_CODING_API_KEY" ) # ==================== Together AI (OpenAI-compatible) ==================== together_api_keys: ApiKeyList = Field( default=(), validation_alias="TOGETHER_API_KEY" ) # ==================== DeepInfra (OpenAI-compatible) ==================== deepinfra_api_keys: ApiKeyList = Field( default=(), validation_alias="DEEPINFRA_API_KEY" ) # ==================== SiliconFlow (OpenAI-compatible) ==================== siliconflow_api_keys: ApiKeyList = Field( default=(), validation_alias="SILICONFLOW_API_KEY" ) # ==================== Nebius Token Factory (OpenAI-compatible) ==================== nebius_api_keys: ApiKeyList = Field(default=(), validation_alias="NEBIUS_API_KEY") # ==================== Chutes (OpenAI-compatible) ==================== chutes_api_keys: ApiKeyList = Field(default=(), validation_alias="CHUTES_API_KEY") # ==================== Featherless AI (OpenAI-compatible) ==================== featherless_api_keys: ApiKeyList = Field( default=(), validation_alias="FEATHERLESS_API_KEY" ) # ==================== Agnes AI (OpenAI-compatible) ==================== agnes_api_keys: ApiKeyList = Field(default=(), validation_alias="AGNES_API_KEY") # ==================== ZenMux (OpenAI-compatible) ==================== zenmux_api_keys: ApiKeyList = Field(default=(), validation_alias="ZENMUX_API_KEY") # ==================== W&B Inference (OpenAI-compatible) ==================== wandb_api_keys: ApiKeyList = Field(default=(), validation_alias="WANDB_API_KEY") # ==================== Cerebras Inference (OpenAI-compatible) ==================== cerebras_api_keys: ApiKeyList = Field( default=(), validation_alias="CEREBRAS_API_KEY" ) # ==================== Scaleway (OpenAI-compatible) ==================== scw_secret_keys: ApiKeyList = Field(default=(), validation_alias="SCW_SECRET_KEY") # ==================== Ollama Cloud ==================== ollama_api_keys: ApiKeyList = Field(default=(), validation_alias="OLLAMA_API_KEY") # ==================== Messaging Platform Selection ==================== # Valid: "telegram" | "discord" | "none" messaging_platform: NonEmptyString = Field( default="discord", validation_alias="MESSAGING_PLATFORM" ) messaging_rate_limit: int = Field( default=1, validation_alias="MESSAGING_RATE_LIMIT" ) messaging_rate_window: float = Field( default=1.0, validation_alias="MESSAGING_RATE_WINDOW" ) # ==================== NVIDIA NIM Config ==================== nvidia_nim_api_keys: ApiKeyList = Field( default=(), validation_alias="NVIDIA_NIM_API_KEY", ) # ==================== LM Studio Config ==================== lm_studio_base_url: NonEmptyString = Field( default="http://localhost:1234/v1", validation_alias="LM_STUDIO_BASE_URL", ) # ==================== Llama.cpp Config ==================== llamacpp_base_url: NonEmptyString = Field( default="http://localhost:8080/v1", validation_alias="LLAMACPP_BASE_URL", ) # ==================== Ollama Config ==================== ollama_base_url: NonEmptyString = Field( default="http://localhost:11434", validation_alias="OLLAMA_BASE_URL", ) # ==================== Model ==================== # All Claude model requests are mapped to this single model (fallback) # Format: provider_type/model/name model: NonEmptyString = Field( default=DEFAULT_MODEL, validation_alias="MODEL", ) # Per-model overrides (optional, use MODEL when unset) # Each can use a different provider model_fable: OptionalNonEmptyString = Field( default=None, validation_alias="MODEL_FABLE" ) model_opus: OptionalNonEmptyString = Field( default=None, validation_alias="MODEL_OPUS" ) model_sonnet: OptionalNonEmptyString = Field( default=None, validation_alias="MODEL_SONNET" ) model_haiku: OptionalNonEmptyString = Field( default=None, validation_alias="MODEL_HAIKU" ) model_fallbacks: ModelFallbacks = Field( default=None, validation_alias="MODEL_FALLBACKS", ) # ==================== Per-Provider Proxy ==================== openai_proxy: OptionalNonEmptyString = Field( default=None, validation_alias="OPENAI_PROXY" ) openai_api_proxy: OptionalNonEmptyString = Field( default=None, validation_alias="OPENAI_API_PROXY" ) xai_proxy: OptionalNonEmptyString = Field( default=None, validation_alias="XAI_PROXY" ) alibaba_cloud_proxy: OptionalNonEmptyString = Field( default=None, validation_alias="ALIBABA_CLOUD_PROXY" ) qwencloud_proxy: OptionalNonEmptyString = Field( default=None, validation_alias="QWENCLOUD_PROXY" ) qwencloud_coding_proxy: OptionalNonEmptyString = Field( default=None, validation_alias="QWENCLOUD_CODING_PROXY" ) together_proxy: OptionalNonEmptyString = Field( default=None, validation_alias="TOGETHER_PROXY" ) deepinfra_proxy: OptionalNonEmptyString = Field( default=None, validation_alias="DEEPINFRA_PROXY" ) siliconflow_proxy: OptionalNonEmptyString = Field( default=None, validation_alias="SILICONFLOW_PROXY" ) nebius_proxy: OptionalNonEmptyString = Field( default=None, validation_alias="NEBIUS_PROXY" ) chutes_proxy: OptionalNonEmptyString = Field( default=None, validation_alias="CHUTES_PROXY" ) featherless_proxy: OptionalNonEmptyString = Field( default=None, validation_alias="FEATHERLESS_PROXY" ) agnes_proxy: OptionalNonEmptyString = Field( default=None, validation_alias="AGNES_PROXY" ) zenmux_proxy: OptionalNonEmptyString = Field( default=None, validation_alias="ZENMUX_PROXY" ) wandb_proxy: OptionalNonEmptyString = Field( default=None, validation_alias="WANDB_PROXY" ) azure_openai_proxy: OptionalNonEmptyString = Field( default=None, validation_alias="AZURE_OPENAI_PROXY" ) nvidia_nim_proxy: OptionalNonEmptyString = Field( default=None, validation_alias="NVIDIA_NIM_PROXY" ) open_router_proxy: OptionalNonEmptyString = Field( default=None, validation_alias="OPENROUTER_PROXY" ) mistral_proxy: OptionalNonEmptyString = Field( default=None, validation_alias="MISTRAL_PROXY" ) codestral_proxy: OptionalNonEmptyString = Field( default=None, validation_alias="CODESTRAL_PROXY" ) lmstudio_proxy: OptionalNonEmptyString = Field( default=None, validation_alias="LMSTUDIO_PROXY" ) llamacpp_proxy: OptionalNonEmptyString = Field( default=None, validation_alias="LLAMACPP_PROXY" ) kimi_proxy: OptionalNonEmptyString = Field( default=None, validation_alias="KIMI_PROXY" ) kimi_code_proxy: OptionalNonEmptyString = Field( default=None, validation_alias="KIMI_CODE_PROXY" ) wafer_proxy: OptionalNonEmptyString = Field( default=None, validation_alias="WAFER_PROXY" ) minimax_proxy: OptionalNonEmptyString = Field( default=None, validation_alias="MINIMAX_PROXY" ) opencode_zen_proxy: OptionalNonEmptyString = Field( default=None, validation_alias="OPENCODE_ZEN_PROXY" ) opencode_go_proxy: OptionalNonEmptyString = Field( default=None, validation_alias="OPENCODE_GO_PROXY" ) vercel_ai_gateway_proxy: OptionalNonEmptyString = Field( default=None, validation_alias="VERCEL_AI_GATEWAY_PROXY" ) bedrock_proxy: OptionalNonEmptyString = Field( default=None, validation_alias="BEDROCK_PROXY" ) huggingface_proxy: OptionalNonEmptyString = Field( default=None, validation_alias="HUGGINGFACE_PROXY" ) cohere_proxy: OptionalNonEmptyString = Field( default=None, validation_alias="COHERE_PROXY" ) sambanova_proxy: OptionalNonEmptyString = Field( default=None, validation_alias="SAMBANOVA_PROXY" ) kilo_proxy: OptionalNonEmptyString = Field( default=None, validation_alias="KILO_PROXY" ) zai_proxy: OptionalNonEmptyString = Field( default=None, validation_alias="ZAI_PROXY" ) zai_api_proxy: OptionalNonEmptyString = Field( default=None, validation_alias="ZAI_API_PROXY" ) tokenrouter_proxy: OptionalNonEmptyString = Field( default=None, validation_alias="TOKENROUTER_PROXY" ) nararoute_proxy: OptionalNonEmptyString = Field( default=None, validation_alias="NARAROUTE_PROXY" ) poolside_proxy: OptionalNonEmptyString = Field( default=None, validation_alias="POOLSIDE_PROXY" ) llm7_proxy: OptionalNonEmptyString = Field( default=None, validation_alias="LLM7_PROXY" ) lightning_proxy: OptionalNonEmptyString = Field( default=None, validation_alias="LIGHTNING_PROXY" ) experiential_proxy: OptionalNonEmptyString = Field( default=None, validation_alias="EXPLABS_PROXY" ) cheaperinference_proxy: OptionalNonEmptyString = Field( default=None, validation_alias="CHEAPER_INFERENCE_PROXY" ) orcarouter_proxy: OptionalNonEmptyString = Field( default=None, validation_alias="ORCAROUTER_PROXY" ) atlascloud_proxy: OptionalNonEmptyString = Field( default=None, validation_alias="ATLASCLOUD_PROXY" ) xkiro_proxy: OptionalNonEmptyString = Field( default=None, validation_alias="XKIRO_PROXY" ) opper_proxy: OptionalNonEmptyString = Field( default=None, validation_alias="OPPER_PROXY" ) fireworks_proxy: OptionalNonEmptyString = Field( default=None, validation_alias="FIREWORKS_PROXY" ) novita_proxy: OptionalNonEmptyString = Field( default=None, validation_alias="NOVITA_PROXY" ) cloudflare_proxy: OptionalNonEmptyString = Field( default=None, validation_alias="CLOUDFLARE_PROXY" ) gemini_proxy: OptionalNonEmptyString = Field( default=None, validation_alias="GEMINI_PROXY" ) vertex_proxy: OptionalNonEmptyString = Field( default=None, validation_alias="VERTEX_PROXY" ) groq_proxy: OptionalNonEmptyString = Field( default=None, validation_alias="GROQ_PROXY" ) cline_pass_proxy: OptionalNonEmptyString = Field( default=None, validation_alias="CLINE_PASS_PROXY" ) cerebras_proxy: OptionalNonEmptyString = Field( default=None, validation_alias="CEREBRAS_PROXY" ) scw_proxy: OptionalNonEmptyString = Field( default=None, validation_alias="SCW_PROXY" ) ollama_cloud_proxy: OptionalNonEmptyString = Field( default=None, validation_alias="OLLAMA_CLOUD_PROXY" ) # ==================== Provider Rate Limiting ==================== provider_rate_limit: int = Field( default=1, gt=0, validation_alias="PROVIDER_RATE_LIMIT" ) provider_rate_window: int = Field( default=2, gt=0, validation_alias="PROVIDER_RATE_WINDOW" ) provider_max_concurrency: int = Field( default=2, gt=0, validation_alias="PROVIDER_MAX_CONCURRENCY" ) provider_progress_timeout: float = Field( default=900.0, gt=0, lt=float(1 << 64), allow_inf_nan=False, validation_alias="PROVIDER_PROGRESS_TIMEOUT", ) provider_max_attempts: int = Field( default=PROVIDER_MAX_ATTEMPTS_DEFAULT, gt=0, validation_alias="PROVIDER_MAX_ATTEMPTS", ) reasoning_policy: ReasoningPreference = Field( default=ReasoningPreference.CLIENT, validation_alias="REASONING_POLICY", ) reasoning_fable: ReasoningPreference = Field( default=ReasoningPreference.INHERIT, validation_alias="REASONING_FABLE", ) reasoning_opus: ReasoningPreference = Field( default=ReasoningPreference.INHERIT, validation_alias="REASONING_OPUS", ) reasoning_sonnet: ReasoningPreference = Field( default=ReasoningPreference.INHERIT, validation_alias="REASONING_SONNET", ) reasoning_haiku: ReasoningPreference = Field( default=ReasoningPreference.INHERIT, validation_alias="REASONING_HAIKU", ) # ==================== HTTP Client Timeouts ==================== http_read_timeout: float = Field( default=600.0, validation_alias="HTTP_READ_TIMEOUT" ) http_write_timeout: float = Field( default=30.0, validation_alias="HTTP_WRITE_TIMEOUT" ) http_connect_timeout: float = Field( default=HTTP_CONNECT_TIMEOUT_DEFAULT, validation_alias="HTTP_CONNECT_TIMEOUT", ) # ==================== Local web server tools (web_search / web_fetch) ==================== # On by default to match Claude Code's normal web-tool availability. enable_web_server_tools: bool = Field( default=True, validation_alias="ENABLE_WEB_SERVER_TOOLS" ) # Comma-separated URL schemes allowed for web_fetch (default: http,https). web_fetch_allowed_schemes: NonEmptyString = Field( default="http,https", validation_alias="WEB_FETCH_ALLOWED_SCHEMES" ) # When true, skip private/loopback/link-local IP blocking for web_fetch (lab only). web_fetch_allow_private_networks: bool = Field( default=False, validation_alias="WEB_FETCH_ALLOW_PRIVATE_NETWORKS" ) # ==================== Debug / diagnostic logging (avoid sensitive content) ==================== # Minimum log level for the JSON file sink (DEBUG, INFO, WARNING, ERROR, CRITICAL). log_level: NonEmptyString = Field(default="INFO", validation_alias="LOG_LEVEL") # When false (default), API and SSE helpers log only metadata (counts, lengths, ids). log_raw_api_payloads: bool = Field( default=False, validation_alias="LOG_RAW_API_PAYLOADS" ) log_raw_sse_events: bool = Field( default=False, validation_alias="LOG_RAW_SSE_EVENTS" ) # When false (default), unhandled exceptions log only type + route metadata (no message/traceback). log_api_error_tracebacks: bool = Field( default=False, validation_alias="LOG_API_ERROR_TRACEBACKS" ) # When false (default), messaging logs omit text/transcription previews (metadata only). log_raw_messaging_content: bool = Field( default=False, validation_alias="LOG_RAW_MESSAGING_CONTENT" ) # When true, log full Claude CLI stderr, non-JSON lines, and parser error text. log_raw_cli_diagnostics: bool = Field( default=False, validation_alias="LOG_RAW_CLI_DIAGNOSTICS" ) # When true, log exception text / CLI error strings in messaging (may leak user content). log_messaging_error_details: bool = Field( default=False, validation_alias="LOG_MESSAGING_ERROR_DETAILS" ) debug_platform_edits: bool = Field( default=False, validation_alias="DEBUG_PLATFORM_EDITS" ) debug_subagent_stack: bool = Field( default=False, validation_alias="DEBUG_SUBAGENT_STACK" ) # ==================== Voice Note Transcription ==================== voice_note_enabled: bool = Field( default=True, validation_alias="VOICE_NOTE_ENABLED" ) # Device: "cpu" | "cuda" | "nvidia_nim" # - "cpu"/"cuda": local Whisper (requires voice_local extra: uv sync --extra voice_local) # - "nvidia_nim": NVIDIA NIM Whisper API (included in the standard installation) whisper_device: NonEmptyString = Field( default="cpu", validation_alias="WHISPER_DEVICE" ) # Whisper model ID or short name (for local Whisper) or NVIDIA NIM model (for nvidia_nim) # Local Whisper: "tiny", "base", "small", "medium", "large-v2", "large-v3", "large-v3-turbo" # NVIDIA NIM: "nvidia/parakeet-ctc-1.1b-asr", "openai/whisper-large-v3", etc. whisper_model: NonEmptyString = Field( default="base", validation_alias="WHISPER_MODEL" ) # ==================== Bot Wrapper Config ==================== telegram_bot_token: OptionalNonEmptyString = Field( default=None, validation_alias="TELEGRAM_BOT_TOKEN", ) allowed_telegram_user_id: OptionalNonEmptyString = Field( default=None, validation_alias="ALLOWED_TELEGRAM_USER_ID", ) telegram_proxy_url: OptionalNonEmptyString = Field( default=None, validation_alias="TELEGRAM_PROXY_URL" ) discord_bot_token: OptionalNonEmptyString = Field( default=None, validation_alias="DISCORD_BOT_TOKEN" ) allowed_discord_channels: OptionalNonEmptyString = Field( default=None, validation_alias="ALLOWED_DISCORD_CHANNELS" ) allowed_dir: OptionalNonEmptyString = Field( default=None, validation_alias="ALLOWED_DIR", ) max_message_log_entries_per_chat: int | None = Field( default=None, validation_alias="MAX_MESSAGE_LOG_ENTRIES_PER_CHAT" ) # ==================== Server ==================== host: NonEmptyString = Field(default="0.0.0.0", validation_alias="HOST") port: int = Field(default=8082, validation_alias="PORT") open_admin_browser: bool = Field(default=True, validation_alias="FCC_OPEN_BROWSER") proxy_auth_enabled: bool = Field( default=False, validation_alias="PROXY_AUTH_ENABLED", ) proxy_auth_token: NonEmptyString = Field( default="freecc", validation_alias="ANTHROPIC_AUTH_TOKEN", ) @field_validator("max_message_log_entries_per_chat", mode="before") @classmethod def parse_optional_log_cap(cls, v: object) -> object: if v == "" or v is None: return None return v @field_validator("log_level") @classmethod def validate_log_level(cls, v: str) -> str: valid = {"DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"} upper = v.upper() if upper not in valid: raise ValueError(f"LOG_LEVEL must be one of {sorted(valid)}, got {v!r}") return upper @field_validator("reasoning_policy") @classmethod def validate_root_reasoning_policy( cls, value: ReasoningPreference ) -> ReasoningPreference: if value is ReasoningPreference.INHERIT: raise ValueError("REASONING_POLICY cannot inherit") return value @field_validator("whisper_device") @classmethod def validate_whisper_device(cls, v: str) -> str: if v not in ("cpu", "cuda", "nvidia_nim"): raise ValueError( f"whisper_device must be 'cpu', 'cuda', or 'nvidia_nim', got {v!r}" ) return v @field_validator("messaging_platform") @classmethod def validate_messaging_platform(cls, v: str) -> str: if v not in ("telegram", "discord", "none"): raise ValueError( f"messaging_platform must be 'telegram', 'discord', or 'none', got {v!r}" ) return v @field_validator("messaging_rate_limit") @classmethod def validate_messaging_rate_limit(cls, v: int) -> int: if v <= 0: raise ValueError("messaging_rate_limit must be > 0") return v @field_validator("messaging_rate_window") @classmethod def validate_messaging_rate_window(cls, v: float) -> float: if v <= 0: raise ValueError("messaging_rate_window must be > 0") return float(v) @field_validator("web_fetch_allowed_schemes") @classmethod def validate_web_fetch_allowed_schemes(cls, v: str) -> str: schemes = [part.strip().lower() for part in v.split(",") if part.strip()] if not schemes: raise ValueError("web_fetch_allowed_schemes must list at least one scheme") for scheme in schemes: if not scheme.isascii() or not scheme.isalpha(): raise ValueError( f"Invalid URL scheme in web_fetch_allowed_schemes: {scheme!r}" ) return ",".join(schemes) @field_validator( "model", "model_fable", "model_opus", "model_sonnet", "model_haiku" ) @classmethod def validate_model_format(cls, v: str | None) -> str | None: if v is None: return None return _validate_model_ref(v) @field_validator("model_fallbacks") @classmethod def validate_model_fallbacks( cls, value: tuple[ModelFallback, ...] | None ) -> tuple[ModelFallback, ...] | None: if value is None: return None refs = tuple((entry.model, entry.api_key_number) for entry in value) if len(refs) != len(set(refs)): raise ValueError( "MODEL_FALLBACKS must not contain duplicate model/key pairs." ) return value @model_validator(mode="after") def check_nvidia_nim_api_key(self) -> Settings: if ( self.voice_note_enabled and self.whisper_device == "nvidia_nim" and not self.nvidia_nim_api_keys ): raise ValueError( "NVIDIA_NIM_API_KEY is required when WHISPER_DEVICE is 'nvidia_nim'. " "Set it in the Admin UI." ) return self