chore: improve code comments and docstrings across UI components

wren-ai-service/streamlit-ui/app.py

@@ -11,44 +11,56 @@
 )
 import streamlit as st
 
-
+# Set Streamlit page layout
 st.set_page_config(
-    layout="wide",  # 使用寬屏模式
-    initial_sidebar_state="expanded"  # 控制側邊欄的初始狀態
+    layout="wide",                # Use a wide layout for better horizontal space
+    initial_sidebar_state="expanded"  # Expand sidebar by default
 )
 
+# Load and group configuration blocks from YAML
 yaml_list = load_config_yaml_blocks()
 blocks = group_blocks(yaml_list)
 
+# Retrieve individual configuration sections
 llm_block = blocks.get("llm", {})
 embedder_block = blocks.get("embedder", {})
-document_store_block   = blocks.get("document_store", {})
+document_store_block = blocks.get("document_store", {})
 engine_blocks = blocks.get("engine", [])
 pipeline_block = blocks.get("pipeline", {})
 settings_block = blocks.get("settings", {})
 
+# Initialize session state with default or imported config values
+ConfigState.init(llm_block, embedder_block, document_store_block, pipeline_block)
 
-# --- Streamlit UI --
-st.title(" Custom LLM Config Generator")
-st.markdown("")
-col1, col2 = st.columns([1.5, 1])  # 左右欄位
+# ----------------------
+# Streamlit UI rendering
+# ----------------------
+st.title("Custom LLM Config Generator")
 
-ConfigState.init(llm_block, embedder_block, document_store_block, pipeline_block)
+# Layout: two columns – left for inputs, right for preview/export
+col1, col2 = st.columns([1.5, 1])  
 
 with col1:
     st.subheader("LLM Configuration")
-    # =====================
-    # LLM Configuration UI
-    # =====================
+
+    # Upload and parse YAML file into session state
     render_import_yaml()
+
+    # API key input section
     render_apikey()
+
+    # LLM model configuration UI
     render_llm_config()
+
+    # Embedding model configuration UI
     render_embedder_config()
+
+    # Document store configuration UI
     render_document_store_config()
+
+    # Pipeline flow configuration UI
     render_pipeline_config()
 
 with col2:
-    # =====================
-    # preview and generate YAML UI 
-    # =====================
+    # Final preview and export of the combined configuration as YAML
     render_preview_and_generate(engine_blocks, pipeline_block, settings_block)

wren-ai-service/streamlit-ui/config_loader.py

@@ -3,11 +3,12 @@
 from session_state import ConfigState
 from pathlib import Path
 import constants as cst
-from typing import Any, Dict, List 
+from typing import Any, Dict, List
 
 def load_config_yaml_blocks() -> List[Dict[str, Any]]:
     """
-    嘗試從本地讀 config.yaml，若不存在則從 GitHub 讀取（不下載）。
+    Load the config.yaml from local disk if available; 
+    otherwise, fetch it from the GitHub URL without downloading it.
     """
     if cst.CONFIG_IN_PATH.exists():
         try:
@@ -18,18 +19,31 @@ def load_config_yaml_blocks() -> List[Dict[str, Any]]:
     else:
         return fetch_yaml_from_url(cst.CONFIG_URL)
 
-def load_selected_example_yaml(example_name: str) -> List[Dict[str, Any]]:
-    url = cst.CONFIG_EXAMPLES_SELECTED_URL + example_name
-    return fetch_yaml_from_url(url)
+def load_selected_example_yaml(selected_example: str) -> List[Dict[str, Any]]:
+    """
+    Fetch a selected YAML example file from GitHub and return it as a list of blocks.
+    """
+    selected_url = cst.CONFIG_EXAMPLES_SELECTED_URL + selected_example
+    try:
+        response = requests.get(selected_url, timeout=cst.REQUEST_TIMEOUT)
+        response.raise_for_status()
+        return list(yaml.safe_load_all(response.text))
+    except requests.RequestException as e:
+        print(f"❌ Error loading config from GitHub: {e}")
+        return []
 
 def fetch_yaml_from_url(url: str) -> List[Dict[str, Any]]:
+    """
+    Fetch and parse a YAML list from a remote URL.
+    Returns an empty list if fetch or parsing fails.
+    """
     try:
         response = requests.get(url, timeout=cst.REQUEST_TIMEOUT)
         response.raise_for_status()
         config_list = list(yaml.safe_load_all(response.text))
 
         if not config_list:
-            raise ValueError(f"⚠️ GitHub 回傳的 YAML 是空的，URL: {url}")
+            raise ValueError(f"⚠️ Received empty YAML content from: {url}")
 
         return config_list
 
@@ -39,7 +53,8 @@ def fetch_yaml_from_url(url: str) -> List[Dict[str, Any]]:
 
 def extract_config_blocks(config_list: List[Dict[str, Any]]) -> Dict[str, Any]:
     """
-    傳入 YAML List，回傳各 block 分類後的 dict
+    Convert a flat list of config blocks into grouped dictionary format 
+    with keys like 'llm', 'embedder', 'document_store', and 'pipeline'.
     """
     grouped = group_blocks(config_list)
     return {
@@ -49,22 +64,18 @@ def extract_config_blocks(config_list: List[Dict[str, Any]]) -> Dict[str, Any]:
         "pipeline": grouped.get("pipeline", {})
     }
 
