deepeval 3.7.6__py3-none-any.whl → 3.7.7__py3-none-any.whl

deepeval/config/settings.py

@@ -17,26 +17,37 @@ import os
 import re
 import threading
 
-from dotenv import dotenv_values
+from contextvars import ContextVar
 from pathlib import Path
 from pydantic import (
     AnyUrl,
     computed_field,
     confloat,
     conint,
+    Field,
     field_validator,
     model_validator,
     SecretStr,
     PositiveFloat,
 )
 from pydantic_settings import BaseSettings, SettingsConfigDict
-from typing import Any, Dict, List, Optional, NamedTuple
+from typing import (
+    Any,
+    Dict,
+    List,
+    Optional,
+    Union,
+    NamedTuple,
+    get_args,
+    get_origin,
+)
 
 from deepeval.config.utils import (
-    parse_bool,
     coerce_to_list,
     constrain_between,
     dedupe_preserve_order,
+    parse_bool,
+    read_dotenv_file,
 )
 from deepeval.constants import SUPPORTED_PROVIDER_SLUGS, slugify
 
@@ -44,6 +55,10 @@ from deepeval.constants import SUPPORTED_PROVIDER_SLUGS, slugify
 logger = logging.getLogger(__name__)
 _SAVE_RE = re.compile(r"^(?P<scheme>dotenv)(?::(?P<path>.+))?$")
 
+_ACTIVE_SETTINGS_EDIT_CTX: ContextVar[Optional["Settings._SettingsEditCtx"]] = (
+    ContextVar("_ACTIVE_SETTINGS_EDIT_CTX", default=None)
+)
+
 # settings that were converted to computed fields with override counterparts
 _DEPRECATED_TO_OVERRIDE = {
     "DEEPEVAL_PER_TASK_TIMEOUT_SECONDS": "DEEPEVAL_PER_TASK_TIMEOUT_SECONDS_OVERRIDE",
@@ -76,14 +91,12 @@ def _find_legacy_enum(env_key: str):
     return None
 
 
-def _is_secret_key(settings: "Settings", env_key: str) -> bool:
-    field = type(settings).model_fields.get(env_key)
+def _is_secret_key(env_key: str) -> bool:
+    field = Settings.model_fields.get(env_key)
     if not field:
         return False
     if field.annotation is SecretStr:
         return True
-    # Optional[SecretStr] etc.
-    from typing import get_origin, get_args, Union
 
     origin = get_origin(field.annotation)
     if origin is Union:
@@ -111,7 +124,6 @@ def _merge_legacy_keyfile_into_env() -> None:
         KeyValues,
         ModelKeyValues,
         EmbeddingKeyValues,
-        SECRET_KEYS,
     )
 
     key_path = Path(HIDDEN_DIR) / KEY_FILE
@@ -148,41 +160,28 @@ def _merge_legacy_keyfile_into_env() -> None:
             continue
 
         # Mirror the legacy warning semantics for secrets, but only once per key
