chromerag 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.
- chromerag-0.1.0/LICENSE +21 -0
- chromerag-0.1.0/LICENSE.txt +21 -0
- chromerag-0.1.0/PKG-INFO +241 -0
- chromerag-0.1.0/README.md +195 -0
- chromerag-0.1.0/pyproject.toml +77 -0
- chromerag-0.1.0/setup.cfg +4 -0
- chromerag-0.1.0/src/chromerag/__init__.py +37 -0
- chromerag-0.1.0/src/chromerag/batch.py +111 -0
- chromerag-0.1.0/src/chromerag/cli.py +296 -0
- chromerag-0.1.0/src/chromerag/config.py +181 -0
- chromerag-0.1.0/src/chromerag/density.py +293 -0
- chromerag-0.1.0/src/chromerag/dvdf.py +129 -0
- chromerag-0.1.0/src/chromerag/extractor.py +226 -0
- chromerag-0.1.0/src/chromerag/input_quality.py +124 -0
- chromerag-0.1.0/src/chromerag/markdown_out.py +164 -0
- chromerag-0.1.0/src/chromerag/models.py +35 -0
- chromerag-0.1.0/src/chromerag/schema_fusion.py +183 -0
- chromerag-0.1.0/src/chromerag/site_chrome.py +362 -0
- chromerag-0.1.0/src/chromerag/tables.py +71 -0
- chromerag-0.1.0/src/chromerag.egg-info/PKG-INFO +241 -0
- chromerag-0.1.0/src/chromerag.egg-info/SOURCES.txt +25 -0
- chromerag-0.1.0/src/chromerag.egg-info/dependency_links.txt +1 -0
- chromerag-0.1.0/src/chromerag.egg-info/entry_points.txt +2 -0
- chromerag-0.1.0/src/chromerag.egg-info/requires.txt +28 -0
- chromerag-0.1.0/src/chromerag.egg-info/top_level.txt +1 -0
- chromerag-0.1.0/tests/test_extractor.py +76 -0
- chromerag-0.1.0/tests/test_input_quality.py +48 -0
chromerag-0.1.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Bhargava Chary Peddapudi
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Bhargava Chary Peddapudi
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
chromerag-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,241 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: chromerag
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: ChromeRAG: ingest-time elimination of site template noise for enterprise web RAG.
|
|
5
|
+
Author-email: Bhargava Chary Peddapudi <pedapudibhargav@gmail.com>
|
|
6
|
+
License: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/pedapudibhargav/ChromeRAG
|
|
8
|
+
Project-URL: Repository, https://github.com/pedapudibhargav/ChromeRAG.git
|
|
9
|
+
Project-URL: Issues, https://github.com/pedapudibhargav/ChromeRAG/issues
|
|
10
|
+
Project-URL: Documentation, https://pedapudibhargav.github.io/ChromeRAG/
|
|
11
|
+
Keywords: rag,html,markdown,boilerplate,chrome,vector,ingest
|
|
12
|
+
Classifier: Development Status :: 3 - Alpha
|
|
13
|
+
Classifier: Intended Audience :: Developers
|
|
14
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
15
|
+
Classifier: Programming Language :: Python :: 3
|
|
16
|
+
Classifier: Topic :: Text Processing :: Markup :: HTML
|
|
17
|
+
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
|
|
18
|
+
Requires-Python: >=3.11
|
|
19
|
+
Description-Content-Type: text/markdown
|
|
20
|
+
License-File: LICENSE
|
|
21
|
+
License-File: LICENSE.txt
|
|
22
|
+
Requires-Dist: beautifulsoup4<5,>=4.12.0
|
|
23
|
+
Requires-Dist: lxml<7,>=5.0.0
|
|
24
|
+
Requires-Dist: pydantic<3,>=2.7.0
|
|
25
|
+
Requires-Dist: pyyaml<7,>=6.0.0
|
|
26
|
+
Requires-Dist: tiktoken>=0.7.0
|
|
27
|
+
Requires-Dist: numpy<3,>=1.26.0
|
|
28
|
+
Provides-Extra: dvdf
|
|
29
|
+
Requires-Dist: onnxruntime<2,>=1.17.0; extra == "dvdf"
|
|
30
|
+
Provides-Extra: fetch
|
|
31
|
+
Requires-Dist: httpx<0.29,>=0.27.0; extra == "fetch"
|
|
32
|
+
Provides-Extra: baselines
|
|
33
|
+
Requires-Dist: markdownify>=0.13.0; extra == "baselines"
|
|
34
|
+
Requires-Dist: readability-lxml>=0.8.1; extra == "baselines"
|
|
35
|
+
Requires-Dist: trafilatura>=1.12.0; extra == "baselines"
|
|
36
|
+
Requires-Dist: markitdown>=0.1.0; extra == "baselines"
|
|
37
|
+
Requires-Dist: html2text>=2024.2.26; extra == "baselines"
|
|
38
|
+
Provides-Extra: ui
|
|
39
|
+
Requires-Dist: fastapi>=0.110.0; extra == "ui"
|
|
40
|
+
Requires-Dist: uvicorn>=0.27.0; extra == "ui"
|
|
41
|
+
Provides-Extra: dev
|
|
42
|
+
Requires-Dist: pytest>=8.0.0; extra == "dev"
|
|
43
|
+
Requires-Dist: ruff>=0.6.0; extra == "dev"
|
|
44
|
+
Requires-Dist: httpx<0.29,>=0.27.0; extra == "dev"
|
|
45
|
+
Dynamic: license-file
|
|
46
|
+
|
|
47
|
+
# ChromeRAG
|
|
48
|
+
|
|
49
|
+
[](LICENSE)
|
|
50
|
+
[](https://www.python.org/downloads/)
|
|
51
|
+
[](https://pedapudibhargav.github.io/ChromeRAG/)
|
|
52
|
+
|
|
53
|
+
**HTML → RAG-ready Markdown** that strips site-template chrome (nav, footer, CTAs, cookie banners) while keeping documentation, pricing tables, and article body text.
|
|
54
|
+
|
|
55
|
+
> Built for **enterprise RAG ingest**, **LLM chunking**, **vector indexing**, and **boilerplate / noise removal** from scraped HTML — not for pixel-perfect web archiving.
|
|
56
|
+
|
|
57
|
+
| Owns | Does **not** own |
|
|
58
|
+
|---|---|
|
|
59
|
+
| HTML string / file → clean Markdown | Crawling, Playwright, rate limits |
|
|
60
|
+
| Optional site-chrome **learn → extract** (STCE) | Full browser rendering of empty JS shells (warns; caller must render first) |
|
|
61
|
+
| Schema.org → YAML front-matter | Vector DB / embeddings |
|
|
62
|
+
| Precision / coverage priority knobs | Hosted SaaS API |
|
|
63
|
+
|
|
64
|
+
**Paper:** *ChromeRAG: Ingest-Time Elimination of Site Template Noise for Enterprise Web RAG*
|
|
65
|
+
**Release:** [`v0.1.0`](https://github.com/pedapudibhargav/ChromeRAG/tree/v0.1.0)
|
|
66
|
+
**Author:** [Bhargava Chary Peddapudi](https://orcid.org/0009-0002-8523-8415)
|
|
67
|
+
|
|
68
|
+
---
|
|
69
|
+
|
|
70
|
+
## Why ChromeRAG (vs MarkItDown / Trafilatura)?
|
|
71
|
+
|
|
72
|
+
| Tool | Best at | Gap for corporate web RAG |
|
|
73
|
+
|------|---------|---------------------------|
|
|
74
|
+
| **MarkItDown** | Office/PDF/HTML → Markdown for LLMs | Keeps a lot of page chrome; not tuned to strip SaaS nav/footer |
|
|
75
|
+
| **Trafilatura** | News/article main-content | Weaker on docs hubs, pricing matrices, marketing shells |
|
|
76
|
+
| **Readability** | Article extraction | Often drops tables / side content needed for RAG |
|
|
77
|
+
| **ChromeRAG** | Ingest-time chrome elimination + schema + tables | Focused HTML→RAG Markdown (fetch stays in your crawler) |
|
|
78
|
+
|
|
79
|
+
---
|
|
80
|
+
|
|
81
|
+
## Benchmarks (public corpus)
|
|
82
|
+
|
|
83
|
+
**Deterministic metrics** (primary claims) — independent of any single extractor:
|
|
84
|
+
|
|
85
|
+
| Metric | Meaning | Better |
|
|
86
|
+
|--------|---------|--------|
|
|
87
|
+
| **Recall** (`content_recall`) | Fraction of main/article text anchors kept | Higher |
|
|
88
|
+
| **Noise ret** (`noise_retention`) | Fraction of nav/footer chrome anchors kept | Lower |
|
|
89
|
+
| **Fbal** (`f_balanced`) | Balance of high recall + low noise | Higher |
|
|
90
|
+
|
|
91
|
+
**Baselines compared:** ChromeRAG (balanced / coverage / precision), Trafilatura, Readability, **MarkItDown**, markdownify, html2text, BeautifulSoup text.
|
|
92
|
+
|
|
93
|
+
**Corpus:** **373** URLs listed in `poc/corpus_urls.json` across `docs`, `pricing`, `marketing`, `wiki`, `hub`, `news`, `article`, `cloud`. Latest run fetched **277** HTML pages; **238** were scoreable (DOM content-anchor coverage ≥ 0.05; same fixed cohort for every tool); **39** thin pages are excluded from leaderboard *means* so empty JS shells are not silently averaged into SOTA claims.
|
|
94
|
+
|
|
95
|
+
**Latest leaderboard (238 scoreable pages):**
|
|
96
|
+
|
|
97
|
+
| Method | Recall ↑ | Noise ↓ | Fbal ↑ |
|
|
98
|
+
|--------|--------:|--------:|-------:|
|
|
99
|
+
| chromerag_coverage | 0.701 | 0.005 | **0.800** |
|
|
100
|
+
| chromerag (balanced) | 0.678 | 0.005 | 0.783 |
|
|
101
|
+
| trafilatura | 0.662 | 0.019 | 0.752 |
|
|
102
|
+
| markitdown | 0.702 | 0.261 | 0.695 |
|
|
103
|
+
| readability | 0.456 | 0.016 | 0.535 |
|
|
104
|
+
|
|
105
|
+
Full tables + per-category breakdown: [Results](https://pedapudibhargav.github.io/ChromeRAG/results.html) · `docs/data/corpus_comparison_summary.md`.
|
|
106
|
+
|
|
107
|
+
**Optional LLM judge** (secondary): stratified sample scored 1–5 on content keep / noise strip / structure when `OPENAI_API_KEY` is set (`python -m poc.run_llm_eval`). Does not replace Recall/Noise/Fbal.
|
|
108
|
+
|
|
109
|
+
---
|
|
110
|
+
|
|
111
|
+
## Quick start
|
|
112
|
+
|
|
113
|
+
### From PyPI (recommended)
|
|
114
|
+
|
|
115
|
+
```bash
|
|
116
|
+
pip install chromerag
|
|
117
|
+
# Optional: ONNX MiniLM density pruning
|
|
118
|
+
# pip install "chromerag[dvdf]"
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
### From source
|
|
122
|
+
|
|
123
|
+
```bash
|
|
124
|
+
git clone https://github.com/pedapudibhargav/ChromeRAG.git
|
|
125
|
+
cd ChromeRAG
|
|
126
|
+
python3 -m venv .venv
|
|
127
|
+
source .venv/bin/activate # Windows: .venv\Scripts\activate
|
|
128
|
+
|
|
129
|
+
# Core library + CLI
|
|
130
|
+
pip install -e .
|
|
131
|
+
|
|
132
|
+
# Optional: comparison baselines + tests
|
|
133
|
+
pip install -e ".[dev,baselines]"
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
### CLI
|
|
137
|
+
|
|
138
|
+
```bash
|
|
139
|
+
# Single page
|
|
140
|
+
chromerag extract path/to/page.html -o out.md --priority balanced --json-meta
|
|
141
|
+
|
|
142
|
+
# Priorities: precision | balanced | coverage
|
|
143
|
+
chromerag extract page.html -o clean.md --priority coverage
|
|
144
|
+
|
|
145
|
+
# Thin / JS-shell HTML prints WARNING on stderr (caller must Playwright-render first)
|
|
146
|
+
# chromerag extract spa.html -o out.md --fail-on-thin # exit 3 if thin
|
|
147
|
+
|
|
148
|
+
# Learn site chrome across a folder, then batch-extract
|
|
149
|
+
chromerag learn data/raw -o data/chrome_models/site.json --min-pages 3
|
|
150
|
+
chromerag batch data/raw -o data/outputs --chrome-model data/chrome_models/site.json
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
### Python
|
|
154
|
+
|
|
155
|
+
```python
|
|
156
|
+
from chromerag import ChromeRAG, PipelineConfig, ContentPriority
|
|
157
|
+
|
|
158
|
+
html = open("page.html", encoding="utf-8").read()
|
|
159
|
+
result = ChromeRAG(
|
|
160
|
+
config=PipelineConfig.from_priority(ContentPriority.BALANCED, enable_dvdf=False)
|
|
161
|
+
).extract(html, url="https://example.com/docs")
|
|
162
|
+
|
|
163
|
+
print(result.markdown) # RAG-ready Markdown (+ YAML front-matter when Schema.org present)
|
|
164
|
+
print(result.front_matter) # dict
|
|
165
|
+
print(result.tokens_estimate)
|
|
166
|
+
print(result.warnings) # e.g. JS shell → render with Playwright first
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
---
|
|
170
|
+
|
|
171
|
+
## Reproduce the evaluation
|
|
172
|
+
|
|
173
|
+
```bash
|
|
174
|
+
# 1) Fetch / refresh the public corpus (uses poc/corpus_urls.json)
|
|
175
|
+
python -m poc.run_corpus_comparison
|
|
176
|
+
|
|
177
|
+
# 2) Export tables + JSON into docs/ for GitHub Pages
|
|
178
|
+
python -m poc.export_site_results
|
|
179
|
+
|
|
180
|
+
# 3) Revalidate published numbers + classify thin pages
|
|
181
|
+
python scripts/revalidate_corpus.py
|
|
182
|
+
|
|
183
|
+
# 4) Optional LLM subset judge (needs OPENAI_API_KEY)
|
|
184
|
+
python -m poc.run_llm_eval --sample 40
|
|
185
|
+
|
|
186
|
+
# 5) Unit tests + regenerate docs/tests.html
|
|
187
|
+
./scripts/build_docs.sh
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
Skip re-fetch if HTML is already under `data/raw/`:
|
|
191
|
+
|
|
192
|
+
```bash
|
|
193
|
+
python -m poc.run_corpus_comparison --no-fetch
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
---
|
|
197
|
+
|
|
198
|
+
## Docs site (GitHub Pages)
|
|
199
|
+
|
|
200
|
+
Static files live in [`docs/`](docs/) (relative links only).
|
|
201
|
+
|
|
202
|
+
CI (`.github/workflows/pages.yml`) on every push to **`main`**:
|
|
203
|
+
|
|
204
|
+
1. runs `pytest`
|
|
205
|
+
2. rebuilds `docs/tests.html` + exports corpus results
|
|
206
|
+
3. deploys `docs/` → **`gh-pages`** branch
|
|
207
|
+
|
|
208
|
+
Enable once: **Settings → Pages → Deploy from a branch → `gh-pages` / (root)**.
|
|
209
|
+
Site: https://pedapudibhargav.github.io/ChromeRAG/
|
|
210
|
+
|
|
211
|
+
---
|
|
212
|
+
|
|
213
|
+
## Project layout
|
|
214
|
+
|
|
215
|
+
```
|
|
216
|
+
src/chromerag/ # library (HTML in → Markdown out)
|
|
217
|
+
poc/ # fetch, baselines, corpus comparison, LLM eval (not required at runtime)
|
|
218
|
+
docs/ # GitHub Pages site + published metrics
|
|
219
|
+
tests/ # unit tests
|
|
220
|
+
papers/softwarex/ # SoftwareX manuscript draft
|
|
221
|
+
```
|
|
222
|
+
|
|
223
|
+
---
|
|
224
|
+
|
|
225
|
+
|
|
226
|
+
## Publishing (SoftwareX)
|
|
227
|
+
|
|
228
|
+
- Manuscript draft (Markdown): [`papers/softwarex/SOFTWAREX_DRAFT.md`](papers/softwarex/SOFTWAREX_DRAFT.md)
|
|
229
|
+
- Filled official OSP Word manuscript: [`papers/softwarex/ChromeRAG_SoftwareX_OSP.docx`](papers/softwarex/ChromeRAG_SoftwareX_OSP.docx)
|
|
230
|
+
- Figures: [`papers/softwarex/figures/`](papers/softwarex/figures/)
|
|
231
|
+
- Limitations (JS shells / scoreable filter): [docs/limitations.html](docs/limitations.html)
|
|
232
|
+
- Draft self-check: `python scripts/check_softwarex_draft.py`
|
|
233
|
+
- Highlights / APC / refs explained: [`papers/softwarex/WHAT_THESE_MEAN.md`](papers/softwarex/WHAT_THESE_MEAN.md)
|
|
234
|
+
- Optional screencast shot list: [`papers/softwarex/SCREENCAST.md`](papers/softwarex/SCREENCAST.md)
|
|
235
|
+
|
|
236
|
+
SoftwareX APC (journal OA fee) is paid **only after acceptance**, not at submission.
|
|
237
|
+
|
|
238
|
+
|
|
239
|
+
## License
|
|
240
|
+
|
|
241
|
+
MIT — see [LICENSE](LICENSE) / [LICENSE.txt](LICENSE.txt) (SoftwareX naming) · also `Licence.txt`.
|
|
@@ -0,0 +1,195 @@
|
|
|
1
|
+
# ChromeRAG
|
|
2
|
+
|
|
3
|
+
[](LICENSE)
|
|
4
|
+
[](https://www.python.org/downloads/)
|
|
5
|
+
[](https://pedapudibhargav.github.io/ChromeRAG/)
|
|
6
|
+
|
|
7
|
+
**HTML → RAG-ready Markdown** that strips site-template chrome (nav, footer, CTAs, cookie banners) while keeping documentation, pricing tables, and article body text.
|
|
8
|
+
|
|
9
|
+
> Built for **enterprise RAG ingest**, **LLM chunking**, **vector indexing**, and **boilerplate / noise removal** from scraped HTML — not for pixel-perfect web archiving.
|
|
10
|
+
|
|
11
|
+
| Owns | Does **not** own |
|
|
12
|
+
|---|---|
|
|
13
|
+
| HTML string / file → clean Markdown | Crawling, Playwright, rate limits |
|
|
14
|
+
| Optional site-chrome **learn → extract** (STCE) | Full browser rendering of empty JS shells (warns; caller must render first) |
|
|
15
|
+
| Schema.org → YAML front-matter | Vector DB / embeddings |
|
|
16
|
+
| Precision / coverage priority knobs | Hosted SaaS API |
|
|
17
|
+
|
|
18
|
+
**Paper:** *ChromeRAG: Ingest-Time Elimination of Site Template Noise for Enterprise Web RAG*
|
|
19
|
+
**Release:** [`v0.1.0`](https://github.com/pedapudibhargav/ChromeRAG/tree/v0.1.0)
|
|
20
|
+
**Author:** [Bhargava Chary Peddapudi](https://orcid.org/0009-0002-8523-8415)
|
|
21
|
+
|
|
22
|
+
---
|
|
23
|
+
|
|
24
|
+
## Why ChromeRAG (vs MarkItDown / Trafilatura)?
|
|
25
|
+
|
|
26
|
+
| Tool | Best at | Gap for corporate web RAG |
|
|
27
|
+
|------|---------|---------------------------|
|
|
28
|
+
| **MarkItDown** | Office/PDF/HTML → Markdown for LLMs | Keeps a lot of page chrome; not tuned to strip SaaS nav/footer |
|
|
29
|
+
| **Trafilatura** | News/article main-content | Weaker on docs hubs, pricing matrices, marketing shells |
|
|
30
|
+
| **Readability** | Article extraction | Often drops tables / side content needed for RAG |
|
|
31
|
+
| **ChromeRAG** | Ingest-time chrome elimination + schema + tables | Focused HTML→RAG Markdown (fetch stays in your crawler) |
|
|
32
|
+
|
|
33
|
+
---
|
|
34
|
+
|
|
35
|
+
## Benchmarks (public corpus)
|
|
36
|
+
|
|
37
|
+
**Deterministic metrics** (primary claims) — independent of any single extractor:
|
|
38
|
+
|
|
39
|
+
| Metric | Meaning | Better |
|
|
40
|
+
|--------|---------|--------|
|
|
41
|
+
| **Recall** (`content_recall`) | Fraction of main/article text anchors kept | Higher |
|
|
42
|
+
| **Noise ret** (`noise_retention`) | Fraction of nav/footer chrome anchors kept | Lower |
|
|
43
|
+
| **Fbal** (`f_balanced`) | Balance of high recall + low noise | Higher |
|
|
44
|
+
|
|
45
|
+
**Baselines compared:** ChromeRAG (balanced / coverage / precision), Trafilatura, Readability, **MarkItDown**, markdownify, html2text, BeautifulSoup text.
|
|
46
|
+
|
|
47
|
+
**Corpus:** **373** URLs listed in `poc/corpus_urls.json` across `docs`, `pricing`, `marketing`, `wiki`, `hub`, `news`, `article`, `cloud`. Latest run fetched **277** HTML pages; **238** were scoreable (DOM content-anchor coverage ≥ 0.05; same fixed cohort for every tool); **39** thin pages are excluded from leaderboard *means* so empty JS shells are not silently averaged into SOTA claims.
|
|
48
|
+
|
|
49
|
+
**Latest leaderboard (238 scoreable pages):**
|
|
50
|
+
|
|
51
|
+
| Method | Recall ↑ | Noise ↓ | Fbal ↑ |
|
|
52
|
+
|--------|--------:|--------:|-------:|
|
|
53
|
+
| chromerag_coverage | 0.701 | 0.005 | **0.800** |
|
|
54
|
+
| chromerag (balanced) | 0.678 | 0.005 | 0.783 |
|
|
55
|
+
| trafilatura | 0.662 | 0.019 | 0.752 |
|
|
56
|
+
| markitdown | 0.702 | 0.261 | 0.695 |
|
|
57
|
+
| readability | 0.456 | 0.016 | 0.535 |
|
|
58
|
+
|
|
59
|
+
Full tables + per-category breakdown: [Results](https://pedapudibhargav.github.io/ChromeRAG/results.html) · `docs/data/corpus_comparison_summary.md`.
|
|
60
|
+
|
|
61
|
+
**Optional LLM judge** (secondary): stratified sample scored 1–5 on content keep / noise strip / structure when `OPENAI_API_KEY` is set (`python -m poc.run_llm_eval`). Does not replace Recall/Noise/Fbal.
|
|
62
|
+
|
|
63
|
+
---
|
|
64
|
+
|
|
65
|
+
## Quick start
|
|
66
|
+
|
|
67
|
+
### From PyPI (recommended)
|
|
68
|
+
|
|
69
|
+
```bash
|
|
70
|
+
pip install chromerag
|
|
71
|
+
# Optional: ONNX MiniLM density pruning
|
|
72
|
+
# pip install "chromerag[dvdf]"
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
### From source
|
|
76
|
+
|
|
77
|
+
```bash
|
|
78
|
+
git clone https://github.com/pedapudibhargav/ChromeRAG.git
|
|
79
|
+
cd ChromeRAG
|
|
80
|
+
python3 -m venv .venv
|
|
81
|
+
source .venv/bin/activate # Windows: .venv\Scripts\activate
|
|
82
|
+
|
|
83
|
+
# Core library + CLI
|
|
84
|
+
pip install -e .
|
|
85
|
+
|
|
86
|
+
# Optional: comparison baselines + tests
|
|
87
|
+
pip install -e ".[dev,baselines]"
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
### CLI
|
|
91
|
+
|
|
92
|
+
```bash
|
|
93
|
+
# Single page
|
|
94
|
+
chromerag extract path/to/page.html -o out.md --priority balanced --json-meta
|
|
95
|
+
|
|
96
|
+
# Priorities: precision | balanced | coverage
|
|
97
|
+
chromerag extract page.html -o clean.md --priority coverage
|
|
98
|
+
|
|
99
|
+
# Thin / JS-shell HTML prints WARNING on stderr (caller must Playwright-render first)
|
|
100
|
+
# chromerag extract spa.html -o out.md --fail-on-thin # exit 3 if thin
|
|
101
|
+
|
|
102
|
+
# Learn site chrome across a folder, then batch-extract
|
|
103
|
+
chromerag learn data/raw -o data/chrome_models/site.json --min-pages 3
|
|
104
|
+
chromerag batch data/raw -o data/outputs --chrome-model data/chrome_models/site.json
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
### Python
|
|
108
|
+
|
|
109
|
+
```python
|
|
110
|
+
from chromerag import ChromeRAG, PipelineConfig, ContentPriority
|
|
111
|
+
|
|
112
|
+
html = open("page.html", encoding="utf-8").read()
|
|
113
|
+
result = ChromeRAG(
|
|
114
|
+
config=PipelineConfig.from_priority(ContentPriority.BALANCED, enable_dvdf=False)
|
|
115
|
+
).extract(html, url="https://example.com/docs")
|
|
116
|
+
|
|
117
|
+
print(result.markdown) # RAG-ready Markdown (+ YAML front-matter when Schema.org present)
|
|
118
|
+
print(result.front_matter) # dict
|
|
119
|
+
print(result.tokens_estimate)
|
|
120
|
+
print(result.warnings) # e.g. JS shell → render with Playwright first
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
---
|
|
124
|
+
|
|
125
|
+
## Reproduce the evaluation
|
|
126
|
+
|
|
127
|
+
```bash
|
|
128
|
+
# 1) Fetch / refresh the public corpus (uses poc/corpus_urls.json)
|
|
129
|
+
python -m poc.run_corpus_comparison
|
|
130
|
+
|
|
131
|
+
# 2) Export tables + JSON into docs/ for GitHub Pages
|
|
132
|
+
python -m poc.export_site_results
|
|
133
|
+
|
|
134
|
+
# 3) Revalidate published numbers + classify thin pages
|
|
135
|
+
python scripts/revalidate_corpus.py
|
|
136
|
+
|
|
137
|
+
# 4) Optional LLM subset judge (needs OPENAI_API_KEY)
|
|
138
|
+
python -m poc.run_llm_eval --sample 40
|
|
139
|
+
|
|
140
|
+
# 5) Unit tests + regenerate docs/tests.html
|
|
141
|
+
./scripts/build_docs.sh
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
Skip re-fetch if HTML is already under `data/raw/`:
|
|
145
|
+
|
|
146
|
+
```bash
|
|
147
|
+
python -m poc.run_corpus_comparison --no-fetch
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
---
|
|
151
|
+
|
|
152
|
+
## Docs site (GitHub Pages)
|
|
153
|
+
|
|
154
|
+
Static files live in [`docs/`](docs/) (relative links only).
|
|
155
|
+
|
|
156
|
+
CI (`.github/workflows/pages.yml`) on every push to **`main`**:
|
|
157
|
+
|
|
158
|
+
1. runs `pytest`
|
|
159
|
+
2. rebuilds `docs/tests.html` + exports corpus results
|
|
160
|
+
3. deploys `docs/` → **`gh-pages`** branch
|
|
161
|
+
|
|
162
|
+
Enable once: **Settings → Pages → Deploy from a branch → `gh-pages` / (root)**.
|
|
163
|
+
Site: https://pedapudibhargav.github.io/ChromeRAG/
|
|
164
|
+
|
|
165
|
+
---
|
|
166
|
+
|
|
167
|
+
## Project layout
|
|
168
|
+
|
|
169
|
+
```
|
|
170
|
+
src/chromerag/ # library (HTML in → Markdown out)
|
|
171
|
+
poc/ # fetch, baselines, corpus comparison, LLM eval (not required at runtime)
|
|
172
|
+
docs/ # GitHub Pages site + published metrics
|
|
173
|
+
tests/ # unit tests
|
|
174
|
+
papers/softwarex/ # SoftwareX manuscript draft
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
---
|
|
178
|
+
|
|
179
|
+
|
|
180
|
+
## Publishing (SoftwareX)
|
|
181
|
+
|
|
182
|
+
- Manuscript draft (Markdown): [`papers/softwarex/SOFTWAREX_DRAFT.md`](papers/softwarex/SOFTWAREX_DRAFT.md)
|
|
183
|
+
- Filled official OSP Word manuscript: [`papers/softwarex/ChromeRAG_SoftwareX_OSP.docx`](papers/softwarex/ChromeRAG_SoftwareX_OSP.docx)
|
|
184
|
+
- Figures: [`papers/softwarex/figures/`](papers/softwarex/figures/)
|
|
185
|
+
- Limitations (JS shells / scoreable filter): [docs/limitations.html](docs/limitations.html)
|
|
186
|
+
- Draft self-check: `python scripts/check_softwarex_draft.py`
|
|
187
|
+
- Highlights / APC / refs explained: [`papers/softwarex/WHAT_THESE_MEAN.md`](papers/softwarex/WHAT_THESE_MEAN.md)
|
|
188
|
+
- Optional screencast shot list: [`papers/softwarex/SCREENCAST.md`](papers/softwarex/SCREENCAST.md)
|
|
189
|
+
|
|
190
|
+
SoftwareX APC (journal OA fee) is paid **only after acceptance**, not at submission.
|
|
191
|
+
|
|
192
|
+
|
|
193
|
+
## License
|
|
194
|
+
|
|
195
|
+
MIT — see [LICENSE](LICENSE) / [LICENSE.txt](LICENSE.txt) (SoftwareX naming) · also `Licence.txt`.
|
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=68", "wheel"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "chromerag"
|
|
7
|
+
version = "0.1.0"
|
|
8
|
+
description = "ChromeRAG: ingest-time elimination of site template noise for enterprise web RAG."
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
requires-python = ">=3.11"
|
|
11
|
+
license = { text = "MIT" }
|
|
12
|
+
authors = [{ name = "Bhargava Chary Peddapudi", email = "pedapudibhargav@gmail.com" }]
|
|
13
|
+
keywords = [
|
|
14
|
+
"rag",
|
|
15
|
+
"html",
|
|
16
|
+
"markdown",
|
|
17
|
+
"boilerplate",
|
|
18
|
+
"chrome",
|
|
19
|
+
"vector",
|
|
20
|
+
"ingest",
|
|
21
|
+
]
|
|
22
|
+
classifiers = [
|
|
23
|
+
"Development Status :: 3 - Alpha",
|
|
24
|
+
"Intended Audience :: Developers",
|
|
25
|
+
"License :: OSI Approved :: MIT License",
|
|
26
|
+
"Programming Language :: Python :: 3",
|
|
27
|
+
"Topic :: Text Processing :: Markup :: HTML",
|
|
28
|
+
"Topic :: Scientific/Engineering :: Artificial Intelligence",
|
|
29
|
+
]
|
|
30
|
+
dependencies = [
|
|
31
|
+
"beautifulsoup4>=4.12.0,<5",
|
|
32
|
+
"lxml>=5.0.0,<7",
|
|
33
|
+
"pydantic>=2.7.0,<3",
|
|
34
|
+
"pyyaml>=6.0.0,<7",
|
|
35
|
+
"tiktoken>=0.7.0",
|
|
36
|
+
"numpy>=1.26.0,<3",
|
|
37
|
+
]
|
|
38
|
+
|
|
39
|
+
[project.optional-dependencies]
|
|
40
|
+
dvdf = [
|
|
41
|
+
"onnxruntime>=1.17.0,<2",
|
|
42
|
+
]
|
|
43
|
+
# Fetch stays optional — ChromeRAG core is HTML-in / Markdown-out.
|
|
44
|
+
fetch = [
|
|
45
|
+
"httpx>=0.27.0,<0.29",
|
|
46
|
+
]
|
|
47
|
+
baselines = [
|
|
48
|
+
"markdownify>=0.13.0",
|
|
49
|
+
"readability-lxml>=0.8.1",
|
|
50
|
+
"trafilatura>=1.12.0",
|
|
51
|
+
"markitdown>=0.1.0",
|
|
52
|
+
"html2text>=2024.2.26",
|
|
53
|
+
]
|
|
54
|
+
ui = [
|
|
55
|
+
"fastapi>=0.110.0",
|
|
56
|
+
"uvicorn>=0.27.0",
|
|
57
|
+
]
|
|
58
|
+
dev = [
|
|
59
|
+
"pytest>=8.0.0",
|
|
60
|
+
"ruff>=0.6.0",
|
|
61
|
+
"httpx>=0.27.0,<0.29",
|
|
62
|
+
]
|
|
63
|
+
|
|
64
|
+
[project.scripts]
|
|
65
|
+
chromerag = "chromerag.cli:main"
|
|
66
|
+
|
|
67
|
+
[project.urls]
|
|
68
|
+
Homepage = "https://github.com/pedapudibhargav/ChromeRAG"
|
|
69
|
+
Repository = "https://github.com/pedapudibhargav/ChromeRAG.git"
|
|
70
|
+
Issues = "https://github.com/pedapudibhargav/ChromeRAG/issues"
|
|
71
|
+
Documentation = "https://pedapudibhargav.github.io/ChromeRAG/"
|
|
72
|
+
|
|
73
|
+
[tool.setuptools.packages.find]
|
|
74
|
+
where = ["src"]
|
|
75
|
+
|
|
76
|
+
[tool.setuptools.package-data]
|
|
77
|
+
chromerag = ["assets/*.json", "assets/*.txt"]
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
"""ChromeRAG — Ingest-time elimination of site template noise for enterprise web RAG.
|
|
2
|
+
|
|
3
|
+
Core contract: HTML string in → RAG-ready Markdown out.
|
|
4
|
+
Fetching/crawling is intentionally out of scope (use your crawler / poc harness).
|
|
5
|
+
"""
|
|
6
|
+
|
|
7
|
+
from chromerag.batch import learn_then_extract
|
|
8
|
+
from chromerag.config import ContentPriority, PageType, PipelineConfig, Strictness
|
|
9
|
+
from chromerag.extractor import ChromeRAG
|
|
10
|
+
from chromerag.input_quality import InputQualityReport, assess_input_html
|
|
11
|
+
from chromerag.models import ExtractResult
|
|
12
|
+
from chromerag.site_chrome import (
|
|
13
|
+
SiteChromeModel,
|
|
14
|
+
load_chrome_models,
|
|
15
|
+
mine_site_chrome,
|
|
16
|
+
save_chrome_models,
|
|
17
|
+
)
|
|
18
|
+
|
|
19
|
+
__all__ = [
|
|
20
|
+
"ChromeRAG",
|
|
21
|
+
"ExtractResult",
|
|
22
|
+
"PipelineConfig",
|
|
23
|
+
"ContentPriority",
|
|
24
|
+
"Strictness",
|
|
25
|
+
"PageType",
|
|
26
|
+
"SiteChromeModel",
|
|
27
|
+
"mine_site_chrome",
|
|
28
|
+
"save_chrome_models",
|
|
29
|
+
"load_chrome_models",
|
|
30
|
+
"learn_then_extract",
|
|
31
|
+
"assess_input_html",
|
|
32
|
+
"InputQualityReport",
|
|
33
|
+
]
|
|
34
|
+
__version__ = "0.1.0"
|
|
35
|
+
__paper__ = (
|
|
36
|
+
"ChromeRAG: Ingest-Time Elimination of Site Template Noise for Enterprise Web RAG"
|
|
37
|
+
)
|