From 40ac5f8c16b1d25b5801d0b938ce436fe5702779 Mon Sep 17 00:00:00 2001
From: laansdole <dolelongan@gmail.com>
Date: Sat, 7 Feb 2026 10:45:19 +0700
Subject: [PATCH] chores: improve docstring

---
 .env.example                | 23 ++++++++--------------
 tools/sync_vuegraphs.py     | 39 ++++++++++++++++++++++++++-----------
 tools/validate_all_yamls.py | 31 +++++++++++++++++++++++++++--
 3 files changed, 65 insertions(+), 28 deletions(-)

diff --git a/.env.example b/.env.example
index 0377f008..088d3f63 100644
--- a/.env.example
+++ b/.env.example
@@ -1,24 +1,17 @@
 # ============================================================================
-# LLM Provider Configuration (OpenAI-Compatible API)
+# LLM Provider Configuration
 # ============================================================================
-# This project supports any OpenAI-compatible API provider.
-# Configure BASE_URL, API_KEY, and MODEL_NAME based on your chosen provider.
+# BASE_URL and API_KEY are the standard configurations for model call authentication.
+# These variables support OpenAI, Gemini, LM Studio, Ollama, and other providers.
 
-# ----------------------------------------------------------------------------
-# Option 1: OpenAI
-# ----------------------------------------------------------------------------
 BASE_URL=https://api.openai.com/v1
 API_KEY=sk-your-openai-api-key-here
-MODEL_NAME=gpt-4o
 
-# ----------------------------------------------------------------------------
-# Option 2: Other OpenAI-Compatible Providers
-# ----------------------------------------------------------------------------
-# Example for LM Studio
-
-# BASE_URL=http://localhost:1234/v1
-# API_KEY=lm-studio
-# MODEL_NAME=local-model
+# Example BASE_URL values:
+# - OpenAI:    https://api.openai.com/v1
+# - Gemini:    https://generativelanguage.googleapis.com/v1beta/openai/
+# - LM Studio: http://localhost:1234/v1
+# - Ollama:    http://localhost:11434/v1
 
 # ============================================================================
 # Optional: Web Search and Reading Tools
diff --git a/tools/sync_vuegraphs.py b/tools/sync_vuegraphs.py
index 7ce5f151..60bb7ee9 100644
--- a/tools/sync_vuegraphs.py
+++ b/tools/sync_vuegraphs.py
@@ -1,3 +1,21 @@
+"""
+Synchronize YAML Configurations to VueGraph Database
+
+This tool uploads local YAML workflow configurations from the yaml_instance/
+directory to the VueGraph database via the API endpoint. This is essential for
+making workflow configurations available to the frontend visualization system.
+
+Purpose:
+- Ensures the database reflects the latest YAML configurations
+- Required after modifying workflow YAML files to see changes in the UI
+- Useful for development and deployment workflows
+
+Usage:
+    python tools/sync_vuegraphs.py
+    # or via Makefile:
+    make sync
+"""
+
 import os
 import glob
 import requests
@@ -8,19 +26,20 @@ from pathlib import Path
 API_URL = "http://localhost:6400/api/vuegraphs/upload/content"
 YAML_DIR = "yaml_instance"
 
+
 def sync_yaml_to_vuegraphs():
     """Reads all YAML files and uploads them to the VueGraph database."""
     print(f"Syncing YAML files from {YAML_DIR} to {API_URL}...")
-    
+
     yaml_files = glob.glob(os.path.join(YAML_DIR, "*.yaml"))
-    
+
     for file_path in yaml_files:
         try:
             filename = Path(file_path).stem  # simulation_hospital_lmstudio
-            
+
             with open(file_path, "r") as f:
                 content = f.read()
-                
+
             # Basic validation to ensure it's a valid YAML
             try:
                 yaml.safe_load(content)
@@ -29,20 +48,18 @@ def sync_yaml_to_vuegraphs():
                 continue
 
             # Upload to VueGraph API
-            payload = {
-                "filename": filename,
-                "content": content
-            }
-            
+            payload = {"filename": filename, "content": content}
+
             response = requests.post(API_URL, json=payload)
-            
+
             if response.status_code == 200:
                 print(f"Synced: {filename}")
             else:
                 print(f"Failed: {filename} - {response.status_code} {response.text}")
-                
+
         except Exception as e:
             print(f"Error processing {file_path}: {e}")
 
+
 if __name__ == "__main__":
     sync_yaml_to_vuegraphs()
diff --git a/tools/validate_all_yamls.py b/tools/validate_all_yamls.py
index b4f27ff7..19f89d49 100644
--- a/tools/validate_all_yamls.py
+++ b/tools/validate_all_yamls.py
@@ -1,3 +1,22 @@
+"""
+Validate All YAML Workflow Configurations
+
+This tool performs strict validation on all YAML workflow configuration files
+in the yaml_instance/ directory. It ensures configuration integrity and prevents
+runtime errors by catching issues early in the development process.
+
+Purpose:
+- Validates YAML syntax and schema compliance for all workflow configurations
+- Prevents invalid configurations from causing runtime failures
+- Essential for CI/CD pipelines to ensure code quality
+- Provides detailed error reporting for debugging
+
+Usage:
+    python tools/validate_all_yamls.py
+    # or via Makefile:
+    make validate-yamls
+"""
+
 import sys
 import subprocess
 from pathlib import Path
@@ -57,7 +76,7 @@ def validate_all():
             failed_files.append(str(rel_path))
 
     print("\n" + "=" * 40)
-    print(f"Validation Summary")
+    print(f"YAML Validation Summary")
     print("=" * 40)
     print(f"Total Files: {len(files)}")
     print(f"Passed:      {passed}")
@@ -67,9 +86,17 @@ def validate_all():
         print("\nFailed Files:")
         for f in failed_files:
             print(f"- {f}")
+
+    # Overall validation status
+    print("\n" + "=" * 40)
+    print("Overall Validation Status")
+    print("=" * 40)
+
+    if failed > 0:
+        print("YAML validation: FAILED")
         sys.exit(1)
     else:
-        print("\nAll files passed validation.")
+        print("All validations passed successfully.")
         sys.exit(0)