lightrag-section-anything 0.1.0__tar.gz

lightrag_section_anything-0.1.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

lightrag_section_anything-0.1.0/MANIFEST.in

@@ -0,0 +1,2 @@
+include LICENSE NOTICE README.md
+recursive-include tests *.py

lightrag_section_anything-0.1.0/NOTICE

@@ -0,0 +1,7 @@
+lightrag-section-anything
+Copyright 2026 The Section Anything Authors
+
+This product is licensed under the Apache License, Version 2.0 (see LICENSE).
+
+It uses, without bundling, section-anything (Apache-2.0) and LightRAG
+(lightrag-hku, MIT). Each is installed separately under its own licence.

lightrag_section_anything-0.1.0/PKG-INFO

@@ -0,0 +1,78 @@
+Metadata-Version: 2.4
+Name: lightrag-section-anything
+Version: 0.1.0
+Summary: Section Anything PDF parser engines for LightRAG: accurate headings for heading-aware chunking, with a cost/accuracy dial.
+Author: The Section Anything Authors
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/Omniwot/section-anything/tree/main/packages/lightrag-section-anything
+Project-URL: Repository, https://github.com/Omniwot/section-anything
+Project-URL: Issues, https://github.com/Omniwot/section-anything/issues
+Keywords: lightrag,parser,plugin,pdf,sections,headings,rag,chunking
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Text Processing :: General
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: section-anything<0.2,>=0.1.1
+Requires-Dist: lightrag-hku<1.7,>=1.5.7
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Dynamic: license-file
+
+# lightrag-section-anything
+
+LightRAG parser engines that turn a PDF into heading-aware blocks (`.blocks.jsonl`) using the
+[`section-anything`](https://github.com/Omniwot/section-anything) library, so LightRAG's
+heading-based chunker ("P") and its heading context work on PDFs without a MinerU or Docling
+service.
+
+## Install
+
+```sh
+pip install lightrag-section-anything
+# latest from GitHub:
+pip install "git+https://github.com/Omniwot/section-anything#subdirectory=packages/lightrag-section-anything"
+```
+
+Python 3.11+. Depends on `section-anything` and `lightrag-hku` (1.5.7 or later, below 1.7); the
+LightRAG server needs `lightrag-hku[api]`. The engines register through LightRAG's
+`lightrag.parsers` entry point, which the LightRAG server (`lightrag-server`) and the parser debug
+CLI (`python -m lightrag.parser.cli`) load at startup. When you embed LightRAG as a library, call
+`load_third_party_parsers()` from `lightrag.parser.plugins` first.
+
+## Engines
+
+| Engine | Runs | Cost per 1,000 pages |
+|---|---|---|
+| `sectionany_free` | rules (bookmarks, contents, typography) | $0 |
+| `sectionany_quick` | rules + a small model reviewing candidate lines | about $0.07 |
+| `sectionany_standard` | a model reading all lines | about $0.16 (gpt-6-luna) to $2.90 (gpt-6.1-sol) |
+| `sectionany_local` | quick-style review on a local Ollama model (`SECTIONANY_LOCAL_MODEL`) | $0 |
+| `sectionany` | the mode in `SECTIONANY_MODE` (default `free`) | |
+
+## Use
+
+Route PDFs to an engine with LightRAG's `LIGHTRAG_PARSER` rules, for example:
+
+    LIGHTRAG_PARSER=pdf:sectionany_quick-P,pdf:sectionany-P,*:native-teP,*:legacy-R
+
+Settings are the library's `SECTIONANY_*` environment variables (see its README): API key
+(`SECTIONANY_API_KEY`, else `OPENAI_API_KEY` for OpenAI's endpoint), models, prices,
+`SECTIONANY_MAX_USD_PER_DOC` (default 0.50), `SECTIONANY_OVER_BUDGET=downgrade|fail`,
+`SECTIONANY_MAX_PAGES` (500), `SECTIONANY_MAX_MB` (100), `SECTIONANY_EXTRACT_TIMEOUT_SECONDS`
+(120). The plugin adds `SECTIONANY_MODE`, `SECTIONANY_SYNTHETIC_TITLES` and
+`MAX_PARALLEL_PARSE_SECTIONANY` (default 2). Nothing is written to the process environment, so
+LightRAG's own model settings are untouched. Cost, model and mode per document are reported in
+LightRAG's document status (`parse_warnings`) and in `<name>.sectionany.json`.
+
+Tests: `SECTIONANY_TEST_PDF=<some.pdf> pytest packages/lightrag-section-anything/tests`.
+
+Not yet: tables as tables, images, OCR, re-levelling MinerU/Docling output, a section-path
+prefix inside embeddings (needs LightRAG's chunker plugins, 1.5.8+).

lightrag_section_anything-0.1.0/README.md

@@ -0,0 +1,50 @@
+# lightrag-section-anything
+
+LightRAG parser engines that turn a PDF into heading-aware blocks (`.blocks.jsonl`) using the
+[`section-anything`](https://github.com/Omniwot/section-anything) library, so LightRAG's
+heading-based chunker ("P") and its heading context work on PDFs without a MinerU or Docling
+service.
+
+## Install
+
+```sh
+pip install lightrag-section-anything
+# latest from GitHub:
+pip install "git+https://github.com/Omniwot/section-anything#subdirectory=packages/lightrag-section-anything"
+```
+
+Python 3.11+. Depends on `section-anything` and `lightrag-hku` (1.5.7 or later, below 1.7); the
+LightRAG server needs `lightrag-hku[api]`. The engines register through LightRAG's
+`lightrag.parsers` entry point, which the LightRAG server (`lightrag-server`) and the parser debug
+CLI (`python -m lightrag.parser.cli`) load at startup. When you embed LightRAG as a library, call
+`load_third_party_parsers()` from `lightrag.parser.plugins` first.
+
+## Engines
+
+| Engine | Runs | Cost per 1,000 pages |
+|---|---|---|
+| `sectionany_free` | rules (bookmarks, contents, typography) | $0 |
+| `sectionany_quick` | rules + a small model reviewing candidate lines | about $0.07 |
+| `sectionany_standard` | a model reading all lines | about $0.16 (gpt-6-luna) to $2.90 (gpt-6.1-sol) |
+| `sectionany_local` | quick-style review on a local Ollama model (`SECTIONANY_LOCAL_MODEL`) | $0 |
+| `sectionany` | the mode in `SECTIONANY_MODE` (default `free`) | |
+
+## Use
+
+Route PDFs to an engine with LightRAG's `LIGHTRAG_PARSER` rules, for example:
+
+    LIGHTRAG_PARSER=pdf:sectionany_quick-P,pdf:sectionany-P,*:native-teP,*:legacy-R
+
+Settings are the library's `SECTIONANY_*` environment variables (see its README): API key
+(`SECTIONANY_API_KEY`, else `OPENAI_API_KEY` for OpenAI's endpoint), models, prices,
+`SECTIONANY_MAX_USD_PER_DOC` (default 0.50), `SECTIONANY_OVER_BUDGET=downgrade|fail`,
+`SECTIONANY_MAX_PAGES` (500), `SECTIONANY_MAX_MB` (100), `SECTIONANY_EXTRACT_TIMEOUT_SECONDS`
+(120). The plugin adds `SECTIONANY_MODE`, `SECTIONANY_SYNTHETIC_TITLES` and
+`MAX_PARALLEL_PARSE_SECTIONANY` (default 2). Nothing is written to the process environment, so
+LightRAG's own model settings are untouched. Cost, model and mode per document are reported in
+LightRAG's document status (`parse_warnings`) and in `<name>.sectionany.json`.
+
+Tests: `SECTIONANY_TEST_PDF=<some.pdf> pytest packages/lightrag-section-anything/tests`.
+
+Not yet: tables as tables, images, OCR, re-levelling MinerU/Docling output, a section-path
+prefix inside embeddings (needs LightRAG's chunker plugins, 1.5.8+).

lightrag_section_anything-0.1.0/pyproject.toml

@@ -0,0 +1,54 @@
+[build-system]
+requires = ["setuptools>=77"]  # SPDX licence expression and license-files
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "lightrag-section-anything"
+version = "0.1.0"
+description = "Section Anything PDF parser engines for LightRAG: accurate headings for heading-aware chunking, with a cost/accuracy dial."
+readme = "README.md"
+license = "Apache-2.0"
+license-files = ["LICENSE", "NOTICE"]
+requires-python = ">=3.11"
+authors = [{ name = "The Section Anything Authors" }]
+keywords = ["lightrag", "parser", "plugin", "pdf", "sections", "headings", "rag", "chunking"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Text Processing :: General",
+]
+dependencies = [
+    "section-anything>=0.1.1,<0.2",  # uses its body export (section_anything.export)
+    "lightrag-hku>=1.5.7,<1.7",  # lightrag.parsers entry points and NativeParserBase, from 1.5.7
+]
+
+[project.urls]
+Homepage = "https://github.com/Omniwot/section-anything/tree/main/packages/lightrag-section-anything"
+Repository = "https://github.com/Omniwot/section-anything"
+Issues = "https://github.com/Omniwot/section-anything/issues"
+
+[project.optional-dependencies]
+test = ["pytest>=8"]
+
+[project.entry-points."lightrag.parsers"]
+sectionany = "lightrag_section_anything.plugin:register_parsers"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 120
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "B", "UP", "ASYNC"]
+ignore = ["E501", "E731"]

lightrag_section_anything-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

lightrag_section_anything-0.1.0/src/lightrag_section_anything/__init__.py

@@ -0,0 +1,3 @@
+"""Section Anything parser engines for LightRAG."""
+
+__version__ = "0.1.0"

lightrag_section_anything-0.1.0/src/lightrag_section_anything/blocks.py

@@ -0,0 +1,75 @@
+"""Section Anything sections -> LightRAG sidecar blocks.
+
+One block per section: the heading line (``#`` x level + printed heading), then the section's
+body reflowed into paragraphs (LightRAG's heading chunker treats every line as a paragraph, so
+PDF lines must be joined). ``parent_headings`` holds ancestors only, from a level-keyed stack.
+Text before the first heading is a ``preface`` block. Running headers and footers are dropped.
+Positions: one bbox per page, PDF points with the origin at the bottom left.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+# Paragraph reflow, heading-line detection and heading text are shared with the library's
+# Markdown export.
+from section_anything.export import heading_lines as _heading_lines
+from section_anything.export import heading_text
+from section_anything.export import reflow as _reflow
+
+__all__ = ["build_blocks", "heading_text"]
+
+
+def _positions(lines: list[Any]) -> list[dict]:
+    pages: dict[int, list[float]] = {}
+    for ln in lines:
+        b = pages.setdefault(ln.page, [ln.x0, ln.y1, ln.x1, ln.y0])
+        b[0], b[1], b[2], b[3] = min(b[0], ln.x0), max(b[1], ln.y1), max(b[2], ln.x1), min(b[3], ln.y0)
+    return [{"type": "bbox", "anchor": str(p), "range": [round(v, 2) for v in r]} for p, r in sorted(pages.items())]
+
+
+def build_blocks(ext: Any, sections: list[dict], furniture: set[int] | None = None,
+                 synthetic_titles: bool = False) -> tuple[list[dict], str]:
+    """Returns (blocks, document title). Each block: content, heading, level, parent_headings,
+    session_type, is_title_block, positions."""
+    from lightrag.parser._markdown import render_heading_line
+
+    furniture = furniture or set()
+    lines = ext.lines
+    body = [s for s in sections if "front_matter" not in s.get("flags", [])]
+    if not synthetic_titles:  # headings the model invented for headingless text: fold into the previous block
+        body = [s for s in body if s.get("title_from_text", True) is not False]
+    body.sort(key=lambda s: s["first_line"])
+    doc_title = next((heading_text(s) for s in body if "doc_title" in s.get("flags", [])), "")
+
+    starts = [s["first_line"] for s in body]
+    blocks: list[dict] = []
+
+    def span(a: int, b: int) -> list[Any]:
+        return [ln for ln in lines[a:b] if ln.i not in furniture]
+
+    first = starts[0] if starts else len(lines)
+    pre = span(0, first)
+    if any(ln.text.strip() for ln in pre):
+        blocks.append({"content": "\n".join(_reflow(pre)), "heading": "", "level": 0, "parent_headings": [],
+                       "session_type": "preface", "is_title_block": False, "positions": _positions(pre)})
+
+    stack: list[tuple[int, str]] = []
+    for k, sec in enumerate(body):
+        end = starts[k + 1] if k + 1 < len(starts) else len(lines)
+        seg = span(sec["first_line"], end)
+        head = heading_text(sec)
+        is_title = "doc_title" in sec.get("flags", [])
+        level = 0 if is_title else max(1, int(sec["level"]))
+        n_head = _heading_lines(seg, head)
+        if not is_title:
+            stack = [(lv, h) for lv, h in stack if lv < level]
+        parents = [h for _lv, h in stack]
+        heading_line = render_heading_line(max(level, 1), head)
+        paras = _reflow(seg[n_head:])
+        blocks.append({"content": "\n".join([heading_line, *paras]), "heading": head, "level": level,
+                       "parent_headings": parents, "session_type": "body", "is_title_block": is_title,
+                       "positions": _positions(seg)})
+        if not is_title:
+            stack.append((level, head))
+    return blocks, doc_title

lightrag_section_anything-0.1.0/src/lightrag_section_anything/core.py

@@ -0,0 +1,28 @@
+"""Section a PDF with the `section-anything` library, inside LightRAG's parser thread.
+
+Settings come from the library (``SECTIONANY_*`` environment variables: API key, models, prices,
+``SECTIONANY_MAX_USD_PER_DOC``, ``SECTIONANY_OVER_BUDGET``, page/size caps, extraction time limit).
+The plugin adds ``SECTIONANY_MODE`` for the ``sectionany`` engine. Nothing is written to the
+process environment, so LightRAG's own model settings are never touched.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from section_anything import SectionTree, Settings, section
+
+
+def resolve_mode(mode: str | None) -> str:
+    """The engine's mode, or ``SECTIONANY_MODE`` (default free). Validated by the library."""
+    return (mode or os.getenv("SECTIONANY_MODE") or "free").strip()
+
+
+def section_pdf(path: Path, mode: str | None = None, *, settings: Settings | None = None) -> SectionTree:
+    """Section one PDF. Over-budget runs downgrade (standard -> quick -> free) unless
+    ``SECTIONANY_OVER_BUDGET=fail``; unpriced cloud models are refused before the PDF is read."""
+    tree = section(path, resolve_mode(mode), settings=settings)
+    if not tree.text.strip():  # pragma: no cover - the library refuses text-less PDFs first
+        raise ValueError("no text layer; re-upload with an OCR engine, e.g. name.[mineru-P].pdf")
+    return tree

lightrag_section_anything-0.1.0/src/lightrag_section_anything/parser.py

@@ -0,0 +1,108 @@
+"""LightRAG parser engines: PDF -> Section Anything sections -> sidecar blocks."""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from lightrag.parser.native_base import NativeExtractRuntime, NativeParserBase
+
+if TYPE_CHECKING:
+    from lightrag.sidecar.ir import IRDoc
+
+
+class SectionAnyParser(NativeParserBase):
+    """Mode from ``SECTIONANY_MODE`` (free | quick | standard | local:<model>)."""
+
+    engine_name = "sectionany"
+    empty_content_label = "Section Anything"
+    mode: str | None = None  # None: read SECTIONANY_MODE at parse time
+
+    def validate_source(self, source: Path, file_path: str) -> None:
+        super().validate_source(source, file_path)
+        if source.suffix.lower() != ".pdf":
+            raise ValueError(f"{self.engine_name} parses PDF files only: {file_path}")
+
+    def validate_source_blocking(self, source: Path, file_path: str) -> None:
+        """Size and page caps (SECTIONANY_MAX_MB, SECTIONANY_MAX_PAGES), checked without parsing any
+        page content."""
+        from section_anything import PdfError, Settings, check_pdf
+
+        try:
+            check_pdf(source, Settings())
+        except PdfError as e:
+            raise ValueError(f"{file_path}: {e}") from None
+
+    def extract(self, source: Path, *, parsed_dir: Path, asset_dir: Path, base_name: str,
+                runtime: NativeExtractRuntime | None = None) -> tuple[list[dict[str, Any]], dict[str, Any], dict[str, Any]]:
+        from section_anything.structure import furniture_of
+
+        from lightrag_section_anything import __version__
+        from lightrag_section_anything.blocks import build_blocks
+        from lightrag_section_anything.core import section_pdf
+
+        tree = section_pdf(source, self.mode)
+        ext = tree.extraction
+        blocks, doc_title = build_blocks(ext, tree.resolved, furniture_of(ext),
+                                         synthetic_titles=os.getenv("SECTIONANY_SYNTHETIC_TITLES") == "true")
+        if not any(b["content"].strip() for b in blocks):
+            raise ValueError("no text extracted; scanned PDFs need an OCR engine, e.g. name.[mineru-P].pdf")
+        usage = tree.usage
+        warnings = {
+            "sectionany_mode": tree.mode, "sectionany_model": tree.model or "", "sectionany_cost_usd": tree.cost_usd,
+            "sectionany_calls": usage.get("calls", 0), "sectionany_tokens_in": usage.get("input_tokens", 0),
+            "sectionany_tokens_out": usage.get("output_tokens", 0), "sectionany_seconds": tree.seconds,
+            "sectionany_sections": len(tree.sections),
+            "sectionany_flagged": sum(bool(s.get("flags")) for s in tree.sections),
+        }
+        if tree.downgraded:
+            warnings["sectionany_downgraded"] = tree.downgraded
+        audit = {**warnings, "pages": tree.pages,
+                 "sections": [{k: s.get(k) for k in ("number", "title", "level", "page_start", "page_end", "flags")}
+                              for s in tree.sections]}
+        (parsed_dir / f"{Path(base_name).name}.sectionany.json").write_text(json.dumps(audit, ensure_ascii=False, sort_keys=True, indent=1))
+        metadata = {"doc_title": doc_title, "split_option": {
+            "engine_version": __version__, "mode": tree.mode, "model": tree.model or "", "cost_usd": tree.cost_usd,
+            "sections": len(tree.sections)}}
+        return blocks, warnings, metadata
+
+    def build_ir(self, blocks: list[dict[str, Any]], *, document_name: str, asset_dir_name: str,
+                 metadata: dict[str, Any]) -> IRDoc:
+        from lightrag.sidecar.ir import IRBlock, IRDoc, IRPosition
+
+        ir_blocks = [
+            IRBlock(content_template=b["content"], heading=b["heading"], level=b["level"],
+                    parent_headings=list(b["parent_headings"]), session_type=b["session_type"],
+                    is_title_block=b["is_title_block"],
+                    positions=[IRPosition(type=p["type"], anchor=p["anchor"], range=p["range"]) for p in b["positions"]])
+            for b in blocks
+        ]
+        return IRDoc(document_name=document_name, document_format="pdf",
+                     doc_title=metadata.get("doc_title") or Path(document_name).stem,
+                     split_option=metadata.get("split_option", {}), blocks=ir_blocks,
+                     bbox_attributes={"origin": "LEFTBOTTOM"})
+
+    def surface_warnings(self, warnings: dict[str, Any], source: Path) -> dict[str, Any] | None:
+        return dict(warnings)  # mode, model, cost and counts go to doc_status
+
+
+class FreeParser(SectionAnyParser):
+    engine_name = "sectionany_free"
+    mode = "free"
+
+
+class QuickParser(SectionAnyParser):
+    engine_name = "sectionany_quick"
+    mode = "quick"
+
+
+class StandardParser(SectionAnyParser):
+    engine_name = "sectionany_standard"
+    mode = "standard"
+
+
+class LocalParser(SectionAnyParser):
+    engine_name = "sectionany_local"
+    mode = "local"

lightrag_section_anything-0.1.0/src/lightrag_section_anything/plugin.py

@@ -0,0 +1,30 @@
+"""Entry point for ``lightrag.parsers``: registers one engine per position of the dial.
+Import-cheap: implementations load lazily through ``ParserSpec.impl``."""
+
+from __future__ import annotations
+
+import os
+
+IMPL = "lightrag_section_anything.parser:{}"
+
+
+def _has_key() -> bool:
+    return bool(os.getenv("SECTIONANY_API_KEY") or os.getenv("OPENAI_API_KEY"))
+
+
+def register_parsers() -> None:
+    from lightrag.parser.registry import ParserSpec, register_parser
+
+    pdf = frozenset({"pdf"})
+    register_parser(ParserSpec(
+        engine_name="sectionany", impl=IMPL.format("SectionAnyParser"), suffixes=pdf, queue_group="sectionany",
+        concurrency=int(os.getenv("MAX_PARALLEL_PARSE_SECTIONANY", "2"))))
+    for mode, cls, ready, need in (
+        ("free", "FreeParser", lambda: True, lambda: None),
+        ("quick", "QuickParser", _has_key, lambda: "SECTIONANY_API_KEY or OPENAI_API_KEY"),
+        ("standard", "StandardParser", _has_key, lambda: "SECTIONANY_API_KEY or OPENAI_API_KEY"),
+        ("local", "LocalParser", lambda: bool(os.getenv("SECTIONANY_LOCAL_MODEL")), lambda: "SECTIONANY_LOCAL_MODEL"),
+    ):
+        register_parser(ParserSpec(
+            engine_name=f"sectionany_{mode}", impl=IMPL.format(cls), suffixes=pdf, queue_group="sectionany",
+            endpoint_configured=ready, endpoint_requirement=need))

lightrag_section_anything-0.1.0/src/lightrag_section_anything.egg-info/PKG-INFO

@@ -0,0 +1,78 @@
+Metadata-Version: 2.4
+Name: lightrag-section-anything
+Version: 0.1.0
+Summary: Section Anything PDF parser engines for LightRAG: accurate headings for heading-aware chunking, with a cost/accuracy dial.
+Author: The Section Anything Authors
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/Omniwot/section-anything/tree/main/packages/lightrag-section-anything
+Project-URL: Repository, https://github.com/Omniwot/section-anything
+Project-URL: Issues, https://github.com/Omniwot/section-anything/issues
+Keywords: lightrag,parser,plugin,pdf,sections,headings,rag,chunking
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Text Processing :: General
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: section-anything<0.2,>=0.1.1
+Requires-Dist: lightrag-hku<1.7,>=1.5.7
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Dynamic: license-file
+
+# lightrag-section-anything
+
+LightRAG parser engines that turn a PDF into heading-aware blocks (`.blocks.jsonl`) using the
+[`section-anything`](https://github.com/Omniwot/section-anything) library, so LightRAG's
+heading-based chunker ("P") and its heading context work on PDFs without a MinerU or Docling
+service.
+
+## Install
+
+```sh
+pip install lightrag-section-anything
+# latest from GitHub:
+pip install "git+https://github.com/Omniwot/section-anything#subdirectory=packages/lightrag-section-anything"
+```
+
+Python 3.11+. Depends on `section-anything` and `lightrag-hku` (1.5.7 or later, below 1.7); the
+LightRAG server needs `lightrag-hku[api]`. The engines register through LightRAG's
+`lightrag.parsers` entry point, which the LightRAG server (`lightrag-server`) and the parser debug
+CLI (`python -m lightrag.parser.cli`) load at startup. When you embed LightRAG as a library, call
+`load_third_party_parsers()` from `lightrag.parser.plugins` first.
+
+## Engines
+
+| Engine | Runs | Cost per 1,000 pages |
+|---|---|---|
+| `sectionany_free` | rules (bookmarks, contents, typography) | $0 |
+| `sectionany_quick` | rules + a small model reviewing candidate lines | about $0.07 |
+| `sectionany_standard` | a model reading all lines | about $0.16 (gpt-6-luna) to $2.90 (gpt-6.1-sol) |
+| `sectionany_local` | quick-style review on a local Ollama model (`SECTIONANY_LOCAL_MODEL`) | $0 |
+| `sectionany` | the mode in `SECTIONANY_MODE` (default `free`) | |
+
+## Use
+
+Route PDFs to an engine with LightRAG's `LIGHTRAG_PARSER` rules, for example:
+
+    LIGHTRAG_PARSER=pdf:sectionany_quick-P,pdf:sectionany-P,*:native-teP,*:legacy-R
+
+Settings are the library's `SECTIONANY_*` environment variables (see its README): API key
+(`SECTIONANY_API_KEY`, else `OPENAI_API_KEY` for OpenAI's endpoint), models, prices,
+`SECTIONANY_MAX_USD_PER_DOC` (default 0.50), `SECTIONANY_OVER_BUDGET=downgrade|fail`,
+`SECTIONANY_MAX_PAGES` (500), `SECTIONANY_MAX_MB` (100), `SECTIONANY_EXTRACT_TIMEOUT_SECONDS`
+(120). The plugin adds `SECTIONANY_MODE`, `SECTIONANY_SYNTHETIC_TITLES` and
+`MAX_PARALLEL_PARSE_SECTIONANY` (default 2). Nothing is written to the process environment, so
+LightRAG's own model settings are untouched. Cost, model and mode per document are reported in
+LightRAG's document status (`parse_warnings`) and in `<name>.sectionany.json`.
+
+Tests: `SECTIONANY_TEST_PDF=<some.pdf> pytest packages/lightrag-section-anything/tests`.
+
+Not yet: tables as tables, images, OCR, re-levelling MinerU/Docling output, a section-path
+prefix inside embeddings (needs LightRAG's chunker plugins, 1.5.8+).

lightrag_section_anything-0.1.0/src/lightrag_section_anything.egg-info/SOURCES.txt

@@ -0,0 +1,18 @@
+LICENSE
+MANIFEST.in
+NOTICE
+README.md
+pyproject.toml
+src/lightrag_section_anything/__init__.py
+src/lightrag_section_anything/blocks.py
+src/lightrag_section_anything/core.py
+src/lightrag_section_anything/parser.py
+src/lightrag_section_anything/plugin.py
+src/lightrag_section_anything.egg-info/PKG-INFO
+src/lightrag_section_anything.egg-info/SOURCES.txt
+src/lightrag_section_anything.egg-info/dependency_links.txt
+src/lightrag_section_anything.egg-info/entry_points.txt
+src/lightrag_section_anything.egg-info/requires.txt
+src/lightrag_section_anything.egg-info/top_level.txt
+tests/test_blocks.py
+tests/test_plugin.py

lightrag_section_anything-0.1.0/src/lightrag_section_anything.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

lightrag_section_anything-0.1.0/src/lightrag_section_anything.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[lightrag.parsers]
+sectionany = lightrag_section_anything.plugin:register_parsers

lightrag_section_anything-0.1.0/src/lightrag_section_anything.egg-info/requires.txt

@@ -0,0 +1,5 @@
+section-anything<0.2,>=0.1.1
+lightrag-hku<1.7,>=1.5.7
+
+[test]
+pytest>=8

lightrag_section_anything-0.1.0/src/lightrag_section_anything.egg-info/top_level.txt

@@ -0,0 +1 @@
+lightrag_section_anything

lightrag_section_anything-0.1.0/tests/test_blocks.py

@@ -0,0 +1,73 @@
+from dataclasses import dataclass
+
+from lightrag_section_anything.blocks import _heading_lines, _reflow, build_blocks
+
+
+@dataclass
+class L:  # minimal stand-in for app.sectioning.extract.Line
+    i: int
+    page: int
+    text: str
+    y1: float
+    size: float = 10.0
+    x0: float = 72.0
+    x1: float = 540.0
+
+    @property
+    def y0(self) -> float:
+        return self.y1 - self.size
+
+
+@dataclass
+class Ext:
+    lines: list
+
+
+def _ext(texts):
+    lines, y, page = [], 760.0, 1
+    for _i, t in enumerate(texts):
+        if t == "<page>":
+            page, y = page + 1, 760.0
+            continue
+        lines.append(L(len(lines), page, t, y))
+        y -= 12.0
+    return Ext(lines)
+
+
+def sec(first, level, title, number="", flags=()):
+    return {"first_line": first, "level": level, "title": title, "number": number, "flags": list(flags)}
+
+
+def test_parents_are_ancestors_only_and_title_block():
+    ext = _ext(["My Paper", "intro text", "1 Introduction", "body a", "1.1 Scope", "body b", "2 Methods", "body c"])
+    blocks, title = build_blocks(ext, [sec(0, 1, "My Paper", flags=["doc_title"]), sec(2, 1, "Introduction", "1"),
+                                       sec(4, 2, "Scope", "1.1"), sec(6, 1, "Methods", "2")])
+    assert title == "My Paper"
+    by = {b["heading"]: b for b in blocks}
+    assert by["My Paper"]["level"] == 0 and by["My Paper"]["is_title_block"]
+    assert by["1 Introduction"]["parent_headings"] == []
+    assert by["1.1 Scope"]["parent_headings"] == ["1 Introduction"]
+    assert by["2 Methods"]["parent_headings"] == []
+    assert by["1.1 Scope"]["content"].startswith("## 1.1 Scope\n")
+    assert "body b" in by["1.1 Scope"]["content"] and "Scope\n1.1" not in by["1.1 Scope"]["content"]
+
+
+def test_preface_and_wrapped_heading():
+    ext = _ext(["Copyright notice", "Article 9", "Freedom of association", "All Germans shall have the right"])
+    blocks, _ = build_blocks(ext, [sec(1, 2, "Article 9 Freedom of association")])
+    assert blocks[0]["session_type"] == "preface" and blocks[0]["level"] == 0
+    body = blocks[1]["content"].split("\n")
+    assert body[0] == "## Article 9 Freedom of association" and body[1] == "All Germans shall have the right"
+
+
+def test_run_in_heading_keeps_its_line():
+    ext = _ext(["Short title. This Act may be cited as the Example Act."])
+    assert _heading_lines(ext.lines, "Short title.") == 0
+
+
+def test_reflow_joins_lines_and_dehyphenates():
+    ext = _ext(["The quick brown fox jumps over the lazy dog and keeps run-", "ning until the end of the line.",
+                "<page>", "Next paragraph starts here."])
+    paras = _reflow(ext.lines)
+    assert paras[0] == "The quick brown fox jumps over the lazy dog and keeps running until the end of the line."
+    assert paras[1] == "Next paragraph starts here."

lightrag_section_anything-0.1.0/tests/test_plugin.py

@@ -0,0 +1,88 @@
+import os
+import sys
+from pathlib import Path
+
+import pytest
+
+needs_pdf = pytest.mark.skipif(not os.getenv("SECTIONANY_TEST_PDF"),
+                               reason="set SECTIONANY_TEST_PDF to a PDF for the end-to-end parse")
+
+
+@pytest.fixture(autouse=True)
+def clean_env(monkeypatch):
+    """Library defaults, whatever the shell has set (the test PDF path excepted)."""
+    for key in list(os.environ):
+        if key.upper().startswith("SECTIONANY_") and key.upper() != "SECTIONANY_TEST_PDF":
+            monkeypatch.delenv(key)
+
+
+def test_engines_register():
+    from lightrag.parser import registry
+    from lightrag.parser.plugins import load_third_party_parsers
+
+    load_third_party_parsers(force=True)
+    names = {"sectionany", "sectionany_free", "sectionany_quick", "sectionany_standard", "sectionany_local"}
+    assert names <= set(registry._REGISTRY)
+
+
+def test_core_comes_from_the_library_not_the_web_app():
+    import lightrag_section_anything.core as core
+    import lightrag_section_anything.parser  # noqa: F401
+
+    assert core.section.__module__ == "section_anything.api"
+    assert "app" not in sys.modules and "app.sectioning" not in sys.modules
+
+
+@needs_pdf
+def test_free_parse_writes_sidecar(tmp_path):
+    from lightrag_section_anything.parser import FreeParser
+
+    src = Path(os.environ["SECTIONANY_TEST_PDF"])
+    blocks, warnings, meta = FreeParser().extract(src, parsed_dir=tmp_path, asset_dir=tmp_path / "a", base_name="t")
+    assert warnings["sectionany_mode"] == "free" and warnings["sectionany_cost_usd"] == 0
+    assert any(b["heading"] for b in blocks)
+    seen: list[tuple[int, str]] = []
+    for b in blocks:  # parent_headings must be earlier, shallower headings
+        if b["level"] > 0:
+            for p in b["parent_headings"]:
+                assert any(h == p and lv < b["level"] for lv, h in seen)
+            seen.append((b["level"], b["heading"]))
+    assert (tmp_path / "t.sectionany.json").exists()
+    ir = FreeParser().build_ir(blocks, document_name=src.name, asset_dir_name="a", metadata=meta)
+    assert ir.document_format == "pdf" and len(ir.blocks) == len(blocks)
+
+
+@needs_pdf
+def test_unpriced_cloud_model_is_refused_before_any_call(monkeypatch):
+    from lightrag_section_anything.core import section_pdf
+
+    monkeypatch.setenv("SECTIONANY_QUICK_MODEL", "no-such-model")
+    with pytest.raises(ValueError, match="no price for model"):
+        section_pdf(Path(os.environ["SECTIONANY_TEST_PDF"]), "quick")
+
+
+@needs_pdf
+def test_file_size_cap(monkeypatch):
+    from lightrag_section_anything.parser import FreeParser
+
+    monkeypatch.setenv("SECTIONANY_MAX_MB", "0.001")
+    src = Path(os.environ["SECTIONANY_TEST_PDF"])
+    with pytest.raises(ValueError, match="SECTIONANY_MAX_MB"):
+        FreeParser().validate_source_blocking(src, src.name)
+
+
+@needs_pdf
+def test_page_cap(monkeypatch):
+    from lightrag_section_anything.parser import FreeParser
+
+    monkeypatch.setenv("SECTIONANY_MAX_PAGES", "1")
+    src = Path(os.environ["SECTIONANY_TEST_PDF"])
+    with pytest.raises(ValueError, match="SECTIONANY_MAX_PAGES"):
+        FreeParser().validate_source_blocking(src, src.name)
+
+
+def test_bad_mode_is_a_value_error(tmp_path):
+    from lightrag_section_anything.core import section_pdf
+
+    with pytest.raises(ValueError, match="unknown mode"):
+        section_pdf(tmp_path / "x.pdf", "turbo")