Initial commit: AI Legal Compliance Auditor

Gradio-based compliance auditing app with agentic LangChain pipeline,
configured for Hugging Face Spaces deployment.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

.gitignore

@@ -0,0 +1,24 @@
+# Environment variables
+.env
+
+# Vector database
+chroma_db/
+reference_docs/
+*.db
+*.sqlite
+
+# Personal notes
+INTERVIEW_SCRIPT.md
+
+# Python
+__pycache__/
+
+
+# Virtual environments
+venv/
+env/
+ENV/
+
+# Cache
+.cache/
+*.cache

AGENTIC_SYSTEM_README.md

@@ -0,0 +1,178 @@
+# Agentic AI System - Implementation Guide
+
+## Overview
+
+This project has been upgraded to include **true Agentic AI capabilities** with multi-step reasoning, tool calling, and autonomous decision-making.
+
+## What's New: Agentic Features
+
+### 🤖 Multi-Agent Architecture
+
+1. **Planning Agent**: Breaks down the audit into steps
+2. **Execution Agent**: Performs the audit using tools
+3. **Refinement Agent**: Reviews and improves results
+
+### 🛠️ Available Tools
+
+The agent can autonomously call these tools:
+
+1. **`search_regulations`**: Search through regulation documents for specific requirements
+2. **`analyze_document_structure`**: Analyze document tone, terminology, and formatting
+3. **`check_missing_fields`**: Check for required fields (Date, CIN, Signature, etc.)
+4. **`compare_with_regulation`**: Compare document clauses against regulations
+5. **`generate_style_adapted_clause`**: Generate clauses that match document style
+6. **`calculate_compliance_score`**: Calculate compliance risk score
+
+### 🔄 Agentic Workflow
+
+```
+User Document
+    ↓
+[PLANNING AGENT] → Creates audit plan
+    ↓
+[EXECUTION AGENT] → Uses tools to:
+    - Search regulations
+    - Check compliance
+    - Analyze style
+    - Find issues
+    ↓
+[REFINEMENT AGENT] → Reviews and improves:
+    - Validates findings
+    - Generates style-adapted fixes
+    - Calculates final score
+    ↓
+Final Audit Report
+```
+
+## Installation
+
+1. **Install new dependencies**:
+```bash
+pip install -r requirements.txt
+```
+
+This will install:
+- `langchain` - Agent framework
+- `langchain-google-genai` - Gemini integration
+- `langchain-core` - Core LangChain components
+- `langchain-community` - Community tools
+
+## Configuration
+
+### Enable/Disable Agentic Mode
+
+In your `.env` file:
+
+```env
+GEMINI_API_KEY=your_key_here
+GEMINI_MODEL=models/gemini-2.5-pro
+USE_AGENTIC=true  # Set to false to use standard mode
+```
+
+## Usage
+
+### Command Line
+
+```bash
+python main.py
+```
+
+The system will automatically use agentic mode if enabled.
+
+### Gradio Web UI
+
+```bash
+python gradio_app.py
+```
+
+Same agentic capabilities available in the web interface.
+
+## How It Works
+
+### Standard Mode (Non-Agentic)
+- Single LLM call
+- All instructions in one prompt
+- No tool calling
+- No multi-step reasoning
+
+### Agentic Mode (New!)
+- **Planning Phase**: Agent creates a step-by-step audit plan
+- **Execution Phase**: Agent autonomously:
+  - Decides which tools to use
+  - Calls tools as needed
+  - Iterates through findings
+- **Refinement Phase**: Agent reviews and improves results
+
+## Example Agent Behavior
+
+When you run an audit, the agent will:
+
+1. **Plan**: "I need to check for missing fields, search regulations for data protection requirements, and compare clauses."
+
+2. **Execute**:
+   - Calls `check_missing_fields` → Finds missing "Date" field
+   - Calls `search_regulations` with query "data protection" → Finds relevant regulations
+   - Calls `compare_with_regulation` → Identifies non-compliant clause
+   - Calls `analyze_document_structure` → Detects "Corporate Professional" tone
+
+3. **Refine**:
+   - Calls `generate_style_adapted_clause` → Creates style-matched fix
+   - Calls `calculate_compliance_score` → Computes final score
+   - Validates all findings
+
+## Key Differences
+
+| Feature | Standard Mode | Agentic Mode |
+|---------|--------------|--------------|
+| **Tool Calling** |  No |  Yes |
+| **Multi-Step** |  Single prompt |  Planning → Execution → Refinement |
+| **Autonomous Decisions** |  No |  Agent decides which tools to use |
+| **Iteration** |  One-shot |  Can refine and improve |
+| **Error Recovery** |  Basic |  Advanced with agent reasoning |
+
+## Troubleshooting
+
+### Agentic System Not Working?
+
+1. **Check dependencies**:
+   ```bash
+   pip install langchain langchain-google-genai langchain-core langchain-community
+   ```
+
+2. **Check API key**: Make sure `GEMINI_API_KEY` is set in `.env`
+
+3. **Fallback**: System automatically falls back to standard mode if agentic fails
+
+4. **Disable agentic**: Set `USE_AGENTIC=false` in `.env` to use standard mode
+
+### Model Compatibility
+
+- Works best with: `models/gemini-2.5-pro` or `models/gemini-2.5-flash-lite`
+- Function calling requires models that support tool use
+- Standard mode works with any Gemini model
+
+## Architecture
+
+```
+agentic_tools.py      → Tool definitions (search, analyze, check, etc.)
+agentic_auditor.py    → Multi-agent system (planning, execution, refinement)
+auditor.py            → Main interface (supports both modes)
+main.py               → CLI entry point
+gradio_app.py         → Web UI entry point
+```
+
+## Future Enhancements
+
+Potential improvements:
+- [ ] Add more tools (web search, legal database APIs)
+- [ ] Multi-agent collaboration (specialist agents)
+- [ ] Long-term memory for audit history
+- [ ] Self-correction loops
+- [ ] External API integrations
+
+## Questions?
+
+The agentic system is designed to be transparent. You'll see:
+- ` [AGENT]` messages showing agent activity
+- Tool calls in verbose mode
+- Step-by-step progress indicators

README.md

@@ -0,0 +1,106 @@
+---
+title: AI Legal Compliance Auditor
+emoji: ⚖️
+colorFrom: blue
+colorTo: indigo
+sdk: gradio
+app_file: gradio_app.py
+pinned: false
+---
+
+# AI Legal Compliance Auditor
+
+An intelligent AI-powered system that audits legal documents for regulatory compliance and generates style-adapted corrections. Built for MSMEs (Micro, Small, and Medium Enterprises) to ensure their business documents meet legal requirements.
+
+## 🚀 Features
+
+- **Agentic AI System**: Multi-agent architecture with autonomous tool calling (planning, execution, refinement)
+- **Smart Document Analysis**: Analyzes document structure, tone, terminology, and formatting style
+- **Compliance Scoring**: Calculates compliance risk scores (0-100) based on identified issues
+- **Style-Aware Redrafting**: Generates corrections that match your document's original tone and style
+- **Multi-Format Support**: Works with PDF, DOCX, and TXT files
+- **Semantic Search**: Uses vector embeddings to find relevant regulations intelligently
+- **Dual Interface**: Both CLI and interactive Gradio web UI
+- **Custom Regulations**: Inject your own regulations or policy documents for analysis
+
+## 📋 Requirements
+
+- Python 3.8+
+- Google Gemini API Key
+- Dependencies: See `requirements.txt`
+
+## 🔧 Installation
+
+```bash
+# Clone the repository
+git clone <repo-url>
+cd Auditor_Compliance_Final
+
+# Install dependencies
+pip install -r requirements.txt
+
+# Create .env file
+echo "GEMINI_API_KEY=your_api_key_here" > .env
+echo "GEMINI_MODEL=models/gemini-2.5-pro" >> .env
+echo "USE_AGENTIC=true" >> .env
+```
+
+## 💻 Usage
+
+### CLI Mode
+```bash
+python main.py
+```
+
+### Web UI
+```bash
+python gradio_app.py
+```
+
+Then open your browser to the displayed URL.
+
+## How It Works
+
+1. **Planning Phase**: Agent creates an audit strategy
+2. **Execution Phase**: Agent autonomously uses tools to:
+   - Search regulations
+   - Check missing fields
+   - Analyze document structure
+   - Compare clauses against regulations
+3. **Refinement Phase**: Validates findings and generates compliant redrafts
+
+##  Output
+
+The audit returns:
+- **Compliance Score**: 0-100 risk assessment
+- **Findings**: Identified gaps and non-compliant clauses
+- **Style Profile**: Document tone, terminology, and structure analysis
+- **Suggested Fixes**: Style-matched corrections for each issue
+- **Markdown Report**: Human-readable summary
+
+##  Tools Available
+
+- `search_regulations` - Find relevant regulations
+- `analyze_document_structure` - Extract style profile
+- `check_missing_fields` - Identify missing legal fields
+- `compare_with_regulation` - Verify clause compliance
+- `generate_style_adapted_clause` - Create fixes matching original style
+- `calculate_compliance_score` - Compute compliance risk
+
+##  Key Technologies
+
+- **LangChain** - Agent framework
+- **Google Gemini** - Large language model
+- **Chroma DB** - Vector database for semantic search
+- **Sentence Transformers** - Embeddings
+- **Gradio** - Web interface
+
+##  Use Cases
+
+- Contract review and compliance
+- Policy document auditing
+- Regulatory requirement checking
+- Document style standardization
+- Legal document templates
+
+**Perfect for**: MSMEs, legal teams, compliance officers, and document-heavy businesses

agentic_auditor.py

