Initial commit

.github/workflows/quality_gate.yml

@@ -0,0 +1,32 @@
+name: Production Quality Gate
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+
+jobs:
+  build-and-audit:
+    runs-on: ubuntu-latest
+    
+    steps:
+    - uses: actions/checkout@v3
+    
+    - name: Set up Python 3.10
+      uses: actions/setup-python@v3
+      with:
+        python-version: "3.10"
+        
+    - name: Install Dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install flake8
+        if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
+        
+    - name: Lint with Flake8 (Style Enforcer)
+      run: |
+        # stop the build if there are Python syntax errors or undefined names
+        flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
+        # exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide
+        flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics

.gitignore

@@ -0,0 +1,207 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/

Dockerfile

@@ -0,0 +1,21 @@
+# 1. Base Image
+FROM python:3.10-slim
+
+# 2. INSTALL GIT (Crucial Fix)
+RUN apt-get update && \
+    apt-get install -y git && \
+    rm -rf /var/lib/apt/lists/*
+
+# 3. Setup App
+WORKDIR /app
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+COPY . .
+
+# 4. Permissions
+RUN useradd -m -u 1000 user
+USER user
+ENV PATH="/home/user/.local/bin:$PATH"
+
+# 5. Run Streamlit
+CMD ["streamlit", "run", "app.py", "--server.port=7860", "--server.address=0.0.0.0", "--server.enableCORS=false", "--server.enableXsrfProtection=false"]

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 James Zokah 
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,112 @@
+<div align="center">
+<!-- HERO HERO (Clickable) -->
+  <img src="assets/DocuTrace_hero.jpg" width="100%" alt="DocuTrace header hero" style="border-radius: 8px; box-shadow: 0px 4px 12px rgba(0,0,0,0.3); border: 1px solid #30363d;">
+
+
+<br/><br/>
+
+# DocuTrace: Verifiable AI Auditor
+### *Precision Data Extraction with Pixel-Perfect Source Grounding*
+
+[![Streamlit](https://img.shields.io/badge/Frontend-Streamlit-FF4B4B?style=for-the-badge&logo=streamlit&logoColor=white)](https://streamlit.io/)
+[![LangExtract](https://img.shields.io/badge/Core-LangExtract-4285F4?style=for-the-badge&logo=google&logoColor=white)](https://github.com/google/langextract)
+[![Gemini](https://img.shields.io/badge/Intelligence-Gemini%202.5%20Flash-8E75B2?style=for-the-badge&logo=googlebard&logoColor=white)](https://ai.google.dev/)
+[![Status](https://img.shields.io/badge/Status-Production-success?style=for-the-badge)]()
+
+[View Live Demo](https://huggingface.co/spaces/EATosin/DocuTrace-10K-Analyst) • [Engineering Journey](#-engineering-journey-challenges--solutions) • [Architecture](#-system-architecture)
+
+</div>
+
+---
+
+##  Executive Summary
+**DocuTrace** is a specialized auditing tool designed for high-stakes domains (Legal, Finance, Compliance) where AI hallucinations are unacceptable.
+
+Unlike standard RAG (Retrieval Augmented Generation) pipelines that summarize text, DocuTrace utilizes **Google's LangExtract** library to perform **Source Grounding**. Every extracted data point is cryptographically linked to its specific coordinates in the source PDF, generating an interactive HTML audit trail.
+
+---
+
+## Engineering Journey: Challenges & Solutions
+Building a verifiable extraction engine involves overcoming significant "dependency hell" and rate-limiting barriers.
+
+### 1. The "Slim Image" Dependency Conflict
+*   **The Challenge:** We deployed using the standard `python:3.10-slim` Docker image to minimize boot time. However, the `LangExtract` library requires installation directly from GitHub source, which depends on `git`. The build failed with `ExecutableNotFound: git`.
+*   **The Solution:** Architected a custom multi-stage Dockerfile that injects system-level dependencies (`apt-get install git`) before the Python environment initializes, ensuring a successful build without bloating the final image.
+
+### 2. The PDF Parsing Bottleneck
+*   **The Challenge:** Financial 10-K reports often contain scanned pages or complex layouts that break standard OCR tools.
+*   **The Solution:** Implemented a robust `pypdf` pre-processing layer with a "Fail-Fast" mechanism. The system validates text density before passing data to the LLM, preventing wasted API tokens on unreadable files.
+
+### 3. API Rate Limiting (The "Thundering Herd")
+*   **The Challenge:** LangExtract is designed for enterprise usage (Vertex AI) and attempts parallel chunk processing. On the Gemini Free Tier, this triggered `429 Resource Exhausted` errors immediately.
+*   **The Solution:** Implemented an "Extraction Window" logic in the UI. Users select specific page ranges (e.g., "Risk Factors, Pages 15-20") rather than processing the entire 100-page document at once, keeping the request volume within the 15 RPM limit.
+
+---
+
+## System Architecture
+
+```mermaid
+graph TD
+    User[Financial Analyst] -->|Upload 10-K PDF| UI[Streamlit Interface]
+    User -->|Define Schema| UI
+    
+    subgraph Extraction Engine
+    UI -->|Raw Text| Preprocessor[PyPDF Chuncker]
+    Preprocessor -->|Context Blocks| LangExtract[LangExtract Library]
+    LangExtract -->|Inference Req| Gemini[Gemini 2.5 Flash]
+    Gemini -->|Structured Data| LangExtract
+    end
+    
+    LangExtract -->|HTML Generation| Visualizer[Interactive Highlighter]
+    Visualizer -->|Iframe Render| UI
+```
+
+### Core Components
+1.  **Frontend (Streamlit):** Handles file ingestion and renders the output within a secure container.
+2.  **Intelligence (Gemini 2.5 Flash):** Selected for its 1M token context window, allowing it to hold large document sections in working memory without RAG retrieval loss.
+3.  **Grounding (LangExtract):** Maps the LLM's JSON output back to the original PDF text spans using fuzzy matching algorithms.
+
+---
+
+## ⚠️ Limitations & Constraints
+This is a production-grade Proof of Concept (PoC) with specific constraints:
+
+*   **Text-Only Extraction:** The current pipeline extracts text. It does not parse charts, graphs, or tables (requires multimodal vision upgrade).
+*   **API Quotas:** The Live Demo operates on the Google Gemini Free Tier. Heavy usage may trigger temporary cooldowns (429 Errors).
+*   **Session State:** For privacy, all files are processed in ephemeral memory and discarded immediately after the session ends. No data is persisted.
+
+---
+
+## 🚀 Installation & Local Development
+
+### Prerequisites
+*   Python 3.10+
+*   Google Gemini API Key
+
+### Setup
+```bash
+# 1. Clone the repository
+git clone https://github.com/eatosin/DocuTrace-AI-Auditor.git
+cd DocuTrace-AI-Auditor
+
+# 2. Install dependencies (requires Git installed)
+pip install -r requirements.txt
+
+# 3. Configure Environment
+export GEMINI_API_KEY="your_key_here"
+
+# 4. Run the App
+streamlit run app.py
+```
+
+---
+
+## Author
+**Owadokun Tosin Tobi**
+*Senior AI Engineer | Specialist in MLOps & LLM Evaluation*
+
+*   **Portfolio:** [ReasonBench](https://github.com/eatosin/ReasonBench), [Sentinel](https://github.com/eatosin/Sentinel-MLOps)
+*   **Connect:** [LinkedIn](https://www.linkedin.com/in/owadokun-tosin-tobi-6159091a3?utm_source=share&utm_campaign=share_via&utm_content=profile&utm_medium=android_app)
+
+---
+*Built with Python, Google Cloud AI, and Engineering Rigor.*

app.py

@@ -0,0 +1,421 @@
+import streamlit as st
+import os
+import streamlit.components.v1 as components
+from datetime import datetime
+
+# --- Try to import optional dependencies ---
+try:
+    import google.generativeai as genai
+    GENAI_AVAILABLE = True
+except ImportError:
+    GENAI_AVAILABLE = False
+
+try:
+    import langextract as lx
+    LANGEXTRACT_AVAILABLE = True
+except ImportError:
+    LANGEXTRACT_AVAILABLE = False
+
+try:
+    from pypdf import PdfReader
+    PYPDF_AVAILABLE = True
+except ImportError:
+    PYPDF_AVAILABLE = False
+
+# --- CONFIG ---
+st.set_page_config(
+    page_title="DocuTrace AI",
+    layout="wide",
+    page_icon="🔍",
+    initial_sidebar_state="expanded"
+)
+
+# --- LOAD CUSTOM CSS ---
+def load_css():
+    css_file = os.path.join(os.path.dirname(__file__), "styles.css")
+    if os.path.exists(css_file):
+        with open(css_file, "r") as f:
+            st.markdown(f"<style>{f.read()}</style>", unsafe_allow_html=True)
+
+load_css()
+
+# --- SESSION STATE INIT ---
+if "messages" not in st.session_state:
+    st.session_state.messages = []
+if "extraction_count" not in st.session_state:
+    st.session_state.extraction_count = 0
+if "pages_processed" not in st.session_state:
+    st.session_state.pages_processed = 0
+
+# Load API Key
+api_key = os.getenv("GEMINI_API_KEY")
+if api_key and GENAI_AVAILABLE:
+    os.environ["LANGEXTRACT_API_KEY"] = api_key
+
+# --- HELPER FUNCTIONS ---
+def add_message(role: str, content: str, msg_type: str = "text"):
+    """Add a message to the chat history"""
+    st.session_state.messages.append({
+        "role": role,
+        "content": content,
+        "type": msg_type,
+        "timestamp": datetime.now().strftime("%H:%M")
+    })
+
+def render_chat_message(message):
+    """Render a single chat message with styling"""
+    role = message["role"]
+    content = message["content"]
+    timestamp = message.get("timestamp", "")
+    
+    if role == "user":
+        avatar = "👤"
+        bubble_class = "user"
+    else:
+        avatar = "🔍"
+        bubble_class = "assistant"
+    
+    html = f"""
+    <div class="chat-message {role}">
+        <div class="chat-avatar {role}">{avatar}</div>
+        <div class="chat-bubble {bubble_class}">
+            <div style="margin-bottom: 4px;">{content}</div>
+            <div style="font-size: 0.7rem; opacity: 0.6; text-align: right;">{timestamp}</div>
+        </div>
+    </div>
+    """
+    return html
+
+def render_result_card(title, content, icon="📄"):
+    """Render an extraction result card"""
+    html = f"""
+    <div class="result-card">
+        <div class="result-card-header">
+            <div class="result-card-icon">{icon}</div>
+            <div class="result-card-title">{title}</div>
+        </div>
+        <div class="result-card-content">{content}</div>
+        <span class="evidence-tag">✓ Source Verified</span>
+    </div>
+    """
+    return html
+
+# --- SIDEBAR ---
+with st.sidebar:
+    # Logo / Brand
+    st.markdown("""
+    <div style="text-align: center; padding: 1rem 0 2rem 0;">
+        <div style="font-size: 3rem; margin-bottom: 0.5rem;">🔍</div>
+        <div style="font-family: 'Outfit', sans-serif; font-size: 1.5rem; font-weight: 700; 
+                    background: linear-gradient(135deg, #f1f5f9 0%, #6366f1 100%);
+                    -webkit-background-clip: text; -webkit-text-fill-color: transparent;">
+            DocuTrace
+        </div>
+        <div style="font-size: 0.8rem; color: #64748b; margin-top: 0.25rem;">
+            Verifiable AI Auditor
+        </div>
+    </div>
+    """, unsafe_allow_html=True)
+    
+    st.markdown("### ⚙️ Configuration")
+    
+    # Model Selection with icons
+    model_choice = st.selectbox(
+        "AI Model",
+        ["gemini-2.5-flash", "gemini-1.5-flash"],
+        help="Select the Gemini model for extraction"
+    )
+    
+    # Status indicators
+    all_deps_ready = GENAI_AVAILABLE and LANGEXTRACT_AVAILABLE and PYPDF_AVAILABLE and api_key
+    
+    if all_deps_ready:
+        st.markdown("""
+        <div style="display: flex; align-items: center; gap: 8px; padding: 0.75rem; 
+                    background: rgba(16, 185, 129, 0.15); border-radius: 8px; margin: 1rem 0;">
+            <div style="width: 8px; height: 8px; background: #10b981; border-radius: 50%;"></div>
+            <span style="color: #10b981; font-size: 0.85rem;">System Ready</span>
+        </div>
+        """, unsafe_allow_html=True)
+    else:
+        missing = []
+        if not api_key:
+            missing.append("API Key")
+        if not GENAI_AVAILABLE:
+            missing.append("google-generativeai")
+        if not LANGEXTRACT_AVAILABLE:
+            missing.append("langextract")
+        if not PYPDF_AVAILABLE:
+            missing.append("pypdf")
+            
+        st.markdown(f"""
+        <div style="display: flex; align-items: center; gap: 8px; padding: 0.75rem; 
+                    background: rgba(245, 158, 11, 0.15); border-radius: 8px; margin: 1rem 0;">
+            <div style="width: 8px; height: 8px; background: #f59e0b; border-radius: 50%;"></div>
+            <span style="color: #f59e0b; font-size: 0.85rem;">Demo Mode</span>
+        </div>
+        """, unsafe_allow_html=True)
+    
+    st.divider()
+    
+    # File Upload
+    st.markdown("### 📁 Document")
+    uploaded_file = st.file_uploader(
+        "Upload PDF",
+        type=["pdf"],
+        help="Upload your document for analysis"
+    )
+    
+    st.divider()
+    
+    # Stats
+    st.markdown("### 📊 Session Stats")
+    col1, col2 = st.columns(2)
+    with col1:
+        st.markdown(f"""
+        <div class="metric-container">
+            <div class="metric-value">{st.session_state.extraction_count}</div>
+            <div class="metric-label">Extractions</div>
+        </div>
+        """, unsafe_allow_html=True)
+    with col2:
+        st.markdown(f"""
+        <div class="metric-container">
+            <div class="metric-value">{st.session_state.pages_processed}</div>
+            <div class="metric-label">Pages</div>
+        </div>
+        """, unsafe_allow_html=True)
+    
+    st.divider()
+    
+    # Footer
+    st.markdown("""
+    <div style="text-align: center; padding: 1rem 0; color: #64748b; font-size: 0.75rem;">
+        Powered by <strong>Google LangExtract</strong><br/>
+        & Gemini AI
+    </div>
+    """, unsafe_allow_html=True)
+
+# --- MAIN CONTENT ---
+# Hero Section
+st.markdown("""
+<div class="hero-section">
+    <h1 class="hero-title">📜 DocuTrace AI</h1>
+    <p class="hero-subtitle">Extract structured data from documents with <strong>Source Grounding</strong> & verifiable evidence</p>
+    <div class="hero-badge">
+        <span>●</span> Production Ready
+    </div>
+</div>
+""", unsafe_allow_html=True)
+
+# Main content area
+if uploaded_file:
+    # Read PDF
+    if PYPDF_AVAILABLE:
+        with st.spinner(""):
+            try:
+                reader = PdfReader(uploaded_file)
+                text = ""
+                page_count = min(5, len(reader.pages))
+                for i in range(page_count):
+                    text += reader.pages[i].extract_text() + "\n"
+                
+                st.session_state.pages_processed = page_count
+                
+                # Success notification
+                st.markdown(f"""
+                <div style="display: flex; align-items: center; gap: 12px; padding: 1rem 1.5rem;
+                            background: rgba(16, 185, 129, 0.1); border: 1px solid rgba(16, 185, 129, 0.3);
+                            border-radius: 12px; margin-bottom: 1.5rem;">
+                    <span style="font-size: 1.5rem;">✓</span>
+                    <div>
+                        <div style="color: #10b981; font-weight: 600;">Document Loaded</div>
+                        <div style="color: #94a3b8; font-size: 0.85rem;">
+                            {len(reader.pages)} pages total • Analyzing first {page_count} pages
+                        </div>
+                    </div>
+                </div>
+                """, unsafe_allow_html=True)
+                
+            except Exception as e:
+                st.error(f"Error reading PDF: {e}")
+                st.stop()
+    else:
+        st.warning("PyPDF module not installed. PDF parsing disabled.")
+        text = ""
+
+    # Query Section
+    st.markdown("### 💬 What would you like to extract?")
+    
+    col1, col2 = st.columns([2, 1])
+    with col1:
+        topic = st.text_input(
+            "Search Topic",
+            placeholder="e.g., Risk Factors, Financial Data, Legal Terms...",
+            label_visibility="collapsed"
+        )
+    with col2:
+        fields = st.text_input(
+            "Fields",
+            placeholder="category, summary, impact",
+            label_visibility="collapsed"
+        )
+
+    # Chat History Display
+    if st.session_state.messages:
+        st.markdown("### 📝 Conversation")
+        chat_html = '<div class="chat-container">'
+        for msg in st.session_state.messages:
+            chat_html += render_chat_message(msg)
+        chat_html += '</div>'
+        st.markdown(chat_html, unsafe_allow_html=True)
+
+    # Action Button
+    col1, col2, col3 = st.columns([1, 1, 1])
+    with col2:
+        run_audit = st.button("🚀 Run Audit", type="primary", use_container_width=True)
+
+    if run_audit:
+        if not all_deps_ready:
+            # Demo mode - show simulated results
+            add_message("user", f"Extract **{topic or 'Key Information'}** with fields: {fields or 'auto-detect'}")
+            add_message("assistant", "⚠️ Running in Demo Mode. Install required dependencies (google-generativeai, langextract, pypdf) and set GEMINI_API_KEY for full functionality.")
+            
+            # Show demo result cards
+            st.markdown("### 🔍 Demo Results")
+            st.markdown(render_result_card(
+                "Sample Extraction",
+                "This is a demonstration of the DocuTrace extraction interface. In production mode with proper dependencies installed, real AI-powered extractions with source grounding would appear here.",
+                "📊"
+            ), unsafe_allow_html=True)
+            st.session_state.extraction_count += 1
+            st.rerun()
+        elif not topic:
+            st.warning("Please enter a search topic")
+        else:
+            # Full extraction mode
+            add_message("user", f"Extract **{topic}** with fields: {fields or 'auto-detect'}")
+            
+            with st.status("🕵️ Analyzing Document...", expanded=True) as status:
+                try:
+                    prompt = f"Extract '{topic}'. Fields: {fields}."
+                    status.write("🔍 Scanning document content...")
+                    
+                    examples = [
+                        lx.data.ExampleData(
+                            text="The company faces regulatory risks.", 
+                            extractions=[lx.data.Extraction(
+                                extraction_class="item", 
+                                extraction_text="The company faces regulatory risks", 
+                                attributes={"category": "Legal"}
+                            )]
+                        )
+                    ]
+
+                    status.write("🤖 AI is extracting data...")
+                    
+                    result = lx.extract(
+                        text_or_documents=text,
+                        prompt_description=prompt,
+                        examples=examples,
+                        model_id=model_choice
+                    )
+                    
+                    extraction_count = len(result.extractions)
+                    st.session_state.extraction_count += extraction_count
+                    
+                    status.write(f"✅ Found {extraction_count} items")
+                    status.write("🎨 Generating evidence visualization...")
+                    lx.io.save_annotated_documents([result], output_name="data.jsonl", output_dir=".")
+                    html_obj = lx.visualize("data.jsonl")
+                    html_content = html_obj.data
+                    
+                    status.update(label="✅ Audit Complete!", state="complete")
+                    add_message("assistant", f"Found **{extraction_count}** relevant items for '{topic}'. Evidence is highlighted below with source verification.")
+                    st.rerun()
+
+                except Exception as e:
+                    status.update(label="❌ Error", state="error")
+                    add_message("assistant", f"⚠️ Extraction failed: {str(e)}")
+                    st.error(f"Extraction Failed: {e}")
+
+    # Results Display (after extraction)
+    if os.path.exists("data.jsonl") and LANGEXTRACT_AVAILABLE:
+        st.markdown("---")
+        st.markdown("""
+        <div style="display: flex; align-items: center; gap: 12px; margin-bottom: 1rem;">
+            <div style="font-size: 1.5rem;">🔍</div>
+            <div>
+                <div style="font-family: 'Outfit', sans-serif; font-size: 1.25rem; font-weight: 600; color: #f1f5f9;">
+                    Verified Evidence
+                </div>
+                <div style="color: #64748b; font-size: 0.85rem;">
+                    Click highlights to see source text
+                </div>
+            </div>
+        </div>
+        """, unsafe_allow_html=True)
+        
+        try:
+            html_obj = lx.visualize("data.jsonl")
+            components.html(html_obj.data, height=600, scrolling=True)
+        except:
+            pass
+
+else:
+    # Empty State
+    st.markdown("""
+    <div style="text-align: center; padding: 4rem 2rem;">
+        <div style="font-size: 4rem; margin-bottom: 1.5rem; opacity: 0.5;">📄</div>
+        <div style="font-family: 'Outfit', sans-serif; font-size: 1.5rem; font-weight: 600; color: #94a3b8; margin-bottom: 0.5rem;">
+            No Document Loaded
+        </div>
+        <div style="color: #64748b; max-width: 400px; margin: 0 auto;">
+            Upload a PDF from the sidebar to begin extracting structured data with verifiable source grounding.
+        </div>
+    </div>
+    """, unsafe_allow_html=True)
+    
+    # Feature Cards
+    st.markdown("<br>", unsafe_allow_html=True)
+    
+    col1, col2, col3 = st.columns(3)
+    
+    with col1:
+        st.markdown("""
+        <div class="glass-card" style="text-align: center;">
+            <div style="font-size: 2.5rem; margin-bottom: 1rem;">🎯</div>
+            <div style="font-family: 'Outfit', sans-serif; font-size: 1.1rem; font-weight: 600; color: #f1f5f9; margin-bottom: 0.5rem;">
+                Precision Extraction
+            </div>
+            <div style="color: #64748b; font-size: 0.9rem;">
+                Extract exactly what you need with AI-powered document understanding
+            </div>
+        </div>
+        """, unsafe_allow_html=True)
+    
+    with col2:
+        st.markdown("""
+        <div class="glass-card" style="text-align: center;">
+            <div style="font-size: 2.5rem; margin-bottom: 1rem;">✓</div>
+            <div style="font-family: 'Outfit', sans-serif; font-size: 1.1rem; font-weight: 600; color: #f1f5f9; margin-bottom: 0.5rem;">
+                Source Grounding
+            </div>
+            <div style="color: #64748b; font-size: 0.9rem;">
+                Every extraction is linked to its exact source location in the document
+            </div>
+        </div>
+        """, unsafe_allow_html=True)
+    
+    with col3:
+        st.markdown("""
+        <div class="glass-card" style="text-align: center;">
+            <div style="font-size: 2.5rem; margin-bottom: 1rem;">🔒</div>
+            <div style="font-family: 'Outfit', sans-serif; font-size: 1.1rem; font-weight: 600; color: #f1f5f9; margin-bottom: 0.5rem;">
+                Enterprise Ready
+            </div>
+            <div style="color: #64748b; font-size: 0.9rem;">
+                Built for high-stakes domains: Legal, Finance, and Compliance
+            </div>
+        </div>
+        """, unsafe_allow_html=True)

requirements.txt

@@ -0,0 +1,6 @@
+streamlit
+google-generativeai
+pypdf
+python-dotenv
+pandas
+git+https://github.com/google/langextract.git

styles.css

@@ -0,0 +1,695 @@
+/* DocuTrace Premium Theme */
+/* Custom CSS for Streamlit Premium UI */
+
+@import url("https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&family=Outfit:wght@400;500;600;700;800&family=JetBrains+Mono:wght@400;500&display=swap");
+
+/* === ROOT VARIABLES === */
+:root {
+  --primary: #6366f1;
+  --primary-dark: #4f46e5;
+  --primary-light: #818cf8;
+  --accent: #f59e0b;
+  --accent-glow: #fbbf24;
+  --bg-dark: #0a0a1a;
+  --bg-gradient-1: #0f0f23;
+  --bg-gradient-2: #1a1a2e;
+  --surface: rgba(30, 30, 60, 0.6);
+  --surface-hover: rgba(40, 40, 80, 0.8);
+  --glass: rgba(255, 255, 255, 0.05);
+  --glass-border: rgba(255, 255, 255, 0.1);
+  --text-primary: #f1f5f9;
+  --text-secondary: #94a3b8;
+  --text-muted: #64748b;
+  --success: #10b981;
+  --success-bg: rgba(16, 185, 129, 0.15);
+  --error: #ef4444;
+  --error-bg: rgba(239, 68, 68, 0.15);
+  --warning: #f59e0b;
+  --info: #3b82f6;
+  --border-radius: 16px;
+  --border-radius-sm: 8px;
+  --border-radius-lg: 24px;
+  --shadow-sm: 0 2px 8px rgba(0, 0, 0, 0.3);
+  --shadow-md: 0 4px 20px rgba(0, 0, 0, 0.4);
+  --shadow-lg: 0 8px 40px rgba(0, 0, 0, 0.5);
+  --shadow-glow: 0 0 40px rgba(99, 102, 241, 0.3);
+  --transition-fast: 0.15s ease;
+  --transition-normal: 0.3s ease;
+  --transition-slow: 0.5s ease;
+}
+
+/* === BASE STYLES === */
+.stApp {
+  background: linear-gradient(
+    135deg,
+    var(--bg-dark) 0%,
+    var(--bg-gradient-1) 50%,
+    var(--bg-gradient-2) 100%
+  ) !important;
+  background-attachment: fixed !important;
+}
+
+.stApp::before {
+  content: "";
+  position: fixed;
+  top: 0;
+  left: 0;
+  right: 0;
+  bottom: 0;
+  background:
+    radial-gradient(
+      ellipse at 20% 20%,
+      rgba(99, 102, 241, 0.15) 0%,
+      transparent 50%
+    ),
+    radial-gradient(
+      ellipse at 80% 80%,
+      rgba(245, 158, 11, 0.1) 0%,
+      transparent 50%
+    ),
+    radial-gradient(
+      ellipse at 50% 50%,
+      rgba(139, 92, 246, 0.08) 0%,
+      transparent 60%
+    );
+  pointer-events: none;
+  z-index: -1;
+}
+
+/* === TYPOGRAPHY === */
+h1,
+h2,
+h3,
+h4,
+h5,
+h6,
+.stMarkdown h1,
+.stMarkdown h2,
+.stMarkdown h3 {
+  font-family: "Outfit", sans-serif !important;
+  color: var(--text-primary) !important;
+  font-weight: 600 !important;
+}
+
+p,
+span,
+div,
+label,
+.stMarkdown p {
+  font-family: "Inter", sans-serif !important;
+  color: var(--text-secondary) !important;
+}
+
+code,
+pre,
+.stCode {
+  font-family: "JetBrains Mono", monospace !important;
+}
+
+/* === CUSTOM SCROLLBAR === */
+::-webkit-scrollbar {
+  width: 8px;
+  height: 8px;
+}
+
+::-webkit-scrollbar-track {
+  background: var(--bg-gradient-1);
+  border-radius: 4px;
+}
+
+::-webkit-scrollbar-thumb {
+  background: var(--primary);
+  border-radius: 4px;
+}
+
+::-webkit-scrollbar-thumb:hover {
+  background: var(--primary-light);
+}
+
+/* === SIDEBAR === */
+section[data-testid="stSidebar"] {
+  background: linear-gradient(
+    180deg,
+    rgba(15, 15, 35, 0.95) 0%,
+    rgba(20, 20, 50, 0.98) 100%
+  ) !important;
+  border-right: 1px solid var(--glass-border) !important;
+  backdrop-filter: blur(20px) !important;
+}
+
+section[data-testid="stSidebar"] > div {
+  padding: 2rem 1.5rem !important;
+}
+
+section[data-testid="stSidebar"] .stMarkdown h2,
+section[data-testid="stSidebar"] .stMarkdown h3 {
+  color: var(--text-primary) !important;
+  font-size: 1.1rem !important;
+  text-transform: uppercase;
+  letter-spacing: 0.1em;
+  margin-bottom: 1.5rem;
+  padding-bottom: 0.75rem;
+  border-bottom: 2px solid var(--primary);
+  display: inline-block;
+}
+
+/* === BUTTONS === */
+.stButton > button {
+  background: linear-gradient(
+    135deg,
+    var(--primary) 0%,
+    var(--primary-dark) 100%
+  ) !important;
+  color: white !important;
+  border: none !important;
+  border-radius: var(--border-radius) !important;
+  padding: 0.75rem 2rem !important;
+  font-family: "Inter", sans-serif !important;
+  font-weight: 600 !important;
+  font-size: 1rem !important;
+  letter-spacing: 0.02em;
+  box-shadow: var(--shadow-md), var(--shadow-glow) !important;
+  transition: all var(--transition-normal) !important;
+  position: relative;
+  overflow: hidden;
+}
+
+.stButton > button::before {
+  content: "";
+  position: absolute;
+  top: 0;
+  left: -100%;
+  width: 100%;
+  height: 100%;
+  background: linear-gradient(
+    90deg,
+    transparent,
+    rgba(255, 255, 255, 0.2),
+    transparent
+  );
+  transition: left 0.5s ease;
+}
+
+.stButton > button:hover::before {
+  left: 100%;
+}
+
+.stButton > button:hover {
+  transform: translateY(-2px) !important;
+  box-shadow:
+    var(--shadow-lg),
+    0 0 60px rgba(99, 102, 241, 0.4) !important;
+}
+
+.stButton > button:active {
+  transform: translateY(0) !important;
+}
+
+/* Primary button variant */
+.stButton > button[kind="primary"] {
+  background: linear-gradient(
+    135deg,
+    var(--accent) 0%,
+    #d97706 100%
+  ) !important;
+  box-shadow:
+    var(--shadow-md),
+    0 0 40px rgba(245, 158, 11, 0.3) !important;
+}
+
+.stButton > button[kind="primary"]:hover {
+  box-shadow:
+    var(--shadow-lg),
+    0 0 60px rgba(245, 158, 11, 0.5) !important;
+}
+
+/* === FILE UPLOADER === */
+section[data-testid="stFileUploader"] {
+  background: var(--surface) !important;
+  border: 2px dashed var(--glass-border) !important;
+  border-radius: var(--border-radius) !important;
+  padding: 2rem !important;
+  transition: all var(--transition-normal) !important;
+}
+
+section[data-testid="stFileUploader"]:hover {
+  border-color: var(--primary) !important;
+  background: var(--surface-hover) !important;
+  box-shadow: var(--shadow-glow) !important;
+}
+
+section[data-testid="stFileUploader"] label {
+  color: var(--text-primary) !important;
+  font-weight: 500 !important;
+}
+
+/* === TEXT INPUTS === */
+.stTextInput > div > div {
+  background: var(--surface) !important;
+  border: 1px solid var(--glass-border) !important;
+  border-radius: var(--border-radius-sm) !important;
+  transition: all var(--transition-fast) !important;
+}
+
+.stTextInput > div > div:focus-within {
+  border-color: var(--primary) !important;
+  box-shadow: 0 0 0 3px rgba(99, 102, 241, 0.2) !important;
+}
+
+.stTextInput input {
+  color: var(--text-primary) !important;
+  font-family: "Inter", sans-serif !important;
+}
+
+.stTextInput input::placeholder {
+  color: var(--text-muted) !important;
+}
+
+/* === SELECT BOXES === */
+.stSelectbox > div > div {
+  background: var(--surface) !important;
+  border: 1px solid var(--glass-border) !important;
+  border-radius: var(--border-radius-sm) !important;
+}
+
+.stSelectbox [data-baseweb="select"] {
+  background: transparent !important;
+}
+
+.stSelectbox [data-baseweb="select"] > div {
+  background: var(--surface) !important;
+  border-color: var(--glass-border) !important;
+}
+
+/* === ALERTS & INFO BOXES === */
+.stAlert {
+  background: var(--surface) !important;
+  border: 1px solid var(--glass-border) !important;
+  border-radius: var(--border-radius) !important;
+  backdrop-filter: blur(10px) !important;
+}
+
+div[data-testid="stNotification"] {
+  background: var(--surface) !important;
+  border-left: 4px solid var(--primary) !important;
+  border-radius: var(--border-radius-sm) !important;
+}
+
+.stSuccess {
+  background: var(--success-bg) !important;
+  border-color: var(--success) !important;
+}
+
+.stError {
+  background: var(--error-bg) !important;
+  border-color: var(--error) !important;
+}
+
+/* === EXPANDER === */
+.streamlit-expanderHeader {
+  background: var(--surface) !important;
+  border: 1px solid var(--glass-border) !important;
+  border-radius: var(--border-radius-sm) !important;
+  color: var(--text-primary) !important;
+  font-weight: 500 !important;
+}
+
+/* === DIVIDER === */
+.stDivider {
+  border-color: var(--glass-border) !important;
+}
+
+hr {
+  border-color: var(--glass-border) !important;
+  opacity: 0.5;
+}
+
+/* === STATUS WIDGET === */
+div[data-testid="stStatusWidget"] {
+  background: var(--surface) !important;
+  border: 1px solid var(--glass-border) !important;
+  border-radius: var(--border-radius) !important;
+  backdrop-filter: blur(10px) !important;
+}
+
+/* === SPINNER === */
+.stSpinner > div {
+  border-color: var(--primary) transparent transparent transparent !important;
+}
+
+/* === CHAT MESSAGE STYLES === */
+.chat-container {
+  display: flex;
+  flex-direction: column;
+  gap: 1rem;
+  padding: 1rem 0;
+}
+
+.chat-message {
+  display: flex;
+  gap: 0.75rem;
+  animation: fadeInUp 0.3s ease;
+}
+
+.chat-message.user {
+  flex-direction: row-reverse;
+}
+
+.chat-avatar {
+  width: 40px;
+  height: 40px;
+  border-radius: 50%;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  font-size: 1.25rem;
+  flex-shrink: 0;
+}
+
+.chat-avatar.user {
+  background: linear-gradient(
+    135deg,
+    var(--primary) 0%,
+    var(--primary-dark) 100%
+  );
+}
+
+.chat-avatar.assistant {
+  background: linear-gradient(135deg, var(--accent) 0%, #d97706 100%);
+}
+
+.chat-bubble {
+  max-width: 80%;
+  padding: 1rem 1.25rem;
+  border-radius: var(--border-radius);
+  line-height: 1.6;
+}
+
+.chat-bubble.user {
+  background: linear-gradient(
+    135deg,
+    var(--primary) 0%,
+    var(--primary-dark) 100%
+  );
+  color: white;
+  border-bottom-right-radius: 4px;
+}
+
+.chat-bubble.assistant {
+  background: var(--surface);
+  border: 1px solid var(--glass-border);
+  color: var(--text-primary);
+  border-bottom-left-radius: 4px;
+  backdrop-filter: blur(10px);
+}
+
+/* === RESULT CARDS === */
+.result-card {
+  background: var(--surface);
+  border: 1px solid var(--glass-border);
+  border-radius: var(--border-radius);
+  padding: 1.5rem;
+  margin-bottom: 1rem;
+  backdrop-filter: blur(10px);
+  transition: all var(--transition-normal);
+  animation: fadeInUp 0.4s ease;
+}
+
+.result-card:hover {
+  border-color: var(--primary);
+  box-shadow: var(--shadow-glow);
+  transform: translateY(-2px);
+}
+
+.result-card-header {
+  display: flex;
+  align-items: center;
+  gap: 0.75rem;
+  margin-bottom: 1rem;
+  padding-bottom: 0.75rem;
+  border-bottom: 1px solid var(--glass-border);
+}
+
+.result-card-icon {
+  width: 36px;
+  height: 36px;
+  border-radius: 10px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background: linear-gradient(
+    135deg,
+    var(--primary) 0%,
+    var(--primary-dark) 100%
+  );
+  font-size: 1.1rem;
+}
+
+.result-card-title {
+  font-family: "Outfit", sans-serif;
+  font-size: 1.1rem;
+  font-weight: 600;
+  color: var(--text-primary);
+}
+
+.result-card-content {
+  color: var(--text-secondary);
+  line-height: 1.7;
+}
+
+.evidence-tag {
+  display: inline-block;
+  padding: 0.25rem 0.75rem;
+  background: var(--success-bg);
+  color: var(--success);
+  border-radius: 20px;
+  font-size: 0.75rem;
+  font-weight: 500;
+  margin-top: 0.75rem;
+}
+
+/* === HERO SECTION === */
+.hero-section {
+  text-align: center;
+  padding: 3rem 2rem;
+  margin-bottom: 2rem;
+  background: var(--surface);
+  border: 1px solid var(--glass-border);
+  border-radius: var(--border-radius-lg);
+  backdrop-filter: blur(20px);
+  position: relative;
+  overflow: hidden;
+}
+
+.hero-section::before {
+  content: "";
+  position: absolute;
+  top: -50%;
+  left: -50%;
+  width: 200%;
+  height: 200%;
+  background: conic-gradient(
+    from 0deg at 50% 50%,
+    transparent,
+    var(--primary),
+    transparent,
+    var(--accent),
+    transparent
+  );
+  animation: rotate 20s linear infinite;
+  opacity: 0.1;
+}
+
+.hero-title {
+  font-family: "Outfit", sans-serif;
+  font-size: 3rem;
+  font-weight: 800;
+  background: linear-gradient(
+    135deg,
+    var(--text-primary) 0%,
+    var(--primary-light) 50%,
+    var(--accent) 100%
+  );
+  -webkit-background-clip: text;
+  -webkit-text-fill-color: transparent;
+  background-clip: text;
+  margin-bottom: 0.5rem;
+  position: relative;
+  z-index: 1;
+}
+
+.hero-subtitle {
+  font-size: 1.1rem;
+  color: var(--text-secondary);
+  position: relative;
+  z-index: 1;
+}
+
+.hero-badge {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.5rem;
+  padding: 0.5rem 1rem;
+  background: var(--success-bg);
+  color: var(--success);
+  border-radius: 20px;
+  font-size: 0.85rem;
+  font-weight: 500;
+  margin-top: 1rem;
+  position: relative;
+  z-index: 1;
+}
+
+/* === STATS BAR === */
+.stats-bar {
+  display: flex;
+  justify-content: center;
+  gap: 3rem;
+  padding: 1.5rem;
+  background: var(--surface);
+  border: 1px solid var(--glass-border);
+  border-radius: var(--border-radius);
+  margin-bottom: 2rem;
+  backdrop-filter: blur(10px);
+}
+
+.stat-item {
+  text-align: center;
+}
+
+.stat-value {
+  font-family: "Outfit", sans-serif;
+  font-size: 1.75rem;
+  font-weight: 700;
+  color: var(--primary-light);
+}
+
+.stat-label {
+  font-size: 0.85rem;
+  color: var(--text-muted);
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+}
+
+/* === ANIMATIONS === */
+@keyframes fadeInUp {
+  from {
+    opacity: 0;
+    transform: translateY(20px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+@keyframes rotate {
+  from {
+    transform: rotate(0deg);
+  }
+  to {
+    transform: rotate(360deg);
+  }
+}
+
+@keyframes pulse {
+  0%,
+  100% {
+    opacity: 1;
+  }
+  50% {
+    opacity: 0.5;
+  }
+}
+
+@keyframes shimmer {
+  0% {
+    background-position: -200% 0;
+  }
+  100% {
+    background-position: 200% 0;
+  }
+}
+
+.loading-shimmer {
+  background: linear-gradient(
+    90deg,
+    var(--surface) 25%,
+    var(--surface-hover) 50%,
+    var(--surface) 75%
+  );
+  background-size: 200% 100%;
+  animation: shimmer 1.5s infinite;
+}
+
+/* === TYPING INDICATOR === */
+.typing-indicator {
+  display: flex;
+  gap: 4px;
+  padding: 1rem;
+}
+
+.typing-dot {
+  width: 8px;
+  height: 8px;
+  background: var(--primary);
+  border-radius: 50%;
+  animation: pulse 1s infinite;
+}
+
+.typing-dot:nth-child(2) {
+  animation-delay: 0.2s;
+}
+
+.typing-dot:nth-child(3) {
+  animation-delay: 0.4s;
+}
+
+/* === GLASSMORPHISM CARD === */
+.glass-card {
+  background: var(--surface);
+  border: 1px solid var(--glass-border);
+  border-radius: var(--border-radius);
+  padding: 1.5rem;
+  backdrop-filter: blur(20px);
+  box-shadow: var(--shadow-md);
+}
+
+/* === METRIC DISPLAY === */
+.metric-container {
+  background: var(--surface);
+  border: 1px solid var(--glass-border);
+  border-radius: var(--border-radius);
+  padding: 1.25rem;
+  text-align: center;
+  transition: all var(--transition-normal);
+}
+
+.metric-container:hover {
+  border-color: var(--primary);
+  box-shadow: var(--shadow-glow);
+}
+
+.metric-value {
+  font-family: "Outfit", sans-serif;
+  font-size: 2rem;
+  font-weight: 700;
+  color: var(--primary-light);
+}
+
+.metric-label {
+  font-size: 0.9rem;
+  color: var(--text-muted);
+  margin-top: 0.25rem;
+}
+
+/* === HIDE STREAMLIT BRANDING === */
+#MainMenu {
+  visibility: hidden;
+}
+footer {
+  visibility: hidden;
+}
+header {
+  visibility: hidden;
+}