cadrumo.core.config module

Central settings facade for Cadrumo.

The Settings model is the environment authority for Cadrumo configuration: operators and tests override fields here, and downstream code obtains the effective model through load_settings() or override_settings(). Runtime-tunable Cadrumo settings stay in this schema, while AEAT and Sede route and selector defaults come from core.external_constants through the default factories below.

The storage boundary exposed here is also deliberate. Database URL derivation, active-profile bucket routing, and route classification are surfaced through StorageRouteClassification, classify_storage_route(), and settings_for_active_profile_bucket() so write guards do not re-parse SQL URLs or active-profile pointers independently.

DEV_TEST_DATABASE_PASSWORD

Shared development/test password for database-backed secure-storage tests.

class Settings(_case_sensitive=None, _nested_model_default_partial_update=None, _env_prefix=None, _env_prefix_target=None, _env_file=PosixPath('.'), _env_file_encoding=None, _env_ignore_empty=None, _env_nested_delimiter=None, _env_nested_max_split=None, _env_parse_none_str=None, _env_parse_enums=None, _cli_prog_name=None, _cli_parse_args=None, _cli_settings_source=None, _cli_parse_none_str=None, _cli_hide_none_type=None, _cli_avoid_json=None, _cli_enforce_required=None, _cli_use_class_docs_for_groups=None, _cli_show_env_vars=None, _cli_exit_on_error=None, _cli_prefix=None, _cli_flag_prefix_char=None, _cli_implicit_flags=None, _cli_ignore_unknown_args=None, _cli_kebab_case=None, _cli_shortcuts=None, _secrets_dir=None, _build_sources=None, **values)[source]

Bases: CadrumoLlmSettings

Application settings populated from process environment variables.

Field names map directly to env var names (uppercased). For example, aeat_base_url reads AEAT_BASE_URL. There is no .env file support: the process environment is the sole external override channel, alongside the in-process init_settings source that --profile and override_settings() write through. The model is declarative: it carries operator choices, timeouts, storage roots, live-read opt-ins, and provider selectors, but does not open secret stores, build outbound providers, or execute AEAT browser flows.

Validators keep derived paths coherent with cadrumo_local_storage_root and derive cadrumo_database_url from either an explicit field, the active profile, or the cold root fallback. Tests and CLI scopes should prefer override_settings() over process-wide environment mutation whenever they are not explicitly testing environment parsing.