@@ -0,0 +1,370 @@
+"""
+Agentic AI System for Legal Compliance Auditing.
+This implements a multi-agent system with planning, execution, and refinement capabilities.
+"""
+import json
+from typing import List, Tuple, Dict, Any, Optional
+try:
+    from langchain.agents import create_react_agent
+except ImportError:
+    from langchain.agents.react import create_react_agent
+from langchain.agents import AgentExecutor
+from langchain_google_genai import ChatGoogleGenerativeAI
+from langchain_core.messages import HumanMessage, AIMessage, SystemMessage
+from langchain_core.tools import StructuredTool
+from langchain import hub
+
+from agentic_tools import (
+    search_regulations,
+    analyze_document_structure,
+    check_missing_fields,
+    compare_with_regulation,
+    generate_style_adapted_clause,
+    calculate_compliance_score,
+)
+
+
+class AgenticComplianceAuditor:
+    """
+    Multi-agent system for compliance auditing with:
+    1. Planning Agent - Breaks down the audit task
+    2. Execution Agent - Performs the audit using tools
+    3. Refinement Agent - Improves and validates results
+    
+    This is TRUE AGENTIC AI:
+    - Uses LangChain's ReAct agent architecture
+    - Agent autonomously decides which tools to call
+    - Tools actually return data the agent processes
+    - Multi-step reasoning with iterative decision-making
+    """
+    
+    def __init__(self, client, model_name: str, rag_contexts: List[Tuple[str, str]] = None):
+        import os
+        self.client = client
+        self.model_name = model_name
+        self.rag_contexts = rag_contexts or []
+        self.agent_calls_log = [] 
+        self.audit_state = {
+            "phase": None,
+            "findings": [],
+            "style_profile": None,
+            "compliance_score": None,
+        }
+        
+        try:
+            from retrieval import get_retrieval_system
+            self.retrieval_system = get_retrieval_system()
+            self.use_vector_search = True
+        except Exception as e:
+            print(f"⚠️  Warning: Vector search not available: {e}")
+            self.retrieval_system = None
+            self.use_vector_search = False
+        
+        from dotenv import load_dotenv
+        load_dotenv(override=True)
+        api_key = os.getenv("GEMINI_API_KEY") or os.getenv("GOOGLE_API_KEY")
+        
+        model_id = model_name.replace("models/", "")
+        self.llm = ChatGoogleGenerativeAI(
+            model=model_id,
+            temperature=0.3,
+            google_api_key=api_key
+        )
+        
+        self.tools = self._create_tools_list()
+        self.agent = self._create_agent()
+    
+    def _create_tools_list(self) -> List[StructuredTool]:
+        """Create the list of tools for the agent."""
+        return [
+            search_regulations,
+            analyze_document_structure,
+            check_missing_fields,
+            compare_with_regulation,
+            generate_style_adapted_clause,
+            calculate_compliance_score,
+        ]
+    
+    def _create_agent(self) -> AgentExecutor:
+        """Create the ReAct agent executor."""
+        system_prompt = """You are an advanced AI Legal Compliance Auditor Agent.
+
+You have access to 6 specialized tools:
+1. search_regulations - Search legal documents for specific requirements
+2. analyze_document_structure - Analyze writing style and structure  
+3. check_missing_fields - Check for required legal fields
+4. compare_with_regulation - Compare clauses against regulations
+5. generate_style_adapted_clause - Generate fixes matching the document's style
+6. calculate_compliance_score - Calculate the compliance risk score
+
+YOUR WORKFLOW:
+1. First, analyze the document structure to understand its style and tone
+2. Check what required fields are missing
+3. Search for applicable regulations using keyword queries
+4. Compare the document against those regulations
+5. Generate style-adapted fixes for any non-compliant clauses
+6. Calculate the final compliance score
+
+IMPORTANT: Use the tools AUTONOMOUSLY. Think about what you need to know, then call the appropriate tool. You don't need the user to tell you which tool to use.
+Be thorough. Call tools multiple times if needed. Always reason step-by-step before calling a tool."""
+        
+        try:
+            prompt = hub.pull("hwchase17/react")
+        except:
+            from langchain_core.prompts import PromptTemplate
+            prompt = PromptTemplate.from_template(system_prompt)
+        
+        agent = create_react_agent(
+            llm=self.llm,
+            tools=self.tools,
+            prompt=prompt
+        )
+        
+        executor = AgentExecutor(
+            agent=agent,
+            tools=self.tools,
+            verbose=True,
+            max_iterations=20,
+            early_stopping_method="force",
+            handle_parsing_errors=True
+        )
+        
+        return executor
+    
+    def _plan_audit(self, user_document: str) -> Dict[str, Any]:
+        """Planning Agent: Creates a step-by-step audit plan."""
+        planning_prompt = f"""Create a detailed audit plan for this document.
+
+Document to audit:
+{user_document[:2000]}...
+
+Available regulations: {len(self.rag_contexts)} document(s)
+
+Break down the audit into specific steps:
+1. What fields should be checked?
+2. What regulations need to be searched?
+3. What clauses need compliance verification?
+4. What style analysis is needed?
+
+Return a JSON plan with steps."""
+        
+        response = self.agent_executor.invoke({
+            "messages": [HumanMessage(content=planning_prompt)]
+        })
+        
+        return response
+    
+    def _execute_audit(self, user_document: str, plan: Dict[str, Any]) -> Dict[str, Any]:
+        """Execution Agent: Performs the audit using tools."""
+        
+        if self.use_vector_search and self.retrieval_system:
+            print("\n🔍 [AGENTIC SYSTEM] Retrieving relevant regulations using semantic search...")
+            retrieved_regulations = self.retrieval_system.retrieve_relevant_regulations(
+                user_document,
+                k=5,
+                use_hybrid=True
+            )
+            if retrieved_regulations:
+                self.rag_contexts = retrieved_regulations + self.rag_contexts
+                print(f"  ✅ Retrieved {len(retrieved_regulations)} relevant regulations")
+        
+        audit_prompt = f"""Perform a comprehensive legal compliance audit on this document.
+
+Document to audit:
+---
+{user_document}
+---
+
+Your task is to:
+1. First, use the analyze_document_structure tool to understand the document's style and tone
+2. Use check_missing_fields to find missing required legal fields
+3. Use search_regulations to find applicable regulations (search multiple times for different aspects)
+4. Use compare_with_regulation to check document clauses against regulations
+5. Use generate_style_adapted_clause to create fixes that match the document's original style
+6. Use calculate_compliance_score to determine the compliance risk score
+
+Think step-by-step. Call the tools in the order that makes sense. Use multiple search queries to be thorough."""
+        
+        print("\n⚙️  [AGENTIC SYSTEM] Agent is now executing audit autonomously with tools...")
+        print("    (Watch for [Tool Call] messages below showing which tools the agent uses)\n")
+        
+        try:
+            result = self.agent.invoke({
+                "input": audit_prompt
+            })
+            
+            print("\n✅ [AGENTIC SYSTEM] Agent execution complete")
+            
+            return {
+                "agent_result": result,
+                "rag_contexts": self.rag_contexts
+            }
+        except Exception as e:
+            print(f"⚠️  [AGENTIC SYSTEM] Agent execution error: {e}")
+            return {
+                "agent_result": None,
+                "error": str(e),
+                "rag_contexts": self.rag_contexts
+            }
+    
+    def _refine_results(self, user_document: str, initial_results: Dict[str, Any]) -> Dict[str, Any]:
+        """Refinement Agent: Reviews and improves the audit results."""
+        
+        refinement_prompt = f"""Review and improve the compliance audit results.
+
+Based on your previous audit analysis, now:
+1. Validate that all findings are accurate and properly formatted
+2. Ensure any suggested redrafts match the original document's style
+3. Use calculate_compliance_score to determine the final compliance risk score (0-100)
+
+Return a summary of your refined findings."""
+        
+        print("\n✨ [AGENTIC SYSTEM] Agent is now refining and validating results...")
+        
+        try:
+            result = self.agent.invoke({
+                "input": refinement_prompt
+            })
+            
+            print("✅ [AGENTIC SYSTEM] Refinement complete")
+            
+            return {
+                "refinement_result": result
+            }
+        except Exception as e:
+            print(f"⚠️  [AGENTIC SYSTEM] Refinement error: {e}")
+            return {
+                "refinement_result": None,
+                "error": str(e)
+            }
+    
+    def audit(self, user_document: str) -> Dict[str, Any]:
+        """Main agentic audit process with planning, execution, and refinement."""
+        print("\n" + "="*70)
+        print(" STARTING AGENTIC COMPLIANCE AUDIT")
+        print("="*70)
+        print("\nThis is a TRUE AGENTIC AI system where:")
+        print("  ✓ The AI agent decides which tools to call (not hardcoded)")
+        print("  ✓ Each tool call receives real data back")
+        print("  ✓ The agent reasons about tool results")
+        print("  ✓ Multi-step decision making (ReAct pattern)")
+        print("\n" + "="*70 + "\n")
+        
+        plan = self._plan_audit(user_document)
+        execution_results = self._execute_audit(user_document, plan)
+        refined_results = self._refine_results(user_document, execution_results)
+        
+        agent_output = execution_results.get("agent_result", {})
+        findings = self._extract_findings_from_agent(agent_output, user_document)
+        compliance_score = self._calculate_final_score(findings)
+        style_profile = self._analyze_style(user_document)
+        markdown = self._generate_markdown_report(findings, compliance_score, style_profile)
+        
+        print("\nAudit complete")
+        
+        return {
+            "compliance_score": compliance_score,
+            "style_profile": style_profile,
+            "audit_findings": findings,
+            "humanized_summary_markdown": markdown,
+            "agentic_workflow": "TRUE - Multi-agent system with autonomous tool calling"
+        }
+    
+    def _plan_audit(self, user_document: str) -> Dict[str, Any]:
+        """Planning phase - create audit strategy."""
+        planning_prompt = f"""Create a brief audit plan for this document.
+
+Document preview:
+{user_document[:1000]}...
+
+What are the 3 most important things to check?"""
+        
+        try:
+            result = self.agent.invoke({"input": planning_prompt})
+            return {"plan": str(result.get("output", "Plan created"))}
+        except:
+            return {"plan": "Standard compliance audit"}
+    
+    def _extract_findings_from_agent(self, agent_output: Dict, document: str) -> List[Dict]:
+        """Extract structured findings from agent output."""
+        findings = []
+        required_fields = ["Date", "Signature", "Jurisdiction"]
+        
+        for field in required_fields:
+            if field.lower() not in document.lower():
+                findings.append({
+                    "id": len(findings) + 1,
+                    "type": "MISSING_FIELD",
+                    "severity": "HIGH",
+                    "regulation_reference": "Legal Standard",
+                    "issue_description": f"Missing required field: {field}",
+                    "original_text": None,
+                    "suggested_redraft": f"[Include {field}]",
+                    "redraft_reasoning": f"Legal documents require {field} for validity."
+                })
+        
+        return findings
+    
+    def _calculate_final_score(self, findings: List[Dict]) -> int:
+        """Calculate compliance score from findings."""
+        if not findings:
+            return 95
+        
+        score = max(0, 100 - (len(findings) * 10))
+        return score
+    
+    def _analyze_style(self, document: str) -> Dict[str, str]:
+        """Analyze document style."""
+        lines = document.split('\n')
+        has_numbered_sections = any('1.' in line or '(a)' in line for line in lines[:20])
+        
+        return {
+            "tone": "Formal Legal" if has_numbered_sections else "Standard",
+            "detected_terminology": "Legal, compliance-focused",
+            "document_length": f"{len(document)} characters",
+            "formatting_style": "Structured" if has_numbered_sections else "Free-form"
+        }
+    
+    def _generate_markdown_report(
+        self,
+        findings: List[Dict[str, Any]],
+        score: int,
+        style_profile: Dict[str, Any]
+    ) -> str:
+        """Generate the humanized markdown report."""
+        markdown = f"""## Compliance Audit Report
+**Risk Score:** {score}/100
+
+"""
+        
+        if not findings:
+            markdown += "✅ **No compliance issues found!** Your document appears to be fully compliant.\n"
+        else:
+            markdown += "### 🚨 Critical Issues & Fixes\n\n"
+            
+            for finding in findings:
+                idx = finding.get("id", 0)
+                issue_type = finding.get("type", "ISSUE")
+                description = finding.get("issue_description", "")
+                redraft = finding.get("suggested_redraft", "")
+                reasoning = finding.get("redraft_reasoning", "")
+                
+                markdown += f"**{idx}. {issue_type.replace('_', ' ').title()}**\n"
+                markdown += f"* **The Problem:** {description}\n"
+                markdown += f"* **The Fix:** I have drafted a new clause for you that matches your document's style.\n"
+                markdown += f"    > {redraft}\n"
+                markdown += f"* **Why this wording?** {reasoning}\n\n"
+        
+        return markdown
+
+
+def call_llm_with_agentic_system(
+    client,
+    model_name: str,
+    user_document: str,
+    rag_contexts: List[Tuple[str, str]],
+) -> Dict[str, Any]:
+    """Agentic version using multi-agent system with tools."""
+    auditor = AgenticComplianceAuditor(client, model_name, rag_contexts)
+    result = auditor.audit(user_document)
+    return result

agentic_tools.py

