Spaces:
Running on Zero
Running on Zero
Download generate.py from Varun2007/document-qa-system: direct link, hf CLI and curl.
- Browser
- Download file 17.5 kB
-
https://huggingface.co/spaces/Varun2007/document-qa-system/resolve/main/generate.py
- Command line
-
hf download hf://spaces/Varun2007/document-qa-system/generate.py
-
curl -L -o generate.py https://huggingface.co/spaces/Varun2007/document-qa-system/resolve/main/generate.py
17.5 kB
| """Generation and Response Module for Document Question Answering. | |
| Features: | |
| - Strict evidence grounding (answers ONLY from retrieved chunks) | |
| - Quotes evidence and cites exact [Page X, Section "Y"] | |
| - If answer is not in context, outputs "Not found in the document." | |
| - Streaming support for responsive chat interfaces | |
| - Conversation memory tracking | |
| - Integrated second-pass verification | |
| - Multi-backend LLM support: | |
| 1. Hugging Face Serverless Inference API (Qwen/Qwen2.5-7B, Llama-3.2, Mistral) | |
| 2. OpenAI / OpenAI-compatible APIs (OpenAI, Groq, Ollama, DeepSeek) | |
| 3. Offline Deterministic Grounding Engine (0 external calls, 100% cited) | |
| """ | |
| import json | |
| import os | |
| import re | |
| import time | |
| from dataclasses import dataclass, field | |
| from typing import List, Dict, Any, Optional, Iterator, Tuple | |
| from ingest import DocumentChunk | |
| from verify import AnswerVerifier, VerificationResult | |
| SYSTEM_PROMPT = """You are a production-grade Document Question Answering Assistant. | |
| CRITICAL INSTRUCTIONS: | |
| 1. Answer the user's question ONLY using the factual information in the PROVIDED CONTEXT below. | |
| 2. Do NOT extrapolate, assume, or use any prior or external knowledge outside the provided context. | |
| 3. If the answer cannot be fully determined from the provided context, respond with EXACTLY: | |
| "Not found in the document." | |
| 4. Always quote direct evidence or key statistics from the context when formulating your answer. | |
| 5. For EVERY factual statement you make, append an exact citation in the format: | |
| [Page <page_number>, Section "<section_title>"] | |
| 6. Maintain a professional, concise, and structured tone. | |
| """ | |
| def format_context_for_prompt(chunks: List[DocumentChunk]) -> str: | |
| """Formats retrieved chunks with provenance metadata into an LLM prompt block.""" | |
| if not chunks: | |
| return "No relevant context retrieved." | |
| blocks = [] | |
| for idx, chunk in enumerate(chunks, 1): | |
| block = ( | |
| f"--- Context Chunk {idx} ---\n" | |
| f"Document: {chunk.file_name}\n" | |
| f"Page: {chunk.page_number}\n" | |
| f"Section: {chunk.section_title}\n" | |
| f"Text:\n{chunk.text.strip()}\n" | |
| ) | |
| blocks.append(block) | |
| return "\n".join(blocks) | |
| def normalize_word(w: str) -> str: | |
| """Lightweight rule-based stemmer to match plurals, past tense, and suffixes.""" | |
| w = w.lower().strip() | |
| if len(w) > 4: | |
| if w.endswith("ies"): | |
| return w[:-3] + "y" | |
| if w.endswith("es"): | |
| return w[:-2] | |
| if w.endswith("s") and not w.endswith("ss"): | |
| return w[:-1] | |
| if w.endswith("ing"): | |
| return w[:-3] | |
| if w.endswith("ed"): | |
| return w[:-2] | |
| return w | |
| class OfflineGroundingLLM: | |
| """ | |
| Offline deterministic grounding engine. | |
| Ensures the QA pipeline runs out of the box with zero external API dependencies, | |
| enforcing 100% strict adherence to context and citations. | |
| """ | |
| def generate(self, prompt: str, context_chunks: List[DocumentChunk]) -> str: | |
| if not context_chunks: | |
| return "Not found in the document." | |
| # Extract user query from prompt | |
| match = re.search(r"User Question:\s*(.+?)(?:\n|$)", prompt) | |
| query = match.group(1).strip() if match else prompt.strip() | |
| query_words = set(re.findall(r"\b[a-zA-Z0-9_]{3,}\b", query.lower())) | |
| # Remove common question words and prepositions | |
| stop_words = { | |
| "what", "when", "where", "which", "who", "whom", "whose", "why", "how", | |
| "is", "are", "was", "were", "be", "been", "being", "have", "has", "had", | |
| "do", "does", "did", "the", "a", "an", "and", "or", "in", "on", "at", | |
| "to", "for", "of", "with", "by", "from", "can", "could", "should", "would", | |
| "please", "about", "tell", "explain", "describe", "find", "show", "many", "much" | |
| } | |
| query_keywords = query_words - stop_words | |
| if not query_keywords: | |
| return "Not found in the document." | |
| query_stems = {normalize_word(w) for w in query_keywords} | |
| # Document filename generic words (e.g. "Hyperledger", "Notes", "report", "cloud") | |
| doc_generic_terms = set() | |
| for c in context_chunks: | |
| base = os.path.splitext(c.file_name)[0] | |
| for w in re.findall(r"\b[a-zA-Z]{3,}\b", base.lower()): | |
| doc_generic_terms.add(normalize_word(w)) | |
| core_stems = query_stems - doc_generic_terms | |
| if not core_stems: | |
| core_stems = set(query_stems) | |
| # Helper to detect textbook definitional statements for specific core concepts | |
| def is_definitional_sentence(sentence: str) -> bool: | |
| s_lower = sentence.lower().strip() | |
| target_keywords = (query_keywords - doc_generic_terms) if len(query_keywords) >= 2 else query_keywords | |
| for kw in target_keywords: | |
| kw_clean = kw.lower().rstrip("s") | |
| pattern = rf"\b{kw_clean}s?\s+(?:is|are|refers to|means|defines)\b" | |
| if re.search(pattern, s_lower): | |
| return True | |
| return False | |
| # Scan chunks for matching information | |
| matching_sentences: List[Tuple[str, DocumentChunk, float]] = [] | |
| for chunk_idx, chunk in enumerate(context_chunks): | |
| rank_multiplier = 1.0 / (1.0 + chunk_idx * 0.15) | |
| # Check for table chunk | |
| if chunk.metadata.get("is_table", False): | |
| lines = chunk.text.splitlines() | |
| for line in lines: | |
| line_words = set(re.findall(r"\b[a-zA-Z0-9_]{3,}\b", line.lower())) | |
| line_stems = {normalize_word(w) for w in line_words} | |
| overlap = len(query_stems & line_stems) | |
| exact_overlap = len(query_keywords & line_words) | |
| core_overlap = len(core_stems & line_stems) | |
| if len(core_stems) > 0 and core_overlap == 0 and len(query_keywords) >= 2: | |
| continue | |
| if overlap >= 1: | |
| score = ((overlap ** 2) * 3.0 + (core_overlap ** 2) * 5.0 + exact_overlap * 2.0) * rank_multiplier | |
| matching_sentences.append((line.strip(), chunk, score)) | |
| continue | |
| # Split on sentence enders AND newlines (handling notes, bullet points, slides) | |
| sentences = re.split(r"(?<=[.!?])\s+|\n+", chunk.text) | |
| for s in sentences: | |
| s_clean = re.sub(r"^[\s*\-•#\d+.)]+", "", s).strip() | |
| if len(s_clean.split()) < 3: | |
| continue | |
| # Filter out running page headers / course boilerplate | |
| if re.search(r"\b(B\.Tech|ICFAI|Tech School|Lecture Notes|All rights reserved)\b", s_clean, re.IGNORECASE): | |
| continue | |
| s_words = set(re.findall(r"\b[a-zA-Z0-9_]{3,}\b", s_clean.lower())) | |
| s_stems = {normalize_word(w) for w in s_words} | |
| overlap = len(query_stems & s_stems) | |
| exact_overlap = len(query_keywords & s_words) | |
| core_overlap = len(core_stems & s_stems) | |
| # Disqualify sentences that match ZERO specific core keywords when specific keywords exist | |
| if len(core_stems) > 0 and core_overlap == 0 and len(query_keywords) >= 2: | |
| continue | |
| if overlap >= 1: | |
| score = ((overlap ** 2) * 4.0 + (core_overlap ** 2) * 6.0 + exact_overlap * 2.0) * rank_multiplier | |
| # Definitional boost for core query concepts | |
| if is_definitional_sentence(s_clean): | |
| score += 20.0 | |
| matching_sentences.append((s_clean, chunk, score)) | |
| if not matching_sentences: | |
| return "Not found in the document." | |
| # Sort sentences by match score descending | |
| matching_sentences.sort(key=lambda x: x[2], reverse=True) | |
| # Deduplicate sentences while preserving citation | |
| seen = set() | |
| answer_parts = [] | |
| for s_text, chunk, _ in matching_sentences: | |
| cleaned_key = re.sub(r"[^a-z0-9]", "", s_text.lower()) | |
| if cleaned_key in seen: | |
| continue | |
| seen.add(cleaned_key) | |
| citation = f'[Page {chunk.page_number}, Section "{chunk.section_title}"]' | |
| answer_parts.append(f"{s_text} {citation}") | |
| if len(answer_parts) >= 3: | |
| break | |
| if not answer_parts: | |
| return "Not found in the document." | |
| return " ".join(answer_parts) | |
| class HuggingFaceInferenceClient: | |
| """Client for Hugging Face Serverless Inference API.""" | |
| def __init__( | |
| self, | |
| model: str = "Qwen/Qwen2.5-7B-Instruct", | |
| token: Optional[str] = None, | |
| temperature: float = 0.01, | |
| max_tokens: int = 1024 | |
| ): | |
| self.model = model | |
| self.token = token or os.getenv("HF_TOKEN") or os.getenv("HUGGINGFACEHUB_API_TOKEN") | |
| self.temperature = max(0.01, temperature) | |
| self.max_tokens = max_tokens | |
| self._client = None | |
| try: | |
| from huggingface_hub import InferenceClient | |
| self._client = InferenceClient(model=self.model, token=self.token) | |
| except Exception: | |
| self._client = None | |
| def is_configured(self) -> bool: | |
| return self._client is not None | |
| def stream_chat(self, messages: List[Dict[str, str]]) -> Iterator[str]: | |
| if not self._client: | |
| raise RuntimeError("Hugging Face client is not configured.") | |
| response = self._client.chat_completion( | |
| messages=messages, | |
| temperature=self.temperature, | |
| max_tokens=self.max_tokens, | |
| stream=True | |
| ) | |
| for chunk in response: | |
| content = chunk.choices[0].delta.content or "" | |
| if content: | |
| yield content | |
| def complete_chat(self, messages: List[Dict[str, str]]) -> str: | |
| if not self._client: | |
| raise RuntimeError("Hugging Face client is not configured.") | |
| response = self._client.chat_completion( | |
| messages=messages, | |
| temperature=self.temperature, | |
| max_tokens=self.max_tokens, | |
| stream=False | |
| ) | |
| return response.choices[0].message.content or "" | |
| class OpenAILLMClient: | |
| """Wrapper for OpenAI or OpenAI-compatible APIs (Groq, Ollama, DeepSeek, vLLM).""" | |
| def __init__( | |
| self, | |
| api_key: Optional[str] = None, | |
| base_url: Optional[str] = None, | |
| model: str = "gpt-4o-mini", | |
| temperature: float = 0.0, | |
| max_tokens: int = 1024 | |
| ): | |
| self.api_key = api_key or os.getenv("OPENAI_API_KEY") | |
| self.base_url = base_url or os.getenv("OPENAI_BASE_URL") | |
| self.model = model | |
| self.temperature = temperature | |
| self.max_tokens = max_tokens | |
| self._client = None | |
| if self.api_key: | |
| try: | |
| import openai | |
| self._client = openai.OpenAI( | |
| api_key=self.api_key, | |
| base_url=self.base_url | |
| ) | |
| except Exception: | |
| self._client = None | |
| def is_configured(self) -> bool: | |
| return self._client is not None | |
| def stream_chat(self, messages: List[Dict[str, str]]) -> Iterator[str]: | |
| if not self._client: | |
| raise RuntimeError("OpenAI client is not configured.") | |
| response = self._client.chat.completions.create( | |
| model=self.model, | |
| messages=messages, | |
| temperature=self.temperature, | |
| max_tokens=self.max_tokens, | |
| stream=True | |
| ) | |
| for chunk in response: | |
| content = chunk.choices[0].delta.content or "" | |
| if content: | |
| yield content | |
| def complete_chat(self, messages: List[Dict[str, str]]) -> str: | |
| if not self._client: | |
| raise RuntimeError("OpenAI client is not configured.") | |
| response = self._client.chat.completions.create( | |
| model=self.model, | |
| messages=messages, | |
| temperature=self.temperature, | |
| max_tokens=self.max_tokens, | |
| stream=False | |
| ) | |
| return response.choices[0].message.content or "" | |
| class ConversationMemory: | |
| """Manages chat history and tracks citations per conversation turn.""" | |
| def __init__(self, max_turns: int = 10): | |
| self.max_turns = max_turns | |
| self.history: List[Dict[str, Any]] = [] | |
| def add_user_message(self, message: str) -> None: | |
| self.history.append({"role": "user", "content": message.strip()}) | |
| self._trim() | |
| def add_assistant_message( | |
| self, | |
| message: str, | |
| citations: Optional[List[Dict[str, Any]]] = None, | |
| verification: Optional[VerificationResult] = None | |
| ) -> None: | |
| turn = { | |
| "role": "assistant", | |
| "content": message.strip(), | |
| "citations": citations or [], | |
| "verification": verification.to_dict() if verification else None, | |
| } | |
| self.history.append(turn) | |
| self._trim() | |
| def get_messages_for_prompt(self) -> List[Dict[str, str]]: | |
| """Returns message list formatted for chat completions.""" | |
| return [{"role": m["role"], "content": m["content"]} for m in self.history] | |
| def _trim(self) -> None: | |
| if len(self.history) > self.max_turns * 2: | |
| self.history = self.history[- (self.max_turns * 2):] | |
| def clear(self) -> None: | |
| self.history.clear() | |
| class Generator: | |
| """ | |
| Main Document QA Generator with verification and streaming support. | |
| """ | |
| def __init__( | |
| self, | |
| llm_client: Optional[Any] = None, | |
| verifier: Optional[AnswerVerifier] = None, | |
| enable_verification: bool = True | |
| ): | |
| # Auto-select client if none provided | |
| if llm_client is None: | |
| if os.getenv("HF_TOKEN") or os.getenv("HUGGINGFACEHUB_API_TOKEN"): | |
| self.llm_client = HuggingFaceInferenceClient() | |
| elif os.getenv("OPENAI_API_KEY"): | |
| self.llm_client = OpenAILLMClient() | |
| else: | |
| self.llm_client = None | |
| else: | |
| self.llm_client = llm_client | |
| self.offline_engine = OfflineGroundingLLM() | |
| self.verifier = verifier or AnswerVerifier() | |
| self.enable_verification = enable_verification | |
| self.memory = ConversationMemory() | |
| def build_prompt_messages(self, query: str, context_chunks: List[DocumentChunk]) -> List[Dict[str, str]]: | |
| """Constructs system and user messages incorporating retrieved context.""" | |
| context_str = format_context_for_prompt(context_chunks) | |
| user_content = ( | |
| f"PROVIDED CONTEXT:\n{context_str}\n\n" | |
| f"User Question: {query}\n\n" | |
| "Answer using ONLY the provided context above. Quote direct evidence and cite [Page X, Section Y] for every statement." | |
| ) | |
| messages = [{"role": "system", "content": SYSTEM_PROMPT}] | |
| for turn in self.memory.history[-4:]: | |
| messages.append({"role": turn["role"], "content": turn["content"]}) | |
| messages.append({"role": "user", "content": user_content}) | |
| return messages | |
| def generate_answer( | |
| self, | |
| query: str, | |
| context_chunks: List[DocumentChunk], | |
| verify: bool = True | |
| ) -> Tuple[str, Optional[VerificationResult]]: | |
| """Synchronously generates a verified, grounded answer.""" | |
| messages = self.build_prompt_messages(query, context_chunks) | |
| # 1. Attempt LLM generation | |
| answer = "" | |
| if self.llm_client is not None and hasattr(self.llm_client, "is_configured") and self.llm_client.is_configured(): | |
| try: | |
| answer = self.llm_client.complete_chat(messages) | |
| except Exception: | |
| answer = "" | |
| # 2. Fallback to offline deterministic grounding engine | |
| if not answer: | |
| answer = self.offline_engine.generate( | |
| prompt=f"User Question: {query}", | |
| context_chunks=context_chunks | |
| ) | |
| # 3. Second-pass Verification | |
| verification = None | |
| if verify and self.enable_verification: | |
| verification = self.verifier.verify_answer(answer, context_chunks) | |
| answer = verification.verified_answer | |
| return answer, verification | |
| def stream_answer( | |
| self, | |
| query: str, | |
| context_chunks: List[DocumentChunk], | |
| chunk_delay_sec: float = 0.02 | |
| ) -> Iterator[str]: | |
| """Streams answer token by token for UI interactions.""" | |
| messages = self.build_prompt_messages(query, context_chunks) | |
| # If LLM configured, stream from client | |
| if self.llm_client is not None and hasattr(self.llm_client, "is_configured") and self.llm_client.is_configured(): | |
| try: | |
| for token in self.llm_client.stream_chat(messages): | |
| yield token | |
| return | |
| except Exception: | |
| pass | |
| # Offline streaming emulation | |
| answer = self.offline_engine.generate( | |
| prompt=f"User Question: {query}", | |
| context_chunks=context_chunks | |
| ) | |
| words = answer.split(" ") | |
| for i, word in enumerate(words): | |
| yield word + (" " if i < len(words) - 1 else "") | |
| time.sleep(chunk_delay_sec) | |