Deploy QueryLens (Gradio-SDK launcher: worker :8700 / MCP :8701 / web :7860)

README.md

@@ -1,16 +1,22 @@
 ---
-title: QueryLens V2
-emoji: 🔍
-colorFrom: blue
-colorTo: indigo
 sdk: gradio
-sdk_version: 5.0.0
-app_file: app.py
+sdk_version: 6.30.0
+python_version: 3.11
+title: QueryLens Text2SQL-DocVQA
+emoji: 🤖
+colorFrom: amber
+colorTo: orange
 pinned: false
+  - agents
+  - mcp
+app_file: app.py
+tags:
+  - agents
+  - mcp
 ---
 
 
-# 🤖 Agentic Text2SQL & Document VQA
+# Agentic Text2SQL & Document VQA
  Multi-Agent System
 
 ![Architecture](https://img.shields.io/badge/Architecture-Multi--Agent-blue)
@@ -26,16 +32,16 @@ By leveraging the Model Context Protocol (MCP), local LLMs via Ollama, and intel
 
 ## Key Features
 
-- **Multi-Agent Orchestration:** A dynamic routing system featuring specialized agents — MemoryAgent, QueryCraftAgent, and ResultPresenterAgent — each with a clearly defined role in the pipeline.
-- **Dynamic Database Profiles:** Connect any database by connection string, or upload a `.sqlite`/`.db`/`.csv` file directly from the UI. Profiles are registered, switchable, and deletable at runtime via the `Database` panel or the `/api/schemas` REST surface — the built-in employee sample DB ships as one profile (`demo_employee`) among many.
+- **Multi-Agent Orchestration:** A dynamic routing system featuring specialized agents — MemoryAgent, QueryCraftAgent, and ResultPresenterAgent — each with a clearly defined role in the pipeline.
+- **Dynamic Database Profiles:** Connect any database by connection string, or upload a `.sqlite`/`.db`/`.csv` file directly from the UI. Profiles are registered, switchable, and deletable at runtime via the `Database` panel or the `/api/schemas` REST surface — the built-in employee sample DB ships as one profile (`demo_employee`) among many.
 - **Schema-Aware Generic Agents:** The agent pipeline reads a live introspected schema profile (tables, columns, PK/FK, row counts, sample rows) instead of assuming a fixed schema. The fourteen employee-specific `fast_sql` templates activate only when the employee demo is the active profile; every other database gets generic `schema.list_tables / schema.describe_table / schema.sample_data / sql.build_select` MCP tools and profile-aware prompts, validators, and reducers.
-- **Interactive Charts:** Query results that visualize well (category breakdowns, comparisons, time series) are detected automatically and rendered as ECharts visualizations — pie, bar, or line — in a sepia-toned palette. Chart specs ride in the query response as a first-class `chart` field; detection is conservative and never corrupts a textual answer.
+- **Interactive Charts:** Query results that visualize well (category breakdowns, comparisons, time series) are detected automatically and rendered as ECharts visualizations — pie, bar, or line — in a sepia-toned palette. Chart specs ride in the query response as a first-class `chart` field; detection is conservative and never corrupts a textual answer.
 - **Modern Sepia UI:** A Claude-inspired coffee/sepia interface with serif headings and a warm terracotta accent, wrapping the multi-agent trace panels (Memory / QueryCraft / ResultPresenter), live schema browsing, and charting.
-- **Vision-Language Question Answering:** VQA/OCR extraction from invoices and unstructured documents. Served locally via Ollama (`qwen2-vl:2b`) or — in cloud mode — through Groq's `qwen/qwen3.8-27b` vision model (free tier).
+- **Vision-Language Question Answering:** VQA/OCR extraction from invoices and unstructured documents. Served locally via Ollama (`qwen2-vl:2b`) or — in cloud mode — through Groq's `qwen/qwen3.8-27b` vision model (free tier).
 - **Three-Level Text-to-SQL Engine:** Translates natural language questions into syntactically valid SQL through a progressive reasoning architecture, with automatic self-correction at each escalation level.
 - **Semantic Gatekeeping:** A multi-layer validation pipeline filters hallucinated SQL, undefined aliases, missing joins, and incorrect aggregation patterns before any query reaches the database.
 - **Dynamic VRAM Orchestration:** Custom memory management algorithms automatically load and unload models from GPU VRAM to prevent out-of-memory crashes, enabling concurrent AI workloads on consumer hardware.
-- **Unified MCP Integration:** All external data sources — relational databases and vision models alike — are accessed through a single, uniform Model Context Protocol interface.
+- **Unified MCP Integration:** All external data sources — relational databases and vision models alike — are accessed through a single, uniform Model Context Protocol interface.
 - **Database Agnostic Design:** Architected to interface with PostgreSQL, MySQL, SQLite, MS SQL Server, and Oracle via SQLAlchemy.
 - **Conversational Interface:** A full Web UI supporting natural language interaction with persistent session context.
 
@@ -60,7 +66,7 @@ Profiles persist in `chat_store/schema_profiles.json` and survive restarts; uplo
 
 ### Chart contract
 
-When a query returns rows that visualize well, the ResultPresenter embeds a chart spec (pie/bar/line, labels + numeric series) that the worker exposes as `{"chart": {...}}` alongside the text `answer`. Selection heuristics: date-like first column + numeric series → line; ≤8 categories with a single numeric series → pie; otherwise bar. Detection caps at 60 points and never mutates the answer text.
+When a query returns rows that visualize well, the ResultPresenter embeds a chart spec (pie/bar/line, labels + numeric series) that the worker exposes as `{"chart": {...}}` alongside the text `answer`. Selection heuristics: date-like first column + numeric series → line; ≤8 categories with a single numeric series → pie; otherwise bar. Detection caps at 60 points and never mutates the answer text.
 
 ### Working against the demo employee database
 
@@ -78,15 +84,15 @@ The project employs a decoupled, asynchronous microservices architecture. The We
 
 The MemoryAgent acts as the entry point for all user queries. It performs three functions before any SQL generation occurs: checking whether the current query can be satisfied from historical conversation context, rephrasing ambiguous or under-specified queries based on prior interactions, and routing validated new queries to the appropriate downstream agent. This layer prevents redundant computation and improves response latency for repeated or related questions.
 
-**2. QueryCraftAgent — The Three-Level Text-to-SQL Engine**
+**2. QueryCraftAgent — The Three-Level Text-to-SQL Engine**
 
 The QueryCraftAgent is the core reasoning engine of the system. It implements a progressive escalation architecture that balances inference speed with accuracy:
 
-- **Level 1 — Pure LLM Intelligence:** Zero-shot semantic translation of natural language to SQL using Qwen 2.5 Coder. The generated query passes through a semantic validation pipeline that checks alias correctness, required table joins, aggregation integrity, and department or entity filters before being accepted.
+- **Level 1 — Pure LLM Intelligence:** Zero-shot semantic translation of natural language to SQL using Qwen 2.5 Coder. The generated query passes through a semantic validation pipeline that checks alias correctness, required table joins, aggregation integrity, and department or entity filters before being accepted.
 
-- **Level 2 — LLM with SQL Fixer:** When Level 1 fails validation, the agent enters an autonomous self-correction loop. The SQL Fixer applies a deterministic set of targeted transformations — normalizing aliases, injecting missing to_date filters, repairing phantom column references, and enforcing PostgreSQL-compliant GROUP BY clauses — before re-validating the output.
+- **Level 2 — LLM with SQL Fixer:** When Level 1 fails validation, the agent enters an autonomous self-correction loop. The SQL Fixer applies a deterministic set of targeted transformations — normalizing aliases, injecting missing to_date filters, repairing phantom column references, and enforcing PostgreSQL-compliant GROUP BY clauses — before re-validating the output.
 
-- **Level 3 — LLM with MCP Schema-Grounded SQL Generation:** The deepest reasoning level, reserved for queries that fail both prior levels. For the built-in employee demo, the agent calls one of fourteen registered `fast_sql` MCP tools, each of which queries the live database schema via SQLAlchemy's inspector to retrieve actual column names and table structures, then programmatically constructs a valid SQL template grounded in the real schema. For any user-registered database, the agent instead grounds itself through the generic `schema.list_tables` / `schema.describe_table` / `schema.sample_data` MCP tools, producing a verified live-schema + sample-data hint that applies to any database. In both cases the template is passed as a verified hint to the LLM, which refines it before the Fixer loop runs. Because the hint is built from the actual schema rather than the LLM's training data, this level eliminates the class of failures caused by hallucinated column names or missing joins.
+- **Level 3 — LLM with MCP Schema-Grounded SQL Generation:** The deepest reasoning level, reserved for queries that fail both prior levels. For the built-in employee demo, the agent calls one of fourteen registered `fast_sql` MCP tools, each of which queries the live database schema via SQLAlchemy's inspector to retrieve actual column names and table structures, then programmatically constructs a valid SQL template grounded in the real schema. For any user-registered database, the agent instead grounds itself through the generic `schema.list_tables` / `schema.describe_table` / `schema.sample_data` MCP tools, producing a verified live-schema + sample-data hint that applies to any database. In both cases the template is passed as a verified hint to the LLM, which refines it before the Fixer loop runs. Because the hint is built from the actual schema rather than the LLM's training data, this level eliminates the class of failures caused by hallucinated column names or missing joins.
 
 **3. ResultPresenterAgent**
 
@@ -101,7 +107,7 @@ graph TD
     Web -->|Image Upload| Worker["Backend Worker\nPort 8700"]
     Web -->|Text Query| Worker
 
-    subgraph MCP["MCP Tool Server — Port 8701"]
+    subgraph MCP["MCP Tool Server — Port 8701"]
         DocScan["document_scanner.process\nTesseract OCR"]
         FastSQL["fast_sql tools\nSchema-Grounded SQL Generation"]
         VisionQA["granite_vision.qa\nQwen 3.5 2B Vision"]
@@ -142,7 +148,7 @@ The system is implemented as a Dockerized microservices architecture, with each
 
 For peak inference performance, the system uses a hybrid offloading strategy. The application logic and MCP servers run inside Docker containers for portability and isolation, while Ollama and all GPU inference are offloaded to the native Windows host and accessed by the containers over the WSL2 host bridge network (`OLLAMA_BASE_URL=http://<wsl2-host-ip>:11434`).
 
-This architecture eliminates the virtualization overhead introduced by Docker Desktop's Linux VM layer. By giving the inference engine direct access to NVIDIA CUDA cores and the full system memory pool — rather than a virtualized slice — the 1.5B parameter model achieves response times measured in seconds rather than minutes. The separation also means that GPU memory pressure from Ollama does not compete with the container's allocated memory ceiling.
+This architecture eliminates the virtualization overhead introduced by Docker Desktop's Linux VM layer. By giving the inference engine direct access to NVIDIA CUDA cores and the full system memory pool — rather than a virtualized slice — the 1.5B parameter model achieves response times measured in seconds rather than minutes. The separation also means that GPU memory pressure from Ollama does not compete with the container's allocated memory ceiling.
 
 ### Database Health and Startup Reliability
 
@@ -162,13 +168,13 @@ The Model Context Protocol server runs as a dedicated microservice on port 8701.
 
 ## Unified Multimodal Integration via MCP
 
-A defining architectural feature of this system is that OCR and multimodal reasoning are integrated through the same Model Context Protocol used for database access. The Qwen 3.5 2B Vision model is registered as a named MCP tool: `granite_vision.qa`. This internal tool identifier was retained from the original design specification; the underlying engine was subsequently replaced with Qwen 3.5 2B Vision, which demonstrated superior OCR accuracy and a smaller VRAM footprint. Because the tool interface is decoupled from its implementation, this substitution required no changes to the agent orchestration code — only the MCP tool registration was updated.
+A defining architectural feature of this system is that OCR and multimodal reasoning are integrated through the same Model Context Protocol used for database access. The Qwen 3.5 2B Vision model is registered as a named MCP tool: `granite_vision.qa`. This internal tool identifier was retained from the original design specification; the underlying engine was subsequently replaced with Qwen 3.5 2B Vision, which demonstrated superior OCR accuracy and a smaller VRAM footprint. Because the tool interface is decoupled from its implementation, this substitution required no changes to the agent orchestration code — only the MCP tool registration was updated.
 
 This design delivers three concrete engineering properties:
 
 **Uniform Protocol:** The orchestrator issues identical-format tool calls regardless of whether the data source is a SQL table or a visual document. There are no special-case code paths for different modalities.
 
-**Modular Replaceability:** The vision model is encapsulated behind its MCP interface. Upgrading to a different vision model — such as a GPT-4V endpoint — requires updating only the tool registration, not any agent logic.
+**Modular Replaceability:** The vision model is encapsulated behind its MCP interface. Upgrading to a different vision model — such as a GPT-4V endpoint — requires updating only the tool registration, not any agent logic.
 
 **Cross-Modal Reasoning Capability:** Because both data sources share the same protocol, the agent can compose multi-step reasoning across modalities. For example, the system can extract a value from a document via the vision tool and immediately verify it against a database record via the SQL tool, within a single agentic workflow.
 
@@ -276,24 +282,24 @@ GROQ_API_KEY=gsk_xxx
 GROQ_VISION_MODEL=qwen/qwen3.8-27b
 ```
 
-**Local Ollama (optional):** with `USE_HF_CLOUD=0`, the configured Ollama model is used — and if it is not installed while `HF_API_TOKEN` is present, the worker **auto-falls back** to HF Inference (`HF_LLM_MODEL`) instead of failing with 404 handshakes.
+**Local Ollama (optional):** with `USE_HF_CLOUD=0`, the configured Ollama model is used — and if it is not installed while `HF_API_TOKEN` is present, the worker **auto-falls back** to HF Inference (`HF_LLM_MODEL`) instead of failing with 404 handshakes.
 
 ### 3. Run Without Docker
 
 Start each microservice in a separate terminal:
 
 ```bash
-# Terminal 1 — Backend Worker
+# Terminal 1 — Backend Worker
 python -u -m uvicorn "Agent.worker:app" --port 8700
 
-# Terminal 2 — MCP Tool Server
+# Terminal 2 — MCP Tool Server
 python -m uvicorn "Agent.mcp_server:app" --port 8701
 
-# Terminal 3 — Web UI
+# Terminal 3 — Web UI
 python -m uvicorn "web.app:app" --port 8000
 ```
 
-Navigate to `http://localhost:8000` to interact with the system. Use the **Database** panel to connect your own database (connection URL or `.sqlite`/`.csv` upload) — the built-in employee sample is provided as a container-backed profile.
+Navigate to `http://localhost:8000` to interact with the system. Use the **Database** panel to connect your own database (connection URL or `.sqlite`/`.csv` upload) — the built-in employee sample is provided as a container-backed profile.
 
 ### 4. Run With Docker
 
@@ -313,17 +319,17 @@ The database containers include health checks and will be fully initialized befo
 
 The app is fully cloud-based (`USE_HF_CLOUD=1`): Text-to-SQL runs on HF Inference
 (`Qwen/Qwen2.5-Coder-7B-Instruct`), VQA on Groq (`qwen/qwen3.8-27b`), and the
-built-in `demo_employee` SQLite profile ships with the repo — no external DB
+built-in `demo_employee` SQLite profile ships with the repo — no external DB
 service is needed on Spaces.
 
 > **Note:** HF Spaces moved the **Docker SDK to a paid tier** (free CPU 2026).
-> Deploy there with the free **Gradio SDK** instead — `app.py` at the repo root
+> Deploy there with the free **Gradio SDK** instead — `app.py` at the repo root
 > spawns the same three services the Docker image ran (worker `:8700`,
 > MCP `:8701`, sepia web UI `:7860`) and mounts a minimal Gradio anchor page at
 > `/gradio-lp`. The UI at `/` is unchanged.
 
-1. **Create the Space** — huggingface.co → *New Space* → SDK: **Gradio** →
-   blank template → name it (e.g. `querylens`). Hardware: free CPU basic.
+1. **Create the Space** — huggingface.co → *New Space* → SDK: **Gradio** →
+   blank template → name it (e.g. `querylens`). Hardware: free CPU basic.
 2. **Push the project files** into the Space repo. Easiest on Windows is the
    bundled helper:
    ```powershell
@@ -333,29 +339,29 @@ service is needed on Spaces.
    (respecting the exclusions: no `.env`, no `chat_store/`, no 350 MB
    `dataset_full` dumps, no `__pycache__`), merges the HF frontmatter into the
    Space `README.md` (keeping the generated `sdk_version`), commits and pushes.
-3. **Add Secrets** (Space settings → Variables and Secrets — never commit them):
+3. **Add Secrets** (Space settings → Variables and Secrets — never commit them):
    | Secret | Purpose |
    |---|---|
-   | `HF_API_TOKEN` | HF Inference API — Text-to-SQL (`Qwen/Qwen2.5-Coder-7B-Instruct`) |
+   | `HF_API_TOKEN` | HF Inference API — Text-to-SQL (`Qwen/Qwen2.5-Coder-7B-Instruct`) |
    | `GROQ_API_KEY` | Groq vision VQA (`qwen/qwen3.8-27b`, free tier) |
-   No `DB_CONNECTION_URL` is required — the worker auto-activates the bundled demo.
+   No `DB_CONNECTION_URL` is required — the worker auto-activates the bundled demo.
    Optional: set `DB_CONNECTION_URL` to a hosted Postgres (e.g. Neon) for a real
    external database.
-4. **Open the Space** — the sepia UI loads with the demo profile active.
+4. **Open the Space** — the sepia UI loads with the demo profile active.
    The **Database** panel lets you register additional databases (hosted
    Postgres/MySQL URLs, or uploaded `.sqlite`/`.csv` files) at runtime.
 
 **Local Docker runs still work** for your own machine: `docker build` +
 `docker-compose.yml` are unchanged and `start_hf.sh` serves the identical
-stack — only the Spaces *hosting* path is now the Gradio launcher.
+stack — only the Spaces *hosting* path is now the Gradio launcher.
 
-Note: free Spaces sleep after inactivity (cold start ~1–2 min). Uploaded schema
+Note: free Spaces sleep after inactivity (cold start ~1–2 min). Uploaded schema
 files and chat history are ephemeral unless you enable *Persistent Storage* in
 the Space settings.
 
 ### Historical deployment journey (reference)
 
-This section documents the **complete deployment journey** — from the first proof-of-concept tunnel approach to the final production-ready hybrid architecture. Each phase is explained with commands and rationale so this can serve as a reference for deploying any multi-modal AI application on HuggingFace Spaces.
+This section documents the **complete deployment journey** — from the first proof-of-concept tunnel approach to the final production-ready hybrid architecture. Each phase is explained with commands and rationale so this can serve as a reference for deploying any multi-modal AI application on HuggingFace Spaces.
 
 ---
 
@@ -372,11 +378,11 @@ Before choosing a deployment strategy, it is essential to understand what the fr
 | Public port | 7860 only |
 | Timeout | Space sleeps after inactivity |
 
-The key challenge: **running a local LLM (e.g. `qwen2.5-coder:1.5b`) via Ollama consumes ~1.5–3 GB RAM, leaving limited headroom for vision models and the application stack.** Running a vision-language model such as `qwen3.5:2b` (~3 GB) alongside the text model causes out-of-memory (OOM) failures on the free CPU tier.
+The key challenge: **running a local LLM (e.g. `qwen2.5-coder:1.5b`) via Ollama consumes ~1.5–3 GB RAM, leaving limited headroom for vision models and the application stack.** Running a vision-language model such as `qwen3.5:2b` (~3 GB) alongside the text model causes out-of-memory (OOM) failures on the free CPU tier.
 
 ---
 
-### Phase 1 — Cloudflare Tunnel: Bridging Local Resources to the Cloud
+### Phase 1 — Cloudflare Tunnel: Bridging Local Resources to the Cloud
 
 #### Theory
 
@@ -428,13 +434,13 @@ The application code reads `OLLAMA_BASE_URL` and routes all inference calls thro
 
 ---
 
-### Phase 2 — Self-Contained Docker: Running Ollama Inside the Container
+### Phase 2 — Self-Contained Docker: Running Ollama Inside the Container
 
 #### Theory
 
-The next evolution is to **embed Ollama directly into the Docker image** and pull models at container startup. This makes the deployment fully self-contained — no external machine is needed. The HF Space container becomes a complete inference server.
+The next evolution is to **embed Ollama directly into the Docker image** and pull models at container startup. This makes the deployment fully self-contained — no external machine is needed. The HF Space container becomes a complete inference server.
 
-The challenge is that HF Spaces rebuilds the Docker image on every push but does **not cache downloaded model weights** between restarts (storage is ephemeral). This means every **Factory Reboot** triggers a fresh ~1–3 GB model download, causing a cold-start delay of 2–5 minutes.
+The challenge is that HF Spaces rebuilds the Docker image on every push but does **not cache downloaded model weights** between restarts (storage is ephemeral). This means every **Factory Reboot** triggers a fresh ~1–3 GB model download, causing a cold-start delay of 2–5 minutes.
 
 To prevent HF's health monitor from timing out the Space during this download, model pulling is performed **asynchronously in the background**, allowing the web UI to become responsive immediately while the model fetches in parallel.
 
@@ -491,11 +497,11 @@ The `&` (ampersand) operator sends the model pull to the background. The `exec`
 
 - **Vision model OOM**: Adding `qwen3.5:2b` alongside `qwen2.5-coder:1.5b` exceeds the 16 GB RAM limit when both are loaded simultaneously.
 - Model weights are re-downloaded on every Factory Reboot.
-- Ollama version pinning is critical — newer models require newer Ollama binaries and pulling the wrong combination causes `412` errors.
+- Ollama version pinning is critical — newer models require newer Ollama binaries and pulling the wrong combination causes `412` errors.
 
 ---
 
-### Phase 3 — Hybrid Serverless API (Final Production Architecture)
+### Phase 3 — Hybrid Serverless API (Final Production Architecture)
 
 #### Theory
 
@@ -505,8 +511,8 @@ The final and most robust architecture eliminates the in-container LLM entirely
 |------|----------|-------|------|
 | Text-to-SQL | HuggingFace Inference API | `Qwen/Qwen2.5-Coder-7B-Instruct` | Free tier |
 | Vision Q&A | Groq API | `meta-llama/llama-4-scout-17b-16e-instruct` | Free (14,400 req/day) |
-| OCR | Tesseract (in container) | — | Free |
-| Database | Neon PostgreSQL | — | Free tier |
+| OCR | Tesseract (in container) | — | Free |
+| Database | Neon PostgreSQL | — | Free tier |
 
 This eliminates OOM risk entirely, removes the model download cold-start, and makes the container startup under 30 seconds.
 
@@ -520,7 +526,7 @@ HuggingFace's serverless inference for vision-language models has two limitation
 
 #### Required HuggingFace Space Secrets
 
-Set these in **Space Settings → Variables and Secrets**:
+Set these in **Space Settings → Variables and Secrets**:
 
 ```
 USE_HF_CLOUD       = 1
@@ -538,7 +544,7 @@ DB_CONNECTION_URL  = # Neon PostgreSQL connection string
 **Groq API Key:**
 1. Go to https://console.groq.com
 2. Sign in with Google / GitHub
-3. Navigate to **API Keys** → **Create API Key**
+3. Navigate to **API Keys** → **Create API Key**
 4. Copy the key
 
 **Neon PostgreSQL:**
@@ -600,7 +606,7 @@ pillow>=10.0.0
 
 4. **Factory Reboot** the Space after adding secrets to trigger a clean rebuild with the new environment variables.
 
-5. **Monitor the build logs** — a successful startup shows:
+5. **Monitor the build logs** — a successful startup shows:
    ```
    [GRANITE_VQA] Target Model: meta-llama/llama-4-scout-17b-16e-instruct (via Groq Vision)
    [INFO] CLOUD MODE: Initializing Official HF InferenceClient (Qwen/Qwen2.5-Coder-7B-Instruct)
@@ -627,7 +633,7 @@ git config core.autocrlf input
 
 This project demonstrates that a self-correcting, multi-modal AI pipeline can be built and deployed entirely on consumer hardware through careful architectural decisions: progressive SQL generation with semantic validation, unified MCP-based tool access across data modalities, dynamic VRAM orchestration to prevent memory exhaustion, and a hybrid containerization strategy that preserves native GPU performance while maintaining deployment portability.
 
-The system was developed iteratively, with each architectural decision — from model selection to validation logic to infrastructure design — informed by observed failure modes and measured outcomes rather than theoretical assumptions.
+The system was developed iteratively, with each architectural decision — from model selection to validation logic to infrastructure design — informed by observed failure modes and measured outcomes rather than theoretical assumptions.
 
 ---
-*Built with ❤️ for advanced Agentic Data Engineering.*
+*Built with ❤️ for advanced Agentic Data Engineering.*