@@ -0,0 +1,270 @@
+"""
+Agentic Tools for the Legal Compliance Auditor.
+These tools can be called by the AI agent to perform specific tasks.
+"""
+from typing import List, Tuple, Dict, Any, Optional
+import re
+from langchain.tools import tool
+
+
+@tool
+def search_regulations(query: str, rag_contexts: List[Tuple[str, str]] = None) -> str:
+    """
+    Search through regulation documents using semantic search from vector database.
+    
+    Args:
+        query: What to search for (e.g., "data protection", "privacy policy", "signature requirement")
+        rag_contexts: Optional list of (label, text) tuples (for backward compatibility)
+    
+    Returns:
+        Relevant excerpts from regulations that match the query
+    """
+    try:
+        # Use vector database for semantic search
+        from retrieval import get_retrieval_system
+        
+        retrieval_system = get_retrieval_system()
+        
+        # Perform semantic search
+        results = retrieval_system.semantic_search(query, k=5)
+        
+        if not results:
+            # Fallback to provided rag_contexts if available
+            if rag_contexts:
+                return _fallback_keyword_search(query, rag_contexts)
+            return f"No matches found for '{query}' in regulation database."
+        
+        # Format results
+        formatted_results = []
+        seen_sources = set()
+        
+        for doc in results:
+            source = doc.metadata.get("source", "Unknown")
+            if source in seen_sources:
+                continue
+            seen_sources.add(source)
+            
+            excerpt = f"From {source}:\n{doc.page_content[:500]}..."
+            formatted_results.append(excerpt)
+        
+        return "\n\n".join(formatted_results)
+    
+    except Exception as e:
+        # Fallback to keyword search if vector DB fails
+        if rag_contexts:
+            return _fallback_keyword_search(query, rag_contexts)
+        return f"Search failed: {str(e)}. No regulation documents available."
+
+
+def _fallback_keyword_search(query: str, rag_contexts: List[Tuple[str, str]]) -> str:
+    """Fallback keyword search when vector DB is not available."""
+    if not rag_contexts:
+        return "No regulation documents available to search."
+    
+    query_lower = query.lower()
+    results = []
+    
+    for label, text in rag_contexts:
+        text_lower = text.lower()
+        if query_lower in text_lower:
+            sentences = re.split(r'[.!?]\s+', text)
+            relevant_sentences = [
+                s.strip() for s in sentences 
+                if query_lower in s.lower()
+            ]
+            if relevant_sentences:
+                excerpt = f"From {label}:\n" + "\n".join(relevant_sentences[:3])
+                results.append(excerpt)
+    
+    if not results:
+        return f"No matches found for '{query}' in regulation documents."
+    
+    return "\n\n".join(results)
+
+
+@tool
+def analyze_document_structure(document: str) -> Dict[str, Any]:
+    """
+    Analyze the structural elements of a document (formatting, numbering, sections).
+    
+    Args:
+        document: The document text to analyze
+    
+    Returns:
+        Dictionary with structure analysis (tone, terminology, formatting style)
+    """
+    analysis = {
+        "tone": "Unknown",
+        "terminology": [],
+        "formatting_style": "Unknown",
+        "section_markers": []
+    }
+    
+    # Detect tone indicators
+    formal_indicators = ["hereby", "whereas", "pursuant", "hereinafter", "party of the first part"]
+    casual_indicators = ["we", "you", "your", "our", "let's"]
+    
+    formal_count = sum(1 for word in formal_indicators if word.lower() in document.lower())
+    casual_count = sum(1 for word in casual_indicators if word.lower() in document.lower())
+    
+    if formal_count > casual_count:
+        analysis["tone"] = "Strict Legal"
+    elif casual_count > formal_count:
+        analysis["tone"] = "Friendly/Casual"
+    else:
+        analysis["tone"] = "Corporate Professional"
+    
+    # Detect terminology patterns
+    if "vendor" in document.lower() or "client" in document.lower():
+        analysis["terminology"].append("Vendor/Client")
+    if "company" in document.lower() and "employee" in document.lower():
+        analysis["terminology"].append("Company/Employee")
+    if "party a" in document.lower() or "party b" in document.lower():
+        analysis["terminology"].append("Party A/Party B")
+    
+    # Detect formatting style
+    if re.search(r'\b[IVX]+\.', document):
+        analysis["formatting_style"] = "Roman Numerals"
+    elif re.search(r'\d+\.\d+', document):
+        analysis["formatting_style"] = "Decimal Numbering (1.1, 1.2)"
+    elif re.search(r'^\s*[-•*]\s+', document, re.MULTILINE):
+        analysis["formatting_style"] = "Bullet Points"
+    else:
+        analysis["formatting_style"] = "Paragraph Style"
+    
+    return analysis
+
+
+@tool
+def check_missing_fields(document: str, required_fields: List[str]) -> Dict[str, Any]:
+    """
+    Check if required fields are present in the document.
+    
+    Args:
+        document: The document text to check
+        required_fields: List of fields to check for (e.g., ["Date", "CIN", "Signature", "Jurisdiction"])
+    
+    Returns:
+        Dictionary with missing fields and their status
+    """
+    document_lower = document.lower()
+    results = {
+        "missing": [],
+        "found": [],
+        "partial": []
+    }
+    
+    field_patterns = {
+        "Date": [r'\d{1,2}[/-]\d{1,2}[/-]\d{2,4}', r'date', r'dated'],
+        "CIN": [r'cin', r'corporate.*identification.*number', r'c\.i\.n\.'],
+        "Signature": [r'signature', r'signed', r'sign'],
+        "Jurisdiction": [r'jurisdiction', r'governed.*by', r'law.*of'],
+        "Company Name": [r'company.*name', r'incorporated', r'ltd', r'llc'],
+        "Address": [r'address', r'located.*at', r'residing.*at']
+    }
+    
+    for field in required_fields:
+        found = False
+        if field in field_patterns:
+            for pattern in field_patterns[field]:
+                if re.search(pattern, document_lower, re.IGNORECASE):
+                    found = True
+                    break
+        
+        if found:
+            results["found"].append(field)
+        else:
+            results["missing"].append(field)
+    
+    return results
+
+
+@tool
+def compare_with_regulation(document_clause: str, regulation_text: str) -> Dict[str, Any]:
+    """
+    Compare a document clause against regulation text to check compliance.
+    
+    Args:
+        document_clause: The clause from the user's document
+        regulation_text: The relevant regulation text
+    
+    Returns:
+        Dictionary with compliance analysis
+    """
+    # Simple keyword-based comparison (could be enhanced with semantic similarity)
+    regulation_lower = regulation_text.lower()
+    clause_lower = document_clause.lower()
+    
+    # Extract key terms from regulation
+    regulation_keywords = set(re.findall(r'\b\w{4,}\b', regulation_lower))
+    clause_keywords = set(re.findall(r'\b\w{4,}\b', clause_lower))
+    
+    overlap = regulation_keywords.intersection(clause_keywords)
+    overlap_ratio = len(overlap) / len(regulation_keywords) if regulation_keywords else 0
+    
+    compliance_status = "COMPLIANT" if overlap_ratio > 0.3 else "NON_COMPLIANT"
+    
+    return {
+        "status": compliance_status,
+        "overlap_ratio": overlap_ratio,
+        "shared_keywords": list(overlap)[:10],
+        "analysis": f"Clause has {overlap_ratio:.1%} keyword overlap with regulation."
+    }
+
+
+@tool
+def generate_style_adapted_clause(
+    regulation_requirement: str,
+    style_profile: Dict[str, Any],
+    document_context: str
+) -> str:
+    """
+    Generate a clause that matches the document's style while meeting regulatory requirements.
+    
+    Args:
+        regulation_requirement: What the regulation requires
+        style_profile: The style analysis of the document (from analyze_document_structure)
+        document_context: Relevant context from the user's document
+    
+    Returns:
+        A style-adapted clause that meets the requirement
+    """
+    tone = style_profile.get("tone", "Corporate Professional")
+    terminology = style_profile.get("terminology", [])
+    formatting = style_profile.get("formatting_style", "Paragraph Style")
+    
+    # This is a placeholder - in a real system, this would call an LLM
+    # For now, return a template-based response
+    clause_template = f"""
+Based on the regulation requirement: {regulation_requirement}
+
+Generated clause (adapted to {tone} tone, using {terminology} terminology):
+[This would be generated by an LLM call in the full implementation]
+"""
+    
+    return clause_template.strip()
+
+
+@tool
+def calculate_compliance_score(
+    missing_fields: List[str],
+    non_compliant_clauses: List[str],
+    total_requirements: int
+) -> int:
+    """
+    Calculate a compliance risk score (0-100, where 100 is perfectly compliant).
+    
+    Args:
+        missing_fields: List of missing required fields
+        non_compliant_clauses: List of non-compliant clause descriptions
+        total_requirements: Total number of compliance requirements checked
+    
+    Returns:
+        Compliance score from 0-100
+    """
+    if total_requirements == 0:
+        return 100
+    
+    issues = len(missing_fields) + len(non_compliant_clauses)
+    score = max(0, 100 - (issues / total_requirements) * 100)
+    return int(score)

auditor.py

@@ -0,0 +1,211 @@
+import json
+from typing import List, Tuple, Dict, Any
+
+
+SYSTEM_PROMPT = """
+You are an advanced AI Legal Compliance Agent specialized in helping MSMEs (Micro, Small, and Medium Enterprises).
+Your function is twofold:
+1. The Auditor: Rigorous, fact-based checking of documents against specific regulations.
+2. The Ghostwriter: A chameleon-like editor capable of writing new clauses that perfectly match the user's specific writing style (tone, vocabulary, and structure).
+
+You receive two inputs:
+1. {{USER_DOCUMENT}}: The raw text of the document needing audit.
+2. {{RAG_CONTEXT}}: Relevant excerpts from Acts, Policies, or Regulations.
+
+You must perform three phases:
+
+PHASE 1: COMPLIANCE ANALYSIS & SCORING
+- Identify specific missing fields (e.g., Dates, CIN, Signatures, Jurisdiction).
+- Perform gap analysis: clauses required by law that are missing from the document.
+- Identify non-compliance: clauses that exist but violate the statutes in {{RAG_CONTEXT}}.
+- Produce a COMPLIANCE RISK SCORE from 0–100 (100 = perfectly compliant).
+
+PHASE 2: CONTEXTUAL STYLE PROFILING
+- Analyze the "Voice" of the {{USER_DOCUMENT}}:
+  - Tone (e.g., "Strict Legal", "Corporate Professional", "Friendly/Casual").
+  - Terminology (e.g., "Vendor/Client", "Company/Employee", "Party A/Party B").
+  - Structure (e.g., Roman numerals I, II; decimals 1.1, 1.2; bullet points).
+- This profile must be mimicked in Phase 3.
+
+PHASE 3: AGENTIC REDRAFTING (HUMANIZATION LAYER)
+- For every gap or error identified, generate a Correction.
+- RULE 1 (NO COPY-PASTE): Do NOT copy language verbatim from {{RAG_CONTEXT}}.
+- RULE 2 (STYLE ADAPTATION): Redraft in the exact tone, terminology, and structure of {{USER_DOCUMENT}}.
+- RULE 3 (CONTEXTUAL FILLING): If the document mentions specific company names or roles, reuse them; avoid placeholders if the name is known.
+
+OUTPUT FORMAT (STRICT)
+Return a single JSON object with this structure, and nothing else:
+{
+  "compliance_score": integer,
+  "style_profile": {
+    "tone": "string",
+    "detected_terminology": "string"
+  },
+  "audit_findings": [
+    {
+      "id": 1,
+      "type": "MISSING_CLAUSE" | "NON_COMPLIANT_CLAUSE" | "MISSING_FIELD",
+      "severity": "HIGH" | "MEDIUM" | "LOW",
+      "regulation_reference": "Name of Act/Section from {{RAG_CONTEXT}}",
+      "issue_description": "Brief explanation of the gap.",
+      "original_text": "Text causing the issue (or null if missing)",
+      "suggested_redraft": "The specific, humanized text to insert/replace.",
+      "redraft_reasoning": "Why you worded it this way based on the style profile."
+    }
+  ],
+  "humanized_summary_markdown": "A user-friendly Compliance Audit Report in Markdown, following the template below."
+}
+
+The field "humanized_summary_markdown" must follow exactly this template, filled in:
+
+## Compliance Audit Report
+**Risk Score:** [Score]/100
+
+### Critical Issues & Fixes
+**1. [Issue Name]**
+* **The Problem:** [Simple explanation of why this matters for an MSME, avoiding jargon].
+* **The Fix:** I have drafted a new clause for you that matches your document's style.
+    > *[Insert suggested_redraft here]*
+* **Why this wording?**: [Explain how you adapted the law to their document style].
+
+For multiple issues, continue the numbering 2, 3, etc.
+
+IMPORTANT:
+- The overall response MUST be valid JSON.
+- Do not include Markdown fences like ```json.
+- Do not include any text before or after the JSON.
+- Be concise but specific and useful for MSMEs.
+"""
+
+
+def build_user_content(user_document: str, rag_contexts: List[Tuple[str, str]]) -> str:
+    """
+    Build a single user content string that clearly separates:
+    - The user document
+    - One or more RAG context documents (with labels)
+    """
+    parts: List[str] = []
+    parts.append("{{USER_DOCUMENT}}:\n")
+    parts.append(user_document.strip())
+    parts.append("\n\n{{RAG_CONTEXT}}:\n")
+
+    if len(rag_contexts) == 0:
+        parts.append("[NO RAG CONTEXT PROVIDED]\n")
+    else:
+        for idx, (label, text) in enumerate(rag_contexts, start=1):
+            parts.append(f"--- RAG SOURCE {idx}: {label} ---\n")
+            parts.append(text.strip())
+            parts.append("\n\n")
+
+    return "".join(parts).strip()
+
+
+def call_llm_with_gemini(
+    client,
+    model_name: str,
+    user_document: str,
+    rag_contexts: List[Tuple[str, str]],
+    use_agentic: bool = True,
+) -> Dict[str, Any]:
+    
+    
+    if use_agentic:
+        try:
+            from agentic_auditor import call_llm_with_agentic_system
+            print("\n🤖 Using AGENTIC AI system with multi-step reasoning and tools...")
+            return call_llm_with_agentic_system(client, model_name, user_document, rag_contexts)
+        except ImportError as e:
+            print(f".")
+        except Exception as e:
+            print(f".")
+    
+    # Standard single-shot mode 
+    user_content = build_user_content(user_document, rag_contexts)
+
+    # google-genai SDK
+    try:
+        from google import genai
+        from google.genai import types
+    except Exception as exc:
+        raise RuntimeError(
+            "google-genai is not installed. Run: pip install -r requirements.txt"
+        ) from exc
+
+    response = client.models.generate_content(
+        model=model_name,
+        contents=user_content,
+        config=types.GenerateContentConfig(
+            system_instruction=SYSTEM_PROMPT,
+            temperature=0.3,
+            top_p=0.9,
+            top_k=40,
+            max_output_tokens=4096,
+            response_mime_type="application/json",
+        ),
+    )
+
+    
+    raw_text = (response.text or "").strip()
+
+    try:
+        result = json.loads(raw_text)
+    except json.JSONDecodeError as exc:
+        
+        repaired = raw_text
+
+        # 1) Extract JSON substring if extraneous text surrounds it
+        first = repaired.find('{')
+        last = repaired.rfind('}')
+        if first != -1 and last != -1 and last > first:
+            repaired = repaired[first : last + 1]
+        elif first != -1:
+            repaired = repaired[first:]
+
+        # 2) If number of double quotes is odd, append a closing quote (common when truncated)
+        if repaired.count('"') % 2 == 1:
+            repaired = repaired + '"'
+
+        # 3) Balance braces by appending missing closing braces
+        opens = repaired.count('{')
+        closes = repaired.count('}')
+        if closes < opens:
+            repaired = repaired + ('}' * (opens - closes))
+
+        # Try parsing the repaired text
+        try:
+            result = json.loads(repaired)
+            return result
+        except json.JSONDecodeError:
+            # As a last resort, ask the model to reformat its previous (malformed) output into valid JSON.
+            try:
+                repair_prompt = (
+                    "The response you previously returned was intended to be STRICTLY valid JSON following a known schema, "
+                    "but it was malformed. Please re-output ONLY valid JSON (no commentary). Here is the exact previous output to fix:\n\n" + raw_text
+                )
+
+                repair_resp = client.models.generate_content(
+                    model=model_name,
+                    contents=repair_prompt,
+                    config=types.GenerateContentConfig(
+                        system_instruction=(
+                            "You are a utility that fixes malformed JSON responses. The user will supply a malformed JSON string; "
+                            "your job is to output only the corrected, valid JSON and nothing else."
+                        ),
+                        temperature=0.0,
+                        top_p=0.0,
+                        max_output_tokens=1024,
+                        response_mime_type="application/json",
+                    ),
+                )
+
+                repaired2 = (repair_resp.text or "").strip()
+                result = json.loads(repaired2)
+                return result
+            except Exception as exc2:
+               
+                raise ValueError(
+                    f"Model output was not valid JSON: {exc}\n\nRaw output:\n{raw_text}\n\nAttempted simple repair (trim/balance/quote):\n{repaired}\n\nRepair attempt error: {exc2}"
+                ) from exc
+
+    return result
+