Parameters:

  • _case_sensitive (bool | None)

  • _nested_model_default_partial_update (bool | None)

  • _env_prefix (str | None)

  • _env_prefix_target (EnvPrefixTarget | None)

  • _env_file (DotenvType | None)

  • _env_file_encoding (str | None)

  • _env_ignore_empty (bool | None)

  • _env_nested_delimiter (str | None)

  • _env_nested_max_split (int | None)

  • _env_parse_none_str (str | None)

  • _env_parse_enums (bool | None)

  • _cli_prog_name (str | None)

  • _cli_parse_args (bool | list[str] | tuple[str, ...] | None)

  • _cli_settings_source (CliSettingsSource[Any] | None)

  • _cli_parse_none_str (str | None)

  • _cli_hide_none_type (bool | None)

  • _cli_avoid_json (bool | None)

  • _cli_enforce_required (bool | None)

  • _cli_use_class_docs_for_groups (bool | None)

  • _cli_show_env_vars (bool | None)

  • _cli_exit_on_error (bool | None)

  • _cli_prefix (str | None)

  • _cli_flag_prefix_char (str | None)

  • _cli_implicit_flags (bool | Literal['dual', 'toggle'] | None)

  • _cli_ignore_unknown_args (bool | None)

  • _cli_kebab_case (bool | Literal['all', 'no_enums'] | None)

  • _cli_shortcuts (Mapping[str, str | list[str]] | None)

  • _secrets_dir (PathType | None)

  • _build_sources (tuple[tuple[PydanticBaseSettingsSource, ...], dict[str, Any]] | None)

  • cadrumo_browser_navigation_timeout_ms (int)

  • cadrumo_browser_form_interaction_timeout_ms (int)

  • cadrumo_browser_ver_click_timeout_ms (int)

  • cadrumo_browser_buscar_settle_ms (int)

  • cadrumo_browser_selector_probe_timeout_ms (int)

  • cadrumo_browser_close_timeout_ms (int)

  • cadrumo_live_iva_surface_timeout_ms (int)

  • cadrumo_live_iva_declaration_capture_timeout_ms (int)

  • cadrumo_live_filed_register_walk_timeout_ms (int)

  • cadrumo_live_iva_cancellation_drain_ms (int)

  • cadrumo_live_iva_cli_watchdog_timeout_ms (int)

  • cadrumo_fx_rate_lookup_timeout_s (int)

  • cadrumo_llm_openai_chat_completions_url (str)

  • cadrumo_llm_gemini_generate_content_template (str)

  • cadrumo_llm_ollama_chat_url (str)

  • cadrumo_llm_ollama_num_ctx (int)

  • cadrumo_llm_vision_read_timeout_s (int)

  • cadrumo_llm_ollama_vision_model (str)

  • cadrumo_llm_ollama_text_model (str)

  • cadrumo_llm_ollama_mapping_model (str)

  • cadrumo_llm_cloud_vision_model (str)

  • cadrumo_llm_cloud_text_model (str)

  • cadrumo_llm_cloud_mapping_model (str)

  • cadrumo_llm_model_runtime_memory_floor_bytes (int)

  • cadrumo_llm_contention_safety_margin_bytes (int)

  • cadrumo_llm_contention_check_override (bool)

  • cadrumo_llm_local_inference_concurrency (int)

  • cadrumo_llm_default_max_tokens (int)

  • cadrumo_llm_default_temperature (float)

  • cadrumo_browser_locale (str)

  • cadrumo_browser_timezone (str)

  • cadrumo_browser_viewport_width (int)

  • cadrumo_browser_viewport_height (int)

  • cadrumo_file_lock_timeout_s (float)

  • cadrumo_file_lock_retry_backoff_s (float)

  • cadrumo_bucket_lock_poll_interval_s (float)

  • cadrumo_bucket_default_idle_lock_minutes (int)

  • cadrumo_bucket_default_session_absolute_minutes (int)

  • cadrumo_auth_clave_movil_lock_buffer_s (int)

  • cadrumo_auth_certificate_lock_ttl_s (int)

  • cadrumo_log_stderr_level (str)

  • cadrumo_log_file_level (str)

  • cadrumo_log_file_max_bytes (int)

  • cadrumo_log_file_backup_count (int)

  • cadrumo_log_root_level (str)

  • cadrumo_manuals_http_timeout_s (float)

  • cadrumo_google_drive_vault_folder_name (str)

  • cadrumo_google_oauth_access_refresh_buffer_s (int)

  • cadrumo_calc_sheets_recalc_delay_s (float)

  • financial_base_currency (str)

  • financial_default_csv_encoding (str)

  • cadrumo_financial_txs_dir (Path)

  • cadrumo_invoices_dir (Path)

  • cadrumo_attachments_dir (Path)

  • cadrumo_usage_ratios_path (Path)

  • cadrumo_llm_provider (LLMProvider)

  • cadrumo_llm_model (str)

  • cadrumo_llm_anthropic_api_key (SecretStr | None)

  • cadrumo_llm_openai_api_key (SecretStr | None)

  • cadrumo_llm_gemini_api_key (SecretStr | None)

  • cadrumo_llm_cache_dir (Path)

  • cadrumo_llm_usage_dir (Path)

  • cadrumo_llm_run_telemetry_dir (Path)

  • cadrumo_llm_run_telemetry_retention_days (int)

  • cadrumo_llm_run_telemetry_max_records (int)

  • cadrumo_llm_cache_retention_days (int)

  • cadrumo_llm_cache_max_records (int)

  • cadrumo_llm_usage_retention_days (int)

  • cadrumo_llm_usage_max_records (int)

  • cadrumo_llm_default_timeout_s (int)

  • cadrumo_llm_max_retries (int)

  • cadrumo_token_dir (Path)

  • aeat_base_url (str)

  • cadrumo_log_level (str)

  • cadrumo_tui_appearance (TuiAppearance)

  • cadrumo_output_language (Annotated[OutputLanguage | None, BeforeValidator(func=~cadrumo.core.config_support.coerce_output_language_setting, json_schema_input_type=PydanticUndefined)])

  • aeat_authoritative_language_aeat_terms (str)

  • cadrumo_authoritative_language_project_docs (str)

  • cadrumo_fallback_languages (str)

  • cadrumo_database_url (str)

  • cadrumo_secret_store_dir (Path)

  • cadrumo_dev_test_database_password (SecretStr)

  • cadrumo_blob_store_dir (Path)

  • cadrumo_live_state_dir (Path)

  • cadrumo_storage_provider_kind (str)

  • cadrumo_local_storage_root (Path)

  • cadrumo_google_drive_root_folder_id (str | None)

  • cadrumo_profile_kdf_measure_calibration (bool)

  • cadrumo_live_tests_enabled (str)

  • cadrumo_live_tests_google (str)

  • cadrumo_force_color (bool)

  • no_color (bool)

  • cadrumo_cli_reveal_identifiers (bool)

  • cadrumo_log_dir (Path | None)

  • cadrumo_secret_passphrase (SecretStr | None)

  • aeat_manuals_root (Path)

  • aeat_normatives_root (Path)

  • cadrumo_corpus_search_cache_dir (Path)

  • cadrumo_authority_root (Path | None)

  • cadrumo_browser_channel (str)

  • cadrumo_browser_headless (bool)

  • cadrumo_wallet_diagnostic_dump_dir (Path | None)

  • cadrumo_wallet_diagnostic_retention_days (int)

  • cadrumo_active_profile (str | None)

  • cadrumo_proxy_url (str)

  • cadrumo_proxy_username (str)

  • cadrumo_proxy_password_secret (SecretStr | None)

  • cadrumo_proxy_bypass (str)

  • cadrumo_rate_limit_delay_seconds (float)

  • site_health_probe_url (str)

  • site_health_rate_limit_retry_after_default (int)

  • cadrumo_certificate_path (Path | None)

  • cadrumo_certificate_password_secret (SecretStr | None)

  • cadrumo_certificate_friendly_name (str | None)

  • cadrumo_auth_timeout_ms (int)

  • cadrumo_strict_security (bool)

  • cadrumo_cert_warn_days (int)

  • cadrumo_cert_critical_days (int)

  • cadrumo_auth_provider (AuthProviderKind | None)

  • cadrumo_clave_movil_dni_nie (SecretStr | None)

  • cadrumo_clave_movil_dni_fecha (str | None)

  • cadrumo_clave_movil_nie_soporte (SecretStr | None)

  • cadrumo_clave_prefer_non_qr (bool)

  • cadrumo_clave_movil_timeout_ms (int)

  • aeat_clave_sede_access_url_template (str)

  • aeat_sede_expedientes_path (str)

  • cadrumo_clave_permanente_dni_nie (SecretStr | None)

  • cadrumo_clave_permanente_password (SecretStr | None)

  • cadrumo_clave_permanente_timeout_ms (int)

  • aeat_clave_permanente_sede_access_url_template (str)

  • cadrumo_evidence_cloud_upload_permitted (bool)

  • cadrumo_evidence_gestor_mode (bool)

  • cadrumo_telemetry_opt_in (bool)

  • cadrumo_telemetry_tier (TelemetryTier)

  • cadrumo_telemetry_gestor_mode (bool)

  • cadrumo_telemetry_endpoint (str | None)

  • cadrumo_deadline_due_soon_days (int)

  • cadrumo_submissions_dir (Path)

  • cadrumo_inbox_alert_lead_days (int)

  • cadrumo_workflow_runs_dir (Path)

  • cadrumo_drafts_dir (Path)

  • cadrumo_draft_fail_on_warning (bool)

  • aeat_status_detail_url_template (str)

  • aeat_status_notificaciones_path (str)

  • cadrumo_runs_dir (Path)

  • cadrumo_runs_retention_days (int)

  • cadrumo_runs_max_total_bytes (int)

  • cadrumo_justificantes_dir (Path)

  • cadrumo_filed_declarations_dir (Path)

  • cadrumo_iva_compensation_history_dir (Path)

  • cadrumo_iva_read_evidence_dir (Path)

  • cadrumo_justificante_parser_backend (JustificanteParserBackendSetting)

  • cadrumo_filing_history_dir (Path)

  • cadrumo_filing_history_cache_ttl_s (int)

  • cadrumo_filing_history_archive_html (bool)

