CoolFace
Apppublic

bidgoli77/ai-document-intelligence

sourceHugging Faceupdated 4mo agoView on Hugging Face
0likes
App README

AI Document Intelligence Tool v3.2

Advanced multi-document and table-aware RAG assistant optimized for minimum Gemini API usage while preserving answer quality.

Main goal

Use Gemini only when it is truly needed. Everything else is handled locally:

  • —PDF text extraction: local
  • —DOCX text extraction: local
  • —Embeddings: local BGE-M3
  • —BM25 retrieval: local
  • —Cross-Encoder re-ranking: local
  • —Tesseract OCR: local
  • —Gemini Vision: fallback only
  • —Gemini chat answer: only after retrieval and cache checks

API-saving architecture

1. Text PDFs do not use Gemini

Selectable text is extracted locally with PyPDFLoader. Gemini Vision is not called for normal PDFs.

2. Mixed PDFs are handled page-by-page

If a PDF has both text pages and scanned pages, only weak/blank pages are OCR processed.

3. Local-first OCR

Images and scanned pages are processed with Tesseract first. Gemini Vision is called only when local OCR quality is low.

4. OCR quality scoring

The pipeline checks:

  • —extracted text length
  • —valid Persian/English character ratio
  • —Tesseract confidence
  • —OCR garbage/symbol ratio

This reduces unnecessary Gemini Vision calls.

5. OCR cache

OCR results are cached by:

  • —file hash
  • —page number
  • —OCR mode
  • —OCR settings

Re-uploading the same image/PDF page does not repeat OCR or Gemini Vision.

6. Exact + semantic answer cache

Repeated questions reuse cached answers. Similar questions can reuse the same answer when:

  • —selected files match
  • —retrieved source context matches
  • —question embedding similarity is high

Example:

  • —“What is the replacement part number?”
  • —“Tell me the new part number.”

can reuse the answer without another Gemini chat call.

7. Adaptive retrieval

The app adjusts retrieval size based on question complexity:

  • —simple fact question: fewer chunks
  • —medium question: moderate context
  • —summary/analysis question: larger context

This reduces prompt tokens while preserving quality.

8. Context budget control

Only the most relevant context is sent to Gemini. Long chunks are trimmed intelligently before sending.

9. Query rewriting disabled by default

No extra Gemini call is used for multi-query generation. Hybrid retrieval handles most cases locally.

Environment variables

Required in Hugging Face Space secrets:

  • —GOOGLE_API_KEY or GEMINI_API_KEY

Optional cost/quality controls:

  • —MAX_CONTEXT_CHARS default: 9000
  • —APP_CACHE_DIR default: .cache
  • —OCR_CACHE_DIR default: .cache/ocr
  • —TESSERACT_LANG default: fas+eng
  • —ENABLE_GEMINI_VISION_FALLBACK default: true
  • —FORCE_LOCAL_OCR_ONLY default: false
  • —MIN_GOOD_OCR_CHARS default: 80
  • —MIN_VALID_CHAR_RATIO default: 0.38
  • —MIN_TESSERACT_CONFIDENCE default: 45
  • —MIN_OCR_QUALITY_SCORE default: 0.62
  • —SEMANTIC_CACHE_THRESHOLD default: 0.95
  • —MAX_ANSWER_CACHE_ITEMS default: 300
  • —ENABLE_SEMANTIC_ANSWER_CACHE default: true

Recommended Hugging Face settings

Use Docker Space. Upload all 7 files:

  • —app.py
  • —rag_pipeline.py
  • —document_loaders.py
  • —requirements.txt
  • —Dockerfile
  • —README.md
  • —gitattributes

Then restart the Space.

Practical result

For most text PDFs, Gemini Vision usage should be zero. For scanned documents, Gemini Vision is used only when local OCR quality is not good enough. For repeated questions, Gemini chat calls are avoided through caching.

v2.0 Quality + Cost Optimization

This release prioritizes high answer quality while minimizing Gemini API usage:

  • —SQLite persistent answer cache for repeated and semantically similar questions.
  • —No-answer guard to avoid Gemini calls when retrieved context does not support the question.
  • —Stronger grounded-answer prompt to reduce hallucinations.
  • —Adaptive retrieval/context budgets based on question complexity.
  • —Local-first OCR with Tesseract and Gemini Vision fallback only for weak OCR.
  • —Local API-usage logs in .cache/api_usage_log.jsonl.

Recommended environment variables:

env
ENABLE_NO_ANSWER_GUARD=true
ENABLE_SEMANTIC_ANSWER_CACHE=true
SEMANTIC_CACHE_THRESHOLD=0.95
MAX_CONTEXT_CHARS=9000
ENABLE_GEMINI_VISION_FALLBACK=true

v2.0 additions

Version 2.0 keeps the v1.9 API-saving architecture and adds quality-control features:

  • —Answer confidence meter based on retrieved-source strength
  • —Local answer verifier that checks whether an answer is supported by retrieved context without making a second API call
  • —User feedback logging for helpful/wrong answers
  • —API/cache dashboard in the sidebar
  • —Evaluation CSV template export
  • —Separate SQLite tables for feedback and evaluation logs
  • —New Chroma collection version to avoid distance-function conflicts from older deployments

The design goal remains: highest answer quality with the fewest possible API calls.

v3.2 additions

Version 3.0 extends the v2.0 quality/cost architecture with broader document intelligence while keeping API usage low:

  • —CSV support with local table-to-text conversion.
  • —Excel .xlsx / .xls support using local pandas/openpyxl extraction.
  • —TXT and Markdown support.
  • —Table-aware chunking: rows are grouped into retrieval-friendly chunks with columns, row ranges, and sheet metadata.
  • —Spreadsheet/table questions are answered from local extracted table text before Gemini receives only the most relevant chunks.
  • —New Chroma collection version document_intelligence_v30_bge_m3_cosine to avoid old collection conflicts.
  • —Still follows the core rule: local extraction first, Gemini only when needed for final grounded answers or weak OCR fallback.

Supported uploads in v3.2:

  • —PDF
  • —DOCX
  • —CSV
  • —XLSX / XLS
  • —TXT / MD
  • —JPG / JPEG / PNG / WEBP