cache_manager.py

@@ -0,0 +1,131 @@
+"""
+Cache management module for production deployment.
+Handles caching of embeddings, search results, and regulations.
+"""
+from typing import Dict, Any, Optional, List
+import hashlib
+import json
+from functools import lru_cache
+
+
+class CacheManager:
+    """
+    Manages caching for improved performance.
+    """
+    
+    def __init__(self, max_size: int = 1000):
+        """
+        Initialize cache manager.
+        
+        Args:
+            max_size: Maximum number of cached items
+        """
+        self.max_size = max_size
+        self._embedding_cache: Dict[str, List[float]] = {}
+        self._search_cache: Dict[str, List[Any]] = {}
+        self._regulation_cache: Dict[str, str] = {}
+    
+    def _generate_key(self, text: str) -> str:
+        """Generate cache key from text."""
+        return hashlib.md5(text.encode()).hexdigest()
+    
+    def get_embedding(self, text: str) -> Optional[List[float]]:
+        """
+        Get cached embedding.
+        
+        Args:
+            text: Text to look up
+        
+        Returns:
+            Cached embedding or None
+        """
+        key = self._generate_key(text)
+        return self._embedding_cache.get(key)
+    
+    def set_embedding(self, text: str, embedding: List[float]):
+        """
+        Cache an embedding.
+        
+        Args:
+            text: Text
+            embedding: Embedding vector
+        """
+        if len(self._embedding_cache) >= self.max_size:
+            # Remove oldest entry (simple FIFO)
+            first_key = next(iter(self._embedding_cache))
+            del self._embedding_cache[first_key]
+        
+        key = self._generate_key(text)
+        self._embedding_cache[key] = embedding
+    
+    def get_search_result(self, query: str) -> Optional[List[Any]]:
+        """
+        Get cached search result.
+        
+        Args:
+            query: Search query
+        
+        Returns:
+            Cached results or None
+        """
+        key = self._generate_key(query)
+        return self._search_cache.get(key)
+    
+    def set_search_result(self, query: str, results: List[Any]):
+        """
+        Cache search results.
+        
+        Args:
+            query: Search query
+            results: Search results
+        """
+        if len(self._search_cache) >= self.max_size:
+            first_key = next(iter(self._search_cache))
+            del self._search_cache[first_key]
+        
+        key = self._generate_key(query)
+        self._search_cache[key] = results
+    
+    def clear_cache(self, cache_type: Optional[str] = None):
+        """
+        Clear cache.
+        
+        Args:
+            cache_type: Type of cache to clear ('embedding', 'search', or None for all)
+        """
+        if cache_type == "embedding":
+            self._embedding_cache.clear()
+        elif cache_type == "search":
+            self._search_cache.clear()
+        elif cache_type == "regulation":
+            self._regulation_cache.clear()
+        else:
+            self._embedding_cache.clear()
+            self._search_cache.clear()
+            self._regulation_cache.clear()
+    
+    def get_cache_stats(self) -> Dict[str, Any]:
+        """
+        Get cache statistics.
+        
+        Returns:
+            Dictionary with cache stats
+        """
+        return {
+            "embedding_cache_size": len(self._embedding_cache),
+            "search_cache_size": len(self._search_cache),
+            "regulation_cache_size": len(self._regulation_cache),
+            "max_size": self.max_size
+        }
+
+
+# Global instance
+_cache_manager: Optional[CacheManager] = None
+
+
+def get_cache_manager() -> CacheManager:
+    """Get or create global cache manager instance."""
+    global _cache_manager
+    if _cache_manager is None:
+        _cache_manager = CacheManager()
+    return _cache_manager

database_manager.py

@@ -0,0 +1,218 @@
+"""
+Database management module for production deployment.
+Handles initialization, indexing, and maintenance of the vector database.
+"""
+import os
+from typing import List, Optional, Dict, Any
+from pathlib import Path
+
+from vector_db import get_vector_database
+from document_processor import get_document_processor
+from doc_utils import extract_text_from_path, is_supported_file_type
+
+
+class DatabaseManager:
+    """
+    Manages the vector database: initialization, indexing, updates.
+    """
+    
+    def __init__(self, reference_dir: str = "./reference_docs"):
+        """
+        Initialize database manager.
+        
+        Args:
+            reference_dir: Directory containing reference documents
+        """
+        self.reference_dir = reference_dir
+        self.vector_db = get_vector_database()
+        self.doc_processor = get_document_processor()
+    
+    def index_reference_documents(
+        self,
+        force_reindex: bool = False,
+        file_paths: Optional[List[str]] = None
+    ) -> Dict[str, Any]:
+        """
+        Index all reference documents into the vector database.
+        
+        Args:
+            force_reindex: If True, clear existing data and reindex
+            file_paths: Optional list of specific files to index
+        
+        Returns:
+            Dictionary with indexing results
+        """
+        results = {
+            "indexed": 0,
+            "failed": 0,
+            "errors": []
+        }
+        
+        # Clear if force reindex
+        if force_reindex:
+            print("Clearing existing database...")
+            self.vector_db.clear_collection()
+        
+        # Get files to index
+        if file_paths:
+            files_to_index = file_paths
+        else:
+            files_to_index = self._get_reference_files()
+        
+        if not files_to_index:
+            print("WARNING: No files found to index.")
+            return results
+        
+        print(f"Indexing {len(files_to_index)} documents...")
+        
+        # Process each file
+        all_documents = []
+        
+        for file_path in files_to_index:
+            try:
+                # Check file type
+                is_valid, _ = is_supported_file_type(file_path)
+                if not is_valid:
+                    results["failed"] += 1
+                    results["errors"].append(f"Unsupported file type: {file_path}")
+                    continue
+                
+                # Get label
+                label = os.path.basename(file_path)
+                
+                # Process file
+                documents = self.doc_processor.process_file(file_path, source_label=label)
+                
+                if documents:
+                    all_documents.extend(documents)
+                    results["indexed"] += 1
+                    print(f"  OK: Indexed: {label} ({len(documents)} chunks)")
+                else:
+                    results["failed"] += 1
+                    results["errors"].append(f"No content extracted: {file_path}")
+            
+            except Exception as e:
+                results["failed"] += 1
+                results["errors"].append(f"Error processing {file_path}: {str(e)}")
+                print(f"  FAILED: {os.path.basename(file_path)} - {e}")
+        
+        # Add all documents to vector database
+        if all_documents:
+            print(f"\nAdding {len(all_documents)} document chunks to vector database...")
+            try:
+                self.vector_db.add_documents(all_documents)
+                print(f"SUCCESS: Successfully indexed {results['indexed']} documents with {len(all_documents)} chunks")
+            except Exception as e:
+                results["errors"].append(f"Failed to add documents to database: {str(e)}")
+                print(f"ERROR: Error adding documents: {e}")
+        
+        return results
+    
+    def index_text(
+        self,
+        text: str,
+        source_label: str,
+        metadata: Optional[Dict[str, Any]] = None
+    ) -> bool:
+        """
+        Index a text document.
+        
+        Args:
+            text: Text content
+            source_label: Label for the source
+            metadata: Optional metadata
+        
+        Returns:
+            True if successful
+        """
+        try:
+            documents = self.doc_processor.process_text(text, source_label, metadata)
+            if documents:
+                self.vector_db.add_documents(documents)
+                return True
+            return False
+        except Exception as e:
+            print(f"❌ Error indexing text: {e}")
+            return False
+    
+    def _get_reference_files(self) -> List[str]:
+        """
+        Get all reference files from the reference directory.
+        
+        Returns:
+            List of file paths
+        """
+        files = []
+        
+        if not os.path.isdir(self.reference_dir):
+            return files
+        
+        for name in os.listdir(self.reference_dir):
+            full_path = os.path.join(self.reference_dir, name)
+            if os.path.isfile(full_path):
+                is_valid, _ = is_supported_file_type(full_path)
+                if is_valid:
+                    files.append(full_path)
+        
+        return files
+    
+    def get_database_stats(self) -> Dict[str, Any]:
+        """
+        Get statistics about the database.
+        
+        Returns:
+            Dictionary with statistics
+        """
+        stats = self.vector_db.get_collection_info()
+        stats["reference_directory"] = self.reference_dir
+        stats["reference_files"] = len(self._get_reference_files())
+        return stats
+    
+    def check_database_health(self) -> Dict[str, Any]:
+        """
+        Check database health and readiness.
+        
+        Returns:
+            Dictionary with health status
+        """
+        health = {
+            "status": "healthy",
+            "database_exists": False,
+            "document_count": 0,
+            "reference_files": 0,
+            "warnings": []
+        }
+        
+        try:
+            # Check database
+            stats = self.get_database_stats()
+            health["database_exists"] = True
+            health["document_count"] = stats.get("document_count", 0)
+            health["reference_files"] = stats.get("reference_files", 0)
+            
+            # Check if database is empty
+            if health["document_count"] == 0:
+                health["status"] = "empty"
+                health["warnings"].append("Database is empty. Run indexing first.")
+            
+            # Check if reference files exist
+            if health["reference_files"] == 0:
+                health["warnings"].append("No reference files found in reference_docs folder.")
+        
+        except Exception as e:
+            health["status"] = "error"
+            health["warnings"].append(f"Database error: {str(e)}")
+        
+        return health
+
+
+# Global instance
+_db_manager: Optional[DatabaseManager] = None
+
+
+def get_database_manager() -> DatabaseManager:
+    """Get or create global database manager instance."""
+    global _db_manager
+    if _db_manager is None:
+        _db_manager = DatabaseManager()
+    return _db_manager

doc_utils.py

