DocuReason v1.1.1 — Enterprise-Grade Tri-Path Multimodal RAG Framework

DocuReason (docureason-framework) is an enterprise-grade, multimodal Retrieval-Augmented Generation (RAG) framework for Python. Built for multi-format enterprise document processing, DocuReason ingests, parses, segments, indexes, routes, retrieves, synthesizes grounded answers, and evaluates document corpora across text, tabular, and visual modalities.

---

Table of Contents

1. Overview
2. Key Features
3. Architecture
4. Installation
   • PyPI Installation
   • Install from Source
   • Kaggle & Offline Notebook Installation
5. Quick Start
   • Python API
   • CLI Commands
   • FastAPI REST Server
   • Interactive Web Dashboard
6. Underlying Open-Source Libraries & Documentation Links
7. Standard Library API Reference
   • docureason.pipeline
   • docureason.ingestion
   • docureason.serving
   • src.tripath.retrieval
   • src.tripath.attribution
   • src.tripath.evaluation
8. Fine-Tuning Dataset Exporter
9. REST API Endpoint Reference
10. Configuration Guide
11. Running Tests & Validation
12. CI/CD & PyPI Release Engineering
13. License

---

Overview

Enterprise document collections contain a mix of prose, multi-row financial tables, and embedded diagrams or charts. Standard RAG systems treat all content as plain text, leading to severe accuracy degradation on tabular data and visual figures.

DocuReason 1.1.1 addresses this via a Tri-Path Multimodal RAG Architecture:

1. Text Path: Combines dense vector embeddings (SentenceTransformers / Qdrant) with sparse keyword retrieval (BM25S).
2. Table / Text-to-SQL Path: Extracts tabular regions, serializes to Markdown/HTML/JSON schemas, and executes SQL aggregations using DuckDB.
3. Vision / Chart Path: Uses visual feature extractors (ColPali / CLIP) and BLIP-2 figure captioning for visual chart understanding.

Incoming queries are dynamically routed using soft probability scoring, retrieved hits are merged via Reciprocal Rank Fusion (RRF) and Cross-Encoder reranking, and outputs undergo NLI-based attribution to guarantee zero hallucinations.

---

Key Features

• Multi-Format Document Parsing: Native support for .pdf, .docx, .pptx, .xlsx, .html, .csv, .md, and .txt.
• Deep Layout Segmentation: Uses TableFormer + DocLayNet via Docling to separate text blocks, data tables, and figures.
• EasyOCR Fallback: Automatic scan detection and optical character recognition for scanned PDFs or image-only document pages using EasyOCR.
• FastAPI Serving & Visualization Dashboard: Production REST API endpoints and an interactive local HTML pipeline dashboard.

---

Architecture

flowchart TD
    A[Raw Enterprise Documents] --> B[FormatAwareLoader & DoclingLayoutParser]
    B --> C1[Text Regions]
    B --> C2[Table Regions]
    B --> C3[Figure / Image Regions]
    
    C1 --> D1[Dense & BM25S Index]
    C2 --> D2[DuckDB SQL Engine]
    C3 --> D3[BLIP-2 / CLIP Index]
    
    E[User Query] --> F[ConfigurableRouter]
    F -->|Text Intent| G1[Text Retrieval Path]
    F -->|Table Intent| G2[Table & Text-to-SQL Path]
    F -->|Vision Intent| G3[Vision & Chart Path]
    
    G1 & G2 & G3 --> H[Reciprocal Rank Fusion - RRF]
    H --> I[Cross-Encoder Reranking]
    I --> J[Multimodal Generation Engine]
    J --> K[NLI Faithfulness Attributor]
    K --> L[Grounded Response + Citations]

---

Installation

PyPI Installation

Install the official published package from PyPI:

pip install docureason-framework

Install from Source

Clone the repository and install in editable mode:

git clone https://github.com/arpitkumar2004/DocuReason.git
cd DocuReason
pip install -e .

Verify installation:

import docureason
print(docureason.__version__)  # Output: 1.0.1

Kaggle & Offline Notebook Installation

To install in Kaggle or offline environments without internet access, upload the .whl package file as a Kaggle Dataset and install:

!pip install /kaggle/input/your-dataset-name/docureason_framework-1.1.1-py3-none-any.whl

Or install directly from GitHub:

!pip install git+https://github.com/arpitkumar2004/DocuReason.git

---

Quick Start

1. Python API

High-Level Ingestion and Indexing Pipeline

from docureason import DocuReasonPipeline

# Initialize the offline ingestion pipeline
pipeline = DocuReasonPipeline(
    input_dir="samples",
    output_dir="artifacts/my_index"
)

