md-rag-core 0.0.1__tar.gz

md_rag_core-0.0.1/.gitignore

@@ -0,0 +1,58 @@
+# Compiled class file
+*.class
+
+# Log file
+*.log
+
+# BlueJ files
+*.ctxt
+
+*.ini
+
+# Mobile Tools for Java (J2ME)
+.mtj.tmp/
+
+# Package Files #
+*.jar
+*.war
+
+# virtual machine crash logs, see http://www.java.com/en/download/help/error_hotspot.xml
+hs_err_pid*
+
+# IDEA or eclipse files #
+.settings/
+.project
+.classpath
+.factorypath
+.idea/
+*.iml
+
+# mvn target
+target/
+.mvn/
+
+# log files
+logs/
+
+# npm files
+node_modules/
+rebel.xml
+
+# mac os
+.DS_Store
+
+docker-compose/
+finalshell/
+__pycache__/
+nlb-nginx/
+build/
+dist/
+.pytest_cache/
+/royal_tsx/
+deploy_python/
+inis-*/
+logs/
+*.c
+*.key
+*.pem
+nacos-data

md_rag_core-0.0.1/PKG-INFO

@@ -0,0 +1,18 @@
+Metadata-Version: 2.4
+Name: md-rag-core
+Version: 0.0.1
+Summary: A core library for Markdown-aware chunking, semantic structuring, vectorization, and RAG retrieval.
+Author-email: ferdinand <gongjpa@gmail.com>
+License-Expression: Apache-2.0 OR MIT
+Keywords: RAG,chunking,markdown,retrieval,semantic
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.12
+Provides-Extra: test
+Requires-Dist: pytest>=9.0.2; extra == 'test'

md_rag_core-0.0.1/pyproject.toml