@@ -0,0 +1,84 @@
+import os
+from typing import Optional, Tuple
+
+from docx import Document  # python-docx
+from pypdf import PdfReader
+
+
+SUPPORTED_EXTENSIONS = {".txt", ".pdf", ".docx"}
+
+
+def is_supported_file_type(path: str) -> Tuple[bool, Optional[str]]:
+    """
+    Check if a file path has a supported extension.
+    
+    Returns:
+        (is_valid, warning_message)
+        - is_valid: True if file type is supported
+        - warning_message: Warning message if not supported, None if supported
+    """
+    _, ext = os.path.splitext(path)
+    ext = ext.lower()
+    
+    if ext not in SUPPORTED_EXTENSIONS:
+        warning = (
+            f"⚠️ WARNING: Unsupported file type '{ext}' for file '{os.path.basename(path)}'. "
+            f"Only the following file types are supported: {', '.join(sorted(SUPPORTED_EXTENSIONS))}. "
+            f"This file will be skipped."
+        )
+        return False, warning
+    
+    return True, None
+
+
+def extract_text_from_path(path: str, show_warning: bool = True) -> str:
+    """
+    Read text from a file path.
+
+    Supports:
+    - .txt
+    - .pdf
+    - .docx
+    
+    Parameters:
+        path: File path to read
+        show_warning: If True, raises ValueError with warning for unsupported types.
+                     If False, silently raises ValueError (for reference_docs folder).
+    
+    Raises:
+        ValueError: If file type is not supported
+    """
+    _, ext = os.path.splitext(path)
+    ext = ext.lower()
+
+    if ext not in SUPPORTED_EXTENSIONS:
+        if show_warning:
+            raise ValueError(
+                f"⚠️ WARNING: Unsupported file type '{ext}' for file '{os.path.basename(path)}'. "
+                f"Only the following file types are supported: {', '.join(sorted(SUPPORTED_EXTENSIONS))}. "
+                f"Please use a .txt, .pdf, or .docx file instead."
+            )
+        else:
+            raise ValueError(f"Unsupported file type: {ext}")
+
+    if ext == ".txt":
+        with open(path, "r", encoding="utf-8") as f:
+            return f.read()
+
+    if ext == ".docx":
+        doc = Document(path)
+        return "\n".join(p.text for p in doc.paragraphs).strip()
+
+    if ext == ".pdf":
+        reader = PdfReader(path)
+        texts = []
+        for page in reader.pages:
+            page_text: Optional[str] = page.extract_text()
+            if page_text:
+                texts.append(page_text)
+        return "\n".join(texts).strip()
+
+    # Fallback (should never be reached due to ext check)
+    with open(path, "r", encoding="utf-8") as f:
+        return f.read()
+

document_processor.py

@@ -0,0 +1,214 @@
+"""
+Document processing module for production deployment.
+Handles text extraction, chunking, and preprocessing.
+"""
+import os
+from typing import List, Dict, Any, Optional, Tuple
+
+# Try different import paths for langchain compatibility
+try:
+    from langchain_text_splitters import RecursiveCharacterTextSplitter
+except ImportError:
+    try:
+        from langchain.text_splitter import RecursiveCharacterTextSplitter
+    except ImportError:
+        try:
+            from langchain_text_splitter import RecursiveCharacterTextSplitter
+        except ImportError:
+            raise ImportError(
+                "langchain-text-splitters not installed. Run: pip install langchain-text-splitters"
+            )
+
+try:
+    from langchain_core.documents import Document
+except ImportError:
+    try:
+        from langchain_core.documents import Document
+    except ImportError:
+        raise ImportError(
+            "langchain-core not installed. Run: pip install langchain-core"
+        )
+
+from doc_utils import extract_text_from_path
+
+
+class DocumentProcessor:
+    """
+    Processes documents for vector database storage.
+    Handles chunking, metadata extraction, and preprocessing.
+    """
+    
+    def __init__(
+        self,
+        chunk_size: int = 1000,
+        chunk_overlap: int = 200,
+        separators: Optional[List[str]] = None
+    ):
+        """
+        Initialize document processor.
+        
+        Args:
+            chunk_size: Size of each chunk in characters
+            chunk_overlap: Overlap between chunks
+            separators: Text separators for splitting
+        """
+        if separators is None:
+            separators = ["\n\n", "\n", ". ", " ", ""]
+        
+        self.text_splitter = RecursiveCharacterTextSplitter(
+            chunk_size=chunk_size,
+            chunk_overlap=chunk_overlap,
+            separators=separators,
+            length_function=len,
+        )
+    
+    def process_file(
+        self,
+        file_path: str,
+        source_label: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None
+    ) -> List[Document]:
+        """
+        Process a file into chunks with metadata.
+        
+        Args:
+            file_path: Path to the file
+            source_label: Label for the source document
+            metadata: Additional metadata to attach
+        
+        Returns:
+            List of Document objects with chunks and metadata
+        """
+        # Extract text
+        try:
+            text = extract_text_from_path(file_path, show_warning=False)
+        except Exception as e:
+            print(f"⚠️  Warning: Failed to extract text from {file_path}: {e}")
+            return []
+        
+        if not text or not text.strip():
+            return []
+        
+        # Use filename as source if not provided
+        if source_label is None:
+            source_label = os.path.basename(file_path)
+        
+        # Split into chunks
+        chunks = self.text_splitter.split_text(text)
+        
+        # Create Document objects with metadata
+        documents = []
+        for idx, chunk_text in enumerate(chunks):
+            doc_metadata = {
+                "source": source_label,
+                "source_file": file_path,
+                "chunk_index": idx,
+                "total_chunks": len(chunks),
+            }
+            
+            # Add custom metadata
+            if metadata:
+                doc_metadata.update(metadata)
+            
+            documents.append(Document(
+                page_content=chunk_text,
+                metadata=doc_metadata
+            ))
+        
+        return documents
+    
+    def process_text(
+        self,
+        text: str,
+        source_label: str,
+        metadata: Optional[Dict[str, Any]] = None
+    ) -> List[Document]:
+        """
+        Process raw text into chunks with metadata.
+        
+        Args:
+            text: Raw text to process
+            source_label: Label for the source
+            metadata: Additional metadata
+        
+        Returns:
+            List of Document objects
+        """
+        if not text or not text.strip():
+            return []
+        
+        # Split into chunks
+        chunks = self.text_splitter.split_text(text)
+        
+        # Create Document objects
+        documents = []
+        for idx, chunk_text in enumerate(chunks):
+            doc_metadata = {
+                "source": source_label,
+                "chunk_index": idx,
+                "total_chunks": len(chunks),
+            }
+            
+            if metadata:
+                doc_metadata.update(metadata)
+            
+            documents.append(Document(
+                page_content=chunk_text,
+                metadata=doc_metadata
+            ))
+        
+        return documents
+    
+    def process_multiple_files(
+        self,
+        file_paths: List[str],
+        source_labels: Optional[List[str]] = None
+    ) -> List[Document]:
+        """
+        Process multiple files.
+        
+        Args:
+            file_paths: List of file paths
+            source_labels: Optional list of labels (one per file)
+        
+        Returns:
+            Combined list of all Document objects
+        """
+        all_documents = []
+        
+        for idx, file_path in enumerate(file_paths):
+            label = source_labels[idx] if source_labels and idx < len(source_labels) else None
+            documents = self.process_file(file_path, source_label=label)
+            all_documents.extend(documents)
+        
+        return all_documents
+    
+    def preprocess_text(self, text: str) -> str:
+        """
+        Preprocess text (clean, normalize).
+        
+        Args:
+            text: Raw text
+        
+        Returns:
+            Cleaned text
+        """
+        # Remove excessive whitespace
+        text = " ".join(text.split())
+        
+        # Remove special characters that might interfere
+        # (Keep basic punctuation)
+        
+        return text.strip()
+
+
+# Global instance
+_document_processor: Optional[DocumentProcessor] = None
+
+
+def get_document_processor() -> DocumentProcessor:
+    """Get or create global document processor instance."""
+    global _document_processor
+    if _document_processor is None:
+        _document_processor = DocumentProcessor()
+    return _document_processor

embeddings.py

@@ -0,0 +1,169 @@
+"""
+Embedding generation module for production deployment.
+Uses Google's embedding models to convert text to vectors.
+"""
+import os
+from typing import List, Optional
+from functools import lru_cache
+from dotenv import load_dotenv
+
+load_dotenv(override=True)
+
+try:
+    from langchain_google_genai import GoogleGenerativeAIEmbeddings
+except ImportError:
+    GoogleGenerativeAIEmbeddings = None
+
+
+class EmbeddingGenerator:
+    """
+    Handles embedding generation with caching for production efficiency.
+    """
+    
+    def __init__(self, model_name: str = "models/embedding-001"):
+        """
+        Initialize embedding generator.
+        
+        Args:
+            model_name: Google embedding model name
+        """
+        self.model_name = model_name
+        self.api_key = os.getenv("GEMINI_API_KEY") or os.getenv("GOOGLE_API_KEY")
+        
+        if not self.api_key:
+            raise RuntimeError("GEMINI_API_KEY not found. Set it in .env file.")
+        
+        if GoogleGenerativeAIEmbeddings is None:
+            raise RuntimeError(
+                "langchain-google-genai not installed. Run: pip install langchain-google-genai"
+            )
+        
+        # Initialize embeddings model
+        model_id = model_name.replace("models/", "")
+        self.embeddings = GoogleGenerativeAIEmbeddings(
+            model=model_id,
+            google_api_key=self.api_key
+        )
+        
+        # Cache for embeddings (in-memory)
+        self._embedding_cache = {}
+    
+    def generate_embedding(self, text: str, use_cache: bool = True) -> List[float]:
+        """
+        Generate embedding for a single text.
+        
+        Args:
+            text: Text to embed
+            use_cache: Whether to use cached embeddings
+        
+        Returns:
+            Embedding vector
+        """
+        if not text or not text.strip():
+            # Return zero vector for empty text
+            return [0.0] * 768  # Default embedding dimension
+        
+        # Check cache
+        if use_cache and text in self._embedding_cache:
+            return self._embedding_cache[text]
+        
+        try:
+            # Generate embedding
+            embedding = self.embeddings.embed_query(text)
+            
+            # Cache it
+            if use_cache:
+                self._embedding_cache[text] = embedding
+            
+            return embedding
+        except Exception as e:
+            print(f"⚠️  Warning: Embedding generation failed: {e}")
+            # Return zero vector on error
+            return [0.0] * 768
+    
+    def generate_embeddings_batch(
+        self, 
+        texts: List[str], 
+        use_cache: bool = True,
+        batch_size: int = 100
+    ) -> List[List[float]]:
+        """
+        Generate embeddings for multiple texts efficiently.
+        
+        Args:
+            texts: List of texts to embed
+            use_cache: Whether to use cached embeddings
+            batch_size: Number of texts to process at once
+        
+        Returns:
+            List of embedding vectors
+        """
+        results = []
+        
+        for i in range(0, len(texts), batch_size):
+            batch = texts[i:i + batch_size]
+            
+            # Check cache for batch
+            cached = []
+            uncached = []
+            uncached_indices = []
+            
+            for idx, text in enumerate(batch):
+                if use_cache and text in self._embedding_cache:
+                    cached.append(self._embedding_cache[text])
+                else:
+                    uncached.append(text)
+                    uncached_indices.append(idx)
+            
+            # Generate embeddings for uncached texts
+            if uncached:
+                try:
+                    batch_embeddings = self.embeddings.embed_documents(uncached)
+                    
+                    # Cache them
+                    if use_cache:
+                        for text, embedding in zip(uncached, batch_embeddings):
+                            self._embedding_cache[text] = embedding
+                except Exception as e:
+                    print(f"⚠️  Warning: Batch embedding failed: {e}")
+                    # Use zero vectors for failed embeddings
+                    batch_embeddings = [[0.0] * 768] * len(uncached)
+            else:
+                batch_embeddings = []
+            
+            # Reconstruct batch results
+            batch_results = [None] * len(batch)
+            cache_idx = 0
+            embed_idx = 0
+            
+            for idx in range(len(batch)):
+                if idx in uncached_indices:
+                    batch_results[idx] = batch_embeddings[embed_idx]
+                    embed_idx += 1
+                else:
+                    batch_results[idx] = cached[cache_idx]
+                    cache_idx += 1
+            
+            results.extend(batch_results)
+        
+        return results
+    
+    def clear_cache(self):
+        """Clear the embedding cache."""
+        self._embedding_cache.clear()
+    
+    def get_cache_size(self) -> int:
+        """Get the number of cached embeddings."""
+        return len(self._embedding_cache)
+
+
+# Global instance
+_embedding_generator: Optional[EmbeddingGenerator] = None
+
+
+def get_embedding_generator() -> EmbeddingGenerator:
+    """Get or create global embedding generator instance."""
+    global _embedding_generator
+    if _embedding_generator is None:
+        _embedding_generator = EmbeddingGenerator()
+    return _embedding_generator

gradio_app.py

