refactor: added docstrings and verbose

app.py

@@ -3,16 +3,16 @@ import requests
 import json
 import os
 import shutil
-from models import OptimizeRequest, AutotuneRequest, QARequest
 import threading
+from models import OptimizeRequest, AutotuneRequest, QARequest
 from api import start_api
 
 threading.Thread(target=start_api, daemon=True).start()
 
-
 # Base URL for internal calls
 BASE_INTERNAL = "http://127.0.0.1:8000"
 
+
 def call_api(endpoint: str, payload: dict) -> str:
     try:
         r = requests.post(f"{BASE_INTERNAL}{endpoint}", json=payload, timeout=120)
@@ -20,7 +20,18 @@ def call_api(endpoint: str, payload: dict) -> str:
     except Exception as e:
         return str(e)
 
+
 def upload_docs_tool(files, docs_path="data/docs"):
+    """
+    Upload documents to the server's docs folder.
+
+    Parameters:
+    - files: List of file paths to upload
+    - docs_path: Destination folder (default: data/docs)
+
+    Returns:
+    - dict with uploaded filenames and docs_path
+    """
     os.makedirs(docs_path, exist_ok=True)
     saved = []
     for f in files:
@@ -30,18 +41,33 @@ def upload_docs_tool(files, docs_path="data/docs"):
         saved.append(fname)
     return {"status": "ok", "uploaded_files": saved, "docs_path": docs_path}
 
+
 def optimize_rag_tool(payload: str) -> str:
+    """🔧 Explicit optimization request: user provides all pipeline configs manually."""
     return call_api("/optimize_rag", json.loads(payload))
 
+
 def autotune_tool(payload: str) -> str:
+    """🔧 Autotune RAG: recommends chunk sizes and embedding models automatically."""
     return call_api("/autotune_rag", json.loads(payload))
 
+
 def generate_qa_tool(payload: str) -> str:
+    """🧩 Generates a validation QA dataset for RAG evaluation."""
     return call_api("/generate_validation_qa", json.loads(payload))
 
+
+# Dynamically assign Pydantic model docstrings to MCP tool functions
+optimize_rag_tool.__doc__ = OptimizeRequest.__doc__
+autotune_tool.__doc__ = AutotuneRequest.__doc__
+generate_qa_tool.__doc__ = QARequest.__doc__
+
+
 def model_to_json(model_cls) -> str:
     return json.dumps({k: v.default for k, v in model_cls.__fields__.items()}, indent=2)
 
+
+# Default inputs
 DEFAULT_UPLOAD_PATH = "data/docs"
 DEFAULT_OPTIMIZE_JSON = model_to_json(OptimizeRequest)
 DEFAULT_AUTOTUNE_JSON = model_to_json(AutotuneRequest)
@@ -49,8 +75,11 @@ DEFAULT_QA_JSON = model_to_json(QARequest)
 
 with gr.Blocks(theme=gr.themes.Soft()) as demo:
     gr.Markdown("# Ragmint MCP Client")
+
+    # Upload Documents
     with gr.Column():
         gr.Markdown("## Upload Documents")
+        gr.Markdown("📂 Upload files to your `data/docs` folder")
         upload_files = gr.File(file_count="multiple", type="filepath")
         upload_path = gr.Textbox(value=DEFAULT_UPLOAD_PATH, label="Docs Path")
         upload_btn = gr.Button("Upload", variant="primary")
@@ -58,27 +87,33 @@ with gr.Blocks(theme=gr.themes.Soft()) as demo:
         upload_btn.click(upload_docs_tool, inputs=[upload_files, upload_path], outputs=upload_out)
         gr.Markdown("---")
 
+    # Optimize RAG
     with gr.Column():
         gr.Markdown("## Optimize RAG")
+        gr.Markdown(OptimizeRequest.__doc__ or "No description available.")
         optimize_input = gr.Textbox(lines=12, value=DEFAULT_OPTIMIZE_JSON, label="OptimizeRequest JSON")
         optimize_btn = gr.Button("Submit", variant="primary")
-        optimize_out = gr.Textbox(lines=15,label="Response")
+        optimize_out = gr.Textbox(lines=15, label="Response")
         optimize_btn.click(optimize_rag_tool, inputs=optimize_input, outputs=optimize_out)
         gr.Markdown("---")
 
+    # Autotune RAG
     with gr.Column():
         gr.Markdown("## Autotune RAG")
+        gr.Markdown(AutotuneRequest.__doc__ or "No description available.")
         autotune_input = gr.Textbox(lines=12, value=DEFAULT_AUTOTUNE_JSON, label="AutotuneRequest JSON")
         autotune_btn = gr.Button("Submit", variant="primary")
         autotune_out = gr.Textbox(lines=15)
         autotune_btn.click(autotune_tool, inputs=autotune_input, outputs=autotune_out)
         gr.Markdown("---")
 
+    # Generate QA
     with gr.Column():
         gr.Markdown("## Generate QA")