cadrumo_token_dir: Path
aeat_base_url: str
cadrumo_log_level: str
cadrumo_tui_appearance: _config_support.TuiAppearance
cadrumo_output_language: Annotated[OutputLanguage | None, BeforeValidator(_config_support.coerce_output_language_setting)]
aeat_authoritative_language_aeat_terms: str
cadrumo_authoritative_language_project_docs: str
cadrumo_fallback_languages: str
cadrumo_database_url: str
cadrumo_secret_store_dir: Path
cadrumo_dev_test_database_password: SecretStr
cadrumo_blob_store_dir: Path
cadrumo_live_state_dir: Path
cadrumo_storage_provider_kind: str
cadrumo_local_storage_root: Path
cadrumo_google_drive_root_folder_id: str | None
cadrumo_profile_kdf_measure_calibration: bool
cadrumo_live_tests_enabled: str
cadrumo_live_tests_google: str
property live_tests_enabled: bool

Whether the pytest live-read opt-in is enabled.

This is a strict "1" predicate for test selection only; production live-read access gates consume their own policy and capability checks.

property live_tests_google_enabled: bool

Whether the Google live-test opt-in is enabled.

Google OAuth / Drive tests use the same strict "1" predicate as the general live-read opt-in and remain separate from production provider construction.

cadrumo_force_color: bool
no_color: bool
cadrumo_cli_reveal_identifiers: bool
cadrumo_log_dir: Path | None
cadrumo_secret_passphrase: SecretStr | None
aeat_manuals_root: Path
aeat_normatives_root: Path
cadrumo_corpus_search_cache_dir: Path
cadrumo_authority_root: Path | None
cadrumo_browser_channel: str
cadrumo_browser_headless: bool
cadrumo_wallet_diagnostic_dump_dir: Path | None
cadrumo_wallet_diagnostic_retention_days: int
cadrumo_active_profile: str | None
cadrumo_proxy_url: str
cadrumo_proxy_username: str
cadrumo_proxy_password_secret: SecretStr | None
cadrumo_proxy_bypass: str
cadrumo_rate_limit_delay_seconds: float
site_health_probe_url: str
site_health_rate_limit_retry_after_default: int
cadrumo_certificate_path: Path | None
cadrumo_certificate_password_secret: SecretStr | None
cadrumo_certificate_friendly_name: str | None
cadrumo_auth_timeout_ms: int
cadrumo_strict_security: bool
cadrumo_cert_warn_days: int
cadrumo_cert_critical_days: int
cadrumo_auth_provider: _AuthProviderKind | None
cadrumo_clave_movil_dni_nie: SecretStr | None
cadrumo_clave_movil_dni_fecha: str | None
cadrumo_clave_movil_nie_soporte: SecretStr | None
cadrumo_clave_prefer_non_qr: bool
cadrumo_clave_movil_timeout_ms: int
aeat_clave_sede_access_url_template: str
aeat_sede_expedientes_path: str
cadrumo_clave_permanente_dni_nie: SecretStr | None
cadrumo_clave_permanente_password: SecretStr | None
cadrumo_clave_permanente_timeout_ms: int
aeat_clave_permanente_sede_access_url_template: str
cadrumo_evidence_cloud_upload_permitted: bool
cadrumo_evidence_gestor_mode: bool
cadrumo_telemetry_opt_in: bool
cadrumo_telemetry_tier: TelemetryTier
cadrumo_telemetry_gestor_mode: bool
cadrumo_telemetry_endpoint: str | None
cadrumo_deadline_due_soon_days: int
cadrumo_submissions_dir: Path
cadrumo_inbox_alert_lead_days: int
cadrumo_workflow_runs_dir: Path
cadrumo_drafts_dir: Path
cadrumo_draft_fail_on_warning: bool
aeat_status_detail_url_template: str
aeat_status_notificaciones_path: str
cadrumo_runs_dir: Path
cadrumo_runs_retention_days: int
cadrumo_runs_max_total_bytes: int
cadrumo_justificantes_dir: Path
cadrumo_filed_declarations_dir: Path
cadrumo_iva_compensation_history_dir: Path
cadrumo_iva_read_evidence_dir: Path
cadrumo_justificante_parser_backend: JustificanteParserBackendSetting
cadrumo_filing_history_dir: Path
cadrumo_filing_history_cache_ttl_s: int
cadrumo_filing_history_archive_html: bool
classmethod env_var_names()[source]