-        if (
-            json_key in SECRET_KEYS
-            and json_key not in _LEGACY_KEYFILE_SECRET_WARNED
+        if env_key not in _LEGACY_KEYFILE_SECRET_WARNED and _is_secret_key(
+            env_key
         ):
             logger.warning(
-                "Reading secret '%s' from legacy %s/%s. "
+                "Reading secret '%s' (legacy key '%s') from legacy %s/%s. "
                 "Persisting API keys in plaintext is deprecated. "
                 "Move this to your environment (.env / .env.local). "
                 "This fallback will be removed in a future release.",
+                env_key,
                 json_key,
                 HIDDEN_DIR,
                 KEY_FILE,
             )
-            _LEGACY_KEYFILE_SECRET_WARNED.add(json_key)
-
+            _LEGACY_KEYFILE_SECRET_WARNED.add(env_key)
         # Let Settings validators coerce types; we just inject the raw string
         os.environ[env_key] = str(raw)
 
 
-def _read_env_file(path: Path) -> Dict[str, str]:
-    if not path.exists():
-        return {}
-    try:
-        # filter out None to avoid writing "None" later
-        return {
-            k: v for k, v in dotenv_values(str(path)).items() if v is not None
-        }
-    except Exception:
-        return {}
-
-
 def _discover_app_env_from_files(env_dir: Path) -> Optional[str]:
     # prefer base .env.local, then .env for APP_ENV discovery
     for name in (".env.local", ".env"):
-        v = _read_env_file(env_dir / name).get("APP_ENV")
+        v = read_dotenv_file(env_dir / name).get("APP_ENV")
         if v:
             v = str(v).strip()
             if v:
@@ -211,8 +210,8 @@ def autoload_dotenv() -> None:
         env_dir = Path(os.getcwd())
 
     # merge files in precedence order
-    base = _read_env_file(env_dir / ".env")
-    local = _read_env_file(env_dir / ".env.local")
+    base = read_dotenv_file(env_dir / ".env")
+    local = read_dotenv_file(env_dir / ".env.local")
 
     # Pick APP_ENV (process -> .env.local -> .env -> default)
     app_env = (
@@ -223,7 +222,7 @@ def autoload_dotenv() -> None:
     if app_env is not None:
         app_env = app_env.strip()
         if app_env:
-            env_specific = _read_env_file(env_dir / f".env.{app_env}")
+            env_specific = read_dotenv_file(env_dir / f".env.{app_env}")
             merged.setdefault("APP_ENV", app_env)
 
     merged.update(base)
@@ -243,6 +242,14 @@ class PersistResult(NamedTuple):
 
 
 class Settings(BaseSettings):
+    # def __init__(self):
+    #     super().__init__()
+    def __setattr__(self, name: str, value):
+        ctx = _ACTIVE_SETTINGS_EDIT_CTX.get()
+        if ctx is not None and name in type(self).model_fields:
+            ctx._touched.add(name)
+        return super().__setattr__(name, value)
+
     model_config = SettingsConfigDict(
         extra="ignore",
         case_sensitive=True,
@@ -253,23 +260,50 @@ class Settings(BaseSettings):
     # General
     #
 
-    APP_ENV: str = "dev"
-    LOG_LEVEL: Optional[int] = None
-    PYTHONPATH: str = "."
-    CONFIDENT_REGION: Optional[str] = None
-    CONFIDENT_OPEN_BROWSER: Optional[bool] = True
+    APP_ENV: str = Field(
+        "dev",
+        description="Application environment name used for dotenv selection (loads .env.<APP_ENV> if present).",
+    )
+    LOG_LEVEL: Optional[int] = Field(
+        None,
+        description="Global logging level (e.g. DEBUG/INFO/WARNING/ERROR/CRITICAL or numeric).",
+    )
+    PYTHONPATH: str = Field(
+        ".",
+        description="Extra PYTHONPATH used by the CLI runner (default: current project '.').",
+    )
+    CONFIDENT_REGION: Optional[str] = Field(
+        None,
+        description="Optional Confident AI region hint (uppercased).",
+    )
+    CONFIDENT_OPEN_BROWSER: Optional[bool] = Field(
+        True,
+        description="Open a browser automatically for Confident AI links/flows when available.",
+    )
 
     #
     # CLI
     #
-
-    DEEPEVAL_DEFAULT_SAVE: Optional[str] = None
-    DEEPEVAL_DISABLE_DOTENV: Optional[bool] = None
-    ENV_DIR_PATH: Optional[Path] = (
-        None  # where .env files live (CWD if not set)
+    DEEPEVAL_DEFAULT_SAVE: Optional[str] = Field(
+        None,
+        description="Default persistence target for settings changes (e.g. 'dotenv' or 'dotenv:/path/to/.env.local').",
+    )
+    DEEPEVAL_DISABLE_DOTENV: Optional[bool] = Field(
+        None,
+        description="Disable dotenv autoloading (.env → .env.<APP_ENV> → .env.local). Tip: set to 1 in pytest/CI to prevent loading env files on import.",
+    )
+    ENV_DIR_PATH: Optional[Path] = Field(
+        None,
+        description="Directory containing .env files (default: current working directory).",
+    )
+    DEEPEVAL_FILE_SYSTEM: Optional[str] = Field(
+        None,
+        description="Filesystem mode for runtime/CLI (currently supports READ_ONLY).",
+    )
+    DEEPEVAL_IDENTIFIER: Optional[str] = Field(
+        None,
+        description="Identifier/tag to help identify your test run on Confident AI.",
     )
-    DEEPEVAL_FILE_SYSTEM: Optional[str] = None
-    DEEPEVAL_IDENTIFIER: Optional[str] = None
 
     #
     # Storage & Output
@@ -277,143 +311,360 @@ class Settings(BaseSettings):
 
     # When set, DeepEval will export a timestamped JSON of the latest test run
     # into this directory. The directory will be created on demand.
-    DEEPEVAL_RESULTS_FOLDER: Optional[Path] = None
+    DEEPEVAL_RESULTS_FOLDER: Optional[Path] = Field(
+        None,
+        description="If set, export a timestamped JSON of the latest test run into this folder (created if missing).",
+    )
 
     # Display / Truncation
-    DEEPEVAL_MAXLEN_TINY: Optional[int] = 40
-    DEEPEVAL_MAXLEN_SHORT: Optional[int] = 60
-    DEEPEVAL_MAXLEN_MEDIUM: Optional[int] = 120
-    DEEPEVAL_MAXLEN_LONG: Optional[int] = 240
+    DEEPEVAL_MAXLEN_TINY: Optional[int] = Field(
+        40,
+        description="Default truncation length for 'tiny' displays in logs/UI.",
+    )
+    DEEPEVAL_MAXLEN_SHORT: Optional[int] = Field(
+        60,
+        description="Default truncation length for 'short' displays in logs/UI.",
+    )
+    DEEPEVAL_MAXLEN_MEDIUM: Optional[int] = Field(
+        120,
+        description="Default truncation length for 'medium' displays in logs/UI.",
+    )
+    DEEPEVAL_MAXLEN_LONG: Optional[int] = Field(
+        240,
+        description="Default truncation length for 'long' displays in logs/UI.",
+    )
 
     # If set, this overrides the default max_len used by deepeval/utils shorten
     # falls back to DEEPEVAL_MAXLEN_LONG when None.
-    DEEPEVAL_SHORTEN_DEFAULT_MAXLEN: Optional[int] = None
+    DEEPEVAL_SHORTEN_DEFAULT_MAXLEN: Optional[int] = Field(
+        None,
+        description="Override default max_len for deepeval.utils.shorten (falls back to DEEPEVAL_MAXLEN_LONG when unset).",
+    )
 
     # Optional global suffix (keeps your "..." default).
-    DEEPEVAL_SHORTEN_SUFFIX: Optional[str] = "..."
+    DEEPEVAL_SHORTEN_SUFFIX: Optional[str] = Field(
+        "...",
+        description="Suffix appended by deepeval.utils.shorten when truncating (default: '...').",
+    )
 
     #
     # GPU and perf toggles
     #
 
-    CUDA_LAUNCH_BLOCKING: Optional[bool] = None
-    CUDA_VISIBLE_DEVICES: Optional[str] = None
-    TOKENIZERS_PARALLELISM: Optional[bool] = None
-    TRANSFORMERS_NO_ADVISORY_WARNINGS: Optional[bool] = None
+    CUDA_LAUNCH_BLOCKING: Optional[bool] = Field(
+        None,
+        description="CUDA debug toggle (forces synchronous CUDA ops). Useful for debugging GPU errors.",
+    )
+    CUDA_VISIBLE_DEVICES: Optional[str] = Field(
+        None,
+        description="CUDA device visibility mask (e.g. '0' or '0,1').",
+    )
+    TOKENIZERS_PARALLELISM: Optional[bool] = Field(
+        None,
+        description="HuggingFace tokenizers parallelism toggle (set to false to reduce warnings/noise).",
+    )
+    TRANSFORMERS_NO_ADVISORY_WARNINGS: Optional[bool] = Field(
+        None,
+        description="Disable advisory warnings from transformers (reduces console noise).",
+    )
 
     #
     # Model Keys
     #
 
-    API_KEY: Optional[SecretStr] = None
-    CONFIDENT_API_KEY: Optional[SecretStr] = None
+    API_KEY: Optional[SecretStr] = Field(
+        None,
+        description="Alias for CONFIDENT_API_KEY (Confident AI API key).",
+    )
+    CONFIDENT_API_KEY: Optional[SecretStr] = Field(
+        None,
+        description="Confident AI API key (used for uploading results/telemetry to Confident).",
+    )
 
     # ======
     # Base URL for Confident AI API server
     # ======
-    CONFIDENT_BASE_URL: Optional[str] = None
+    CONFIDENT_BASE_URL: Optional[str] = Field(
+        None,
+        description="Base URL for Confident AI API server (set only if using a custom/hosted endpoint).",
+    )
 
     # General
-    TEMPERATURE: Optional[confloat(ge=0, le=2)] = None
+    TEMPERATURE: Optional[confloat(ge=0, le=2)] = Field(
+        None,
+        description="Global default model temperature (0–2). Model-specific constructors may override.",
+    )
 
     # Anthropic
-    ANTHROPIC_API_KEY: Optional[SecretStr] = None
-    ANTHROPIC_MODEL_NAME: Optional[str] = None
-    ANTHROPIC_COST_PER_INPUT_TOKEN: Optional[PositiveFloat] = None
-    ANTHROPIC_COST_PER_OUTPUT_TOKEN: Optional[PositiveFloat] = None
+    USE_ANTHROPIC_MODEL: Optional[bool] = Field(
+        None,
+        description="Select Anthropic as the active LLM provider (USE_* flags are mutually exclusive in CLI helpers).",
+    )
+    ANTHROPIC_API_KEY: Optional[SecretStr] = Field(
+        None, description="Anthropic API key."
+    )
+    ANTHROPIC_MODEL_NAME: Optional[str] = Field(
+        None, description="Anthropic model name (e.g. 'claude-3-...')."
+    )
+    ANTHROPIC_COST_PER_INPUT_TOKEN: Optional[PositiveFloat] = Field(
+        None,
+        description="Anthropic input token cost (used for cost reporting).",
+    )
+    ANTHROPIC_COST_PER_OUTPUT_TOKEN: Optional[PositiveFloat] = Field(
+        None,
+        description="Anthropic output token cost (used for cost reporting).",
+    )
 
     # AWS
-    AWS_ACCESS_KEY_ID: Optional[SecretStr] = None
-    AWS_SECRET_ACCESS_KEY: Optional[SecretStr] = None
+    AWS_ACCESS_KEY_ID: Optional[SecretStr] = Field(
+        None,
+        description="AWS access key ID (for Bedrock or other AWS-backed integrations).",
+    )
+    AWS_SECRET_ACCESS_KEY: Optional[SecretStr] = Field(
+        None,
+        description="AWS secret access key (for Bedrock or other AWS-backed integrations).",
+    )
     # AWS Bedrock
-    USE_AWS_BEDROCK_MODEL: Optional[bool] = None
-    AWS_BEDROCK_MODEL_NAME: Optional[str] = None
-    AWS_BEDROCK_REGION: Optional[str] = None
-    AWS_BEDROCK_COST_PER_INPUT_TOKEN: Optional[PositiveFloat] = None
-    AWS_BEDROCK_COST_PER_OUTPUT_TOKEN: Optional[PositiveFloat] = None
+    USE_AWS_BEDROCK_MODEL: Optional[bool] = Field(
+        None, description="Select AWS Bedrock as the active LLM provider."
+    )
+    AWS_BEDROCK_MODEL_NAME: Optional[str] = Field(
+        None, description="AWS Bedrock model identifier."
+    )
+    AWS_BEDROCK_REGION: Optional[str] = Field(
+        None, description="AWS region for Bedrock (normalized to lowercase)."
+    )
+    AWS_BEDROCK_COST_PER_INPUT_TOKEN: Optional[PositiveFloat] = Field(
+        None, description="Bedrock input token cost (used for cost reporting)."
+    )
+    AWS_BEDROCK_COST_PER_OUTPUT_TOKEN: Optional[PositiveFloat] = Field(
+        None, description="Bedrock output token cost (used for cost reporting)."
+    )
     # Azure Open AI
-    AZURE_OPENAI_API_KEY: Optional[SecretStr] = None
-    AZURE_OPENAI_ENDPOINT: Optional[AnyUrl] = None
-    OPENAI_API_VERSION: Optional[str] = None
-    AZURE_DEPLOYMENT_NAME: Optional[str] = None
-    AZURE_MODEL_NAME: Optional[str] = None
-    AZURE_MODEL_VERSION: Optional[str] = None
-    USE_AZURE_OPENAI: Optional[bool] = None
+    USE_AZURE_OPENAI: Optional[bool] = Field(
+        None, description="Select Azure OpenAI as the active LLM provider."
+    )
+    AZURE_OPENAI_API_KEY: Optional[SecretStr] = Field(
+        None, description="Azure OpenAI API key."
+    )
+    AZURE_OPENAI_ENDPOINT: Optional[AnyUrl] = Field(
+        None, description="Azure OpenAI endpoint URL."
+    )
+    OPENAI_API_VERSION: Optional[str] = Field(
+        None,
+        description="Azure OpenAI API version (if required by your deployment).",
+    )
+    AZURE_DEPLOYMENT_NAME: Optional[str] = Field(
+        None,
+        description="Azure OpenAI deployment name (required for most Azure configs).",
+    )
+    AZURE_MODEL_NAME: Optional[str] = Field(
+        None,
+        description="Azure model name label (informational; may be used in reporting).",
+    )
+    AZURE_MODEL_VERSION: Optional[str] = Field(
+        None,
+        description="Azure model version label (informational; may be used in reporting).",
+    )
     # DeepSeek
-    USE_DEEPSEEK_MODEL: Optional[bool] = None
-    DEEPSEEK_API_KEY: Optional[SecretStr] = None
-    DEEPSEEK_MODEL_NAME: Optional[str] = None
-    DEEPSEEK_COST_PER_INPUT_TOKEN: Optional[float] = None
-    DEEPSEEK_COST_PER_OUTPUT_TOKEN: Optional[float] = None
+    USE_DEEPSEEK_MODEL: Optional[bool] = Field(
+        None, description="Select DeepSeek as the active LLM provider."
+    )
+    DEEPSEEK_API_KEY: Optional[SecretStr] = Field(
+        None, description="DeepSeek API key."
+    )
+    DEEPSEEK_MODEL_NAME: Optional[str] = Field(
+        None, description="DeepSeek model name."
+    )
+    DEEPSEEK_COST_PER_INPUT_TOKEN: Optional[float] = Field(
+        None, description="DeepSeek input token cost (used for cost reporting)."
+    )
+    DEEPSEEK_COST_PER_OUTPUT_TOKEN: Optional[float] = Field(
+        None,
+        description="DeepSeek output token cost (used for cost reporting).",
+    )
     # Gemini
-    USE_GEMINI_MODEL: Optional[bool] = None
-    GOOGLE_API_KEY: Optional[SecretStr] = None
-    GEMINI_MODEL_NAME: Optional[str] = None
-    GOOGLE_GENAI_USE_VERTEXAI: Optional[bool] = None
-    GOOGLE_CLOUD_PROJECT: Optional[str] = None
-    GOOGLE_CLOUD_LOCATION: Optional[str] = None
-    GOOGLE_SERVICE_ACCOUNT_KEY: Optional[SecretStr] = None
+    USE_GEMINI_MODEL: Optional[bool] = Field(
+        None, description="Select Google Gemini as the active LLM provider."
+    )
+    GOOGLE_API_KEY: Optional[SecretStr] = Field(
+        None, description="Google API key for Gemini (non-Vertex usage)."
+    )
+    GEMINI_MODEL_NAME: Optional[str] = Field(
+        None, description="Gemini model name (e.g. 'gemini-...')."
+    )
+    GOOGLE_GENAI_USE_VERTEXAI: Optional[bool] = Field(
+        None,
+        description="Use Vertex AI for Gemini requests instead of direct API key mode.",
+    )
+    GOOGLE_CLOUD_PROJECT: Optional[str] = Field(
+        None,
+        description="GCP project ID for Vertex AI (required if GOOGLE_GENAI_USE_VERTEXAI=true).",
+    )
+    GOOGLE_CLOUD_LOCATION: Optional[str] = Field(
+        None,
+        description="GCP region/location for Vertex AI (e.g. 'us-central1').",
+    )
+    GOOGLE_SERVICE_ACCOUNT_KEY: Optional[SecretStr] = Field(
+        None,
+        description="Service account JSON key for Vertex AI auth (if not using ADC).",
+    )
     # Grok
-    USE_GROK_MODEL: Optional[bool] = None
-    GROK_API_KEY: Optional[SecretStr] = None
-    GROK_MODEL_NAME: Optional[str] = None
-    GROK_COST_PER_INPUT_TOKEN: Optional[float] = None
-    GROK_COST_PER_OUTPUT_TOKEN: Optional[float] = None
+    USE_GROK_MODEL: Optional[bool] = Field(
+        None, description="Select Grok as the active LLM provider."
+    )
+    GROK_API_KEY: Optional[SecretStr] = Field(None, description="Grok API key.")
+    GROK_MODEL_NAME: Optional[str] = Field(None, description="Grok model name.")
+    GROK_COST_PER_INPUT_TOKEN: Optional[float] = Field(
+        None, description="Grok input token cost (used for cost reporting)."
+    )
+    GROK_COST_PER_OUTPUT_TOKEN: Optional[float] = Field(
+        None, description="Grok output token cost (used for cost reporting)."
+    )
     # LiteLLM
-    USE_LITELLM: Optional[bool] = None
-    LITELLM_API_KEY: Optional[SecretStr] = None
-    LITELLM_MODEL_NAME: Optional[str] = None
-    LITELLM_API_BASE: Optional[AnyUrl] = None
-    LITELLM_PROXY_API_BASE: Optional[AnyUrl] = None
-    LITELLM_PROXY_API_KEY: Optional[SecretStr] = None
+    USE_LITELLM: Optional[bool] = Field(
+        None, description="Select LiteLLM as the active LLM provider."
+    )
+    LITELLM_API_KEY: Optional[SecretStr] = Field(
+        None,
+        description="LiteLLM API key (if required by your LiteLLM deployment).",
+    )
+    LITELLM_MODEL_NAME: Optional[str] = Field(
+        None,
+        description="LiteLLM model name (as exposed by your LiteLLM endpoint).",
+    )
+    LITELLM_API_BASE: Optional[AnyUrl] = Field(
+        None, description="LiteLLM API base URL (direct)."
+    )
+    LITELLM_PROXY_API_BASE: Optional[AnyUrl] = Field(
+        None, description="LiteLLM proxy base URL (if using proxy mode)."
+    )
+    LITELLM_PROXY_API_KEY: Optional[SecretStr] = Field(
+        None, description="LiteLLM proxy API key (if required)."
+    )
     # LM Studio
-    LM_STUDIO_API_KEY: Optional[SecretStr] = None
-    LM_STUDIO_MODEL_NAME: Optional[str] = None
+    LM_STUDIO_API_KEY: Optional[SecretStr] = Field(
+        None, description="LM Studio API key (if configured)."
+    )
+    LM_STUDIO_MODEL_NAME: Optional[str] = Field(
+        None, description="LM Studio model name."
+    )
     # Local Model
-    USE_LOCAL_MODEL: Optional[bool] = None
-    LOCAL_MODEL_API_KEY: Optional[SecretStr] = None
-    LOCAL_EMBEDDING_API_KEY: Optional[SecretStr] = None
-    LOCAL_MODEL_NAME: Optional[str] = None
-    LOCAL_MODEL_BASE_URL: Optional[AnyUrl] = None
-    LOCAL_MODEL_FORMAT: Optional[str] = None
+    USE_LOCAL_MODEL: Optional[bool] = Field(
+        None,
+        description="Select a local/self-hosted model as the active LLM provider.",
+    )
+    LOCAL_MODEL_API_KEY: Optional[SecretStr] = Field(
+        None,
+        description="API key for a local/self-hosted LLM endpoint (if required).",
+    )
+    LOCAL_EMBEDDING_API_KEY: Optional[SecretStr] = Field(
+        None,
+        description="API key for a local/self-hosted embedding endpoint (if required).",
+    )
+    LOCAL_MODEL_NAME: Optional[str] = Field(
+        None,
+        description="Local/self-hosted model name (informational / routing).",
+    )
+    LOCAL_MODEL_BASE_URL: Optional[AnyUrl] = Field(
+        None, description="Base URL for a local/self-hosted LLM endpoint."
+    )
+    LOCAL_MODEL_FORMAT: Optional[str] = Field(
+        None,
+        description="Local model API format identifier (implementation-specific).",
+    )
     # Moonshot
-    USE_MOONSHOT_MODEL: Optional[bool] = None
-    MOONSHOT_API_KEY: Optional[SecretStr] = None
-    MOONSHOT_MODEL_NAME: Optional[str] = None
-    MOONSHOT_COST_PER_INPUT_TOKEN: Optional[float] = None
-    MOONSHOT_COST_PER_OUTPUT_TOKEN: Optional[float] = None
+    USE_MOONSHOT_MODEL: Optional[bool] = Field(
+        None, description="Select Moonshot as the active LLM provider."
+    )
+    MOONSHOT_API_KEY: Optional[SecretStr] = Field(
+        None, description="Moonshot API key."
+    )
+    MOONSHOT_MODEL_NAME: Optional[str] = Field(
+        None, description="Moonshot model name."
+    )
+    MOONSHOT_COST_PER_INPUT_TOKEN: Optional[float] = Field(
+        None, description="Moonshot input token cost (used for cost reporting)."
+    )
+    MOONSHOT_COST_PER_OUTPUT_TOKEN: Optional[float] = Field(
+        None,
+        description="Moonshot output token cost (used for cost reporting).",
+    )
     # Ollama
-    OLLAMA_MODEL_NAME: Optional[str] = None
+    OLLAMA_MODEL_NAME: Optional[str] = Field(
+        None,
+        description="Ollama model name (used when running via Ollama integration).",
+    )
     # OpenAI
-    USE_OPENAI_MODEL: Optional[bool] = None
-    OPENAI_API_KEY: Optional[SecretStr] = None
-    OPENAI_MODEL_NAME: Optional[str] = None
-    OPENAI_COST_PER_INPUT_TOKEN: Optional[float] = None
-    OPENAI_COST_PER_OUTPUT_TOKEN: Optional[float] = None
+    USE_OPENAI_MODEL: Optional[bool] = Field(
+        None, description="Select OpenAI as the active LLM provider."
+    )
+    OPENAI_API_KEY: Optional[SecretStr] = Field(
+        None, description="OpenAI API key."
+    )
+    OPENAI_MODEL_NAME: Optional[str] = Field(
+        None, description="OpenAI model name (e.g. 'gpt-4.1')."
+    )
+    OPENAI_COST_PER_INPUT_TOKEN: Optional[float] = Field(
+        None, description="OpenAI input token cost (used for cost reporting)."
+    )
+    OPENAI_COST_PER_OUTPUT_TOKEN: Optional[float] = Field(
+        None, description="OpenAI output token cost (used for cost reporting)."
+    )
     # PortKey
-    USE_PORTKEY_MODEL: Optional[bool] = None
-    PORTKEY_API_KEY: Optional[SecretStr] = None
-    PORTKEY_MODEL_NAME: Optional[str] = None
-    PORTKEY_BASE_URL: Optional[AnyUrl] = None
-    PORTKEY_PROVIDER_NAME: Optional[str] = None
+    USE_PORTKEY_MODEL: Optional[bool] = Field(
+        None, description="Select Portkey as the active LLM provider."
+    )
+    PORTKEY_API_KEY: Optional[SecretStr] = Field(
+        None, description="Portkey API key."
+    )
+    PORTKEY_MODEL_NAME: Optional[str] = Field(
+        None, description="Portkey model name (as configured in Portkey)."
+    )
+    PORTKEY_BASE_URL: Optional[AnyUrl] = Field(
+        None, description="Portkey base URL (if using a custom endpoint)."
+    )
+    PORTKEY_PROVIDER_NAME: Optional[str] = Field(
+        None, description="Provider name/routing hint for Portkey."
+    )
     # Vertex AI
-    VERTEX_AI_MODEL_NAME: Optional[str] = None
+    VERTEX_AI_MODEL_NAME: Optional[str] = Field(
+        None,
+        description="Vertex AI model name (used by some Google integrations).",
+    )
     # VLLM
-    VLLM_API_KEY: Optional[SecretStr] = None
-    VLLM_MODEL_NAME: Optional[str] = None
+    VLLM_API_KEY: Optional[SecretStr] = Field(
+        None, description="vLLM API key (if required by your vLLM gateway)."
+    )
+    VLLM_MODEL_NAME: Optional[str] = Field(None, description="vLLM model name.")
 
     #
     # Embedding Keys
     #
 
     # Azure OpenAI
-    USE_AZURE_OPENAI_EMBEDDING: Optional[bool] = None
-    AZURE_EMBEDDING_MODEL_NAME: Optional[str] = None
-    AZURE_EMBEDDING_DEPLOYMENT_NAME: Optional[str] = None
+    USE_AZURE_OPENAI_EMBEDDING: Optional[bool] = Field(
+        None, description="Use Azure OpenAI for embeddings."
+    )
+    AZURE_EMBEDDING_MODEL_NAME: Optional[str] = Field(
+        None, description="Azure embedding model name label."
+    )
+    AZURE_EMBEDDING_DEPLOYMENT_NAME: Optional[str] = Field(
+        None, description="Azure embedding deployment name."
+    )
+
     # Local
-    USE_LOCAL_EMBEDDINGS: Optional[bool] = None
-    LOCAL_EMBEDDING_MODEL_NAME: Optional[str] = None
-    LOCAL_EMBEDDING_BASE_URL: Optional[AnyUrl] = None
+    USE_LOCAL_EMBEDDINGS: Optional[bool] = Field(
+        None, description="Use a local/self-hosted embeddings endpoint."
+    )
+    LOCAL_EMBEDDING_MODEL_NAME: Optional[str] = Field(
+        None,
+        description="Local embedding model name (informational / routing).",
+    )
+    LOCAL_EMBEDDING_BASE_URL: Optional[AnyUrl] = Field(
+        None,
+        description="Base URL for a local/self-hosted embeddings endpoint.",
+    )
 
     #
     # Retry Policy
@@ -425,60 +676,133 @@ class Settings(BaseSettings):
     #   contribution is ~ JITTER/2 per sleep.
     # - logging levels are looked up dynamically each attempt, so if you change LOG_LEVEL at runtime,
     #   the retry loggers will honor it without restart.
-    DEEPEVAL_SDK_RETRY_PROVIDERS: Optional[List[str]] = (
-        None  # ["*"] to delegate all retries to SDKs
+    DEEPEVAL_SDK_RETRY_PROVIDERS: Optional[List[str]] = Field(
+        None,
+        description="Providers for which retries should be delegated to the provider SDK (use ['*'] for all).",
+    )
+    DEEPEVAL_RETRY_BEFORE_LOG_LEVEL: Optional[int] = Field(
+        None,
+        description="Log level for 'before retry' logs (defaults to LOG_LEVEL if set, else INFO).",
     )
-    DEEPEVAL_RETRY_BEFORE_LOG_LEVEL: Optional[int] = (
-        None  # default is LOG_LEVEL if set, else INFO
+    DEEPEVAL_RETRY_AFTER_LOG_LEVEL: Optional[int] = Field(
+        None,
+        description="Log level for 'after retry' logs (defaults to ERROR).",
     )
-    DEEPEVAL_RETRY_AFTER_LOG_LEVEL: Optional[int] = None  # default -> ERROR
-    DEEPEVAL_RETRY_MAX_ATTEMPTS: conint(ge=1) = (
-        2  # attempts = first try + retries
+    DEEPEVAL_RETRY_MAX_ATTEMPTS: conint(ge=1) = Field(
+        2,
+        description="Max attempts per provider call (includes the first call; 1 = no retries).",
     )
-    DEEPEVAL_RETRY_INITIAL_SECONDS: confloat(ge=0) = (
-        1.0  # first sleep before retry, if any
+    DEEPEVAL_RETRY_INITIAL_SECONDS: confloat(ge=0) = Field(
+        1.0,
+        description="Initial backoff sleep (seconds) before the first retry.",
     )
-    DEEPEVAL_RETRY_EXP_BASE: confloat(ge=1) = (
-        2.0  # exponential growth factor for sleeps
+    DEEPEVAL_RETRY_EXP_BASE: confloat(ge=1) = Field(
+        2.0, description="Exponential backoff growth factor."
     )
-    DEEPEVAL_RETRY_JITTER: confloat(ge=0) = 2.0  # uniform jitter
-    DEEPEVAL_RETRY_CAP_SECONDS: confloat(ge=0) = (
-        5.0  # cap for each backoff sleep
+    DEEPEVAL_RETRY_JITTER: confloat(ge=0) = Field(
+        2.0, description="Uniform jitter added to each retry sleep (seconds)."
+    )
+    DEEPEVAL_RETRY_CAP_SECONDS: confloat(ge=0) = Field(
+        5.0, description="Maximum backoff sleep per retry (seconds)."
     )
 
     #
     # Telemetry and Debug
     #
-    DEEPEVAL_DEBUG_ASYNC: Optional[bool] = None
-    DEEPEVAL_TELEMETRY_OPT_OUT: Optional[bool] = None
-    DEEPEVAL_UPDATE_WARNING_OPT_IN: Optional[bool] = None
-    DEEPEVAL_GRPC_LOGGING: Optional[bool] = None
-    GRPC_VERBOSITY: Optional[str] = None
-    GRPC_TRACE: Optional[str] = None
-    ERROR_REPORTING: Optional[bool] = None
-    IGNORE_DEEPEVAL_ERRORS: Optional[bool] = None
-    SKIP_DEEPEVAL_MISSING_PARAMS: Optional[bool] = None
-    DEEPEVAL_VERBOSE_MODE: Optional[bool] = None
-    DEEPEVAL_LOG_STACK_TRACES: Optional[bool] = None
-    ENABLE_DEEPEVAL_CACHE: Optional[bool] = None
-
-    CONFIDENT_TRACE_FLUSH: Optional[bool] = None
-    CONFIDENT_TRACE_ENVIRONMENT: Optional[str] = "development"
-    CONFIDENT_TRACE_VERBOSE: Optional[bool] = True
-    CONFIDENT_TRACE_SAMPLE_RATE: Optional[float] = 1.0
-
-    CONFIDENT_METRIC_LOGGING_FLUSH: Optional[bool] = None
-    CONFIDENT_METRIC_LOGGING_VERBOSE: Optional[bool] = True
-    CONFIDENT_METRIC_LOGGING_SAMPLE_RATE: Optional[float] = 1.0
-    CONFIDENT_METRIC_LOGGING_ENABLED: Optional[bool] = True
-
-    OTEL_EXPORTER_OTLP_ENDPOINT: Optional[AnyUrl] = None
+    DEEPEVAL_DEBUG_ASYNC: Optional[bool] = Field(
+        None, description="Enable extra async debugging logs/behavior."
+    )
+    DEEPEVAL_TELEMETRY_OPT_OUT: Optional[bool] = Field(
+        None,
+        description="Opt out of DeepEval telemetry (OFF wins if conflicting legacy flags are set).",
+    )
+    DEEPEVAL_UPDATE_WARNING_OPT_IN: Optional[bool] = Field(
+        None,
+        description="Opt in to update warnings in the CLI/runtime when new versions are available.",
+    )
+    DEEPEVAL_GRPC_LOGGING: Optional[bool] = Field(
+        None,
+        description="Enable extra gRPC logging for Confident transport/debugging.",
+    )
+    GRPC_VERBOSITY: Optional[str] = Field(
+        None, description="gRPC verbosity (grpc env var passthrough)."
+    )
+    GRPC_TRACE: Optional[str] = Field(
+        None, description="gRPC trace categories (grpc env var passthrough)."
+    )
+    ERROR_REPORTING: Optional[bool] = Field(
+        None,
+        description="Enable/disable error reporting (implementation/integration dependent).",
+    )
+    IGNORE_DEEPEVAL_ERRORS: Optional[bool] = Field(
+        None,
+        description="Continue execution when DeepEval encounters certain recoverable errors.",
+    )
+    SKIP_DEEPEVAL_MISSING_PARAMS: Optional[bool] = Field(
+        None,
+        description="Skip metrics/test cases with missing required params instead of raising.",
+    )
+    DEEPEVAL_VERBOSE_MODE: Optional[bool] = Field(
+        None, description="Enable verbose logging and additional warnings."
+    )
+    DEEPEVAL_LOG_STACK_TRACES: Optional[bool] = Field(
+        None, description="Include stack traces in certain DeepEval error logs."
+    )
+    ENABLE_DEEPEVAL_CACHE: Optional[bool] = Field(
+        None,
+        description="Enable DeepEval caching where supported (may improve performance).",
+    )
+
+    CONFIDENT_TRACE_FLUSH: Optional[bool] = Field(
+        None,
+        description="Flush traces eagerly (useful for debugging; may add overhead).",
+    )
+    CONFIDENT_TRACE_ENVIRONMENT: Optional[str] = Field(
+        "development",
+        description="Trace environment label (e.g. development/staging/production).",
+    )
+    CONFIDENT_TRACE_VERBOSE: Optional[bool] = Field(
+        True, description="Enable verbose trace logging for Confident tracing."
+    )
+    CONFIDENT_TRACE_SAMPLE_RATE: Optional[float] = Field(
+        1.0, description="Trace sampling rate (0–1). Lower to reduce overhead."
+    )
+
+    CONFIDENT_METRIC_LOGGING_FLUSH: Optional[bool] = Field(
+        None,
+        description="Flush metric logs eagerly (useful for debugging; may add overhead).",
+    )
+    CONFIDENT_METRIC_LOGGING_VERBOSE: Optional[bool] = Field(
+        True, description="Enable verbose metric logging."
+    )
+    CONFIDENT_METRIC_LOGGING_SAMPLE_RATE: Optional[float] = Field(
+        1.0,
+        description="Metric logging sampling rate (0–1). Lower to reduce overhead.",
+    )
+    CONFIDENT_METRIC_LOGGING_ENABLED: Optional[bool] = Field(
+        True, description="Enable metric logging to Confident where supported."
+    )
+
+    OTEL_EXPORTER_OTLP_ENDPOINT: Optional[AnyUrl] = Field(
+        None,
+        description="OpenTelemetry OTLP exporter endpoint (if using OTEL export).",
+    )
 
     #
     # Network
     #
-    MEDIA_IMAGE_CONNECT_TIMEOUT_SECONDS: float = 3.05
-    MEDIA_IMAGE_READ_TIMEOUT_SECONDS: float = 10.0
+    MEDIA_IMAGE_CONNECT_TIMEOUT_SECONDS: float = Field(
+        3.05,
+        description="Connect timeout (seconds) when fetching remote images for multimodal inputs.",
+    )
+    MEDIA_IMAGE_READ_TIMEOUT_SECONDS: float = Field(
+        10.0,
+        description="Read timeout (seconds) when fetching remote images for multimodal inputs.",
+    )
+    DEEPEVAL_DISABLE_TIMEOUTS: Optional[bool] = Field(
+        None,
+        description="Disable DeepEval-enforced timeouts (per-attempt, per-task, gather). Provider SDK timeouts may still apply.",
+    )
     # DEEPEVAL_PER_ATTEMPT_TIMEOUT_SECONDS_OVERRIDE
     # Per-attempt timeout (seconds) for provider calls used by the retry policy.
     # This is an OVERRIDE setting. The effective value you should rely on at runtime is
@@ -491,20 +815,31 @@ class Settings(BaseSettings):
     #
     # Tip: Set this OR the outer override, but generally not both
     DEEPEVAL_PER_ATTEMPT_TIMEOUT_SECONDS_OVERRIDE: Optional[confloat(gt=0)] = (
-        None
+        Field(
+            None,
+            description="Override per-attempt provider call timeout (seconds). Leave unset to derive from task timeout.",
+        )
     )
 
     #
     # Async Document Pipelines
     #
 
-    DEEPEVAL_MAX_CONCURRENT_DOC_PROCESSING: conint(ge=1) = 2
+    DEEPEVAL_MAX_CONCURRENT_DOC_PROCESSING: conint(ge=1) = Field(
+        2, description="Max concurrent async document processing tasks."
+    )
 
     #
     # Async Task Configuration
     #
-    DEEPEVAL_TIMEOUT_THREAD_LIMIT: conint(ge=1) = 128
-    DEEPEVAL_TIMEOUT_SEMAPHORE_WARN_AFTER_SECONDS: confloat(ge=0) = 5.0
+    DEEPEVAL_TIMEOUT_THREAD_LIMIT: conint(ge=1) = Field(
+        128,
+        description="Max worker threads used for timeout enforcement in async execution.",
+    )
+    DEEPEVAL_TIMEOUT_SEMAPHORE_WARN_AFTER_SECONDS: confloat(ge=0) = Field(
+        5.0,
+        description="Warn if waiting on the timeout semaphore longer than this many seconds.",
+    )
     # DEEPEVAL_PER_TASK_TIMEOUT_SECONDS_OVERRIDE
     # Outer time budget (seconds) for a single metric/test-case, including retries and backoff.
     # This is an OVERRIDE setting. If None or 0 the DEEPEVAL_PER_TASK_TIMEOUT_SECONDS field is computed:
@@ -517,7 +852,12 @@ class Settings(BaseSettings):
     # usage:
     #   - set DEEPEVAL_PER_ATTEMPT_TIMEOUT_SECONDS_OVERRIDE along with DEEPEVAL_RETRY_MAX_ATTEMPTS, or
     #   - set DEEPEVAL_PER_TASK_TIMEOUT_SECONDS_OVERRIDE alone.
-    DEEPEVAL_PER_TASK_TIMEOUT_SECONDS_OVERRIDE: Optional[confloat(ge=0)] = None
+    DEEPEVAL_PER_TASK_TIMEOUT_SECONDS_OVERRIDE: Optional[confloat(ge=0)] = (
+        Field(
+            None,
+            description="Override outer per-test-case timeout budget (seconds), including retries/backoff. Leave unset to auto-derive.",
+        )
+    )
 
     # Buffer time for gathering results from all tasks, added to the longest task duration
     # Increase if many tasks are running concurrently
@@ -525,7 +865,10 @@ class Settings(BaseSettings):
     #     30  # 15s seemed like not enough. we may make this computed later.
     # )
     DEEPEVAL_TASK_GATHER_BUFFER_SECONDS_OVERRIDE: Optional[confloat(ge=0)] = (
-        None
+        Field(
+            None,
+            description="Override buffer added to the longest task duration when gathering async results (seconds).",
+        )
     )
 
     ###################
@@ -619,10 +962,16 @@ class Settings(BaseSettings):
     ##############
 
     @field_validator(
+        "CONFIDENT_METRIC_LOGGING_ENABLED",
+        "CONFIDENT_METRIC_LOGGING_VERBOSE",
+        "CONFIDENT_METRIC_LOGGING_FLUSH",
         "CONFIDENT_OPEN_BROWSER",
         "CONFIDENT_TRACE_FLUSH",
         "CONFIDENT_TRACE_VERBOSE",
         "CUDA_LAUNCH_BLOCKING",
+        "DEEPEVAL_DEBUG_ASYNC",
+        "DEEPEVAL_LOG_STACK_TRACES",
+        "DEEPEVAL_DISABLE_TIMEOUTS",
         "DEEPEVAL_VERBOSE_MODE",
         "DEEPEVAL_GRPC_LOGGING",
         "DEEPEVAL_DISABLE_DOTENV",
@@ -951,6 +1300,7 @@ class Settings(BaseSettings):
             self._save = save
             self._persist = persist
             self._before: Dict[str, Any] = {}
+            self._touched: set[str] = set()
             self.result: Optional[PersistResult] = None
 
         @property
@@ -959,122 +1309,168 @@ class Settings(BaseSettings):
 
         def __enter__(self) -> "Settings._SettingsEditCtx":
             # snapshot current state
+            self._token = _ACTIVE_SETTINGS_EDIT_CTX.set(self)
             self._before = {
                 k: getattr(self._s, k) for k in type(self._s).model_fields
             }
             return self
 
         def __exit__(self, exc_type, exc, tb):
-            if exc_type is not None:
-                return False  # don’t persist on error
-
-            from deepeval.config.settings_manager import (
-                update_settings_and_persist,
-                _normalize_for_env,
-            )
-
-            # lazy import legacy JSON store deps
-            from deepeval.key_handler import KEY_FILE_HANDLER
-
-            model_fields = type(self._s).model_fields
-            # Exclude computed fields from persistence
-
-            # compute diff of changed fields
-            after = {k: getattr(self._s, k) for k in model_fields}
-
-            before_norm = {
-                k: _normalize_for_env(v) for k, v in self._before.items()
-            }
-            after_norm = {k: _normalize_for_env(v) for k, v in after.items()}
+            try:
+                if exc_type is not None:
+                    return False  # don’t persist on error
 
-            changed_keys = {
-                k for k in after_norm if after_norm[k] != before_norm.get(k)
-            }
-            changed_keys -= self.COMPUTED_FIELDS
+                from deepeval.config.settings_manager import (
+                    update_settings_and_persist,
+                    _normalize_for_env,
+                    _resolve_save_path,
+                )
 
-            if not changed_keys:
-                self.result = PersistResult(False, None, {})
-                return False
+                # lazy import legacy JSON store deps
+                from deepeval.key_handler import KEY_FILE_HANDLER
+
+                model_fields = type(self._s).model_fields
+                # Exclude computed fields from persistence
+
+                # compute diff of changed fields
+                after = {k: getattr(self._s, k) for k in model_fields}
+
+                before_norm = {
+                    k: _normalize_for_env(v) for k, v in self._before.items()
+                }
+                after_norm = {
+                    k: _normalize_for_env(v) for k, v in after.items()
+                }
+
+                changed_keys = {
+                    k for k in after_norm if after_norm[k] != before_norm.get(k)
+                }
+                changed_keys -= self.COMPUTED_FIELDS
+                touched_keys = set(self._touched) - self.COMPUTED_FIELDS
+
+                # dotenv should persist union(changed, touched)
+                persist_dotenv = self._persist is not False
+                ok, resolved_path = _resolve_save_path(self._save)
+
+                existing_dotenv = {}
+                if persist_dotenv and ok and resolved_path is not None:
+                    existing_dotenv = read_dotenv_file(resolved_path)
+
+                candidate_keys_for_dotenv = (
+                    changed_keys | touched_keys
+                ) - self.COMPUTED_FIELDS
+
+                keys_for_dotenv: set[str] = set()
+                for key in candidate_keys_for_dotenv:
+                    desired = after_norm.get(key)  # normalized string or None
+                    if desired is None:
+                        # only need to unset if it's actually present in dotenv
+                        # if key in existing_dotenv:
+                        #     keys_for_dotenv.add(key)
+                        keys_for_dotenv.add(key)
+                    else:
+                        if existing_dotenv.get(key) != desired:
+                            keys_for_dotenv.add(key)
 
-            updates = {k: after[k] for k in changed_keys}
+                updates_for_dotenv = {
+                    key: after[key] for key in keys_for_dotenv
+                }
 
-            if "LOG_LEVEL" in updates:
-                from deepeval.config.logging import (
-                    apply_deepeval_log_level,
-                )
+                if not changed_keys and not updates_for_dotenv:
+                    if self._persist is False:
+                        # we report handled so that the cli does not mistakenly report invalid save option
+                        self.result = PersistResult(True, None, {})
+                        return False
 
-                apply_deepeval_log_level()
+                    ok, resolved_path = _resolve_save_path(self._save)
+                    self.result = PersistResult(ok, resolved_path, {})
+                    return False
 
-            #
-            # .deepeval JSON support
-            #
+                updates = {k: after[k] for k in changed_keys}
 
-            if self._persist is not False:
-                for k in changed_keys:
-                    legacy_member = _find_legacy_enum(k)
-                    if legacy_member is None:
-                        continue  # skip if not a defined as legacy field
+                if "LOG_LEVEL" in updates:
+                    from deepeval.config.logging import (
+                        apply_deepeval_log_level,
+                    )
 
-                    val = updates[k]
-                    # Remove from JSON if unset
-                    if val is None:
-                        KEY_FILE_HANDLER.remove_key(legacy_member)
-                        continue
+                    apply_deepeval_log_level()
 
-                    # Never store secrets in the JSON keystore
-                    if _is_secret_key(self._s, k):
-                        continue
+                #
+                # .deepeval JSON support
+                #
 
-                    # For booleans, the legacy store expects "YES"/"NO"
-                    if isinstance(val, bool):
-                        KEY_FILE_HANDLER.write_key(
-                            legacy_member, "YES" if val else "NO"
-                        )
-                    else:
-                        # store as string
-                        KEY_FILE_HANDLER.write_key(legacy_member, str(val))
-
-            #
-            # dotenv store
-            #
-
-            # defer import to avoid cyclics
-            handled, path = update_settings_and_persist(
-                updates,
-                save=self._save,
-                persist_dotenv=(False if self._persist is False else True),
-            )
-            self.result = PersistResult(handled, path, updates)
-            return False
+                if self._persist is not False:
+                    for k in changed_keys:
+                        legacy_member = _find_legacy_enum(k)
+                        if legacy_member is None:
+                            continue  # skip if not a defined as legacy field
+
+                        val = updates[k]
+                        # Remove from JSON if unset
+                        if val is None:
+                            KEY_FILE_HANDLER.remove_key(legacy_member)
+                            continue
+
+                        # Never store secrets in the JSON keystore
+                        if _is_secret_key(k):
+                            continue
+
+                        # For booleans, the legacy store expects "YES"/"NO"
+                        if isinstance(val, bool):
+                            KEY_FILE_HANDLER.write_key(
+                                legacy_member, "YES" if val else "NO"
+                            )
+                        else:
+                            # store as string
+                            KEY_FILE_HANDLER.write_key(legacy_member, str(val))
+
+                #
+                # dotenv store
+                #
+
+                # defer import to avoid cyclics
+                handled, path = update_settings_and_persist(
+                    updates_for_dotenv,
+                    save=self._save,
+                    persist_dotenv=persist_dotenv,
+                )
+                self.result = PersistResult(handled, path, updates_for_dotenv)
+                return False
+            finally:
+                if self._token is not None:
+                    _ACTIVE_SETTINGS_EDIT_CTX.reset(self._token)
 
         def switch_model_provider(self, target) -> None:
             """
-            Flip all USE_* toggles so that the one matching the target is True and the rest are False.
-            Also,  mirror this change into the legacy JSON keystore as "YES"/"NO".
-
-            `target` may be an Enum with `.value`, such as ModelKeyValues.USE_OPENAI_MODEL
-            or a plain string like "USE_OPENAI_MODEL".
+            Flip USE_* settings within the target's provider family (LLM vs embeddings).
             """
             from deepeval.key_handler import KEY_FILE_HANDLER
 
-            # Target key is the env style string, such as "USE_OPENAI_MODEL"
             target_key = getattr(target, "value", str(target))
 
+            def _is_embedding_flag(k: str) -> bool:
+                return "EMBEDDING" in k
+
+            target_is_embedding = _is_embedding_flag(target_key)
+
             use_fields = [
-                k for k in type(self._s).model_fields if k.startswith("USE_")
+                field
+                for field in type(self._s).model_fields
+                if field.startswith("USE_")
+                and _is_embedding_flag(field) == target_is_embedding
             ]
+
             if target_key not in use_fields:
                 raise ValueError(
                     f"{target_key} is not a recognized USE_* field"
                 )
 
-            for k in use_fields:
-                on = k == target_key
-                # dotenv persistence will serialize to "1"/"0"
-                setattr(self._s, k, on)
+            for field in use_fields:
+                on = field == target_key
+                setattr(self._s, field, on)
+
                 if self._persist is not False:
-                    # legacy json persistence will serialize to "YES"/"NO"
-                    legacy_member = _find_legacy_enum(k)
+                    legacy_member = _find_legacy_enum(field)
                     if legacy_member is not None:
                         KEY_FILE_HANDLER.write_key(
                             legacy_member, "YES" if on else "NO"
@@ -1123,7 +1519,7 @@ class Settings(BaseSettings):
 
 
 _settings_singleton: Optional[Settings] = None
-_settings_env_fingerprint: "str | None" = None
+_settings_env_fingerprint: Optional[str] = None
 _settings_lock = threading.RLock()