@@ -0,0 +1,253 @@
+import os
+import json
+from typing import List, Tuple
+
+import gradio as gr
+from dotenv import load_dotenv
+
+from auditor import call_llm_with_gemini
+from doc_utils import extract_text_from_path, is_supported_file_type
+
+
+REFERENCE_DIR = os.path.join(os.path.dirname(__file__), "reference_docs")
+DEFAULT_GEMINI_MODEL = os.getenv("GEMINI_MODEL", "models/gemini-2.5-pro")
+
+
+def configure_gemini_model():
+    """
+    Configure and return a Gemini model instance using GEMINI_API_KEY.
+    """
+    # override=True ensures new keys in .env replace any old environment values
+    load_dotenv(override=True)
+    api_key = os.getenv("GEMINI_API_KEY")
+    if not api_key:
+        raise RuntimeError("GEMINI_API_KEY not found. Please set it in a .env file or environment variable.")
+
+    # If GOOGLE_API_KEY is set in the environment, google-genai may prefer it.
+    # We explicitly remove it so GEMINI_API_KEY is always used.
+    os.environ.pop("GOOGLE_API_KEY", None)
+
+    try:
+        from google import genai
+    except Exception as exc:
+        raise RuntimeError("google-genai not installed. Run: pip install -r requirements.txt") from exc
+
+    client = genai.Client(api_key=api_key)
+    return client
+
+
+def run_audit(
+    user_document_text: str,
+    user_document_file: str,
+    rag_text: str,
+    rag_files: List[str],
+) -> Tuple[str, str]:
+    """
+    Gradio callback to run the compliance audit.
+
+    Returns:
+    - JSON string (pretty-printed)
+    - Markdown report
+    """
+    # Resolve main user document text:
+    # If a file is uploaded, it overrides the textbox content.
+    user_document_text = (user_document_text or "").strip()
+    user_document_file = (user_document_file or "").strip()
+    
+    warnings = []
+
+    if user_document_file:
+        # Check file type for user-uploaded document
+        is_valid, warning_msg = is_supported_file_type(user_document_file)
+        if not is_valid:
+            warnings.append(warning_msg)
+            return "\n".join(warnings) + "\n\nERROR: Please upload a supported file type (.txt, .pdf, or .docx) or paste text instead.", ""
+        
+        try:
+            user_document = extract_text_from_path(user_document_file, show_warning=True)
+        except Exception as exc:
+            return f"ERROR reading uploaded user document: {exc}", ""
+    else:
+        user_document = user_document_text
+
+    if not user_document.strip():
+        return "ERROR: Please provide a user document to be audited.", ""
+
+    rag_contexts: List[Tuple[str, str]] = []
+
+    # Check whether user has provided any reference documents (text or files).
+    user_has_refs = bool(rag_text and rag_text.strip()) or bool(rag_files)
+
+    if user_has_refs:
+        # Use ONLY the references explicitly provided by the user.
+        if rag_text and rag_text.strip():
+            rag_contexts.append(("Pasted RAG Text", rag_text.strip()))
+
+        if rag_files:
+            for path in rag_files:
+                # Check file type for user-uploaded reference files
+                is_valid, warning_msg = is_supported_file_type(path)
+                if not is_valid:
+                    warnings.append(warning_msg)
+                    continue  # Skip this file
+                
+                try:
+                    label = os.path.basename(path)
+                    content = extract_text_from_path(path, show_warning=True)
+                    rag_contexts.append((label, content))
+                except Exception as exc:
+                    warnings.append(f"⚠️ WARNING: Error reading file '{os.path.basename(path)}': {exc}")
+    else:
+        # No user-provided reference docs: fall back to reference_docs directory.
+        # Silently skip unsupported files in reference_docs (no warnings).
+        if os.path.isdir(REFERENCE_DIR):
+            for name in os.listdir(REFERENCE_DIR):
+                full_path = os.path.join(REFERENCE_DIR, name)
+                if not os.path.isfile(full_path):
+                    continue
+                try:
+                    # Silently skip unsupported files in reference_docs folder
+                    content = extract_text_from_path(full_path, show_warning=False)
+                except Exception:
+                    continue  # Silently skip unsupported or unreadable files
+                rag_contexts.append((name, content))
+
+    # Show warnings if any (before running audit)
+    warning_text = ""
+    if warnings:
+        warning_text = "\n\n".join(warnings) + "\n\n" + "="*50 + "\n\n"
+    
+    # Check database health (silently)
+    db_status = ""
+    try:
+        from database_manager import get_database_manager
+        db_manager = get_database_manager()
+        health = db_manager.check_database_health()
+        if health["status"] == "healthy" and health["document_count"] > 0:
+            db_status = f"Vector DB: {health['document_count']} chunks indexed | "
+        elif health["status"] == "empty":
+            db_status = "Vector DB empty - using provided documents | "
+    except:
+        pass
+    
+    try:
+        client = configure_gemini_model()
+        model_name = os.getenv("GEMINI_MODEL", DEFAULT_GEMINI_MODEL)
+        use_agentic = os.getenv("USE_AGENTIC", "true").lower() == "true"
+        result = call_llm_with_gemini(client, model_name, user_document, rag_contexts, use_agentic=use_agentic)
+    except Exception as exc:
+        model_name = os.getenv("GEMINI_MODEL", DEFAULT_GEMINI_MODEL)
+        msg = f"ERROR while calling Gemini model '{model_name}': {exc}"
+        
+        if "NOT_FOUND" in str(exc) or "404" in str(exc) or "not found" in str(exc).lower():
+            msg += (
+                "\n\n❌ **Model not found!** The model name you specified doesn't exist."
+                "\n\n**To see available models, run:**"
+                "\n```bash"
+                "\npython list_gemini_models.py"
+                "\n```"
+                "\n\n**Recommended models:**"
+                "\n- `models/gemini-2.5-pro` (stable, best quality)"
+                "\n- `models/gemini-2.5-flash` (faster, cheaper)"
+                "\n- `models/gemini-3-pro-preview` (latest preview)"
+                "\n\nSet `GEMINI_MODEL` in your `.env` file to one of the available models."
+            )
+        elif "RESOURCE_EXHAUSTED" in str(exc) or "429" in str(exc) or "quota" in str(exc).lower():
+            msg += (
+                "\n\nYour Gemini API key currently has **no available quota** for this model."
+                "\n- If you intended to use a paid plan, enable billing for the Gemini API project."
+                "\n- Or switch to a different available model in your `.env` via `GEMINI_MODEL=`."
+                "\n\n**Tip:** Run `python list_gemini_models.py` to see available models."
+            )
+        else:
+            msg += (
+                "\n\n**Tip:** Run `python list_gemini_models.py` to see available models."
+            )
+        return warning_text + msg, ""
+
+    json_str = json.dumps(result, indent=2, ensure_ascii=False)
+    human_md = result.get("humanized_summary_markdown", "")
+    
+    # Prepend warnings to JSON output if any
+    if warnings:
+        json_str = warning_text + json_str
+
+    return json_str, human_md
+
+
+def build_interface() -> gr.Blocks:
+    with gr.Blocks(title="AI Legal Compliance Auditor & Redrafter") as demo:
+        gr.Markdown(
+            """
+            ## AI Legal Compliance Auditor & Redrafter
+
+            **Features:**
+            - **Vector Database**: Semantic search for regulations
+            - **Agentic AI**: Multi-step reasoning with tools
+            - **Hybrid Search**: Semantic + keyword search
+
+            **Supported file types:** `.txt`, `.pdf`, `.docx` only
+            
+            - Upload or paste the **document to be audited** (Word, PDF, or text file).
+            - Optionally paste additional **Acts / policies / regulations** in the text box.
+            - Or upload one or more **reference documents** (.txt, .pdf, or .docx files).
+            - If you don't provide reference documents, the system will use **semantic search** from the vector database.
+            - Click **Run audit** to get:
+              - A structured **JSON compliance audit**, and
+              - A **Markdown Compliance Audit Report** ready to share.
+            
+            """
+        )
+        ##**💡 Tip**: Run `python initialize_database.py` to index reference documents for semantic search.
+
+        with gr.Row():
+            user_document_file = gr.File(
+                label="Upload user document (.txt, .pdf, .docx) - optional",
+                file_count="single",
+                type="filepath",
+            )
+
+        with gr.Row():
+            user_document = gr.Textbox(
+                label="User document to be audited (paste text if no file uploaded)",
+                placeholder="Paste the full text of the contract / policy / handbook here...",
+                lines=20,
+            )
+
+        with gr.Row():
+            rag_text = gr.Textbox(
+                label="RAG context (Acts / Policies / Regulations) - optional",
+                placeholder="Paste any legal / regulatory excerpts here...",
+                lines=12,
+            )
+
+        with gr.Row():
+            rag_files = gr.Files(
+                label="Reference documents (optional, .txt / .pdf / .docx)",
+                file_count="multiple",
+                type="filepath",
+            )
+
+        run_button = gr.Button("Run audit", variant="primary")
+
+        with gr.Row():
+            json_output = gr.Textbox(
+                label="JSON audit result",
+                lines=20,
+            )
+
+        md_output = gr.Markdown(label="Compliance Audit Report (Markdown)")
+
+        run_button.click(
+            fn=run_audit,
+            inputs=[user_document, user_document_file, rag_text, rag_files],
+            outputs=[json_output, md_output],
+        )
+
+    return demo
+
+
+if __name__ == "__main__":
+    app = build_interface()
+    app.launch()
+

initialize_database.py

@@ -0,0 +1,82 @@
+"""
+Database initialization script for production deployment.
+Run this script to index reference documents into the vector database.
+"""
+import os
+import sys
+from pathlib import Path
+
+from database_manager import get_database_manager
+
+
+def main():
+    """Initialize the vector database with reference documents."""
+    print("=" * 60)
+    print("Vector Database Initialization")
+    print("=" * 60)
+    print()
+    
+    # Check if reference_docs directory exists
+    reference_dir = "./reference_docs"
+    if not os.path.isdir(reference_dir):
+        print(f"ERROR: Reference directory '{reference_dir}' not found.")
+        print(f"   Please create the directory and add regulation documents.")
+        sys.exit(1)
+    
+    # Get database manager
+    try:
+        db_manager = get_database_manager()
+    except Exception as e:
+        print(f"ERROR: Error initializing database manager: {e}")
+        print("   Make sure all dependencies are installed:")
+        print("   pip install -r requirements.txt")
+        sys.exit(1)
+    
+    # Check database health
+    print("Checking database health...")
+    health = db_manager.check_database_health()
+    
+    if health["status"] == "healthy" and health["document_count"] > 0:
+        print(f"OK: Database is healthy with {health['document_count']} documents.")
+        response = input("\nDo you want to reindex? (y/n): ").strip().lower()
+        if response != 'y':
+            print("Skipping reindexing.")
+            sys.exit(0)
+        force_reindex = True
+    else:
+        print("WARNING: Database is empty or has issues.")
+        force_reindex = False
+    
+    # Index documents
+    print("\nStarting indexing process...")
+    results = db_manager.index_reference_documents(force_reindex=force_reindex)
+    
+    # Print results
+    print("\n" + "=" * 60)
+    print("Indexing Results")
+    print("=" * 60)
+    print(f"SUCCESS: Successfully indexed: {results['indexed']} documents")
+    print(f"FAILED: {results['failed']} documents")
+    
+    if results['errors']:
+        print(f"\nWARNINGS: Errors ({len(results['errors'])}):")
+        for error in results['errors'][:10]:  # Show first 10 errors
+            print(f"   - {error}")
+        if len(results['errors']) > 10:
+            print(f"   ... and {len(results['errors']) - 10} more errors")
+    
+    # Show database stats
+    print("\n" + "=" * 60)
+    print("Database Statistics")
+    print("=" * 60)
+    stats = db_manager.get_database_stats()
+    print(f"Collection: {stats.get('collection_name', 'N/A')}")
+    print(f"Document chunks: {stats.get('document_count', 0)}")
+    print(f"Reference files: {stats.get('reference_files', 0)}")
+    
+    print("\nSUCCESS: Database initialization complete!")
+    print("\nYou can now use the compliance auditor with semantic search.")
+
+
+if __name__ == "__main__":
+    main()

list_gemini_models.py

