updated configuration to pydantic

README.md

@@ -61,3 +61,26 @@ chainlit run app.py
 - Web search integration via Tavily
 - Semantic chunking for better context retrieval
 - Interactive chat interface through Chainlit
+
+## ⚙️ Configuration Options
+
+You can customize the behavior of PsTuts RAG using environment variables. Set these in your shell, `.env` file, or deployment environment. Here are the available options:
+
+| Env Var | Description |
+|---------|-------------|
+| `EVA_WORKFLOW_NAME` | 🏷️ Name of the EVA workflow. Default: `EVA_workflow` |
+| `EVA_LOG_LEVEL` | 🪵 Logging level for EVA. Default: `INFO` |
+| `TRANSCRIPT_GLOB` | 📄 Glob pattern for transcript JSON files (supports multiple files separated by `:`). Default: `data/test.json` |
+| `EMBEDDING_MODEL` | 🧊 Name of the embedding model to use (default: custom fine-tuned snowflake model). Default: `mbudisic/snowflake-arctic-embed-s-ft-pstuts` |
+| `EVA_STRIP_THINK` | 💭 If set (present in env), strips 'think' steps from EVA output. |
+| `EMBEDDING_API` | 🔌 API provider for embeddings (`OPENAI`, `HUGGINGFACE`, or `OLLAMA`). Default: `HUGGINGFACE` |
+| `LLM_API` | 🤖 API provider for LLM (`OPENAI`, `HUGGINGFACE`, or `OLLAMA`). Default: `OLLAMA` |
+| `MAX_RESEARCH_LOOPS` | 🔁 Maximum number of research loops to perform. Default: `3` |
+| `LLM_TOOL_MODEL` | 🛠️ Name of the LLM model to use for tool calling. Default: `smollm2:1.7b-instruct-q2_K` |
+| `N_CONTEXT_DOCS` | 📚 Number of context documents to retrieve for RAG. Default: `2` |
+| `EVA_SEARCH_PERMISSION` | 🌐 Permission for search (`yes`, `no`, or `ask`). Default: `no` |
+| `EVA_DB_PERSIST` | 💾 Path or flag for DB persistence. Default: unset |
+| `EVA_REINITIALIZE` | 🔄 If true, reinitializes EVA DB. Default: `False` |
+| `THREAD_ID` | 🧵 Thread ID for the current session. Default: unset |
+
+Set these variables to control model selection, logging, search permissions, and more. For advanced usage, see the developer documentation.

docs/DEVELOPER.md

@@ -165,6 +165,31 @@ This feature enables controlled access to external resources while maintaining a
 - **`evaluator_utils.py`**: RAG evaluation utilities using RAGAS framework
 - **Notebook-based evaluation**: `evaluate_rag.ipynb` for systematic testing
 