-def load__selected_config_yaml_blocks(selected_examples) -> List[Dict[str, Any]]:
-        selected_url = cst.CONFIG_EXAMPLES_SELECTED_URL + selected_examples
-        # return selected_url
-        try:
-            response = requests.get(selected_url, timeout=cst.REQUEST_TIMEOUT)
-            response.raise_for_status()
-            return list(yaml.safe_load_all(response.text))
-        except requests.RequestException as e:
-            print(f"❌ Error loading config from GitHub: {e}")
-            return []
-
 def load_yaml_list(path: Path) -> List[Dict[str, Any]]:
+    """
+    Load and parse all YAML documents from a file path.
+    """
     with path.open("r", encoding="utf-8") as f:
         return list(yaml.safe_load_all(f))
 
 def group_blocks(blocks: List[Dict[str, Any]]) -> Dict[str, Any]:
+    """
+    Group YAML blocks by their 'type' field.
+    If multiple blocks share the same type, they are stored as a list.
+    """
     save_blocks = {}
     for block in blocks:
         key = block.get("type") or ("settings" if "settings" in block else None)
@@ -80,7 +91,10 @@ def group_blocks(blocks: List[Dict[str, Any]]) -> Dict[str, Any]:
     return save_blocks
 
 def fetch_example_yaml_filenames() -> List[str]:
-    """從 GitHub 的 config_examples 目錄中取得所有 .yaml 檔案名稱（不載入內容）"""
+    """
+    Fetch the filenames of all .yaml example configs from the GitHub directory 
+    (does not download the content).
+    """
     try:
         response = requests.get(cst.CONFIG_EXAMPLES_URL, timeout=cst.REQUEST_TIMEOUT)
         response.raise_for_status()
@@ -91,13 +105,15 @@ def fetch_example_yaml_filenames() -> List[str]:
         return []
 
 def apply_config_blocks(config_blocks: List[Dict[str, Any]]):
+    """
+    Group and apply config blocks by updating the Streamlit session state via ConfigState.
+    """
     grouped = extract_config_blocks(config_blocks)
 
-    # 更新 ConfigState
     ConfigState.init(
         grouped["llm"],
         grouped["embedder"],
         grouped["document_store"],
         grouped["pipeline"],
         force=True
-    )
+    )

wren-ai-service/streamlit-ui/constants.py

@@ -1,25 +1,56 @@
 from pathlib import Path
 import requests
 
-# --- 自動取得最新版本 tag ---
+# -------------------------------
+# Fetch Latest Release Version
+# -------------------------------
+
 def get_latest_config_version():
+    """
+    Retrieve the latest release tag from the WrenAI GitHub repository.
+
+    Returns:
+        str: The latest version tag (e.g., "0.20.2") if successful,
+             or "main" as a fallback if the request fails.
+    """
     url = "https://api.github.com/repos/Canner/WrenAI/releases/latest"
     try:
         response = requests.get(url, timeout=10)
         if response.status_code == 200:
             data = response.json()
-            return data["tag_name"]  # ← 這裡就是 "0.20.2" 這種版本號
+            return data["tag_name"]  # e.g., "0.20.2"
         else:
             print(f"Failed to get latest release: {response.status_code}")
     except Exception as e:
         print(f"Error fetching latest config version: {e}")
-    return "main"  # fallback 版本，如果失敗就用 main branch
 
-# --- constant ---
+    return "main"  # Fallback to 'main' branch if fetch fails
+
+
+# -------------------------------
+# Constants for Config Loading
+# -------------------------------
+
 CONFIG_VERSION = get_latest_config_version()
+
+# URL of the default config YAML file (used when no local file is available)
 CONFIG_URL = f"https://raw.githubusercontent.com/Canner/WrenAI/{CONFIG_VERSION}/docker/config.example.yaml"
-CONFIG_EXAMPLES_URL = f"https://api.github.com/repos/Canner/WrenAI/contents/wren-ai-service/docs/config_examples?ref={CONFIG_VERSION}"
-CONFIG_EXAMPLES_SELECTED_URL = f"https://raw.githubusercontent.com/Canner/WrenAI/{CONFIG_VERSION}/wren-ai-service/docs/config_examples/"
+
+# GitHub API URL to list example config files (metadata only, no content)
+CONFIG_EXAMPLES_URL = (
+    f"https://api.github.com/repos/Canner/WrenAI/contents/wren-ai-service/docs/config_examples?ref={CONFIG_VERSION}"
+)
+
+# Base URL to fetch actual example YAML content by filename
+CONFIG_EXAMPLES_SELECTED_URL = (
+    f"https://raw.githubusercontent.com/Canner/WrenAI/{CONFIG_VERSION}/wren-ai-service/docs/config_examples/"
+)
+
+# Path to local input config file (used if exists)
 CONFIG_IN_PATH = Path("config.yaml")
+
+# Path to write the generated config YAML file
 CONFIG_OUT_PATH = Path("generated_config.yaml")
-REQUEST_TIMEOUT = 10  # seconds
+
+# Timeout duration for HTTP requests (in seconds)
+REQUEST_TIMEOUT = 10