sdca-rag 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (49) hide show
  1. sdca_rag-0.1.0/PKG-INFO +109 -0
  2. sdca_rag-0.1.0/README.md +85 -0
  3. sdca_rag-0.1.0/pyproject.toml +38 -0
  4. sdca_rag-0.1.0/sdca/__init__.py +60 -0
  5. sdca_rag-0.1.0/sdca_rag.egg-info/PKG-INFO +109 -0
  6. sdca_rag-0.1.0/sdca_rag.egg-info/SOURCES.txt +47 -0
  7. sdca_rag-0.1.0/sdca_rag.egg-info/dependency_links.txt +1 -0
  8. sdca_rag-0.1.0/sdca_rag.egg-info/requires.txt +5 -0
  9. sdca_rag-0.1.0/sdca_rag.egg-info/top_level.txt +2 -0
  10. sdca_rag-0.1.0/setup.cfg +4 -0
  11. sdca_rag-0.1.0/src/__init__.py +6 -0
  12. sdca_rag-0.1.0/src/app/__init__.py +1 -0
  13. sdca_rag-0.1.0/src/app/comparison.py +271 -0
  14. sdca_rag-0.1.0/src/app/streamlit_app.py +1982 -0
  15. sdca_rag-0.1.0/src/baselines/__init__.py +32 -0
  16. sdca_rag-0.1.0/src/baselines/fixed.py +108 -0
  17. sdca_rag-0.1.0/src/baselines/models.py +37 -0
  18. sdca_rag-0.1.0/src/baselines/recursive.py +267 -0
  19. sdca_rag-0.1.0/src/baselines/sentence.py +174 -0
  20. sdca_rag-0.1.0/src/baselines/tokenization.py +160 -0
  21. sdca_rag-0.1.0/src/evaluation/__init__.py +0 -0
  22. sdca_rag-0.1.0/src/experiments/__init__.py +34 -0
  23. sdca_rag-0.1.0/src/experiments/metrics.py +179 -0
  24. sdca_rag-0.1.0/src/experiments/runner.py +347 -0
  25. sdca_rag-0.1.0/src/experiments/runner_v2.py +294 -0
  26. sdca_rag-0.1.0/src/extraction/__init__.py +17 -0
  27. sdca_rag-0.1.0/src/extraction/models.py +100 -0
  28. sdca_rag-0.1.0/src/extraction/pdf_parser.py +148 -0
  29. sdca_rag-0.1.0/src/retrieval/__init__.py +10 -0
  30. sdca_rag-0.1.0/src/retrieval/embeddings.py +142 -0
  31. sdca_rag-0.1.0/src/retrieval/faiss_store.py +111 -0
  32. sdca_rag-0.1.0/src/retrieval/hybrid.py +67 -0
  33. sdca_rag-0.1.0/src/sdca/__init__.py +23 -0
  34. sdca_rag-0.1.0/src/sdca/chunker.py +358 -0
  35. sdca_rag-0.1.0/src/sdca/structure.py +276 -0
  36. sdca_rag-0.1.0/src/sdca/v2/__init__.py +24 -0
  37. sdca_rag-0.1.0/src/sdca/v2/chunker.py +308 -0
  38. sdca_rag-0.1.0/src/sdca/v2/structure.py +297 -0
  39. sdca_rag-0.1.0/src/sdca/v3/__init__.py +9 -0
  40. sdca_rag-0.1.0/src/sdca/v3/chunker.py +185 -0
  41. sdca_rag-0.1.0/tests/test_app.py +482 -0
  42. sdca_rag-0.1.0/tests/test_baselines.py +307 -0
  43. sdca_rag-0.1.0/tests/test_experiments.py +160 -0
  44. sdca_rag-0.1.0/tests/test_extraction.py +239 -0
  45. sdca_rag-0.1.0/tests/test_qasper_pdf_eval.py +25 -0
  46. sdca_rag-0.1.0/tests/test_retrieval.py +167 -0
  47. sdca_rag-0.1.0/tests/test_sdca.py +430 -0
  48. sdca_rag-0.1.0/tests/test_sdca_v2.py +237 -0
  49. sdca_rag-0.1.0/tests/test_sdca_v3.py +55 -0