# Run document parsing, layout segmentation, table serialization, and index generation
report = pipeline.run()
print(f"Processed {report['document_count']} documents and {report['chunk_count']} chunks.")

Online Query Execution & Answer Serving

from docureason.serving import QueryService

# Initialize the end-to-end serving query engine
service = QueryService(
    input_dir="samples",
    output_dir="artifacts/my_index"
)

# Execute a multimodal query
response = service.query("What was the Q3 revenue growth shown in the comparison table?")

print("Answer:", response["answer"])
print("Routing:", response["route"])
print("Top Document:", response["results"][0]["document_id"])

2. CLI Commands

DocuReason provides built-in command-line interfaces:

# Execute the full end-to-end processing pipeline
python -m docureason --input-dir samples --output-dir artifacts/test_run

# Or run via script
python scripts/run_pipeline.py

3. FastAPI REST Server

Launch the production REST API server:

uvicorn src.tripath.serving.main:app --host 0.0.0.0 --port 8000 --reload

4. Interactive Web Dashboard

Launch the local HTML dashboard to inspect pipeline metrics and indices visually:

python scripts/serve_dashboard.py

Open browser at: http://127.0.0.1:8001

---

Underlying Open-Source Libraries & Documentation Links

DocuReason builds upon industry-standard machine learning and data processing libraries. Below is the mapping of components to their official documentation:

Component / Engine	Purpose in DocuReason	Official Library Documentation	Primary Function / Class Used
Docling	Deep document layout parsing & TableFormer	Docling Documentation	DocumentConverter
DuckDB	In-memory Text-to-SQL tabular execution	DuckDB Python API	duckdb.connect()
Qdrant	High-performance vector index storage	Qdrant Documentation	QdrantClient
BM25S	Fast sparse lexical search engine	BM25S GitHub	bm25s.BM25
SentenceTransformers	Dense vector text embeddings	SentenceTransformers Docs	SentenceTransformer.encode()
Hugging Face Transformers	Cross-Encoder reranking & NLI entailment	Transformers Documentation	AutoModelForSequenceClassification
BLIP-2	Image & chart visual captioning	BLIP-2 Model Docs	Blip2ForConditionalGeneration
ColPali & CLIP	Multi-modal visual feature extraction	ColPali Repository	ColPaliForRetrieval
EasyOCR	Scanned document OCR fallback engine	EasyOCR Documentation	easyocr.Reader
FastAPI	Asynchronous HTTP REST microservice	FastAPI Documentation	FastAPI()
MLflow	Metrics logging & experiment tracking	MLflow Documentation	mlflow.log_metrics()

---

Standard Library API Reference

docureason.pipeline

class docureason.pipeline.DocuReasonPipeline(input_dir: str | Path, output_dir: str | Path)

High-level offline ingestion pipeline orchestrator. Manages layout parsing, table serialization, OCR fallback, figure captioning, and vector index construction.

• Parameters:
  • input_dir (str | Path): Directory path containing raw enterprise documents.
  • output_dir (str | Path): Directory path where index artifacts are stored.

run() -> Dict[str, Any]

Executes end-to-end layout segmentation, table processing, vector indexing, and artifact generation.

---

docureason.ingestion

Multi-format document loaders, vision layout parsers, OCR fallback engines, and table serializers.

class docureason.ingestion.DoclingLayoutParser(page_batch_size: int = 1, do_ocr: bool = False)

Deep layout parsing wrapper utilizing Docling (TableFormer + DocLayNet) to segment text, tables, and figures.

parse(document_path: str | Path) -> List[Region]

Parses document_path and returns typed region bounding boxes and layouts.

class docureason.ingestion.TableSerializer()

Serializes tabular document regions into GFM Markdown tables, HTML representations, and DuckDB JSON schemas.

serialize(table_region: Region) -> Dict[str, Any]

Converts table_region into linearized Markdown, HTML, and structured schema dictionary {"columns": [...], "rows": [[...]]}.

---

docureason.serving

Synchronous and asynchronous query services for production serving.

class docureason.serving.QueryService(input_dir: str | Path, output_dir: str | Path)

Production query service providing dynamic query routing, multi-path retrieval, RRF fusion, reranking, and generation.

query(text: str) -> Dict[str, Any]

Executes search, fusion, reranking, and generation for input query text.

---

src.tripath.retrieval

Tri-path retrieval engines (Text, Table/SQL, Vision), chart understanding, and cross-encoder rankers.

class src.tripath.retrieval.hybrid_retriever.HybridRetriever()

Full multi-path retriever integrating routing, sub-path retrieval, Reciprocal Rank Fusion (RRF), parent-child chunk expansion, and cross-encoder reranking.