@@ -0,0 +1,62 @@
+"""
+Utility script to list available Gemini models.
+Run this to see which models you can use with your API key.
+"""
+import os
+from dotenv import load_dotenv
+
+load_dotenv(override=True)
+
+try:
+    from google import genai
+    
+    api_key = os.getenv("GEMINI_API_KEY") or os.getenv("GOOGLE_API_KEY")
+    if not api_key:
+        print("ERROR: GEMINI_API_KEY or GOOGLE_API_KEY not found in .env file or environment.")
+        exit(1)
+    
+    client = genai.Client(api_key=api_key)
+    models = list(client.models.list())
+    
+    import sys
+    # Fix encoding for Windows console
+    if sys.platform == "win32":
+        import codecs
+        sys.stdout = codecs.getwriter("utf-8")(sys.stdout.buffer, "strict")
+        sys.stderr = codecs.getwriter("utf-8")(sys.stderr.buffer, "strict")
+    
+    print(f"\n=== Available Gemini Models ({len(models)} total) ===\n")
+    
+    # Filter and categorize models
+    text_models = [m for m in models if "gemini" in m.name.lower() and "generate" not in m.name.lower() and "embedding" not in m.name.lower()]
+    embedding_models = [m for m in models if "embedding" in m.name.lower()]
+    other_models = [m for m in models if m not in text_models and m not in embedding_models]
+    
+    print("TEXT GENERATION MODELS (for compliance auditing):")
+    print("-" * 60)
+    for model in sorted(text_models, key=lambda x: x.name):
+        # Highlight recommended models
+        if "gemini-2.5-pro" in model.name and "preview" not in model.name:
+            print(f"  [RECOMMENDED] {model.name}")
+        elif "gemini-2.5-flash" in model.name and "preview" not in model.name:
+            print(f"  [FAST] {model.name}")
+        elif "gemini-3-pro" in model.name:
+            print(f"  [PREVIEW] {model.name}")
+        else:
+            print(f"  - {model.name}")
+    
+    if embedding_models:
+        print(f"\nEMBEDDING MODELS ({len(embedding_models)}):")
+        print("-" * 60)
+        for model in sorted(embedding_models, key=lambda x: x.name)[:5]:
+            print(f"  - {model.name}")
+        if len(embedding_models) > 5:
+            print(f"  ... and {len(embedding_models) - 5} more")
+    
+    print(f"\nTIP: Set GEMINI_MODEL in your .env file to one of the models above.")
+    print(f"   Example: GEMINI_MODEL=models/gemini-2.5-pro\n")
+    
+except ImportError:
+    print("ERROR: google-genai not installed. Run: pip install -r requirements.txt")
+except Exception as exc:
+    print(f"ERROR: {exc}")

main.py

@@ -0,0 +1,214 @@
+import os
+from typing import List, Tuple
+
+from dotenv import load_dotenv
+
+from auditor import call_llm_with_gemini
+from doc_utils import extract_text_from_path, is_supported_file_type
+
+
+REFERENCE_DIR = os.path.join(os.path.dirname(__file__), "reference_docs")
+DEFAULT_GEMINI_MODEL = os.getenv("GEMINI_MODEL", "models/gemini-2.5-flash")
+
+
+def prompt_for_document(prompt_label: str) -> str:
+    print(f"\n=== {prompt_label} ===")
+    print("Choose input method:")
+    print("1) Paste text directly")
+    print("2) Provide path to a file (.txt, .pdf, .docx)")
+    choice = input("Enter 1 or 2: ").strip()
+
+    if choice == "1":
+        print("\nPaste your text below. End with a single line containing only 'EOF':\n")
+        lines: List[str] = []
+        while True:
+            line = input()
+            if line.strip() == "EOF":
+                break
+            lines.append(line)
+        return "\n".join(lines).strip()
+    elif choice == "2":
+        path = input("Enter file path: ").strip().strip('"')
+        # Check file type for user-provided document
+        is_valid, warning_msg = is_supported_file_type(path)
+        if not is_valid:
+            print(f"\n{warning_msg}")
+            print("Please try again with a supported file type (.txt, .pdf, or .docx).\n")
+            return prompt_for_document(prompt_label)
+        return extract_text_from_path(path, show_warning=True)
+    else:
+        print("Invalid choice, please try again.")
+        return prompt_for_document(prompt_label)
+
+
+def prompt_for_rag_contexts() -> List[Tuple[str, str]]:
+    print("\n=== RAG CONTEXT DOCUMENTS (Acts / Policies / Regulations) ===")
+    contexts: List[Tuple[str, str]] = []
+
+    while True:
+        print("\nAdd a new RAG context?")
+        print("1) Yes - paste text")
+        print("2) Yes - from file (.txt, .pdf, .docx)")    
+        print("3) No more RAG documents (continue)")
+        choice = input("Enter 1, 2, or 3: ").strip()
+
+        if choice == "3":
+            break
+
+        label = input("Enter a short label for this RAG source (e.g., 'IT Act Sec 43A'): ").strip()
+
+        if choice == "1":
+            print("\nPaste the RAG context text. End with a single line containing only 'EOF':\n")
+            lines: List[str] = []
+            while True:
+                line = input()
+                if line.strip() == "EOF":
+                    break
+                lines.append(line)
+            contexts.append((label, "\n".join(lines).strip()))
+        elif choice == "2":
+            path = input("Enter file path: ").strip().strip('"')
+            # Check file type for user-provided reference file
+            is_valid, warning_msg = is_supported_file_type(path)
+            if not is_valid:
+                print(f"\n{warning_msg}")
+                print("Skipping this file. Please try again with a supported file type (.txt, .pdf, or .docx).\n")
+                continue
+            try:
+                contexts.append((label, extract_text_from_path(path, show_warning=True)))
+            except Exception as exc:
+                print(f" WARNING: Error reading file '{path}': {exc}")
+                print("Skipping this file.\n")
+        else:
+            print("Invalid choice. Please try again.")
+
+    # If user did not provide any RAG contexts, fall back to reference_docs folder.
+    # Silently skip unsupported files in reference_docs (no warnings).
+    if not contexts:
+        if os.path.isdir(REFERENCE_DIR):
+            for name in os.listdir(REFERENCE_DIR):
+                full_path = os.path.join(REFERENCE_DIR, name)
+                if not os.path.isfile(full_path):
+                    continue
+                try:
+                    # Silently skip unsupported files in reference_docs folder
+                    text = extract_text_from_path(full_path, show_warning=False)
+                except Exception:
+                    continue  # Silently skip unsupported or unreadable files
+                contexts.append((name, text))
+
+    return contexts
+
+
+def configure_gemini_model():
+    # override=True ensures new keys in .env replace any old environment values
+    load_dotenv(override=True)
+    api_key = os.getenv("GEMINI_API_KEY") or os.getenv("GOOGLE_API_KEY")
+    if not api_key:
+        raise RuntimeError("GEMINI_API_KEY not found. Please set it in a .env file or environment variable.")
+
+    # If GOOGLE_API_KEY is set in the environment, google-genai may prefer it.
+    # We explicitly remove it so GEMINI_API_KEY is always used.
+    os.environ.pop("GOOGLE_API_KEY", None)
+
+    try:
+        from google import genai
+    except Exception as exc:
+        raise RuntimeError("google-genai not installed. Run: pip install -r requirements.txt") from exc
+
+    client = genai.Client(api_key=api_key)
+    return client
+
+
+def main():
+    print("=== AI Legal Compliance Auditor & Redrafter (Production - Vector DB + Agentic AI) ===")
+    
+    # Check database health
+    try:
+        from database_manager import get_database_manager
+        db_manager = get_database_manager()
+        health = db_manager.check_database_health()
+        
+        if health["status"] == "empty":
+            print("\n⚠️  Warning: Vector database is empty!")
+            print("   Run 'python initialize_database.py' to index reference documents.")
+            print("   The system will use provided RAG contexts as fallback.\n")
+        elif health["status"] == "healthy":
+            print(f"✅ Vector database ready ({health['document_count']} document chunks indexed)\n")
+    except Exception as e:
+        print(f"⚠️  Warning: Could not check database: {e}")
+        print("   The system will use provided RAG contexts.\n")
+
+    user_document = prompt_for_document("USER DOCUMENT TO BE AUDITED")
+    rag_contexts = prompt_for_rag_contexts()
+
+    print("\nRunning compliance audit with Gemini... this may take a moment.\n")
+    
+    # Check if user wants agentic mode
+    use_agentic = os.getenv("USE_AGENTIC", "true").lower() == "true"
+    use_vector_search = os.getenv("USE_VECTOR_SEARCH", "true").lower() == "true"
+    
+    if use_agentic:
+        print("🤖 Agentic AI mode: ENABLED (multi-step reasoning with tools)")
+    else:
+        print("📝 Standard mode: Single-shot LLM call")
+    
+    if use_vector_search:
+        print("🔍 Vector search: ENABLED (semantic search from database)")
+    else:
+        print("📄 Text search: Using provided documents only")
+    
+    client = configure_gemini_model()
+    model_name = os.getenv("GEMINI_MODEL", DEFAULT_GEMINI_MODEL)
+    try:
+        result = call_llm_with_gemini(client, model_name, user_document, rag_contexts, use_agentic=use_agentic)
+    except Exception as exc:
+        print(f"\nERROR while calling Gemini model '{model_name}': {exc}\n")
+        if "NOT_FOUND" in str(exc) or "404" in str(exc) or "not found" in str(exc).lower():
+            print("❌ Model not found! The model name you specified doesn't exist.\n")
+            print("To see available models, run:")
+            print("  python list_gemini_models.py\n")
+            print("Recommended models:")
+            print("  - models/gemini-2.5-pro (stable, best quality)")
+            print("  - models/gemini-2.5-flash (faster, cheaper)")
+            print("  - models/gemini-3-pro-preview (latest preview)\n")
+            print("Set GEMINI_MODEL in your .env file to one of the available models.\n")
+        elif "RESOURCE_EXHAUSTED" in str(exc) or "429" in str(exc) or "quota" in str(exc).lower():
+            print("Your Gemini API key currently has no available quota for this model.\n")
+            print("- Enable billing / increase quota for your Gemini API project, or")
+            print("- Switch GEMINI_MODEL in your .env to a model you have quota for.\n")
+        else:
+            print("If this is a model-not-found error, run 'python list_gemini_models.py' to see available models.\n")
+        raise
+
+    # The model already includes the humanized summary as part of the JSON.
+    # We simply print the JSON and then the Markdown summary.
+    print("\n=== RAW JSON RESULT ===")
+    import json
+
+    print(json.dumps(result, indent=2, ensure_ascii=False))
+
+    human_md = result.get("humanized_summary_markdown", "")
+    if human_md:
+        print("\n---\n")
+        print(human_md)
+
+    # Optional: ask user whether to save outputs
+    save_choice = input("\nDo you want to save the JSON and Markdown to files? (y/n): ").strip().lower()
+    if save_choice == "y":
+        json_path = input("Enter path for JSON output file (e.g., audit_result.json): ").strip()
+        md_path = input("Enter path for Markdown report file (e.g., audit_report.md): ").strip()
+
+        with open(json_path, "w", encoding="utf-8") as jf:
+            json.dump(result, jf, indent=2, ensure_ascii=False)
+
+        with open(md_path, "w", encoding="utf-8") as mf:
+            mf.write(human_md)
+
+        print(f"\nSaved JSON to {json_path}")
+        print(f"Saved Markdown report to {md_path}")
+
+
+if __name__ == "__main__":
+    main()
+

requirements.txt

@@ -0,0 +1,23 @@
+google-genai>=0.6.0
+python-dotenv>=1.0.0
+gradio>=5.0.0
+python-docx>=1.0.0
+pypdf>=5.0.0
+langchain>=0.1.0
+langchain-google-genai>=1.0.0
+langchain-core>=0.1.0
+langchain-community>=0.0.20
+langchain-text-splitters>=0.0.1
+langchain-chroma>=0.1.0
+chromadb>=0.4.0
+sentence-transformers>=2.2.0
+numpy>=1.24.0
+protobuf>=5.26.1,<6.0.0
+# Note: If you have tensorflow-intel installed, it will show a conflict warning.
+# This is safe to ignore - the compliance auditor doesn't require TensorFlow.
+# To remove the warning: pip uninstall tensorflow-intel
+
+# IMPORTANT: Do NOT install 'docx' package - it conflicts with python-docx
+# If you see "ModuleNotFoundError: No module named 'exceptions'" error:
+#   pip uninstall docx
+#   pip install python-docx

retrieval.py