@@ -0,0 +1,109 @@
1
+ Metadata-Version: 2.4
2
+ Name: sdca-rag
3
+ Version: 0.1.0
4
+ Summary: Structure-Aware Document Chunking Algorithm for Retrieval-Augmented Generation (RAG) Systems
5
+ Author: Subodh Butt, Ashish Dhillon
6
+ License-Expression: MIT
7
+ Keywords: rag,chunking,llm,information-retrieval,document-ai,pdf-parsing,stair
8
+ Classifier: Development Status :: 4 - Beta
9
+ Classifier: Intended Audience :: Developers
10
+ Classifier: Intended Audience :: Science/Research
11
+ Classifier: Programming Language :: Python :: 3
12
+ Classifier: Programming Language :: Python :: 3.9
13
+ Classifier: Programming Language :: Python :: 3.10
14
+ Classifier: Programming Language :: Python :: 3.11
15
+ Classifier: Programming Language :: Python :: 3.12
16
+ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
17
+ Requires-Python: >=3.9
18
+ Description-Content-Type: text/markdown
19
+ Requires-Dist: pymupdf>=1.24.0
20
+ Requires-Dist: sentence-transformers>=2.2.0
21
+ Requires-Dist: faiss-cpu>=1.7.0
22
+ Requires-Dist: numpy>=1.24.0
23
+ Requires-Dist: pandas>=2.0.0
24
+
25
+ # Structure-Aware Document Chunking Algorithm for Retrieval-Augmented Generation Systems (SDCA)
26
+
27
+ ## Overview
28
+ This repository implements **SDCA (Structure-Aware Document Chunking Algorithm)**, an M.Tech research project addressing chunk boundary degradation in PDF-based Retrieval-Augmented Generation (RAG) pipelines.
29
+
30
+ Standard naive chunking strategies (fixed-size windowing, simple character recursive splitting) often cleave paragraphs mid-sentence, ignore section hierarchies, and fragment semantic context, leading to degraded retrieval precision. SDCA provides a deterministic, layout-aware chunking pipeline that leverages PDF typography and document structure extracted via PyMuPDF.
31
+
32
+ ---
33
+
34
+ ## 5-Phase Implementation Plan
35
+
36
+ 1. **Phase 1: PDF Extraction Foundation** (**COMPLETED**)
37
+ - Extract structured text blocks, bounding boxes, font sizes, flags, and page metadata via PyMuPDF (`fitz`).
38
+ 2. **Phase 2: Baseline Chunking** (**COMPLETED**)
39
+ - Implement three standard RAG chunking baselines: Fixed-Size, Recursive, and Sentence-based Chunking.
40
+ 3. **Phase 3: SDCA Proposed Algorithm** (**COMPLETED**)
41
+ - Implement the deterministic structure-aware chunking algorithm targeting ~400 tokens (range 200–600 tokens) with heading detection, paragraph preservation, and sentence-bounded splitting.
42
+ 4. **Phase 4: Retrieval and Controlled Experiments** (**COMPLETED**)
43
+ - Generate embeddings using Sentence Transformers (`all-MiniLM-L6-v2`) and build FAISS vector indexes (`IndexFlatIP`) under strict *Ceteris Paribus* conditions.
44
+ 5. **Phase 5 & 5.1: Evaluation Dashboard & Interactive Research Laboratory** (**COMPLETED**)
45
+ - Interactive viva research laboratory for visual inspection, multi-algorithm side-by-side chunking, multi-strategy live FAISS retrieval, and frozen official benchmark presentation.
46
+ 6. **Phase V2: SDCA V2 Hierarchical Evolution & Controlled 5-Way Benchmark** (**COMPLETED**)
47
+ - Hierarchical section context (`section_path`), heading-content binding, structure-aware retrieval text (`chunk.retrieval_text`), small-chunk merging, and 5-strategy comparative benchmark.
48
+
49
+ ---
50
+
51
+ ## Running the SDCA Research Laboratory
52
+
53
+ Launch the interactive Streamlit research laboratory:
54
+
55
+ ```bash
56
+ # Direct run via virtual environment
57
+ .venv/bin/streamlit run src/app/streamlit_app.py
58
+ ```
59
+
60
+ The application opens at `http://localhost:8501` featuring 5 dedicated research views:
61
+ 1. **Overview:** Executive product landing page with capability cards and aggregate dataset metrics.
62
+ 2. **SDCA Explorer:** Deep visual inspection of both SDCA V1 and SDCA V2 (modal body font inference, hierarchical breadcrumbs, heading binding, and structure-aware retrieval text).
63
+ 3. **Algorithm Comparison:** Side-by-side multi-algorithm execution (`Fixed`, `Recursive`, `Sentence`, `SDCA V1`, `SDCA V2`) on the same PDF with token statistics, distribution charts, and sequential position chunk inspection.
64
+ 4. **Live Retrieval Lab:** Multi-algorithm semantic search under identical embedding and FAISS conditions with side-by-side cosine similarity scoring and vector text inspection.
65
+ 5. **Official Benchmark:** Tabbed evaluation featuring the full 5-way V2 benchmark, the frozen Phase 4 baseline, and direct head-to-head SDCA V1 vs SDCA V2 evolution analysis.
66
+ 6. **About SDCA:** Algorithmic pipeline, typography heuristics, and viva examination defense notes.
67
+
68
+ ---
69
+
70
+ ## Running the Automated Test Suite
71
+
72
+ Execute the full 100-test automated test suite across all project phases:
73
+
74
+ ```bash
75
+ .venv/bin/pytest -v tests/
76
+ ```
77
+
78
+ Expected result: `100 passed, 0 failures` (100% pass rate).
79
+
80
+
81
+ ---
82
+
83
+ ## Research Controls (*Ceteris Paribus*)
84
+ To ensure scientific validity, all retrieval benchmarks hold constant:
85
+ - Document corpus (3 landmark academic papers: Attention, RAG, BERT; 50 pages total)
86
+ - Benchmark query set & ground truth (15 verified technical queries)
87
+ - Embedding model (`sentence-transformers/all-MiniLM-L6-v2`, 384 dimensions)
88
+ - Subword tokenizer (injected model tokenizer across all 4 chunkers)
89
+ - Vector index algorithm (FAISS `IndexFlatIP`)
90
+ - Similarity metric (Exact Cosine Similarity via unit $L_2$-normalized inner product)
91
+ - Retrieval depth ($K = 5$)
92
+ - Evaluation metrics (Precision@5, Recall@5, Hit Rate@5, MRR, NDCG@5)
93
+
94
+ *The only independent variable is the chunking algorithm.*
95
+
96
+ ---
97
+
98
+ ## Technical Documentation
99
+ - [docs/SDCA_ALGORITHM.md](file:///Users/ashishdhillon/DPG/Coordinator/Mtech%20Synopsis/SDCA%20PRoject/Project/docs/SDCA_ALGORITHM.md): Algorithmic specification, pseudocode, and typography heuristics.
100
+ - [docs/EXPERIMENT_PROTOCOL.md](file:///Users/ashishdhillon/DPG/Coordinator/Mtech%20Synopsis/SDCA%20PRoject/Project/docs/EXPERIMENT_PROTOCOL.md): 19-point formal controlled retrieval experiment protocol.
101
+ - [docs/PHASE5_DASHBOARD.md](file:///Users/ashishdhillon/DPG/Coordinator/Mtech%20Synopsis/SDCA%20PRoject/Project/docs/PHASE5_DASHBOARD.md): Demonstration dashboard architecture and viva defense guide.
102
+
103
+ ---
104
+
105
+ ## Governance Documents
106
+ - [RULES.md](file:///Users/ashishdhillon/DPG/Coordinator/Mtech%20Synopsis/SDCA%20PRoject/Project/RULES.md): Research rules, algorithmic boundaries, and coding standards.
107
+ - [PROJECT_STATE.md](file:///Users/ashishdhillon/DPG/Coordinator/Mtech%20Synopsis/SDCA%20PRoject/Project/PROJECT_STATE.md): Current phase, deliverable tracker, and experiment states.
108
+ - [DECISIONS.md](file:///Users/ashishdhillon/DPG/Coordinator/Mtech%20Synopsis/SDCA%20PRoject/Project/DECISIONS.md): Architectural Decision Records (ADRs).
109
+ - [ERROR_CHANGE_LOG.md](file:///Users/ashishdhillon/DPG/Coordinator/Mtech%20Synopsis/SDCA%20PRoject/Project/ERROR_CHANGE_LOG.md): Historical log of errors, refactorings, and changes.
@@ -0,0 +1,85 @@
1
+ # Structure-Aware Document Chunking Algorithm for Retrieval-Augmented Generation Systems (SDCA)
2
+
3
+ ## Overview
4
+ This repository implements **SDCA (Structure-Aware Document Chunking Algorithm)**, an M.Tech research project addressing chunk boundary degradation in PDF-based Retrieval-Augmented Generation (RAG) pipelines.
5
+
6
+ Standard naive chunking strategies (fixed-size windowing, simple character recursive splitting) often cleave paragraphs mid-sentence, ignore section hierarchies, and fragment semantic context, leading to degraded retrieval precision. SDCA provides a deterministic, layout-aware chunking pipeline that leverages PDF typography and document structure extracted via PyMuPDF.
7
+
8
+ ---
9
+
10
+ ## 5-Phase Implementation Plan
11
+
12
+ 1. **Phase 1: PDF Extraction Foundation** (**COMPLETED**)
13
+ - Extract structured text blocks, bounding boxes, font sizes, flags, and page metadata via PyMuPDF (`fitz`).
14
+ 2. **Phase 2: Baseline Chunking** (**COMPLETED**)
15
+ - Implement three standard RAG chunking baselines: Fixed-Size, Recursive, and Sentence-based Chunking.
16
+ 3. **Phase 3: SDCA Proposed Algorithm** (**COMPLETED**)
17
+ - Implement the deterministic structure-aware chunking algorithm targeting ~400 tokens (range 200–600 tokens) with heading detection, paragraph preservation, and sentence-bounded splitting.
18
+ 4. **Phase 4: Retrieval and Controlled Experiments** (**COMPLETED**)
19
+ - Generate embeddings using Sentence Transformers (`all-MiniLM-L6-v2`) and build FAISS vector indexes (`IndexFlatIP`) under strict *Ceteris Paribus* conditions.
20
+ 5. **Phase 5 & 5.1: Evaluation Dashboard & Interactive Research Laboratory** (**COMPLETED**)
21
+ - Interactive viva research laboratory for visual inspection, multi-algorithm side-by-side chunking, multi-strategy live FAISS retrieval, and frozen official benchmark presentation.
22
+ 6. **Phase V2: SDCA V2 Hierarchical Evolution & Controlled 5-Way Benchmark** (**COMPLETED**)
23
+ - Hierarchical section context (`section_path`), heading-content binding, structure-aware retrieval text (`chunk.retrieval_text`), small-chunk merging, and 5-strategy comparative benchmark.
24
+
25
+ ---
26
+
27
+ ## Running the SDCA Research Laboratory
28
+
29
+ Launch the interactive Streamlit research laboratory:
30
+
31
+ ```bash
32
+ # Direct run via virtual environment
33
+ .venv/bin/streamlit run src/app/streamlit_app.py
34
+ ```
35
+
36
+ The application opens at `http://localhost:8501` featuring 5 dedicated research views:
37
+ 1. **Overview:** Executive product landing page with capability cards and aggregate dataset metrics.
38
+ 2. **SDCA Explorer:** Deep visual inspection of both SDCA V1 and SDCA V2 (modal body font inference, hierarchical breadcrumbs, heading binding, and structure-aware retrieval text).
39
+ 3. **Algorithm Comparison:** Side-by-side multi-algorithm execution (`Fixed`, `Recursive`, `Sentence`, `SDCA V1`, `SDCA V2`) on the same PDF with token statistics, distribution charts, and sequential position chunk inspection.
40
+ 4. **Live Retrieval Lab:** Multi-algorithm semantic search under identical embedding and FAISS conditions with side-by-side cosine similarity scoring and vector text inspection.
41
+ 5. **Official Benchmark:** Tabbed evaluation featuring the full 5-way V2 benchmark, the frozen Phase 4 baseline, and direct head-to-head SDCA V1 vs SDCA V2 evolution analysis.
42
+ 6. **About SDCA:** Algorithmic pipeline, typography heuristics, and viva examination defense notes.
43
+
44
+ ---
45
+
46
+ ## Running the Automated Test Suite
47
+
48
+ Execute the full 100-test automated test suite across all project phases:
49
+
50
+ ```bash
51
+ .venv/bin/pytest -v tests/
52
+ ```
53
+
54
+ Expected result: `100 passed, 0 failures` (100% pass rate).
55
+
56
+
57
+ ---
58
+
59
+ ## Research Controls (*Ceteris Paribus*)
60
+ To ensure scientific validity, all retrieval benchmarks hold constant:
61
+ - Document corpus (3 landmark academic papers: Attention, RAG, BERT; 50 pages total)
62
+ - Benchmark query set & ground truth (15 verified technical queries)
63
+ - Embedding model (`sentence-transformers/all-MiniLM-L6-v2`, 384 dimensions)
64
+ - Subword tokenizer (injected model tokenizer across all 4 chunkers)
65
+ - Vector index algorithm (FAISS `IndexFlatIP`)
66
+ - Similarity metric (Exact Cosine Similarity via unit $L_2$-normalized inner product)
67
+ - Retrieval depth ($K = 5$)
68
+ - Evaluation metrics (Precision@5, Recall@5, Hit Rate@5, MRR, NDCG@5)
69
+
70
+ *The only independent variable is the chunking algorithm.*
71
+
72
+ ---
73
+
74
+ ## Technical Documentation
75
+ - [docs/SDCA_ALGORITHM.md](file:///Users/ashishdhillon/DPG/Coordinator/Mtech%20Synopsis/SDCA%20PRoject/Project/docs/SDCA_ALGORITHM.md): Algorithmic specification, pseudocode, and typography heuristics.
76
+ - [docs/EXPERIMENT_PROTOCOL.md](file:///Users/ashishdhillon/DPG/Coordinator/Mtech%20Synopsis/SDCA%20PRoject/Project/docs/EXPERIMENT_PROTOCOL.md): 19-point formal controlled retrieval experiment protocol.
77
+ - [docs/PHASE5_DASHBOARD.md](file:///Users/ashishdhillon/DPG/Coordinator/Mtech%20Synopsis/SDCA%20PRoject/Project/docs/PHASE5_DASHBOARD.md): Demonstration dashboard architecture and viva defense guide.
78
+
79
+ ---
80
+
81
+ ## Governance Documents
82
+ - [RULES.md](file:///Users/ashishdhillon/DPG/Coordinator/Mtech%20Synopsis/SDCA%20PRoject/Project/RULES.md): Research rules, algorithmic boundaries, and coding standards.
83
+ - [PROJECT_STATE.md](file:///Users/ashishdhillon/DPG/Coordinator/Mtech%20Synopsis/SDCA%20PRoject/Project/PROJECT_STATE.md): Current phase, deliverable tracker, and experiment states.
84
+ - [DECISIONS.md](file:///Users/ashishdhillon/DPG/Coordinator/Mtech%20Synopsis/SDCA%20PRoject/Project/DECISIONS.md): Architectural Decision Records (ADRs).
85
+ - [ERROR_CHANGE_LOG.md](file:///Users/ashishdhillon/DPG/Coordinator/Mtech%20Synopsis/SDCA%20PRoject/Project/ERROR_CHANGE_LOG.md): Historical log of errors, refactorings, and changes.
@@ -0,0 +1,38 @@
1
+ [build-system]
2
+ requires = ["setuptools>=61.0"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "sdca-rag"
7
+ version = "0.1.0"
8
+ authors = [
9
+ { name = "Subodh Butt" },
10
+ { name = "Ashish Dhillon" }
11
+ ]
12
+ description = "Structure-Aware Document Chunking Algorithm for Retrieval-Augmented Generation (RAG) Systems"
13
+ readme = "README.md"
14
+ requires-python = ">=3.9"
15
+ license = "MIT"
16
+ keywords = ["rag", "chunking", "llm", "information-retrieval", "document-ai", "pdf-parsing", "stair"]
17
+ classifiers = [
18
+ "Development Status :: 4 - Beta",
19
+ "Intended Audience :: Developers",
20
+ "Intended Audience :: Science/Research",
21
+ "Programming Language :: Python :: 3",
22
+ "Programming Language :: Python :: 3.9",
23
+ "Programming Language :: Python :: 3.10",
24
+ "Programming Language :: Python :: 3.11",
25
+ "Programming Language :: Python :: 3.12",
26
+ "Topic :: Scientific/Engineering :: Artificial Intelligence",
27
+ ]
28
+ dependencies = [
29
+ "pymupdf>=1.24.0",
30
+ "sentence-transformers>=2.2.0",
31
+ "faiss-cpu>=1.7.0",
32
+ "numpy>=1.24.0",
33
+ "pandas>=2.0.0"
34
+ ]
35
+
36
+ [tool.setuptools.packages.find]
37
+ where = ["."]
38
+ include = ["src*", "sdca*"]
@@ -0,0 +1,60 @@
1
+ """SDCA: Structure-Aware Document Chunking Algorithm for Retrieval-Augmented Generation (RAG) Systems.
2
+
3
+ Developed by Subodh Butt & Ashish Dhillon.
4
+ """
5
+
6
+ from src.baselines.models import Chunk
7
+ from src.extraction.models import Document
8
+ from src.extraction.pdf_parser import load_pdf
9
+ from src.retrieval.hybrid import BM25, rrf, structure_guided_rrf
10
+ from src.sdca.chunker import chunk_sdca
11
+ from src.sdca.v2.chunker import chunk_sdca_v2
12
+ from src.sdca.v3.chunker import V3Options, chunk_sdca_stair, chunk_sdca_v3
13
+
14
+ __version__ = "0.1.0"
15
+ __all__ = [
16
+ "chunk_document",
17
+ "load_pdf",
18
+ "chunk_sdca_stair",
19
+ "chunk_sdca_v2",
20
+ "chunk_sdca",
21
+ "structure_guided_rrf",
22
+ "SDCATextSplitter",
23
+ "Chunk",
24
+ "Document",
25
+ "V3Options",
26
+ ]
27
+
28
+
29
+ def chunk_document(pdf_path: str, target_tokens: int = 300, **kwargs):
30
+ """High-level convenience API to load and chunk any PDF using the champion SDCA algorithm.
31
+
32
+ Args:
33
+ pdf_path: Path to the target PDF document.
34
+ target_tokens: Desired target token size per chunk (default: 300).
35
+
36
+ Returns:
37
+ List of layout-aware Chunk objects.
38
+ """
39
+ doc = load_pdf(pdf_path)
40
+ return chunk_sdca_stair(doc, target_tokens=target_tokens, **kwargs)
41
+
42
+
43
+ class SDCATextSplitter:
44
+ """Drop-in LangChain-compatible Document Transformer for SDCA."""
45
+
46
+ def __init__(self, target_tokens: int = 300, min_tokens: int = 120, max_tokens: int = 420, **kwargs):
47
+ self.target_tokens = target_tokens
48
+ self.min_tokens = min_tokens
49
+ self.max_tokens = max_tokens
50
+ self.kwargs = kwargs
51
+
52
+ def split_pdf(self, pdf_path: str):
53
+ """Chunks a PDF document preserving section hierarchies and tables."""
54
+ return chunk_document(
55
+ pdf_path,
56
+ target_tokens=self.target_tokens,
57
+ min_tokens=self.min_tokens,
58
+ max_tokens=self.max_tokens,
59
+ **self.kwargs,
60
+ )
@@ -0,0 +1,109 @@
1
+ Metadata-Version: 2.4
2
+ Name: sdca-rag
3
+ Version: 0.1.0
4
+ Summary: Structure-Aware Document Chunking Algorithm for Retrieval-Augmented Generation (RAG) Systems
5
+ Author: Subodh Butt, Ashish Dhillon
6
+ License-Expression: MIT
7
+ Keywords: rag,chunking,llm,information-retrieval,document-ai,pdf-parsing,stair
8
+ Classifier: Development Status :: 4 - Beta
9
+ Classifier: Intended Audience :: Developers
10
+ Classifier: Intended Audience :: Science/Research
11
+ Classifier: Programming Language :: Python :: 3
12
+ Classifier: Programming Language :: Python :: 3.9
13
+ Classifier: Programming Language :: Python :: 3.10
14
+ Classifier: Programming Language :: Python :: 3.11
15
+ Classifier: Programming Language :: Python :: 3.12
16
+ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
17
+ Requires-Python: >=3.9
18
+ Description-Content-Type: text/markdown
19
+ Requires-Dist: pymupdf>=1.24.0
20
+ Requires-Dist: sentence-transformers>=2.2.0
21
+ Requires-Dist: faiss-cpu>=1.7.0
22
+ Requires-Dist: numpy>=1.24.0
23
+ Requires-Dist: pandas>=2.0.0
24
+
25
+ # Structure-Aware Document Chunking Algorithm for Retrieval-Augmented Generation Systems (SDCA)
26
+
27
+ ## Overview
28
+ This repository implements **SDCA (Structure-Aware Document Chunking Algorithm)**, an M.Tech research project addressing chunk boundary degradation in PDF-based Retrieval-Augmented Generation (RAG) pipelines.
29
+
30
+ Standard naive chunking strategies (fixed-size windowing, simple character recursive splitting) often cleave paragraphs mid-sentence, ignore section hierarchies, and fragment semantic context, leading to degraded retrieval precision. SDCA provides a deterministic, layout-aware chunking pipeline that leverages PDF typography and document structure extracted via PyMuPDF.
31
+
32
+ ---
33
+
34
+ ## 5-Phase Implementation Plan
35
+
36
+ 1. **Phase 1: PDF Extraction Foundation** (**COMPLETED**)
37
+ - Extract structured text blocks, bounding boxes, font sizes, flags, and page metadata via PyMuPDF (`fitz`).
38
+ 2. **Phase 2: Baseline Chunking** (**COMPLETED**)
39
+ - Implement three standard RAG chunking baselines: Fixed-Size, Recursive, and Sentence-based Chunking.
40
+ 3. **Phase 3: SDCA Proposed Algorithm** (**COMPLETED**)
41
+ - Implement the deterministic structure-aware chunking algorithm targeting ~400 tokens (range 200–600 tokens) with heading detection, paragraph preservation, and sentence-bounded splitting.
42
+ 4. **Phase 4: Retrieval and Controlled Experiments** (**COMPLETED**)
43
+ - Generate embeddings using Sentence Transformers (`all-MiniLM-L6-v2`) and build FAISS vector indexes (`IndexFlatIP`) under strict *Ceteris Paribus* conditions.
44
+ 5. **Phase 5 & 5.1: Evaluation Dashboard & Interactive Research Laboratory** (**COMPLETED**)
45
+ - Interactive viva research laboratory for visual inspection, multi-algorithm side-by-side chunking, multi-strategy live FAISS retrieval, and frozen official benchmark presentation.
46
+ 6. **Phase V2: SDCA V2 Hierarchical Evolution & Controlled 5-Way Benchmark** (**COMPLETED**)
47
+ - Hierarchical section context (`section_path`), heading-content binding, structure-aware retrieval text (`chunk.retrieval_text`), small-chunk merging, and 5-strategy comparative benchmark.
48
+
49
+ ---
50
+
51
+ ## Running the SDCA Research Laboratory
52
+
53
+ Launch the interactive Streamlit research laboratory:
54
+
55
+ ```bash
56
+ # Direct run via virtual environment
57
+ .venv/bin/streamlit run src/app/streamlit_app.py
58
+ ```
59
+
60
+ The application opens at `http://localhost:8501` featuring 5 dedicated research views:
61
+ 1. **Overview:** Executive product landing page with capability cards and aggregate dataset metrics.
62
+ 2. **SDCA Explorer:** Deep visual inspection of both SDCA V1 and SDCA V2 (modal body font inference, hierarchical breadcrumbs, heading binding, and structure-aware retrieval text).
63
+ 3. **Algorithm Comparison:** Side-by-side multi-algorithm execution (`Fixed`, `Recursive`, `Sentence`, `SDCA V1`, `SDCA V2`) on the same PDF with token statistics, distribution charts, and sequential position chunk inspection.
64
+ 4. **Live Retrieval Lab:** Multi-algorithm semantic search under identical embedding and FAISS conditions with side-by-side cosine similarity scoring and vector text inspection.
65
+ 5. **Official Benchmark:** Tabbed evaluation featuring the full 5-way V2 benchmark, the frozen Phase 4 baseline, and direct head-to-head SDCA V1 vs SDCA V2 evolution analysis.
66
+ 6. **About SDCA:** Algorithmic pipeline, typography heuristics, and viva examination defense notes.
67
+
68
+ ---
69
+
70
+ ## Running the Automated Test Suite
71
+
72
+ Execute the full 100-test automated test suite across all project phases:
73
+
74
+ ```bash
75
+ .venv/bin/pytest -v tests/
76
+ ```
77
+
78
+ Expected result: `100 passed, 0 failures` (100% pass rate).
79
+
80
+
81
+ ---
82
+
83
+ ## Research Controls (*Ceteris Paribus*)
84
+ To ensure scientific validity, all retrieval benchmarks hold constant:
85
+ - Document corpus (3 landmark academic papers: Attention, RAG, BERT; 50 pages total)
86
+ - Benchmark query set & ground truth (15 verified technical queries)
87
+ - Embedding model (`sentence-transformers/all-MiniLM-L6-v2`, 384 dimensions)
88
+ - Subword tokenizer (injected model tokenizer across all 4 chunkers)
89
+ - Vector index algorithm (FAISS `IndexFlatIP`)
90
+ - Similarity metric (Exact Cosine Similarity via unit $L_2$-normalized inner product)
91
+ - Retrieval depth ($K = 5$)
92
+ - Evaluation metrics (Precision@5, Recall@5, Hit Rate@5, MRR, NDCG@5)
93
+
94
+ *The only independent variable is the chunking algorithm.*
95
+
96
+ ---
97
+
98
+ ## Technical Documentation
99
+ - [docs/SDCA_ALGORITHM.md](file:///Users/ashishdhillon/DPG/Coordinator/Mtech%20Synopsis/SDCA%20PRoject/Project/docs/SDCA_ALGORITHM.md): Algorithmic specification, pseudocode, and typography heuristics.
100
+ - [docs/EXPERIMENT_PROTOCOL.md](file:///Users/ashishdhillon/DPG/Coordinator/Mtech%20Synopsis/SDCA%20PRoject/Project/docs/EXPERIMENT_PROTOCOL.md): 19-point formal controlled retrieval experiment protocol.
101
+ - [docs/PHASE5_DASHBOARD.md](file:///Users/ashishdhillon/DPG/Coordinator/Mtech%20Synopsis/SDCA%20PRoject/Project/docs/PHASE5_DASHBOARD.md): Demonstration dashboard architecture and viva defense guide.
102
+
103
+ ---
104
+
105
+ ## Governance Documents
106
+ - [RULES.md](file:///Users/ashishdhillon/DPG/Coordinator/Mtech%20Synopsis/SDCA%20PRoject/Project/RULES.md): Research rules, algorithmic boundaries, and coding standards.
107
+ - [PROJECT_STATE.md](file:///Users/ashishdhillon/DPG/Coordinator/Mtech%20Synopsis/SDCA%20PRoject/Project/PROJECT_STATE.md): Current phase, deliverable tracker, and experiment states.
108
+ - [DECISIONS.md](file:///Users/ashishdhillon/DPG/Coordinator/Mtech%20Synopsis/SDCA%20PRoject/Project/DECISIONS.md): Architectural Decision Records (ADRs).
109
+ - [ERROR_CHANGE_LOG.md](file:///Users/ashishdhillon/DPG/Coordinator/Mtech%20Synopsis/SDCA%20PRoject/Project/ERROR_CHANGE_LOG.md): Historical log of errors, refactorings, and changes.
@@ -0,0 +1,47 @@
1
+ README.md
2
+ pyproject.toml
3
+ sdca/__init__.py
4
+ sdca_rag.egg-info/PKG-INFO
5
+ sdca_rag.egg-info/SOURCES.txt
6
+ sdca_rag.egg-info/dependency_links.txt
7
+ sdca_rag.egg-info/requires.txt
8
+ sdca_rag.egg-info/top_level.txt
9
+ src/__init__.py
10
+ src/app/__init__.py
11
+ src/app/comparison.py
12
+ src/app/streamlit_app.py
13
+ src/baselines/__init__.py
14
+ src/baselines/fixed.py
15
+ src/baselines/models.py
16
+ src/baselines/recursive.py
17
+ src/baselines/sentence.py
18
+ src/baselines/tokenization.py
19
+ src/evaluation/__init__.py
20
+ src/experiments/__init__.py
21
+ src/experiments/metrics.py
22
+ src/experiments/runner.py
23
+ src/experiments/runner_v2.py
24
+ src/extraction/__init__.py
25
+ src/extraction/models.py
26
+ src/extraction/pdf_parser.py
27
+ src/retrieval/__init__.py
28
+ src/retrieval/embeddings.py
29
+ src/retrieval/faiss_store.py
30
+ src/retrieval/hybrid.py
31
+ src/sdca/__init__.py
32
+ src/sdca/chunker.py
33
+ src/sdca/structure.py
34
+ src/sdca/v2/__init__.py
35
+ src/sdca/v2/chunker.py
36
+ src/sdca/v2/structure.py
37
+ src/sdca/v3/__init__.py
38
+ src/sdca/v3/chunker.py
39
+ tests/test_app.py
40
+ tests/test_baselines.py
41
+ tests/test_experiments.py
42
+ tests/test_extraction.py
43
+ tests/test_qasper_pdf_eval.py
44
+ tests/test_retrieval.py
45
+ tests/test_sdca.py
46
+ tests/test_sdca_v2.py
47
+ tests/test_sdca_v3.py
@@ -0,0 +1,5 @@
1
+ pymupdf>=1.24.0
2
+ sentence-transformers>=2.2.0
3
+ faiss-cpu>=1.7.0
4
+ numpy>=1.24.0
5
+ pandas>=2.0.0
@@ -0,0 +1,2 @@
1
+ sdca
2
+ src
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,6 @@
1
+ """SDCA Research Project Source Package."""
2
+
3
+ import os
4
+
5
+ # Prevent OpenMP runtime conflict between faiss-cpu and torch on macOS
6
+ os.environ.setdefault("KMP_DUPLICATE_LIB_OK", "TRUE")
@@ -0,0 +1 @@
1
+ """Streamlit Demonstration and Evaluation Dashboard Package for SDCA."""