@@ -0,0 +1,63 @@
+[project]
+name = "md-rag-core"
+dynamic = ["version"]
+description = "A core library for Markdown-aware chunking, semantic structuring, vectorization, and RAG retrieval."
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = []
+
+# 协议信息
+license = "Apache-2.0 OR MIT"
+authors = [
+  { name = "ferdinand", email = "gongjpa@gmail.com" },
+]
+
+# 可以到网站https://pypi.org/classifiers/查找合适的classifiers
+classifiers = [
+  "Development Status :: 2 - Pre-Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: Apache Software License",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+# 关键字方便快速检索
+keywords = [
+  "markdown", "semantic", "RAG", "retrieval", "chunking"
+]
+
+[project.optional-dependencies]
+test = [
+    "pytest>=9.0.2",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+
+# === 关键配置: 指定包的位置 ===
+# 告诉 hatchling，真正得包代码在 src 目录下
+[tool.hatch.build.targets.wheel]
+packages = ["src/md_rag_core"]
+
+[tool.hatch.build.targets.sdist]
+# 明确指定 sdist 只包含 src 目录，排除 test 目录等其他根目录文件
+include = [
+    "src",
+    # 建议也包含 README 和 LICENSE，否则 pip 安装有时会发出警告
+    "README.md",
+    "pyproject.toml"
+]
+
+[tool.hatch.version]
+path = "src/md_rag_core/__init__.py"
+
+[[tool.uv.index]]
+name = "testpypi"
+url = "https://test.pypi.org/simple/"
+publish-url = "https://test.pypi.org/legacy/"
+explicit = true

md_rag_core-0.0.1/src/md_rag_core/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.0.1"

md_rag_core-0.0.1/src/md_rag_core/chunker/__init__.py

@@ -0,0 +1,25 @@
+"""
+chunker/aggregators/__init__.py — 聚合器包导出
+
+统一导出所有 Aggregator 类，方便外部直接导入。
+"""
+
+from .aggregators.base import BaseAggregator
+from .aggregators.text_aggregator    import TextAggregator
+from .aggregators.code_aggregator    import CodeAggregator
+from .aggregators.table_aggregator   import TableAggregator
+from .aggregators.math_aggregator    import MathAggregator
+from .aggregators.list_aggregator    import ListAggregator
+from .aggregators.image_aggregator   import ImageAggregator
+from .aggregators.section_aggregator import SectionAggregator
+
+__all__ = [
+    "BaseAggregator",
+    "TextAggregator",
+    "CodeAggregator",
+    "TableAggregator",
+    "MathAggregator",
+    "ListAggregator",
+    "ImageAggregator",
+    "SectionAggregator",
+]

md_rag_core-0.0.1/src/md_rag_core/chunker/aggregators/base.py

@@ -0,0 +1,194 @@
+"""
+chunker/aggregators/base.py — 聚合器抽象基类
+
+定义所有类型感知聚合器（Aggregator）的统一接口。
+
+设计思路
+--------
+与 Block 解析层的 Handler 模式类似，Chunk 层的聚合也采用"策略模式"：
+每种 Block 类型对应一个独立的 Aggregator，负责将该类型的 Block 组合成 Chunk。
+
+主协调器（SectionAggregator）按类型将 Block 分流给对应的 Aggregator，
+每个 Aggregator 只关心自己负责的类型，互不干扰，便于独立测试和扩展。
+
+Aggregator 的职责
+-----------------
+1. 接收一组同类 Block（及其位置上下文）
+2. 按本类型的语义聚合规则，生成一个或多个原始 Chunk（尚未注入面包屑）
+3. 返回 Chunk 列表
+
+注意：Aggregator 不负责注入标题面包屑，也不负责 token 大小的最终校正，
+这两项工作由后处理器（PostProcessor）统一完成。
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from ...chunker.models import Chunk, ChunkConfig, Section
+
+
+class BaseAggregator(ABC):
+    """
+    聚合器抽象基类。
+
+    子类需实现 aggregate() 方法，将 Section 内的一组 Block 组合为 Chunk 列表。
+    """
+
+    def __init__(self, config: ChunkConfig) -> None:
+        """
+        Args:
+            config : 全局拆分配置，控制 token 上限、上下文长度等参数
+        """
+        self.config = config
+
+    @abstractmethod
+    def aggregate(
+        self,
+        section: Section,
+        blocks: list[dict[str, Any]],
+        all_section_blocks: list[dict[str, Any]],
+    ) -> list[Chunk]:
+        """
+        将一批 Block 聚合为 Chunk 列表。
+
+        Args:
+            section            : 当前 Block 所属的 Section（用于获取 title_path）
+            blocks             : 本次需要聚合的 Block 列表（已按类型筛选）
+            all_section_blocks : Section 内的全部 Block（用于查找上下文：
+                                 代码/表格/公式需要取前后的 text Block）
+
+        Returns:
+            生成的 Chunk 列表（已设置 content、chunk_type、source_blocks、token_count，
+            但尚未注入 heading_prefix）
+        """
+        ...
+
+    # ------------------------------------------------------------------
+    # 工具方法（供子类共享）
+    # ------------------------------------------------------------------
+
+    def _find_prev_text_block(
+        self,
+        target_block: dict[str, Any],
+        all_blocks: list[dict[str, Any]],
+        max_tokens: int,
+    ) -> dict[str, Any] | None:
+        """
+        在 all_blocks 中找到 target_block 之前最近的一个 text Block，
+        且其 token 数不超过 max_tokens。
+
+        用于代码/表格/公式聚合时绑定"前置说明段落"。
+
+        Args:
+            target_block : 目标 Block（代码/表格/公式）
+            all_blocks   : Section 内的完整 Block 列表
+            max_tokens   : 上下文 token 上限
+
+        Returns:
+            符合条件的 text Block，或 None（不存在时）
+        """
+        from ...chunker.models import estimate_tokens
+
+        target_idx = self._find_block_position(target_block, all_blocks)
+        if target_idx <= 0:
+            return None
+
+        # 向前扫描，找第一个 text 类型的 Block
+        for i in range(target_idx - 1, -1, -1):
+            b = all_blocks[i]
+            if b.get("type") == "text":
+                if estimate_tokens(b.get("text", "")) <= max_tokens:
+                    return b
+                # 超过 token 限制：截取前 max_tokens 对应的字符数
+                return self._truncate_block(b, max_tokens)
+        return None
+
+    def _find_next_text_block(
+        self,
+        target_block: dict[str, Any],
+        all_blocks: list[dict[str, Any]],
+        max_tokens: int,
+    ) -> dict[str, Any] | None:
+        """
+        在 all_blocks 中找到 target_block 之后最近的一个 text Block，
+        且其 token 数不超过 max_tokens。
+
+        用于代码/表格/公式聚合时绑定"后置补充段落"。
+        """
+        from ...chunker.models import estimate_tokens
+
+        target_idx = self._find_block_position(target_block, all_blocks)
+        if target_idx < 0 or target_idx >= len(all_blocks) - 1:
+            return None
+
+        for i in range(target_idx + 1, len(all_blocks)):
+            b = all_blocks[i]
+            if b.get("type") == "text":
+                if estimate_tokens(b.get("text", "")) <= max_tokens:
+                    return b
+                return self._truncate_block(b, max_tokens)
+        return None
+
+    @staticmethod
+    def _find_block_position(
+        target: dict[str, Any],
+        block_list: list[dict[str, Any]],
+    ) -> int:
+        """
+        在 block_list 中定位 target Block 的索引。
+
+        优先通过 _block_index 字段（全局原始索引）匹配，
+        以应对 Block 字典被复制或部分修改的情况。
+
+        Args:
+            target     : 目标 Block
+            block_list : 待搜索的列表
+
+        Returns:
+            目标在列表中的位置索引，未找到返回 -1
+        """
+        target_global_idx = target.get("_block_index")
+        if target_global_idx is not None:
+            for i, b in enumerate(block_list):
+                if b.get("_block_index") == target_global_idx:
+                    return i
+        # 降级：按对象 id 匹配
+        for i, b in enumerate(block_list):
+            if b is target:
+                return i
+        return -1
+
+    @staticmethod
+    def _truncate_block(block: dict[str, Any], max_tokens: int) -> dict[str, Any]:
+        """
+        返回一个 text Block 的截断副本，使其 token 数不超过 max_tokens。
+
+        截断在字符层面进行（chars ≈ tokens * 1.5），
+        尽量在句子末尾（句号/换行）处截断，保证截断后语义相对完整。
+
+        Args:
+            block      : 原始 text Block
+            max_tokens : 截断后的 token 上限
+
+        Returns:
+            截断后的 Block 副本（不修改原始 Block）
+        """
+        max_chars = int(max_tokens * 1.5)
+        text = block.get("text", "")
+        if len(text) <= max_chars:
+            return block
+
+        # 在 max_chars 附近找最近的句子边界（句号、问号、感叹号、换行）
+        truncated = text[:max_chars]
+        for sep in ("。", "\n", ".", "!", "?", "；"):
+            pos = truncated.rfind(sep)
+            if pos > max_chars // 2:  # 避免截断点太靠前
+                truncated = truncated[: pos + 1]
+                break
+
+        result = dict(block)
+        result["text"] = truncated
+        result["_truncated"] = True
+        return result

md_rag_core-0.0.1/src/md_rag_core/chunker/aggregators/code_aggregator.py

@@ -0,0 +1,241 @@
+"""
+chunker/aggregators/code_aggregator.py — 代码块聚合器
+
+负责将代码 Block 与其上下文绑定，生成语义完整的 Chunk。
+
+问题背景
+--------
+孤立的代码块向量无法表达"这段代码是干什么用的"。
+用户提问"怎么初始化连接池"时，代码块本身可能不含"连接池"这个词，
+无法被向量检索命中。
+
+绑定策略
+--------
+  前置上下文（≤ code_context_max token）
+  + 代码块完整内容
+  + 后置上下文（≤ code_context_max token，可选）
+  → 一个 code 类 Chunk
+
+超大代码块处理
+--------------
+当代码块本身 token 数超过 code_token_max 时，按以下规则拆分：
+  1. 按连续空行（≥2 个空行，通常是函数/类之间的间隔）拆分为逻辑段
+  2. 每段保留代码语言标识，前置上下文只附加到第一段
+  3. 相邻段之间保留 overlap_token_size 个 token 的重叠
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from ...chunker.models import Chunk, ChunkType, Section, estimate_tokens
+from ...chunker.aggregators.base import BaseAggregator
+
+
+class CodeAggregator(BaseAggregator):
+    """代码块聚合器，将代码 Block 与前后上下文绑定成 Chunk。"""
+
+    def aggregate(
+        self,
+        section: Section,
+        blocks: list[dict[str, Any]],
+        all_section_blocks: list[dict[str, Any]],
+    ) -> list[Chunk]:
+        """
+        每个代码 Block 独立处理，绑定前后最近的 text Block 作为上下文。
+
+        Args:
+            section            : 当前章节（提供 title_path）
+            blocks             : 经过类型筛选的 code Block 列表
+            all_section_blocks : 章节内全部 Block（用于查找前后上下文）
+
+        Returns:
+            code 类 Chunk 列表
+        """
+        chunks: list[Chunk] = []
+
+        for code_block in blocks:
+            # 查找前置说明段落
+            prev_text = self._find_prev_text_block(
+                code_block, all_section_blocks, self.config.code_context_max
+            )
+            # 查找后置补充说明
+            next_text = self._find_next_text_block(
+                code_block, all_section_blocks, self.config.code_context_max
+            )
+
+            code_text    = code_block.get("text", "")
+            code_tokens  = estimate_tokens(code_text)
+            language     = code_block.get("meta", {}).get("language", "")
+
+            if code_tokens <= self.config.code_token_max:
+                # 正常大小的代码块：直接绑定上下文成一个 Chunk
+                chunks.append(
+                    self._make_code_chunk(
+                        code_block=code_block,
+                        prev_text_block=prev_text,
+                        next_text_block=next_text,
+                        section=section,
+                    )
+                )
+            else:
+                # 超大代码块：按逻辑边界拆分后逐段处理
+                sub_chunks = self._split_large_code(
+                    code_block=code_block,
+                    prev_text_block=prev_text,
+                    language=language,
+                    section=section,
+                )
+                chunks.extend(sub_chunks)
+
+        return chunks
+
+    def _make_code_chunk(
+        self,
+        code_block: dict[str, Any],
+        prev_text_block: dict[str, Any] | None,
+        next_text_block: dict[str, Any] | None,
+        section: Section,
+    ) -> Chunk:
+        """
+        将代码块与前后上下文拼接为一个 Chunk。
+
+        拼接格式：
+          [前置说明]（可选）
+          [空行]
+          [代码内容]
+          [空行]
+          [后置说明]（可选）
+        """
+        parts: list[str] = []
+        source_blocks: list[dict[str, Any]] = []
+
+        if prev_text_block:
+            parts.append(prev_text_block.get("text", ""))
+            source_blocks.append(prev_text_block)
+
+        parts.append(code_block.get("text", ""))
+        source_blocks.append(code_block)
+
+        if next_text_block:
+            parts.append(next_text_block.get("text", ""))
+            source_blocks.append(next_text_block)
+
+        content = "\n\n".join(parts)
+        return Chunk(
+            content=content,
+            chunk_type=ChunkType.CODE,
+            title_path=list(section.title_path),
+            source_blocks=source_blocks,
+            token_count=estimate_tokens(content),
+            metadata={"language": code_block.get("meta", {}).get("language", "")},
+        )
+
+    def _split_large_code(
+        self,
+        code_block: dict[str, Any],
+        prev_text_block: dict[str, Any] | None,
+        language: str,
+        section: Section,
+    ) -> list[Chunk]:
+        """
+        将超大代码块按逻辑边界（连续空行）拆分为多个 Chunk。
+
+        拆分规则：
+          - 以连续 2 个或以上空行作为逻辑段的分隔点（通常是函数/类之间）
+          - 每段保留语言标识（代码围栏格式）
+          - 前置上下文只附加到第一段，避免上下文在每段重复，稀释语义
+          - 相邻段之间保留重叠：后一段包含前一段最后 overlap_token_size 个 token 的内容
+
+        Args:
+            code_block      : 原始代码 Block
+            prev_text_block : 前置上下文（可为 None）
+            language        : 代码语言标识
+            section         : 当前章节
+
+        Returns:
+            拆分后的 Chunk 列表
+        """
+        code_text = code_block.get("text", "")
+
+        # 按连续空行切分代码段
+        # re.split 以 2 个以上连续换行为分隔符
+        raw_segments = re.split(r"\n{2,}", code_text)
+        # 过滤掉空段
+        segments = [s.strip() for s in raw_segments if s.strip()]
+
+        if len(segments) <= 1:
+            # 无法找到逻辑边界，强制按字符数切割（兜底策略）
+            segments = self._force_split_by_size(code_text)
+
+        chunks: list[Chunk] = []
+        overlap_text = ""  # 前一段的重叠尾部
+
+        for seg_idx, segment in enumerate(segments):
+            # 在重叠文本前加上语言标识围栏（便于向量模型识别代码类型）
+            if language:
+                seg_with_lang = f"```{language}\n{overlap_text}{segment}\n```"
+            else:
+                seg_with_lang = f"```\n{overlap_text}{segment}\n```"
+
+            parts: list[str] = []
+            source_blocks: list[dict[str, Any]] = [code_block]
+
+            # 前置上下文只附加到第一个子段
+            if seg_idx == 0 and prev_text_block:
+                parts.append(prev_text_block.get("text", ""))
+                source_blocks.insert(0, prev_text_block)
+
+            parts.append(seg_with_lang)
+            content = "\n\n".join(parts)
+
+            chunks.append(Chunk(
+                content=content,
+                chunk_type=ChunkType.CODE,
+                title_path=list(section.title_path),
+                source_blocks=source_blocks,
+                token_count=estimate_tokens(content),
+                metadata={
+                    "language":      language,
+                    "segment_index": seg_idx,
+                    "total_segments": len(segments),
+                },
+            ))
+
+            # 计算下一段的重叠内容：取当前段末尾 overlap_token_size 对应的字符
+            overlap_chars = int(self.config.overlap_token_size * 1.5)
+            overlap_text  = segment[-overlap_chars:] if len(segment) > overlap_chars else segment
+            # 重叠文本加注释标记，让向量模型知道这是延续内容
+            overlap_text  = f"# ... (续上段)\n{overlap_text}\n\n"
+
+        return chunks
+
+    def _force_split_by_size(self, code_text: str) -> list[str]:
+        """
+        兜底策略：在无法找到逻辑边界时，按固定字符数强制切割代码。
+
+        切割时尽量在换行处切割，避免在代码行中间截断。
+
+        Args:
+            code_text : 完整代码文本
+
+        Returns:
+            切割后的代码片段列表
+        """
+        max_chars = int(self.config.code_token_max * 1.5)
+        segments  = []
+        remaining = code_text
+
+        while len(remaining) > max_chars:
+            # 在 max_chars 附近找最近的换行处
+            cut_pos = remaining.rfind("\n", 0, max_chars)
+            if cut_pos <= 0:
+                cut_pos = max_chars  # 实在找不到换行，强制截断
+            segments.append(remaining[:cut_pos])
+            remaining = remaining[cut_pos:].lstrip("\n")
+
+        if remaining:
+            segments.append(remaining)
+
+        return segments