fix(config): honor dotenv backend selection at runtime (#210)

* fix(config): honor dotenv backend selection at runtime

Settings classes now read .env directly through pydantic-settings so backend and related runtime configuration match the repo documentation without requiring callers to load dotenv themselves.

A focused regression test reloads the config module from a temporary working directory to prove EVOLVE_BACKEND=postgres is picked up from .env and that the module-level singleton follows the same behavior.

Constraint: Keep configuration loading dependency-free and inside existing pydantic settings flow
Rejected: Add manual load_dotenv bootstrap in library entrypoints | spreads config side effects across multiple runtimes
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: If config needs to work outside the repo root, prefer an explicit absolute env file strategy rather than adding more implicit loaders
Tested: ./.venv/bin/pytest -v tests/unit/test_client.py; ./.venv/bin/ruff check altk_evolve/config/evolve.py altk_evolve/config/postgres.py altk_evolve/config/filesystem.py altk_evolve/config/milvus.py altk_evolve/config/llm.py altk_evolve/config/phoenix.py tests/unit/test_client.py
Not-tested: Full e2e MCP or CLI startup from non-repo working directories

* test(client): preserve default config state after dotenv reload

The dotenv-backed backend assertion reloads altk_evolve.config.evolve under a temporary working directory. The cleanup now restores the original cwd and clears EVOLVE_BACKEND before reloading so the module singleton is rebuilt against the default repo context instead of the temporary postgres fixture.

Constraint: importlib.reload reconstructs evolve_config from the current cwd and environment\nRejected: Only overwrite evolve_config.backend after reload | the module instance is still recreated from tmp_path/.env\nConfidence: high\nScope-risk: narrow\nReversibility: clean\nDirective: Tests that reload settings modules should restore both cwd and env before cleanup reloads\nTested: uv run pytest -v tests/unit/test_client.py\nNot-tested: Full test suite

Author: gaodan-fang

altk_evolve/config/evolve.py

@@ -3,7 +3,7 @@
 
 
 class EvolveConfig(BaseSettings):
-    model_config = SettingsConfigDict(env_prefix="EVOLVE_")
+    model_config = SettingsConfigDict(env_prefix="EVOLVE_", env_file=".env", extra="ignore")
     backend: Literal["milvus", "filesystem", "postgres"] = "filesystem"
     namespace_id: str = "evolve"
     settings: BaseSettings | None = None

altk_evolve/config/filesystem.py

@@ -3,7 +3,7 @@
 
 
 class FilesystemSettings(BaseSettings):
-    model_config = SettingsConfigDict(env_prefix="EVOLVE_")
+    model_config = SettingsConfigDict(env_prefix="EVOLVE_", env_file=".env", extra="ignore")
     data_dir: str = Field(default="evolve_data", description="Directory to store JSON data files")
 
 

altk_evolve/config/llm.py

@@ -21,7 +21,7 @@ def _default_custom_provider() -> str | None:
 
 
 class LLMSettings(BaseSettings):
-    model_config = SettingsConfigDict(env_prefix="EVOLVE_")
+    model_config = SettingsConfigDict(env_prefix="EVOLVE_", env_file=".env", extra="ignore")
     tips_model: str = Field(default_factory=_default_model_name)
     conflict_resolution_model: str = Field(default_factory=_default_model_name)
     fact_extraction_model: str = Field(default_factory=_default_model_name)

altk_evolve/config/milvus.py

@@ -3,7 +3,7 @@
 
 
 class MilvusDBSettings(BaseSettings):
-    model_config = SettingsConfigDict(env_prefix="EVOLVE_")
+    model_config = SettingsConfigDict(env_prefix="EVOLVE_", env_file=".env", extra="ignore")
     uri: str = Field(default="entities.milvus.db")
     user: str = Field(default="")
     password: str = Field(default="")
@@ -15,7 +15,7 @@ class MilvusDBSettings(BaseSettings):
 
 
 class MilvusOtherSettings(BaseSettings):
-    model_config = SettingsConfigDict(env_prefix="EVOLVE_")
+    model_config = SettingsConfigDict(env_prefix="EVOLVE_", env_file=".env", extra="ignore")
     embedding_model: str = "sentence-transformers/all-MiniLM-L6-v2"
 
 

altk_evolve/config/phoenix.py

@@ -3,7 +3,7 @@
 
 
 class PhoenixSettings(BaseSettings):
-    model_config = SettingsConfigDict(env_prefix="PHOENIX_")
+    model_config = SettingsConfigDict(env_prefix="PHOENIX_", env_file=".env", extra="ignore")
     url: str = Field(default="http://localhost:6006", description="Phoenix server URL")
     project: str = Field(default="default", description="Phoenix project name")
 

altk_evolve/config/postgres.py

@@ -3,7 +3,7 @@
 
 
 class PostgresDBSettings(BaseSettings):
-    model_config = SettingsConfigDict(env_prefix="EVOLVE_PG_")
+    model_config = SettingsConfigDict(env_prefix="EVOLVE_PG_", env_file=".env", extra="ignore")
     embedding_model: str = "sentence-transformers/all-MiniLM-L6-v2"
     host: str = Field(default="localhost")
     port: int = Field(default=5432)

tests/unit/test_client.py

@@ -3,6 +3,9 @@
 """
 
 import datetime
+import importlib
+from pathlib import Path
+
 import pytest
 
 from altk_evolve.backend.base import BaseEntityBackend
@@ -20,6 +23,31 @@ def evolve_client() -> EvolveClient:
     return evolve_client
 
 
+@pytest.mark.unit
+def test_evolve_config_reads_backend_from_dotenv(tmp_path, monkeypatch):
+    env_path = tmp_path / ".env"
+    env_path.write_text("EVOLVE_BACKEND=postgres\n", encoding="utf-8")
+
+    original_cwd = Path.cwd()
+    monkeypatch.chdir(tmp_path)
+    monkeypatch.delenv("EVOLVE_BACKEND", raising=False)
+
+    import altk_evolve.config.evolve as evolve_module
+
+    original_backend = evolve_module.evolve_config.backend
+    reloaded_module = importlib.reload(evolve_module)
+
+    try:
+        assert reloaded_module.EvolveConfig().backend == "postgres"
+        assert reloaded_module.evolve_config.backend == "postgres"
+    finally:
+        monkeypatch.chdir(original_cwd)
+        monkeypatch.delenv("EVOLVE_BACKEND", raising=False)
+        reloaded_module.evolve_config.backend = original_backend
+        importlib.reload(reloaded_module)
+        reloaded_module.evolve_config.backend = original_backend
+
+
 @pytest.mark.unit
 def test_health_check(evolve_client: EvolveClient, monkeypatch):
     # Client should return False derived from API response