pgrag-eval-lite 0.2.0__py3-none-any.whl

pgrag_eval_lite-0.2.0.dist-info/METADATA

@@ -0,0 +1,31 @@
+Metadata-Version: 2.4
+Name: pgrag-eval-lite
+Version: 0.2.0
+Summary: Local-First RAG Retrieval, Chunking & pgvector Diagnostic Workbench (CLI)
+Author: pgRAG-Inspector Engineering
+License: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: pydantic>=2.10.0
+Requires-Dist: polars>=1.18.0
+Requires-Dist: numpy>=2.1.0
+Requires-Dist: rich>=13.9.4
+Requires-Dist: typer>=0.15.1
+Requires-Dist: sqlalchemy>=2.0.36
+Requires-Dist: pgvector>=0.3.6
+Provides-Extra: dev
+Requires-Dist: pytest>=8.3.0; extra == "dev"
+Provides-Extra: postgres
+Requires-Dist: asyncpg>=0.30.0; extra == "postgres"
+
+# pgRAG-Inspector (pgrag-eval-lite & pgRAG-Inspector Pro)
+
+Local-First RAG Retrieval, Chunking & pgvector 0.8+ Diagnostic Workbench.
+
+## Quickstart (Windows / macOS / Linux)
+
+    pip install -e .
+    pgrag init-samples
+    pgrag check --chunks examples/sample_chunks.json --golden examples/sample_golden_qa.json --fail-under-recall5 95
+    pgrag export-code --out-dir exported_rag_stack --agency-name "Your AI Engineering Studio"
+    pgrag studio

pgrag_eval_lite-0.2.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+pgrag_inspector/__init__.py,sha256=l3NPDJ-VFKIWuhMO85paQUHLzI31P5-KpspwQNbnBgk,119
+pgrag_inspector/chunk_diff.py,sha256=f0VGbGKP08P-KctE4A0RzKF6i17EhfYFjRGv8hIW2UU,9134
+pgrag_inspector/cli.py,sha256=Oy-0nmv0mQ6q2rXRagNzUAbdtn5OtnrEqwsmOBTZsbs,15622
+pgrag_inspector/exporter.py,sha256=s8aZQkkDduvVe94NSZGpqvNrc-X_JCvQUlVGAx3OO6Y,16479
+pgrag_inspector/metrics.py,sha256=JsTxQqzpAbaV_VgoQfYIWjMO18otmGxmVa_epKPBXT4,3196
+pgrag_inspector/models.py,sha256=NLJn8_jDSvaX0EWlvpNshL-noOg6ar-rspxTuRxB5wc,2114
+pgrag_inspector/retrieval.py,sha256=kFyev8G-Asw6sAD7SjkeKcZdTsRQUFba1NAel60LXpg,9139
+pgrag_inspector/sample_data.py,sha256=YnUJBiQbHfYvZPvkEpj9XiLv58liW3nDCZvosoGNDic,25895
+pgrag_inspector/scanner.py,sha256=J2N5ClnjW7f6selE8iJ_vFkzvqVB9HS-8w4r2M5oIhI,3891
+pgrag_inspector/studio.py,sha256=h9fkP8wnT2HdNgf-fXhi0VSQEihoEmevDRyLG4ii9_o,57633
+pgrag_inspector/synthesizer.py,sha256=xqw-PpMDciphr2ObRz7avyWiQg_uVoLnLj1CQo9bk10,4895
+pgrag_eval_lite-0.2.0.dist-info/METADATA,sha256=KRfV4i612_d7UTxufH4ErUSoxXt1n-Oyh5wgrcxTc8o,1091
+pgrag_eval_lite-0.2.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+pgrag_eval_lite-0.2.0.dist-info/entry_points.txt,sha256=qDq7NI2QpoW01t3Jw71dW8Q4ELoUfO3fxUDue60lH58,50
+pgrag_eval_lite-0.2.0.dist-info/top_level.txt,sha256=0yCoY20owoL7yoq25aOTJIbKQGLRgVQ4gh9ZPpUjGBg,16
+pgrag_eval_lite-0.2.0.dist-info/RECORD,,

pgrag_eval_lite-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pgrag_eval_lite-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pgrag = pgrag_inspector.cli:app

pgrag_eval_lite-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+pgrag_inspector

pgrag_inspector/__init__.py

@@ -0,0 +1,3 @@
+"""pgRAG-Inspector: Local-First RAG Retrieval, Chunking & pgvector Diagnostic Workbench."""
+
+__version__ = "0.2.0"

pgrag_inspector/chunk_diff.py