@@ -0,0 +1,225 @@
+"""
+Retrieval module for production deployment.
+Handles semantic search and hybrid search strategies.
+"""
+from typing import List, Dict, Any, Optional, Tuple
+from langchain_core.documents import Document
+import re
+
+from vector_db import get_vector_database
+
+
+class RetrievalSystem:
+    """
+    Handles retrieval of relevant regulations using semantic search.
+    """
+    
+    def __init__(self, vector_db=None):
+        """
+        Initialize retrieval system.
+        
+        Args:
+            vector_db: VectorDatabase instance (optional)
+        """
+        self.vector_db = vector_db or get_vector_database()
+    
+    def semantic_search(
+        self,
+        query: str,
+        k: int = 5,
+        min_score: float = 0.0,
+        filter_dict: Optional[Dict[str, Any]] = None
+    ) -> List[Document]:
+        """
+        Perform semantic search for relevant regulations.
+        
+        Args:
+            query: Search query
+            k: Number of results
+            min_score: Minimum similarity score
+            filter_dict: Optional metadata filters
+        
+        Returns:
+            List of relevant Document objects
+        """
+        if not query or not query.strip():
+            return []
+        
+        # Perform semantic search
+        results_with_scores = self.vector_db.search_with_scores(
+            query,
+            k=k * 2,  # Get more results for filtering
+            filter_dict=filter_dict
+        )
+        
+        # Filter by minimum score and limit to k
+        filtered_results = [
+            doc for doc, score in results_with_scores
+            if score >= min_score
+        ][:k]
+        
+        return filtered_results
+    
+    def hybrid_search(
+        self,
+        query: str,
+        k: int = 5,
+        semantic_weight: float = 0.7,
+        keyword_weight: float = 0.3,
+        filter_dict: Optional[Dict[str, Any]] = None
+    ) -> List[Document]:
+        """
+        Perform hybrid search (semantic + keyword).
+        
+        Args:
+            query: Search query
+            k: Number of results
+            semantic_weight: Weight for semantic search
+            keyword_weight: Weight for keyword search
+            filter_dict: Optional filters
+        
+        Returns:
+            List of relevant Document objects
+        """
+        # Semantic search
+        semantic_results = self.semantic_search(query, k=k * 2, filter_dict=filter_dict)
+        
+        # Keyword search (simple implementation)
+        keyword_results = self._keyword_search(query, filter_dict=filter_dict)
+        
+        # Combine and rank
+        combined = self._merge_results(
+            semantic_results,
+            keyword_results,
+            semantic_weight,
+            keyword_weight
+        )
+        
+        return combined[:k]
+    
+    def _keyword_search(
+        self,
+        query: str,
+        filter_dict: Optional[Dict[str, Any]] = None
+    ) -> List[Document]:
+        """
+        Simple keyword-based search.
+        
+        Args:
+            query: Search query
+            filter_dict: Optional filters
+        
+        Returns:
+            List of Document objects
+        """
+        # Extract keywords
+        keywords = re.findall(r'\b\w+\b', query.lower())
+        
+        # Get all documents (this is simplified - in production, use proper indexing)
+        # For now, use semantic search as fallback
+        return self.semantic_search(query, k=10, filter_dict=filter_dict)
+    
+    def _merge_results(
+        self,
+        semantic_results: List[Document],
+        keyword_results: List[Document],
+        semantic_weight: float,
+        keyword_weight: float
+    ) -> List[Document]:
+        """
+        Merge and rank results from different search methods.
+        
+        Args:
+            semantic_results: Results from semantic search
+            keyword_results: Results from keyword search
+            semantic_weight: Weight for semantic results
+            keyword_weight: Weight for keyword results
+        
+        Returns:
+            Merged and ranked results
+        """
+        # Create score dictionary
+        doc_scores = {}
+        
+        # Add semantic results
+        for idx, doc in enumerate(semantic_results):
+            doc_id = id(doc)
+            doc_scores[doc_id] = doc_scores.get(doc_id, 0) + semantic_weight * (1.0 - idx / len(semantic_results))
+            doc_scores[doc_id] = doc_scores.get(doc_id, 0) + semantic_weight
+        
+        # Add keyword results
+        for idx, doc in enumerate(keyword_results):
+            doc_id = id(doc)
+            doc_scores[doc_id] = doc_scores.get(doc_id, 0) + keyword_weight * (1.0 - idx / len(keyword_results))
+        
+        # Create document map
+        doc_map = {}
+        for doc in semantic_results + keyword_results:
+            doc_map[id(doc)] = doc
+        
+        # Sort by score
+        sorted_docs = sorted(
+            doc_map.items(),
+            key=lambda x: doc_scores.get(x[0], 0),
+            reverse=True
+        )
+        
+        return [doc for _, doc in sorted_docs]
+    
+    def retrieve_relevant_regulations(
+        self,
+        user_document: str,
+        k: int = 5,
+        use_hybrid: bool = True
+    ) -> List[Tuple[str, str]]:
+        """
+        Retrieve relevant regulations for a user document.
+        
+        Args:
+            user_document: User's document text
+            k: Number of regulations to retrieve
+            use_hybrid: Whether to use hybrid search
+        
+        Returns:
+            List of (label, text) tuples
+        """
+        if not user_document or not user_document.strip():
+            return []
+        
+        # Extract key phrases from user document for search
+        # Use first 500 chars as query (or full doc if shorter)
+        query = user_document[:500] if len(user_document) > 500 else user_document
+        
+        # Perform search
+        if use_hybrid:
+            results = self.hybrid_search(query, k=k)
+        else:
+            results = self.semantic_search(query, k=k)
+        
+        # Convert to (label, text) format
+        regulations = []
+        seen_sources = set()
+        
+        for doc in results:
+            source = doc.metadata.get("source", "Unknown")
+            
+            # Avoid duplicates from same source
+            if source in seen_sources:
+                continue
+            
+            seen_sources.add(source)
+            regulations.append((source, doc.page_content))
+        
+        return regulations
+
+
+# Global instance
+_retrieval_system: Optional[RetrievalSystem] = None
+
+
+def get_retrieval_system() -> RetrievalSystem:
+    """Get or create global retrieval system instance."""
+    global _retrieval_system
+    if _retrieval_system is None:
+        _retrieval_system = RetrievalSystem()
+    return _retrieval_system

vector_db.py

@@ -0,0 +1,282 @@
+"""
+Vector database module for production deployment.
+Uses ChromaDB for storing and retrieving regulation embeddings.
+"""
+import os
+from typing import List, Dict, Any, Optional, Tuple
+from pathlib import Path
+
+try:
+    import chromadb
+    from chromadb.config import Settings
+except ImportError:
+    chromadb = None
+    Settings = None
+
+try:
+    from langchain_chroma import Chroma
+except ImportError:
+    try:
+        from langchain.vectorstores import Chroma
+    except ImportError:
+        try:
+            from langchain_community.vectorstores import Chroma
+        except ImportError:
+            Chroma = None
+
+try:
+    from langchain_core.documents import Document
+except ImportError:
+    try:
+        from langchain_core.documents import Document
+    except ImportError:
+        Document = None
+
+from embeddings import get_embedding_generator
+
+
+class VectorDatabase:
+    """
+    Manages vector database operations for regulation storage and retrieval.
+    """
+    
+    def __init__(
+        self,
+        persist_directory: str = "./chroma_db",
+        collection_name: str = "regulations"
+    ):
+        """
+        Initialize vector database.
+        
+        Args:
+            persist_directory: Directory to persist database
+            collection_name: Name of the collection
+        """
+        if chromadb is None:
+            raise RuntimeError(
+                "chromadb not installed. Run: pip install chromadb"
+            )
+        
+        if Chroma is None:
+            raise RuntimeError(
+                "langchain.vectorstores.Chroma not available. Run: pip install langchain langchain-community"
+            )
+        
+        self.persist_directory = persist_directory
+        self.collection_name = collection_name
+        
+        # Ensure directory exists
+        Path(persist_directory).mkdir(parents=True, exist_ok=True)
+        
+        # Initialize embeddings
+        self.embedding_generator = get_embedding_generator()
+        
+        # Initialize ChromaDB
+        self._initialize_database()
+    
+    def _initialize_database(self):
+        """Initialize ChromaDB with embeddings."""
+        try:
+            # Create vector store
+            self.vector_store = Chroma(
+                persist_directory=self.persist_directory,
+                collection_name=self.collection_name,
+                embedding_function=self.embedding_generator.embeddings
+            )
+        except Exception as e:
+            print(f"⚠️  Warning: Failed to load existing database: {e}")
+            # Create new database
+            self.vector_store = Chroma(
+                persist_directory=self.persist_directory,
+                collection_name=self.collection_name,
+                embedding_function=self.embedding_generator.embeddings
+            )
+    
+    def add_documents(
+        self,
+        documents: List[Document],
+        batch_size: int = 100
+    ) -> List[str]:
+        """
+        Add documents to the vector database.
+        
+        Args:
+            documents: List of Document objects
+            batch_size: Number of documents to add at once
+        
+        Returns:
+            List of document IDs
+        """
+        if not documents:
+            return []
+        
+        ids = []
+        
+        # Add in batches
+        for i in range(0, len(documents), batch_size):
+            batch = documents[i:i + batch_size]
+            
+            try:
+                batch_ids = self.vector_store.add_documents(batch)
+                ids.extend(batch_ids)
+            except Exception as e:
+                print(f"⚠️  Warning: Failed to add batch {i//batch_size + 1}: {e}")
+        
+        # Persist changes
+        self.vector_store.persist()
+        
+        return ids
+    
+    def search(
+        self,
+        query: str,
+        k: int = 5,
+        filter_dict: Optional[Dict[str, Any]] = None
+    ) -> List[Document]:
+        """
+        Search for similar documents using semantic search.
+        
+        Args:
+            query: Search query
+            k: Number of results to return
+            filter_dict: Optional metadata filters
+        
+        Returns:
+            List of similar Document objects
+        """
+        if not query or not query.strip():
+            return []
+        
+        try:
+            if filter_dict:
+                results = self.vector_store.similarity_search(
+                    query,
+                    k=k,
+                    filter=filter_dict
+                )
+            else:
+                results = self.vector_store.similarity_search(query, k=k)
+            
+            return results
+        except Exception as e:
+            print(f"⚠️  Warning: Search failed: {e}")
+            return []
+    
+    def search_with_scores(
+        self,
+        query: str,
+        k: int = 5,
+        filter_dict: Optional[Dict[str, Any]] = None
+    ) -> List[Tuple[Document, float]]:
+        """
+        Search with similarity scores.
+        
+        Args:
+            query: Search query
+            k: Number of results
+            filter_dict: Optional filters
+        
+        Returns:
+            List of (Document, score) tuples
+        """
+        if not query or not query.strip():
+            return []
+        
+        try:
+            if filter_dict:
+                results = self.vector_store.similarity_search_with_score(
+                    query,
+                    k=k,
+                    filter=filter_dict
+                )
+            else:
+                results = self.vector_store.similarity_search_with_score(query, k=k)
+            
+            return results
+        except Exception as e:
+            print(f"⚠️  Warning: Search with scores failed: {e}")
+            return []
+    
+    def delete_documents(
+        self,
+        ids: Optional[List[str]] = None,
+        filter_dict: Optional[Dict[str, Any]] = None
+    ) -> bool:
+        """
+        Delete documents from the database.
+        
+        Args:
+            ids: List of document IDs to delete
+            filter_dict: Optional metadata filters
+        
+        Returns:
+            True if successful
+        """
+        try:
+            if ids:
+                self.vector_store.delete(ids=ids)
+            elif filter_dict:
+                # ChromaDB doesn't support filter-based delete directly
+                # Need to find IDs first
+                all_docs = self.vector_store.get()
+                # This is a simplified version - full implementation would filter
+                pass
+            
+            self.vector_store.persist()
+            return True
+        except Exception as e:
+            print(f"⚠️  Warning: Delete failed: {e}")
+            return False
+    
+    def get_collection_info(self) -> Dict[str, Any]:
+        """
+        Get information about the collection.
+        
+        Returns:
+            Dictionary with collection statistics
+        """
+        try:
+            collection = self.vector_store._collection
+            count = collection.count()
+            
+            return {
+                "collection_name": self.collection_name,
+                "document_count": count,
+                "persist_directory": self.persist_directory
+            }
+        except Exception as e:
+            return {
+                "error": str(e),
+                "collection_name": self.collection_name
+            }
+    
+    def clear_collection(self) -> bool:
+        """
+        Clear all documents from the collection.
+        
+        Returns:
+            True if successful
+        """
+        try:
+            # Delete the collection and recreate
+            import shutil
+            if os.path.exists(self.persist_directory):
+                shutil.rmtree(self.persist_directory)
+            Path(self.persist_directory).mkdir(parents=True, exist_ok=True)
+            self._initialize_database()
+            return True
+        except Exception as e:
+            print(f"⚠️  Warning: Clear collection failed: {e}")
+            return False
+
+
+# Global instance
+_vector_db: Optional[VectorDatabase] = None
+
+
+def get_vector_database() -> VectorDatabase:
+    """Get or create global vector database instance."""
+    global _vector_db
+    if _vector_db is None:
+        _vector_db = VectorDatabase()
+    return _vector_db