Return the set of environment variable names this model reads.

Severed names are excluded: a field whose environment source has been cut is still a field, but no environment variable reaches it, so listing it here would document a control that does nothing.

Return type:

set[str]

static external_constants()[source]

Return the parsed external-constants registry.

Bridges core.external_constants to the settings facade so callers reach third-party hostnames, AEAT service paths, OAuth scopes, and LLM endpoints through a single accessor.

Return type:

ExternalConstants

Returns:

The process-wide cached ExternalConstants instance.

classify_storage_route(settings=None)[source]

Classify the effective primary SQL route.

The returned StorageRouteClassification distinguishes explicit database URLs, active-profile bucket databases, and cold root-fallback SQLite routes. Application write guards consume this facade instead of re-parsing cadrumo_database_url or duplicating active-profile pointer rules.

Return type:

StorageRouteClassification

Parameters:

settings (Settings | None)

settings_for_active_profile_bucket(bucket_id, source=None)[source]

Return settings routed to bucket_id’s active-profile database.

Non-route fields are preserved from source (or load_settings()), while cadrumo_database_url is re-derived through the same validators used by normal settings construction. Explicit database URLs are refused by the lower-level route helper because they already define the storage authority.

Return type:

Settings

Returns:

A Settings instance whose database route targets bucket_id.

Parameters:
reset_settings_cache()[source]

Drop every held settings instance so the next load rebuilds.

The pointer key already covers profile switches. This is for the rare caller that changes the process environment and needs it observed; prefer override_settings(), which scopes the change to a block and does not disturb the cache at all.

Return type:

None

load_settings()[source]

Return the effective Settings instance.

Context-local overrides installed by override_settings() win inside their block; otherwise this returns the process-wide settings built once by _constructed_settings().

Return type:

Settings

override_settings(**overrides)[source]

Override one or more Settings fields for the with-block.

Overrides are validated through normal model construction so derived route, token, log, and storage-substrate paths stay coherent. The helper preserves model_fields_set to keep the distinction between explicit operator settings and computed defaults visible to route classification.

When the root itself is overridden, every derived field that the caller did not set and the source had not set explicitly is dropped from the merged dict so it re-derives under the NEW root. Without that, flattening through model_dump turns each previously-derived absolute path into an explicit value and the whole tree stays pinned to the old root – a leak that does not fail any single test, because each one still reads a path that exists. The field set is taken from the taxonomy, so a member added there is covered here the moment it lands.

Return type:

Generator[Settings]

Parameters:

overrides (object)