class src.tripath.retrieval.table_sql.TableSQLRetriever()

Text-to-SQL retriever executing dynamic queries over DuckDB in-memory database tables.

class src.tripath.retrieval.ranker.Ranker()

Cross-encoder relevance scoring module.

rank(query: str, candidates: List[Dict[str, Any]]) -> List[Dict[str, Any]]

Re-scores candidate chunks against query using cross-encoder attention and returns sorted top hits.

---

src.tripath.attribution

Claim attribution and NLI faithfulness engine.

class src.tripath.attribution.nli_attributor.NLIFaithfulnessAttributor()

attribute(answer: str, evidence: List[Dict[str, Any]]) -> Dict[str, Any]

Deconstructs answer into discrete sentence claims and computes entailment precision against evidence.

---

src.tripath.evaluation

Evaluation harness, benchmark runners, and ablation studies.

class src.tripath.evaluation.eval_harness.EvaluationHarness(output_dir: str | Path)

evaluate_single(query: str, results: List[dict], relevant_ids: Optional[List[str]] = None) -> Dict[str, float]

Computes retrieval performance metrics including Recall@K, nDCG@K, MRR, TEDS, NLI Faithfulness, and SLA target verification.

---

Fine-Tuning Dataset Exporter

DocuReason provides a built-in DatasetExporter module to export processed multi-modal corpora and query logs into SFT (Supervised Fine-Tuning) and DPO (Direct Preference Optimization) dataset formats compatible with HuggingFace datasets:

from src.tripath.evaluation.dataset_exporter import DatasetExporter

exporter = DatasetExporter(output_dir="artifacts/my_index")

# Export fine-tuning dataset for SLM training
dataset_path = exporter.export_fine_tuning_dataset(
    output_format="jsonl",
    split="train"
)
print("Exported dataset to:", dataset_path)

---

REST API Endpoint Reference

When running uvicorn src.tripath.serving.main:app --port 8000, the server exposes the following OpenAPI endpoints:

Method	Endpoint	Description	Request Body / Parameters
GET	/health	Server readiness check	None
GET	/api/report	Returns last pipeline execution report	None
POST	/query	Executes multimodal query and returns answer	{"query": "string", "input_dir": "samples"}
POST	/api/ingest	Triggers document ingestion pipeline	{"input_dir": "samples", "output_dir": "artifacts/run"}
POST	/api/evaluate	Evaluates retrieval metrics for query	{"query": "string", "relevant_ids": ["doc_1"]}
GET	/api/benchmarks	Returns loaded benchmark dataset spec	None

---

Configuration Guide

Pipeline parameters can be customized via configs/pipeline_config.yaml:

version: "1.0.1"

ingestion:
  page_batch_size: 1
  do_ocr: false
  ocr_languages: ["en"]

chunking:
  max_tokens: 512
  overlap: 64

router:
  threshold: 0.35
  keywords:
    text: ["revenue", "growth", "statement", "report"]
    table: ["table", "quarter", "sum", "total", "average"]
    vision: ["chart", "figure", "graph", "plot", "diagram"]

retrieval:
  rrf_k: 60
  top_k: 5

---

Running Tests & Validation

DocuReason maintains a comprehensive test suite covering all modules:

# 1. Install development & testing extras
pip install -e ".[dev]"

# 2. Run pytest across all test modules
python -m pytest -v

# 3. Run Ruff code quality check
ruff check .

# 4. Verify local PyPI package build and metadata
python scripts/verify_pypi_package.py

---

CI/CD & PyPI Release Engineering

DocuReason incorporates an enterprise-grade CI/CD pipeline powered by GitHub Actions and PyPI OIDC Trusted Publishing:

• Continuous Integration (.github/workflows/ci.yml):
  • Triggers on all pushes and pull requests targeting main.
  • Runs syntax linting (ruff), static type checking (mypy), and vulnerability audits (pip-audit).
  • Executes unit and integration test matrix across Python 3.10, 3.11, and 3.12.
  • Validates package metadata using PyPA build and twine check --strict.
• PyPI Release Pipeline (.github/workflows/release-pypi.yml):
  • Automatically triggered upon creating a published release on GitHub.
  • Deploys docureason-framework directly to PyPI using secure OIDC token authentication.
  • Automatically attaches .tar.gz and .whl distribution binaries to the GitHub Release.
• Automated Maintenance (.github/dependabot.yml):
  • Checks weekly for dependency upgrades across Python packages and GitHub Actions.

For a full technical architectural deep dive into the CI/CD pipeline, see the CI/CD Specification Document.

---

License

This project is licensed under the MIT License - see the LICENSE file for details.