+        gr.Markdown(QARequest.__doc__ or "No description available.")
         qa_input = gr.Textbox(lines=12, value=DEFAULT_QA_JSON, label="QARequest JSON")
         qa_btn = gr.Button("Submit", variant="primary")
-        qa_out = gr.Textbox(lines=15,label="Response")
+        qa_out = gr.Textbox(lines=15, label="Response")
         qa_btn.click(generate_qa_tool, inputs=qa_input, outputs=qa_out)
         gr.Markdown("---")
 
@@ -86,5 +121,6 @@ if __name__ == "__main__":
     demo.launch(
         server_name="0.0.0.0",
         server_port=7860,
-        mcp_server=True
-    )
+        mcp_server=True,
+        show_error=True
+    )

models.py

@@ -6,7 +6,21 @@ from pydantic import BaseModel, Field
 # Models
 class OptimizeRequest(BaseModel):
     """
-    🔧 Explicit optimization request: user provides all pipeline configs manually.
+    🔧 Explicit optimization request for RAG (Retrieval-Augmented Generation) pipelines.
+
+    Parameters:
+    - docs_path (str, optional): 📂 Folder containing your documents for RAG optimization. Default: "data/docs"
+    - retriever (List[str], optional): 🔍 Retriever type(s) to use. Default: ['faiss']. Example: 'bm25', 'faiss', 'chroma'
+    - embedding_model (List[str], optional): 🧠 Embedding model(s) to use. Default: ['sentence-transformers/all-MiniLM-L6-v2']
+    - strategy (List[str], optional): 🎯 RAG strategy to apply. Default: ['fixed']. Options: 'fixed', 'token', 'sentence'
+    - chunk_sizes (List[int], optional): 📏 List of chunk sizes to evaluate. Default: [200, 400, 600]
+    - overlaps (List[int], optional): 🔁 List of overlap values to test. Default: [50, 100, 200]
+    - rerankers (List[str], optional): ⚖️ Rerankers to apply after retrieval. Default: ['mmr']
+    - search_type (str, optional): 🔍 Search method for parameter exploration. Default: 'grid'. Options: 'grid', 'random', 'bayesian'
+    - trials (int, optional): 🧪 Number of optimization trials. Default: 5
+    - metric (str, optional): 📈 Metric to optimize. Default: 'faithfulness'
+    - validation_choice (str, optional): ✅ Source of validation data. Default: 'generate'. Options: blank (use default), 'generate', local path, HF dataset ID
+    - llm_model (str, optional): 🤖 LLM used for QA generation if validation_choice='generate'. Default: 'gemini-2.5-flash-lite'
     """
     docs_path: Optional[str] = Field(
         default="data/docs",
@@ -66,6 +80,20 @@ class OptimizeRequest(BaseModel):
 
 
 class AutotuneRequest(BaseModel):
+    """
+    ⚡ Automatically tunes RAG pipeline parameters based on document analysis.
+
+    Parameters:
+    - docs_path (str, optional): 📂 Folder containing documents for RAG optimization. Default: "data/docs"
+    - embedding_model (str, optional): 🧠 Embedding model to analyze. Default: 'sentence-transformers/all-MiniLM-L6-v2'
+    - num_chunk_pairs (int, optional): 🔢 Number of chunk pairs to analyze. Default: 5
+    - metric (str, optional): 📈 Metric to optimize. Default: 'faithfulness'
+    - search_type (str, optional): 🔍 Search method for parameter exploration. Default: 'grid'. Options: 'grid', 'random', 'bayesian'
+    - trials (int, optional): 🧪 Number of optimization trials. Default: 5
+    - validation_choice (str, optional): ✅ Source of validation data. Default: 'generate'. Options: blank, 'generate', local path, HF dataset ID
+    - llm_model (str, optional): 🤖 LLM used for QA generation if validation_choice='generate'. Default: 'gemini-2.5-flash-lite'
+    """
+
     docs_path: Optional[str] = Field(
         default="data/docs",
         description="📂 Folder containing your documents for RAG optimization. Example: 'data/docs'"
@@ -108,7 +136,14 @@ class AutotuneRequest(BaseModel):
 
 class QARequest(BaseModel):
     """
-    🧩 Generates a validation QA dataset for RAG evaluation.
+    🧩 Generate a validation QA dataset from documents for RAG evaluation.
+
+    Parameters:
+    - docs_path (str): 📂 Folder containing documents. Default: 'data/docs'
+    - llm_model (str): 🤖 LLM model used for question generation. Default: 'gemini-2.5-flash-lite'
+    - batch_size (int): 📦 Number of documents per batch. Default: 5
+    - min_q (int): ❓ Minimum number of questions per document. Default: 3
+    - max_q (int): ❓ Maximum number of questions per document. Default: 25
     """
     docs_path: str = Field(
         description="📂 Folder containing your documents to generate QA pairs from. Example: 'data/docs'",