+### ⚙️ Configuration Reference
+
+The `Configuration` class (in `pstuts_rag/configuration.py`) is powered by Pydantic and supports environment variable overrides for all fields. Below is a reference for all configuration options:
+
+| Field | Env Var | Type | Default | Description |
+|-------|---------|------|---------|-------------|
+| `eva_workflow_name` | `EVA_WORKFLOW_NAME` | `str` | `EVA_workflow` | 🏷️ Name of the EVA workflow |
+| `eva_log_level` | `EVA_LOG_LEVEL` | `str` | `INFO` | 🪵 Logging level for EVA |
+| `transcript_glob` | `TRANSCRIPT_GLOB` | `str` | `data/test.json` | 📄 Glob pattern for transcript JSON files (supports `:` for multiple) |
+| `embedding_model` | `EMBEDDING_MODEL` | `str` | `mbudisic/snowflake-arctic-embed-s-ft-pstuts` | 🧊 Embedding model name (default: custom fine-tuned snowflake) |
+| `eva_strip_think` | `EVA_STRIP_THINK` | `bool` | `False` | 💭 If set (present in env), strips 'think' steps from EVA output |
+| `embedding_api` | `EMBEDDING_API` | `ModelAPI` | `HUGGINGFACE` | 🔌 API provider for embeddings (`OPENAI`, `HUGGINGFACE`, `OLLAMA`) |
+| `llm_api` | `LLM_API` | `ModelAPI` | `OLLAMA` | 🤖 API provider for LLM (`OPENAI`, `HUGGINGFACE`, `OLLAMA`) |
+| `max_research_loops` | `MAX_RESEARCH_LOOPS` | `int` | `3` | 🔁 Maximum number of research loops to perform |
+| `llm_tool_model` | `LLM_TOOL_MODEL` | `str` | `smollm2:1.7b-instruct-q2_K` | 🛠️ LLM model for tool calling |
+| `n_context_docs` | `N_CONTEXT_DOCS` | `int` | `2` | 📚 Number of context documents to retrieve for RAG |
+| `search_permission` | `EVA_SEARCH_PERMISSION` | `str` | `no` | 🌐 Permission for search (`yes`, `no`, `ask`) |
+| `db_persist` | `EVA_DB_PERSIST` | `str or None` | `None` | 💾 Path or flag for DB persistence |
+| `eva_reinitialize` | `EVA_REINITIALIZE` | `bool` | `False` | 🔄 If true, reinitializes EVA DB |
+| `thread_id` | `THREAD_ID` | `str` | `""` | 🧵 Thread ID for the current session |
+
+- All fields can be set via environment variables (see [Pydantic BaseSettings docs](https://docs.pydantic.dev/latest/usage/settings/)).
+- Types are enforced at runtime. Defaults are shown above.
+- For advanced usage, see the `Configuration` class in `pstuts_rag/configuration.py`.
+
 ## 🎨 UI Customization & Theming
 
 ### Sepia Theme Implementation 🖼️

pstuts_rag/pstuts_rag/configuration.py

@@ -1,8 +1,9 @@
 import os
 import logging
-from dataclasses import dataclass, fields
 from typing import Any, Optional
 from enum import Enum
+from pydantic_settings import BaseSettings
+from pydantic import Field
 
 from langchain_core.runnables import RunnableConfig
 
@@ -21,60 +22,94 @@ class ModelAPI(Enum):
     OLLAMA = "OLLAMA"
 
 
-@dataclass(kw_only=True)
-class Configuration:
+class Configuration(BaseSettings):
     """
-    Configuration parameters for the application.
-
-    Attributes:
-        transcript_glob: Glob pattern for transcript JSON files (supports multiple files separated by ':')
-        embedding_model: Name of the embedding model to use (default: custom fine-tuned snowflake model)
-        embedding_api: API provider for embeddings (OPENAI or HUGGINGFACE)
-        max_research_loops: Maximum number of research loops to perform
-        llm_tool_model: Name of the LLM model to use for tool calling
-        n_context_docs: Number of context documents to retrieve for RAG
+    Configuration parameters for the application. All fields can be set via environment variables.
     """
 
-    eva_workflow_name: str = str(
-        os.environ.get("EVA_WORKFLOW_NAME", "EVA_workflow")
+    eva_workflow_name: str = Field(
+        default_factory=lambda: os.environ.get(
+            "EVA_WORKFLOW_NAME", "EVA_workflow"
+        ),
+        description="Name of the EVA workflow. Set via EVA_WORKFLOW_NAME.",
     )
-
-    eva_log_level: str = str(os.environ.get("EVA_LOG_LEVEL", "INFO")).upper()
-
-    transcript_glob: str = str(
-        os.environ.get("TRANSCRIPT_GLOB", "data/test.json")
+    eva_log_level: str = Field(
+        default_factory=lambda: os.environ.get(
+            "EVA_LOG_LEVEL", "INFO"
+        ).upper(),
+        description="Logging level for EVA. Set via EVA_LOG_LEVEL.",
     )
-
-    embedding_model: str = str(
-        os.environ.get(
+    transcript_glob: str = Field(
+        default_factory=lambda: os.environ.get(
+            "TRANSCRIPT_GLOB", "data/test.json"
+        ),
+        description="Glob pattern for transcript JSON files (supports multiple files separated by ':'). Set via TRANSCRIPT_GLOB.",
+    )
+    embedding_model: str = Field(
+        default_factory=lambda: os.environ.get(
             "EMBEDDING_MODEL", "mbudisic/snowflake-arctic-embed-s-ft-pstuts"
-        )
+        ),
+        description="Name of the embedding model to use (default: custom fine-tuned snowflake model). Set via EMBEDDING_MODEL.",
     )
 
-    eva_strip_think: bool = "EVA_STRIP_THINK" in os.environ
-
-    embedding_api: ModelAPI = ModelAPI(
-        os.environ.get("EMBEDDING_API", ModelAPI.HUGGINGFACE.value)
+    embedding_api: ModelAPI = Field(
+        default_factory=lambda: ModelAPI(
+            os.environ.get("EMBEDDING_API", ModelAPI.HUGGINGFACE.value)
+        ),
+        description="API provider for embeddings (OPENAI, HUGGINGFACE, or OLLAMA). Set via EMBEDDING_API.",
     )
-
-    llm_api: ModelAPI = ModelAPI(
-        os.environ.get("LLM_API", ModelAPI.OLLAMA.value)
+    llm_api: ModelAPI = Field(
+        default_factory=lambda: ModelAPI(
+            os.environ.get("LLM_API", ModelAPI.OLLAMA.value)
+        ),
+        description="API provider for LLM (OPENAI, HUGGINGFACE, or OLLAMA). Set via LLM_API.",
     )
-
-    max_research_loops: int = int(os.environ.get("MAX_RESEARCH_LOOPS", "3"))
-
-    llm_tool_model: str = str(
-        os.environ.get("LLM_TOOL_MODEL", "smollm2:1.7b-instruct-q2_K")
+    max_research_loops: int = Field(
+        default_factory=lambda: int(os.environ.get("MAX_RESEARCH_LOOPS", "3")),
+        description="Maximum number of research loops to perform. Set via MAX_RESEARCH_LOOPS.",
+    )
+    llm_tool_model: str = Field(
+        default_factory=lambda: os.environ.get(
+            "LLM_TOOL_MODEL", "smollm2:1.7b-instruct-q2_K"
+        ),
+        description="Name of the LLM model to use for tool calling. Set via LLM_TOOL_MODEL.",
+    )
+    n_context_docs: int = Field(
+        default_factory=lambda: int(os.environ.get("N_CONTEXT_DOCS", "2")),
+        description="Number of context documents to retrieve for RAG. Set via N_CONTEXT_DOCS.",
+    )
+    search_permission: str = Field(
+        default_factory=lambda: os.environ.get("EVA_SEARCH_PERMISSION", "no"),
+        description="Permission for search (yes/no). Set via EVA_SEARCH_PERMISSION.",
+    )
+    db_persist: Optional[str] = Field(
+        default_factory=lambda: os.environ.get("EVA_DB_PERSIST", None),
+        description="Path or flag for DB persistence. Set via EVA_DB_PERSIST.",
+    )
+    eva_reinitialize: bool = Field(
+        default_factory=lambda: os.environ.get(
+            "EVA_REINITIALIZE", "False"
+        ).lower()
+        in ("true", "1", "yes"),
+        description="If true, reinitializes EVA DB. Set via EVA_REINITIALIZE.",
+    )
+    eva_strip_think: bool = Field(
+        default_factory=lambda: os.environ.get(
+            "EVA_STRIP_THINK", "True"
+        ).lower()
+        in ("true", "1", "yes"),
+        description="If true (default) strips thinking tags from LLM responses. Set via EVA_STRIP_THINK.",
     )
-    n_context_docs: int = int(os.environ.get("N_CONTEXT_DOCS", "2"))
-
-    search_permission: str = str(os.environ.get("EVA_SEARCH_PERMISSION", "no"))
-
-    db_persist: str | None = os.environ.get("EVA_DB_PERSIST", None)
 
-    eva_reinitialize: bool = bool(os.environ.get("EVA_REINITIALIZE", "False"))
+    thread_id: str = Field(
+        default="",
+        description="Thread ID for the current session. Set via THREAD_ID.",
+    )
 
-    thread_id: str = ""
+    class Config:
+        env_file = ".env"
+        env_file_encoding = "utf-8"
+        extra = "ignore"  # Allow extra env vars in .env/environment
 
     @classmethod
     def from_runnable_config(
@@ -96,16 +131,14 @@ class Configuration:
             if config and "configurable" in config
             else {}
         )
-        # Map each dataclass field to environment variables or configurable values
+        # Map each field to environment variables or configurable values
         # Priority: environment variables > configurable dict values > field defaults
         values: dict[str, Any] = {
-            f.name: os.environ.get(f.name.upper(), configurable.get(f.name))
-            for f in fields(cls)
-            if f.init
+            name: os.environ.get(name.upper(), configurable.get(name))
+            for name in cls.__fields__
         }
         logging.info("Configuration:\n%s", values)
-
-        return cls(**{k: v for k, v in values.items() if v})
+        return cls(**{k: v for k, v in values.items() if v is not None})
 
     def print(self, print_like_function=logging.info) -> None:
         """Print all configuration parameters using the provided logging function.
@@ -117,10 +150,9 @@ class Configuration:
             None
         """
         print_like_function("Configuration parameters:")
-        for field in fields(self):
-            if field.init:
-                value = getattr(self, field.name)
-                print_like_function("  %s: %s", field.name, value)
+        for name, field in self.__fields__.items():
+            value = getattr(self, name)
+            print_like_function("  %s: %s", name, value)
 
     def to_runnable_config(self) -> RunnableConfig:
         """Convert Configuration instance to RunnableConfig format.
@@ -129,16 +161,10 @@ class Configuration:
             RunnableConfig: Properly formatted configuration for LangGraph
         """
         configurable_dict = {}
-
-        # Add all non-empty configuration fields to configurable
-        for field in fields(self):
-            if field.init:
-                value = getattr(self, field.name)
-                if value:  # Only include non-empty values
-                    configurable_dict[field.name] = value
-
-        # Ensure thread_id is included if set
+        for name in self.__fields__:
+            value = getattr(self, name)
+            if value:
+                configurable_dict[name] = value
         if self.thread_id:
             configurable_dict["thread_id"] = self.thread_id
-
         return RunnableConfig(configurable=configurable_dict)

pyproject.toml

@@ -52,6 +52,7 @@ dependencies = [
     "langchain-tavily>=0.2.0",
     "beautifulsoup4>=4.13.4",
     "pathvalidate>=3.2.3",
+    "pydantic-settings>=2.9.1",
 ]
 authors = [{ name = "Marko Budisic", email = "[email protected]" }]
 license = "MIT"

uv.lock

@@ -3777,6 +3777,7 @@ dependencies = [
     { name = "pandas" },
     { name = "pathvalidate" },
     { name = "pyarrow" },
+    { name = "pydantic-settings" },
     { name = "python-dotenv" },
     { name = "qdrant-client" },
     { name = "ragas" },
@@ -3850,6 +3851,7 @@ requires-dist = [
     { name = "pandas", specifier = ">=2.0.0" },
     { name = "pathvalidate", specifier = ">=3.2.3" },
     { name = "pyarrow", specifier = ">=19.0.0" },
+    { name = "pydantic-settings", specifier = ">=2.9.1" },
     { name = "pylint-venv", marker = "extra == 'dev'", specifier = ">=3.0.4" },
     { name = "pytest", marker = "extra == 'dev'", specifier = ">=7.0.0" },
     { name = "python-dotenv", specifier = ">=0.9.9" },