Spaces:
Running on Zero
Running on Zero
Download app.py from Varun2007/document-qa-system: direct link, hf CLI and curl.
- Browser
- Download file 19.2 kB
-
https://huggingface.co/spaces/Varun2007/document-qa-system/resolve/main/app.py
- Command line
-
hf download hf://spaces/Varun2007/document-qa-system/app.py
-
curl -L -o app.py https://huggingface.co/spaces/Varun2007/document-qa-system/resolve/main/app.py
19.2 kB
| # IMPORTANT: spaces must be imported at the very top for Hugging Face Spaces / ZeroGPU | |
| try: | |
| import spaces | |
| gpu_decorator = spaces.GPU | |
| except Exception: | |
| def gpu_decorator(fn=None, **kwargs): | |
| if fn is not None: | |
| return fn | |
| def wrapper(f): | |
| return f | |
| return wrapper | |
| """Production Document Question Answering (DQA) - Gradio Web Interface. | |
| Configured for native Hugging Face Spaces deployment (CPU & ZeroGPU). | |
| Features: | |
| - Auto-loads sample documents for instant demonstration. | |
| - Multi-document upload: PDF (layout-aware, OCR fallback), DOCX, TXT. | |
| - Hybrid Retrieval: BAAI/bge-small-en-v1.5 + BM25Okapi + Reciprocal Rank Fusion (RRF). | |
| - Cross-Encoder Reranking: ms-marco-MiniLM-L-6-v2. | |
| - Multi-Backend Generator: | |
| 1. Offline High-Precision Grounding Engine (Default / 0-cost / 100% cited) | |
| 2. Hugging Face Serverless Inference API (Qwen-2.5, Llama-3.2, Mistral) | |
| 3. OpenAI / Groq / DeepSeek APIs | |
| - Strict Grounding with Evidence Quotes & [Page X, Section Y] Citations. | |
| - Second-Pass Verification Audit with Faithfulness Score. | |
| - Real-time token streaming. | |
| """ | |
| import os | |
| import sys | |
| import time | |
| from typing import List, Dict, Any, Generator as TypingGenerator | |
| import gradio as gr | |
| # Local modules | |
| from config import DQAConfig, default_config | |
| from ingest import DocumentIngestionPipeline, DocumentChunk | |
| from retrieve import HybridRetriever, extract_text_from_content | |
| from generate import Generator, OpenAILLMClient, HuggingFaceInferenceClient | |
| from verify import AnswerVerifier | |
| # Global singleton instances | |
| print("Initializing core components...") | |
| pipeline = DocumentIngestionPipeline( | |
| chunk_size=default_config.chunk_size_tokens, | |
| chunk_overlap=default_config.chunk_overlap_tokens, | |
| ocr_fallback=default_config.ocr_fallback_enabled, | |
| ocr_min_chars=default_config.ocr_min_chars_per_page | |
| ) | |
| retriever = HybridRetriever( | |
| embedding_model=default_config.embedding_model_name, | |
| cross_encoder_model=default_config.cross_encoder_model_name, | |
| rrf_k=default_config.rrf_k | |
| ) | |
| verifier = AnswerVerifier( | |
| cross_encoder=retriever.reranker, | |
| threshold=default_config.verification_threshold, | |
| flag_unsupported=default_config.flag_unsupported_claims | |
| ) | |
| generator = Generator(verifier=verifier) | |
| indexed_filenames = [] | |
| def load_initial_samples(): | |
| """Auto-loads sample documents on startup for instant demonstration.""" | |
| global indexed_filenames | |
| sample_files = [ | |
| "data/sample_financial_report.pdf", | |
| "data/sample_cloud_architecture.docx", | |
| "data/sample_security_policy.txt" | |
| ] | |
| parsed_docs = [] | |
| indexed_filenames = [] | |
| for sf in sample_files: | |
| if os.path.exists(sf): | |
| p = pipeline.ingest_file(sf) | |
| parsed_docs.append(p) | |
| indexed_filenames.append(p.file_name) | |
| if parsed_docs: | |
| retriever.index_documents(parsed_docs) | |
| print(f"Auto-loaded {len(parsed_docs)} sample documents ({len(retriever.chunks)} chunks).") | |
| load_initial_samples() | |
| def get_status_markdown() -> str: | |
| """Returns markdown summarizing current indexed documents.""" | |
| total_docs = len(indexed_filenames) | |
| total_chunks = len(retriever.chunks) | |
| doc_list = "<br>".join([f"β’ <code>{f}</code>" for f in indexed_filenames]) if indexed_filenames else "<i>No documents indexed.</i>" | |
| return f"""### π Index Status | |
| - **Documents Indexed:** `{total_docs}` | |
| - **Total Chunks:** `{total_chunks}` | |
| - **Embedding Model:** `{retriever.dense_index.model_name}` | |
| <br> | |
| **Active Files:** | |
| {doc_list} | |
| """ | |
| def process_uploaded_files(files) -> str: | |
| """Processes newly uploaded files and adds them to the index.""" | |
| global indexed_filenames | |
| if not files: | |
| return get_status_markdown() | |
| new_parsed = [] | |
| error_messages = [] | |
| for file_obj in files: | |
| # Robust path and filename extraction across Gradio FileData / wrappers | |
| if hasattr(file_obj, "path"): | |
| file_path = file_obj.path | |
| orig_name = getattr(file_obj, "orig_name", None) or os.path.basename(file_path) | |
| elif hasattr(file_obj, "name"): | |
| file_path = file_obj.name | |
| orig_name = getattr(file_obj, "orig_name", None) or os.path.basename(file_path) | |
| elif isinstance(file_obj, dict): | |
| file_path = file_obj.get("path") or file_obj.get("name") | |
| orig_name = file_obj.get("orig_name") or os.path.basename(file_path) | |
| else: | |
| file_path = str(file_obj) | |
| orig_name = os.path.basename(file_path) | |
| if not file_path or not os.path.exists(file_path): | |
| error_messages.append(f"File not found: {orig_name}") | |
| continue | |
| try: | |
| parsed = pipeline.ingest_file(file_path, original_filename=orig_name) | |
| if parsed.chunks: | |
| new_parsed.append(parsed) | |
| if orig_name not in indexed_filenames: | |
| indexed_filenames.append(orig_name) | |
| else: | |
| error_messages.append(f"No extractable text found in: {orig_name}") | |
| except Exception as e: | |
| error_messages.append(f"Error parsing {orig_name}: {str(e)}") | |
| if new_parsed: | |
| existing = list(retriever.chunks) | |
| combined = existing + [c for p in new_parsed for c in p.chunks] | |
| retriever.index_documents(combined) | |
| status_md = get_status_markdown() | |
| if error_messages: | |
| status_md += "\n\n**β οΈ Upload Warnings:**\n" + "\n".join([f"- {msg}" for msg in error_messages]) | |
| return status_md | |
| def reload_samples_action() -> str: | |
| """Reloads pre-built sample documents.""" | |
| load_initial_samples() | |
| generator.memory.clear() | |
| return get_status_markdown() | |
| def clear_index_action() -> str: | |
| """Clears all documents from the vector store.""" | |
| global indexed_filenames | |
| retriever.index_documents([]) | |
| indexed_filenames = [] | |
| generator.memory.clear() | |
| return get_status_markdown() | |
| # Minimal anchor function to satisfy Hugging Face ZeroGPU startup scanner | |
| def _spaces_startup_anchor(): | |
| return True | |
| def run_neural_pipeline( | |
| message: str, | |
| conv_history: list, | |
| mode: str, | |
| top_k: int, | |
| enable_decomposition: bool, | |
| enable_verification: bool | |
| ): | |
| """ | |
| Executes in-process dense/hybrid search, cross-encoder reranking, and verification | |
| with direct in-memory access to FAISS index and BM25 tables. | |
| """ | |
| ret_res = retriever.retrieve( | |
| query=message, | |
| initial_top_k=20, | |
| rerank_top_k=int(top_k), | |
| mode=mode, | |
| conversation_history=conv_history, | |
| decompose=enable_decomposition | |
| ) | |
| retrieved_chunks = ret_res["chunks"] | |
| rewritten_query = ret_res.get("rewritten_query", message) | |
| raw_answer, verification = generator.generate_answer( | |
| query=rewritten_query, | |
| context_chunks=retrieved_chunks, | |
| verify=enable_verification | |
| ) | |
| return ret_res, raw_answer, verification | |
| def chat_response( | |
| message: str, | |
| history: List[Dict[str, str]], | |
| search_strategy: str, | |
| top_k: int, | |
| enable_verification: bool, | |
| enable_decomposition: bool, | |
| llm_backend: str, | |
| hf_token: str, | |
| hf_model: str, | |
| openai_key: str, | |
| openai_base_url: str | |
| ): | |
| """ | |
| Main conversational QA handler: | |
| 1. Updates LLM backend configuration. | |
| 2. Runs neural retrieval, reranking, and answer generation. | |
| 3. Streams response tokens to the UI. | |
| 4. Displays evidence citations and claim verification audit. | |
| """ | |
| if not message or not message.strip(): | |
| yield history, "No query provided.", "No query provided." | |
| return | |
| # Update generator LLM client according to settings | |
| if llm_backend == "Hugging Face Inference API": | |
| generator.llm_client = HuggingFaceInferenceClient( | |
| model=hf_model or "Qwen/Qwen2.5-7B-Instruct", | |
| token=hf_token or None | |
| ) | |
| elif llm_backend == "OpenAI / Groq API": | |
| if openai_key: | |
| generator.llm_client = OpenAILLMClient( | |
| api_key=openai_key, | |
| base_url=openai_base_url or None | |
| ) | |
| else: | |
| generator.llm_client = None | |
| else: | |
| # High-precision offline grounding engine | |
| generator.llm_client = None | |
| generator.enable_verification = enable_verification | |
| # Map search mode | |
| mode_map = { | |
| "π Hybrid (Dense+BM25) + Cross-Encoder Rerank": "hybrid_rerank", | |
| "β‘ Hybrid Search (No Rerank)": "hybrid_no_rerank", | |
| "π― Dense Vector Only (FAISS)": "dense_only", | |
| "π€ BM25 Lexical Only": "bm25_only" | |
| } | |
| mode = mode_map.get(search_strategy, "hybrid_rerank") | |
| # Format history for conversational memory | |
| conv_history = [] | |
| for turn in history: | |
| if isinstance(turn, dict): | |
| conv_history.append({ | |
| "role": turn.get("role", "user"), | |
| "content": extract_text_from_content(turn.get("content", "")) | |
| }) | |
| elif isinstance(turn, (list, tuple)) and len(turn) == 2: | |
| conv_history.append({"role": "user", "content": extract_text_from_content(turn[0])}) | |
| conv_history.append({"role": "assistant", "content": extract_text_from_content(turn[1])}) | |
| # Execute in-process neural retrieval + rerank + generation | |
| try: | |
| ret_res, raw_answer, verification = run_neural_pipeline( | |
| message=message, | |
| conv_history=conv_history, | |
| mode=mode, | |
| top_k=int(top_k), | |
| enable_decomposition=enable_decomposition, | |
| enable_verification=enable_verification | |
| ) | |
| except Exception as e: | |
| import traceback | |
| err_msg = f"β οΈ Pipeline error: {str(e)}" | |
| print(f"Error in run_neural_pipeline: {traceback.format_exc()}") | |
| updated_history = list(history) + [ | |
| {"role": "user", "content": message}, | |
| {"role": "assistant", "content": err_msg} | |
| ] | |
| yield updated_history, "No citations available due to an internal error.", "Verification aborted." | |
| return | |
| retrieved_chunks = ret_res["chunks"] | |
| scores = ret_res["scores"] | |
| # Format source citations markdown | |
| citations_md = "### π Retrieved Evidence Passages & Citations\n\n" | |
| if not retrieved_chunks: | |
| citations_md += "*No relevant passages retrieved for this query.*\n" | |
| else: | |
| for idx, (c, s) in enumerate(zip(retrieved_chunks, scores), 1): | |
| citations_md += ( | |
| f"**Citation {idx}:** `{c.file_name}` | **Page {c.page_number}**, Section *\"{c.section_title}\"* " | |
| f"(Score: `{s:.3f}`, Table: `{c.metadata.get('is_table', False)}`)\n\n" | |
| f"> \"{c.text}\"\n\n---\n" | |
| ) | |
| # Initialize assistant turn in history | |
| updated_history = list(history) + [ | |
| {"role": "user", "content": message}, | |
| {"role": "assistant", "content": ""} | |
| ] | |
| # Stream output word by word for interactive response | |
| words = raw_answer.split(" ") | |
| streamed_text = "" | |
| for i, w in enumerate(words): | |
| streamed_text += w + (" " if i < len(words) - 1 else "") | |
| updated_history[-1]["content"] = streamed_text | |
| if i % 2 == 0 or i == len(words) - 1: | |
| time.sleep(0.015) | |
| yield updated_history, citations_md, "β³ Verifying claims..." | |
| # Format verification audit markdown | |
| if verification and "not found in the document" not in raw_answer.lower(): | |
| status_badge = "β High Faithfulness" if verification.faithfulness_score >= 0.8 else "β οΈ Potential Hallucination" | |
| ver_md = f"### π‘οΈ Claim-Level Verification Audit\n\n" | |
| ver_md += f"**Overall Status:** {status_badge} (`{int(verification.faithfulness_score * 100)}%` Faithfulness)\n\n" | |
| ver_md += f"- **Total Claims Analyzed:** `{verification.total_claims}`\n" | |
| ver_md += f"- **Supported Claims:** `{len(verification.supported_claims)}`\n" | |
| for sc in verification.supported_claims: | |
| ver_md += f" - β {sc}\n" | |
| if verification.unsupported_claims: | |
| ver_md += f"\n- **β οΈ Flagged / Unsupported Claims:** `{len(verification.unsupported_claims)}`\n" | |
| for uc in verification.unsupported_claims: | |
| ver_md += f" - β οΈ {uc}\n" | |
| else: | |
| ver_md = "### π‘οΈ Claim-Level Verification Audit\n\n*Response is ungrounded negative control or refusal ('Not found in the document.'). Zero hallucination detected.*" | |
| yield updated_history, citations_md, ver_md | |
| # ---------------- GRADIO UI LAYOUT ---------------- | |
| with gr.Blocks(title="Document QA System") as demo: | |
| gr.Markdown(""" | |
| # π Production Document Question Answering (DQA) | |
| **Layout-aware Ingestion β’ Hybrid Dense & BM25 Search β’ Cross-Encoder Reranking β’ Strict Evidence Citations β’ Second-Pass Verification** | |
| """) | |
| with gr.Row(): | |
| # LEFT COLUMN: Ingestion & Configuration | |
| with gr.Column(scale=4): | |
| status_box = gr.Markdown(value=get_status_markdown()) | |
| with gr.Accordion("π Upload & Manage Documents", open=True): | |
| file_input = gr.File( | |
| label="Upload PDF, DOCX, or TXT", | |
| file_count="multiple", | |
| file_types=[".pdf", ".docx", ".txt", ".md"] | |
| ) | |
| with gr.Row(): | |
| upload_btn = gr.Button("π Process Files", variant="primary") | |
| reload_btn = gr.Button("π Reload Samples") | |
| clear_btn = gr.Button("π Clear All") | |
| with gr.Accordion("βοΈ Search & Reranking Settings", open=True): | |
| search_mode = gr.Dropdown( | |
| label="Retrieval Strategy", | |
| choices=[ | |
| "π Hybrid (Dense+BM25) + Cross-Encoder Rerank", | |
| "β‘ Hybrid Search (No Rerank)", | |
| "π― Dense Vector Only (FAISS)", | |
| "π€ BM25 Lexical Only" | |
| ], | |
| value="π Hybrid (Dense+BM25) + Cross-Encoder Rerank" | |
| ) | |
| top_k_slider = gr.Slider( | |
| minimum=1, maximum=10, value=5, step=1, | |
| label="Top-K Chunks for Generation" | |
| ) | |
| verify_chk = gr.Checkbox( | |
| value=True, | |
| label="Enable Claim-Level Verification" | |
| ) | |
| decomp_chk = gr.Checkbox( | |
| value=True, | |
| label="Decompose Complex / Comparative Questions" | |
| ) | |
| with gr.Accordion("π€ Generation Engine", open=False): | |
| backend_select = gr.Radio( | |
| label="LLM Backend", | |
| choices=[ | |
| "Offline High-Precision Grounding Engine", | |
| "Hugging Face Inference API", | |
| "OpenAI / Groq API" | |
| ], | |
| value="Offline High-Precision Grounding Engine" | |
| ) | |
| hf_token_box = gr.Textbox( | |
| label="Hugging Face Token (Optional)", | |
| type="password", | |
| value=os.getenv("HF_TOKEN", "") | |
| ) | |
| hf_model_box = gr.Dropdown( | |
| label="Hugging Face Model", | |
| choices=[ | |
| "Qwen/Qwen2.5-7B-Instruct", | |
| "meta-llama/Llama-3.2-3B-Instruct", | |
| "mistralai/Mistral-7B-Instruct-v0.3" | |
| ], | |
| value="Qwen/Qwen2.5-7B-Instruct" | |
| ) | |
| openai_key_box = gr.Textbox( | |
| label="OpenAI / Groq API Key (Optional)", | |
| type="password", | |
| value=os.getenv("OPENAI_API_KEY", "") | |
| ) | |
| openai_url_box = gr.Textbox( | |
| label="Base URL (Optional, for Groq/Ollama)", | |
| value=os.getenv("OPENAI_BASE_URL", "") | |
| ) | |
| # RIGHT COLUMN: Chat & Audit Inspection | |
| with gr.Column(scale=8): | |
| chatbot = gr.Chatbot( | |
| label="Conversation & Grounded Answers", | |
| height=460 | |
| ) | |
| with gr.Row(): | |
| msg_input = gr.Textbox( | |
| label="Question", | |
| placeholder="Ask a question strictly grounded in the loaded documents...", | |
| scale=9, | |
| lines=1 | |
| ) | |
| submit_btn = gr.Button("Ask π¬", variant="primary", scale=2) | |
| # Quick clickable example prompts | |
| gr.Markdown("**π‘ Quick Examples:**") | |
| with gr.Row(): | |
| ex1 = gr.Button("π Q3 Revenue & Margin", size="sm") | |
| ex2 = gr.Button("β‘ Latency & SLA Targets", size="sm") | |
| ex3 = gr.Button("π MFA & TLS Standards", size="sm") | |
| ex4 = gr.Button("π« Oracle Cloud (Negative)", size="sm") | |
| clear_chat_btn = gr.Button("π§Ή Clear Conversation", size="sm") | |
| with gr.Accordion("π Source Citations & Evidence Quotes", open=True): | |
| citations_display = gr.Markdown( | |
| value="*Ask a question to inspect retrieved citations, page numbers, and similarity scores.*" | |
| ) | |
| with gr.Accordion("π‘οΈ Second-Pass Verification Audit", open=True): | |
| verification_display = gr.Markdown( | |
| value="*Verification audit will show supported vs flagged claims.*" | |
| ) | |
| # Event Handlers | |
| upload_btn.click( | |
| process_uploaded_files, | |
| inputs=[file_input], | |
| outputs=[status_box] | |
| ) | |
| reload_btn.click( | |
| reload_samples_action, | |
| inputs=[], | |
| outputs=[status_box] | |
| ) | |
| clear_btn.click( | |
| clear_index_action, | |
| inputs=[], | |
| outputs=[status_box] | |
| ) | |
| # Chat execution | |
| chat_inputs = [ | |
| msg_input, | |
| chatbot, | |
| search_mode, | |
| top_k_slider, | |
| verify_chk, | |
| decomp_chk, | |
| backend_select, | |
| hf_token_box, | |
| hf_model_box, | |
| openai_key_box, | |
| openai_url_box | |
| ] | |
| chat_outputs = [chatbot, citations_display, verification_display] | |
| submit_btn.click( | |
| chat_response, | |
| inputs=chat_inputs, | |
| outputs=chat_outputs | |
| ).then(lambda: "", None, msg_input) | |
| msg_input.submit( | |
| chat_response, | |
| inputs=chat_inputs, | |
| outputs=chat_outputs | |
| ).then(lambda: "", None, msg_input) | |
| # Example buttons | |
| ex1.click(lambda: "What was the total revenue and net profit margin in Q3?", None, msg_input) | |
| ex2.click(lambda: "What are the target p99 latency and platform availability SLOs?", None, msg_input) | |
| ex3.click(lambda: "What hardware MFA and encryption standards are required?", None, msg_input) | |
| ex4.click(lambda: "Does the system run on Oracle Cloud Infrastructure in Frankfurt?", None, msg_input) | |
| clear_chat_btn.click(lambda: [], None, chatbot) | |
| if __name__ == "__main__": | |
| demo.queue() | |
| demo.launch(server_name="0.0.0.0", server_port=7860) | |