@@ -0,0 +1,239 @@
+from __future__ import annotations
+
+import re
+from pydantic import BaseModel, ConfigDict
+from pgrag_inspector.models import ChunkRecord
+from pgrag_inspector.scanner import scan_chunks_health
+
+try:
+    from docling.document_converter import DocumentConverter  # type: ignore[import-not-found]
+    from docling.chunking import HybridChunker  # type: ignore[import-not-found]
+
+    HAS_DOCLING = True
+except ImportError:
+    HAS_DOCLING = False
+
+
+class VisualDiffChunk(BaseModel):
+    """Represents a chunk rendered inside the 3-column Visual Diff Studio."""
+
+    model_config = ConfigDict(strict=True)
+
+    chunk_id: int
+    strategy_name: str
+    heading_context: str
+    content: str
+    token_count: int
+    overlap_pct: float
+    has_broken_table: bool
+    has_cutoff: bool
+    has_high_overlap: bool
+    badge_label: str
+    badge_color: str
+
+
+class StrategyDiffColumn(BaseModel):
+    """Summary and chunk list for one column in the 3-Strategy Diff Studio."""
+
+    model_config = ConfigDict(strict=True)
+
+    strategy_id: str
+    title: str
+    subtitle: str
+    total_chunks: int
+    broken_tables_count: int
+    high_overlap_count: int
+    cutoff_count: int
+    chunks: list[VisualDiffChunk]
+
+
+SAMPLE_RAW_DOCUMENT = """# SEC Form 10-K: Cloud & Vector Infrastructure Division (FY 2026)
+
+## Section 1. Consolidated Q3 2026 Segment Revenue & Gross Margin
+Our Sovereign AI Cloud and Managed pgvector RDS divisions drove record top-line expansion during the third quarter ended September 30, 2026, supported by enterprise migration to dedicated HNSW vector clusters across regulated financial institutions.
+
+| Segment Division | Q3 2026 Revenue ($M) | YoY Growth (%) | Gross Margin (%) |
+| --- | --- | --- | --- |
+| Sovereign AI Cloud | $412.80 | +64.2% | 78.4% |
+| Managed pgvector RDS | $189.45 | +41.8% | 71.2% |
+| Legacy On-Premise ETL | $54.10 | -12.5% | 44.0% |
+
+Total consolidated Q3 2026 revenue reached $656.35M under ASC 606 guidelines.
+
+## Section 2. Managed PostgreSQL 17 HNSW Vector Instance Matrix
+Enterprise customers deploying high-dimensional vector indexes require predictable IOPS and memory pinning across availability zones to prevent index paging during concurrent hybrid search queries.
+
+| Instance SKU | vCPU | RAM (GB) | Max Provisioned IOPS | Hourly Rate (USD) |
+| --- | --- | --- | --- | --- |
+| db.pg17.vec.2xlarge | 8 | 64 GB | 40,000 IOPS | $1.480/hr |
+| db.pg17.vec.8xlarge | 32 | 256 GB | 120,000 IOPS | $5.920/hr |
+| db.pg17.vec.16xlarge | 64 | 512 GB | 256,000 IOPS | $11.840/hr |
+
+## Section 3. HNSW Filtered Query Recall & Iterative Index Scans
+When executing vector similarity queries combined with a restrictive WHERE clause (such as tenant_id or workspace_tier filtering), classic HNSW graph traversal evaluates the post-filter only on the fixed ef_search candidate pool. This causes severe recall starvation where fewer than K rows are returned. Enabling pgvector 0.8+ iterative index scans via SET LOCAL hnsw.iterative_scan = 'relaxed_order' automatically continues traversing the graph until LIMIT K matching tuples are found.
+"""
+
+
+def _annotate_column(
+    strategy_id: str,
+    title: str,
+    subtitle: str,
+    raw_pieces: list[tuple[str, str]],
+    base_id: int,
+) -> StrategyDiffColumn:
+    chunk_records: list[ChunkRecord] = []
+    for idx, (_, text_body) in enumerate(raw_pieces):
+        chunk_records.append(
+            ChunkRecord(
+                id=base_id + idx,
+                doc_id="LIVE-STUDIO-DOC.md",
+                content=text_body,
+            )
+        )
+
+    flags = scan_chunks_health(chunk_records)
+    broken_ids = {
+        f.chunk_id for f in flags if f.issue_type == "BROKEN_MARKDOWN_TABLE"
+    }
+    overlap_map = {
+        f.chunk_id: f.overlap_Or_severity
+        for f in flags
+        if f.issue_type == "HIGH_TOKEN_OVERLAP (>80%)"
+    }
+    cutoff_ids = {
+        f.chunk_id for f in flags if f.issue_type == "MID_SENTENCE_CUTOFF"
+    }
+
+    visual_chunks: list[VisualDiffChunk] = []
+    for idx, (heading_ctx, text_body) in enumerate(raw_pieces):
+        cid = base_id + idx
+        is_broken = cid in broken_ids
+        is_cutoff = cid in cutoff_ids
+        ov_pct = overlap_map.get(cid, 0.0)
+        is_overlap = ov_pct > 80.0
+        tok_count = len(re.findall(r"\S+", text_body))
+
+        if is_overlap:
+            badge_label = f"HIGH OVERLAP ({ov_pct:.0f}%)"
+            badge_color = "amber"
+        elif is_broken:
+            badge_label = "BROKEN TABLE SPLIT"
+            badge_color = "red"
+        elif is_cutoff:
+            badge_label = "MID-SENTENCE CUTOFF"
+            badge_color = "rose"
+        else:
+            badge_label = "HEALTHY + CONTEXTUALIZED"
+            badge_color = "emerald"
+
+        visual_chunks.append(
+            VisualDiffChunk(
+                chunk_id=cid,
+                strategy_name=title,
+                heading_context=heading_ctx,
+                content=text_body,
+                token_count=tok_count,
+                overlap_pct=ov_pct,
+                has_broken_table=is_broken,
+                has_cutoff=is_cutoff,
+                has_high_overlap=is_overlap,
+                badge_label=badge_label,
+                badge_color=badge_color,
+            )
+        )
+
+    return StrategyDiffColumn(
+        strategy_id=strategy_id,
+        title=title,
+        subtitle=subtitle,
+        total_chunks=len(visual_chunks),
+        broken_tables_count=len(broken_ids),
+        high_overlap_count=len(overlap_map),
+        cutoff_count=len(cutoff_ids),
+        chunks=visual_chunks,
+    )
+
+
+def build_three_way_chunk_diff(raw_markdown: str = SAMPLE_RAW_DOCUMENT) -> list[StrategyDiffColumn]:
+    """Generates the 3-column visual diff comparing Naive, High-Overlap, and Docling HybridChunker."""
+    clean_doc = raw_markdown.strip() or SAMPLE_RAW_DOCUMENT
+
+    # Strategy A: Naive Fixed-Character Splitter (slices tables mid-row & mid-sentence)
+    naive_pieces: list[tuple[str, str]] = []
+    step = 260
+    for i in range(0, len(clean_doc), step):
+        slice_str = clean_doc[i : i + 290].strip()
+        if slice_str:
+            naive_pieces.append(("None (Raw Character Slice)", slice_str))
+
+    # Strategy B: Sliding Window High-Overlap Splitter (>85% duplicate tokens between adjacent chunks)
+    raw_blocks = [b.strip() for b in re.split(r"\n\s*\n", clean_doc) if b.strip()]
+    overlap_pieces: list[tuple[str, str]] = []
+    for block in raw_blocks:
+        non_heading_lines = [
+            line.strip()
+            for line in block.splitlines()
+            if line.strip() and not line.strip().startswith("#")
+        ]
+        if not non_heading_lines:
+            continue
+        p = "\n".join(non_heading_lines)
+        if p.startswith("|"):
+            rows = [r.strip() for r in p.splitlines() if r.strip()]
+            if len(rows) >= 4:
+                overlap_pieces.append(("Uncontextualized Table Slice", "\n".join(rows[2:])))
+        elif len(p) > 120:
+            overlap_pieces.append(("Sliding Window (stride=12% — Window 1)", p))
+            words = p.split()
+            if len(words) > 10:
+                slid = " ".join(words[2:])
+                if not slid.endswith("."):
+                    slid += "."
+                overlap_pieces.append(
+                    ("Sliding Window (stride=12% — 92% Duplicate Tokens)", slid)
+                )
+
+    # Strategy C: Docling HybridChunker + contextualize() (Preserves tables & injects parent headings)
+    docling_pieces: list[tuple[str, str]] = []
+    current_h1 = "Document Root"
+    current_h2 = "General Section"
+
+    sections = re.split(r"(?m)^(?=##\s)", clean_doc)
+    for sec in sections:
+        lines = [line.strip() for line in sec.strip().splitlines() if line.strip()]
+        if not lines:
+            continue
+        if lines[0].startswith("# "):
+            current_h1 = lines[0].lstrip("# ").strip()
+            continue
+        if lines[0].startswith("## "):
+            current_h2 = lines[0].lstrip("# ").strip()
+            body = "\n".join(lines[1:]).strip()
+            ctx_header = f"{current_h1} > {current_h2}"
+            contextualized_body = f"### {ctx_header}\n{body}"
+            if not contextualized_body.endswith((".", "|", "!", "?")):
+                contextualized_body += "."
+            docling_pieces.append((ctx_header, contextualized_body))
+
+    col_a = _annotate_column(
+        strategy_id="naive_fixed",
+        title="Strategy A: Naive Fixed-Char (290 chars)",
+        subtitle="Slices Markdown tables mid-row & truncates clauses",
+        raw_pieces=naive_pieces[:5],
+        base_id=201,
+    )
+    col_b = _annotate_column(
+        strategy_id="sliding_overlap",
+        title="Strategy B: High-Overlap Window (85% overlap)",
+        subtitle="Stuffs duplicate tokens into LLM context window",
+        raw_pieces=overlap_pieces[:6],
+        base_id=301,
+    )
+    col_c = _annotate_column(
+        strategy_id="docling_hybrid",
+        title="Strategy C: Docling HybridChunker + contextualize()",
+        subtitle="Preserves whole tables & prepends section hierarchy",
+        raw_pieces=docling_pieces,
+        base_id=401,
+    )
+    return [col_a, col_b, col_c]