llama-index-node-parser-xberg 1.0.0__tar.gz

llama_index_node_parser_xberg-1.0.0/.gitignore

@@ -0,0 +1,334 @@
+# Build artifacts
+target/
+build/
+dist/
+.polylint/
+# Ad-hoc PDF/image debug binaries
+/check_pdf_oxide
+/check_*
+# Hand-authored WASM JS distribution files (intentionally committed)
+!crates/xberg-wasm/dist/index.js
+!crates/xberg-wasm/dist/extraction/files.js
+!crates/xberg-wasm/dist/ocr/enabler.js
+.lycheecache
+dist-musl/
+*.so
+*.dylib
+*.dll
+*.pdb
+*.node
+*.whl
+*.tar.gz
+*.gem
+*.jar
+wheels/
+**/bin/
+!**/src/bin/
+**/obj/
+
+# Rust
+*.rs.bk
+*.profraw
+rust-coverage.lcov
+rust_out
+
+# Python
+*.py[cod]
+*$py.class
+*.egg-info/
+__pycache__/
+.venv/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.hypothesis/
+.coverage
+.coverage*
+.e2e-logs/
+htmlcov/
+share/python-wheels/
+prompt_template.egg-info/
+packages/python/xberg/xberg-cli
+
+# Node.js / WASM
+node_modules/
+*.tsbuildinfo
+npm-debug.log*
+pnpm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+# NAPI-RS generated files (index.js and index.d.ts are committed for TypeScript type resolution)
+crates/xberg-node/*.tgz
+# ORT dylibs are copied to crates/xberg-node/ at build time and included in npm publish
+# despite the global *.dylib/*.so/*.dll rules below
+!crates/xberg-node/*.dylib
+!crates/xberg-node/*.so
+!crates/xberg-node/*.dll
+.wrangler/
+.pnpm-store/
+
+# Ruby
+packages/ruby/.bundle/
+packages/ruby/vendor/
+!packages/ruby/vendor/rb-sys/
+!vendor/rb-sys/build/
+!vendor/rb-sys/build/**
+*.Cache
+.yardoc/
+
+# PHP
+vendor/
+!crates/xberg-candle-ocr/src/vendor/
+!crates/xberg-libwpd/vendor/
+# The vendored WordPerfect source archives are committed on purpose; re-include
+# them past the global `*.tar.gz` rule above (a dir negation alone won't).
+!crates/xberg-libwpd/vendor/*.tar.gz
+php-xberg.ini
+packages/php/php-xberg.ini
+packages/php/tests.xml
+packages/php/var/
+.php-cs-fixer.cache
+
+# Swift / SwiftPM / Xcode
+.build/
+.swiftpm/
+# Legacy SwiftPM resolved-packages dir — anchored to packages/swift/ so it
+# does NOT match our top-level packages/ directory on macOS case-insensitive
+# filesystems (where the bare `Packages/` pattern previously matched and
+# silently dropped packages/dart/pubspec.yaml + 9 other scaffold files from
+# the index during regen).
+packages/swift/**/Packages/
+Package.resolved
+*.xcodeproj/
+*.xcworkspace/
+DerivedData/
+
+# Java / C# / .NET
+*.suo
+*.user
+*.cscfg
+*.cobertura.xml
+TestResults/
+
+# Generated test apps (e2e-generator --mode published)
+test_apps/
+
+# Elixir
+.nox/
+
+# Go
+packages/go/v*/install
+
+# C FFI
+crates/xberg-ffi/tests/c/test_*
+!crates/xberg-ffi/tests/c/test_*.c
+crates/xberg-ffi/tests/c/*.o
+crates/xberg-ffi/tests/c/*.dSYM/
+e2e/c/test_*
+!e2e/c/test_*.c
+e2e/c/*.o
+e2e/c/*.dSYM/
+
+# Generated pkg-config
+*.pc
+
+# Coverage
+coverage/
+coverage.info
+coverage.json
+coverage.lcov
+coverage.out
+coverage.xml
+packages/*/.coverage
+packages/*/coverage.json
+packages/*/coverage.out
+packages/*/htmlcov/
+packages/*/test-results/
+packages/*/TestResults/
+
+# IDE / Editor
+.idea/
+*.iml
+.vscode/
+.run/
+.DS_store
+
+# CI / Tools
+.cache/
+.tmp/
+*temp/
+*.temp
+*.tmp
+*.log
+**/logs/
+**/test_output.log
+.mvn/
+.tox/
+.artifacts/
+.remote-cache/
+.rumdl_cache/
+docker-logs/
+
+# Benchmarks
+benchmark-results/
+benchmark_results.json
+benchmarks/results/
+!benchmarks/baselines/
+aggregated-results/
+results/
+reports/
+tests/benchmarks/results/
+profiling-results/
+profiling-results-*/
+
+# Local perf-iteration artifacts (flamegraphs/ is committed; intermediate outputs are not)
+profile.json.gz
+profile.pb.gz
+*.heap
+bench/
+
+# Docs
+docs/_build/
+docs/build/
+docs/benchmarks/charts/
+site/
+
+# Elixir build artifacts (lock files MUST stay tracked — see CLAUDE.md
+# task-runner / dependency-awareness rules and the brotli/alloc-no-stdlib
+# regression that bit CI run 27492590406 because the NIF lock wasn't
+# committed and the resolver picked a fresh broken combo).
+packages/elixir/_build/
+packages/elixir/deps/
+e2e/elixir/_build/
+e2e/elixir/deps/
+e2e/elixir/config/
+test_documents/_build/
+test_documents/deps/
+
+# Maven plugin artifacts
+*.versionsBackup
+
+# Gradle (Kotlin e2e)
+e2e/kotlin/.gradle/
+e2e/kotlin/build/
+e2e/kotlin_android/.gradle/
+e2e/kotlin_android/build/
+
+# Ruby native build artifacts
+packages/ruby/lib/*.bundle
+packages/ruby/tmp/
+
+# Tests
+test_report.json
+tests/e2e/logs/
+tests/e2e/test_report.json
+temp-test-*
+packages/csharp/test_html_debug.cs
+# CI renders this from runtime.json.template at publish time; template is the source of truth.
+packages/csharp/Xberg/runtime.json
+
+# AI / MCP / Agent config
+.claude/
+.codex/
+.gemini/
+.xberg/
+.mcp.json
+# Alef-generated agent skills (mirrors of .ai-rulez/skills; .claude/.codex covered above)
+.agents/skills/
+.github/skills/
+.playwright-mcp/
+.fastembed_cache/
+*/.fastembed_cache/
+AGENTS.md
+CLAUDE.md
+GEMINI.md
+.cursorrules
+.windsurfrules
+[Tt][Oo][Dd][Oo]*
+
+# Git worktrees
+.worktrees/
+
+# Misc
+.env
+output.txt
+examples.txt
+requirements.txt
+docker-compose.yaml
+/tmp/xberg-docker-test-results.json
+tools/benchmark-harness/datasets/
+tools/benchmark-harness/.fixtures-pdf-subset/
+tools/benchmark-harness/vendored/docling/md/iso_21111_10.md
+visualizations/
+
+
+# Additional generated artifacts
+.alef/
+*.pyd
+.gems/
+vendor/bundle/
+*.h.bak
+*.test
+*.class
+bin/
+obj/
+*.nupkg
+pkg/
+
+# Dart's alef-generated install-time downloader must ship in the pub.dev package,
+# so it is exempt from the blanket bin/ ignore above.
+!packages/dart/bin/
+!packages/dart/bin/download_libs.dart
+
+
+# Local dev artifacts
+docs-site/public/demo-dev.html
+docs-site/dist/
+docs-site/.astro/
+demo-loaded.png
+scratch/
+
+
+.php-cs-fixer.*
+
+e2e/zig/.zig-cache/
+
+# Swift e2e build artifacts (Swift Package Manager)
+e2e/swift/.build/
+e2e/swift/.swiftpm/
+e2e/swift/Package.resolved
+e2e/swift_e2e/.build/
+e2e/swift_e2e/.swiftpm/
+e2e/swift_e2e/Package.resolved
+
+# Dart e2e build artifacts (lock file tracked for reproducibility)
+e2e/dart/.dart_tool/
+e2e/dart/build/
+
+# Dart FRB codegen cache (incremental build optimization)
+packages/dart/rust/.frb_codegen_hash
+
+# Go e2e build artifacts
+e2e/go/vendor/
+
+erl_crash.dump
+
+
+.gradle/
+
+packages/go/.lib/
+
+.build/
+
+# basemind code-map index (local tooling)
+.basemind/
+
+.bench-rc32/
+.private-bench/
+build-output-musl-node/
+
+poly.local.toml
+
+# BEGIN ai-rulez (DO NOT EDIT - managed by ai-rulez)
+.ai-rulez/.generated-manifest.json
+# END ai-rulez

llama_index_node_parser_xberg-1.0.0/PKG-INFO

@@ -0,0 +1,161 @@
+Metadata-Version: 2.4
+Name: llama-index-node-parser-xberg
+Version: 1.0.0
+Summary: Structure-aware LlamaIndex node parser that turns xberg native chunks and elements into nodes
+Project-URL: Homepage, https://github.com/xberg-io/xberg/tree/main/integrations/python/llama-index/node_parsers/llama-index-node-parser-xberg
+Project-URL: Issues, https://github.com/xberg-io/xberg/issues
+Project-URL: Repository, https://github.com/xberg-io/xberg/tree/main/integrations/python/llama-index/node_parsers/llama-index-node-parser-xberg
+Author-email: xberg <contact@xberg.io>
+Maintainer-email: xberg <contact@xberg.io>
+License-Expression: MIT
+Keywords: ai,chunking,document-structure,llamaindex,llm,node-parser,rag,xberg
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Text Processing :: General
+Classifier: Topic :: Text Processing :: Indexing
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: llama-index-core<0.15,>=0.14.23
+Description-Content-Type: text/markdown
+
+# LlamaIndex Node Parser Xberg
+
+<div align="center" style="display: flex; flex-wrap: wrap; gap: 8px; justify-content: center; margin: 20px 0;">
+  <a href="https://pypi.org/project/llama-index-node-parser-xberg/">
+    <img src="https://img.shields.io/pypi/v/llama-index-node-parser-xberg?label=Node%20Parser&color=007ec6" alt="Node Parser">
+  </a>
+  <a href="https://pypi.org/project/xberg/">
+    <img src="https://img.shields.io/pypi/v/xberg?label=Xberg&color=007ec6" alt="Xberg">
+  </a>
+  <a href="https://github.com/xberg-io/llama-index-xberg/blob/main/LICENSE">
+    <img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License">
+  </a>
+  <a href="https://docs.xberg.io">
+    <img src="https://img.shields.io/badge/docs-xberg.io-blue" alt="Documentation">
+  </a>
+</div>
+
+<img width="3384" height="573" alt="Xberg Banner" src="https://github.com/user-attachments/assets/1b6c6ad7-3b6d-4171-b1c9-f2026cc9deb8" />
+
+<div align="center" style="margin-top: 20px;">
+  <a href="https://discord.gg/xt9WY3GnKR">
+    <img height="22" src="https://img.shields.io/badge/Discord-Join%20our%20community-7289da?logo=discord&logoColor=white" alt="Discord">
+  </a>
+</div>
+
+Structure-aware LlamaIndex node parser for xberg-extracted documents. It turns
+xberg's native **chunks** into nodes, and falls back to structural **elements**
+when chunks are absent.
+
+## Installation
+
+```bash
+pip install llama-index-node-parser-xberg
+```
+
+Requires `llama-index-core>=0.14.23,<0.15`. This package does not depend on
+`xberg` directly — `xberg` is a dependency of the reader
+(`llama-index-readers-xberg`), which produces the documents this parser splits.
+
+## Prerequisites
+
+> **This parser requires documents with `_xberg_chunks` or `_xberg_elements`
+> metadata.** These are produced by `XbergReader`. Prefer native chunking; use
+> element-based extraction when you want one node per structural element.
+> Documents carrying neither pass through unchanged with a warning.
+
+```python
+from xberg import ChunkingConfig, ExtractionConfig
+from llama_index.readers.xberg import XbergReader
+
+# Preferred: native semantic chunks with heading path and page span.
+reader = XbergReader(
+    extraction_config=ExtractionConfig(chunking=ChunkingConfig(max_characters=1000, overlap=200))
+)
+documents = reader.load_data("report.pdf")
+```
+
+## Features
+
+- Chunk-aware splitting — each xberg native chunk becomes a node, carrying `chunk_type`, `heading_path`, and page span
+- Element fallback — when no chunks are present, headings, paragraphs, tables, and code blocks each become a node
+- Source and prev/next relationships tracked via `NodeRelationship`
+- Graceful degradation — documents without chunk or element metadata pass through with a warning
+- Composes with other transformations (e.g., `SentenceSplitter`)
+- Async support via `aget_nodes_from_documents`
+- Serialization support (`to_dict` / `from_dict`)
+
+## Usage
+
+### Basic
+
+Full reader-to-nodes flow:
+
+```python
+from xberg import ChunkingConfig, ExtractionConfig
+from llama_index.readers.xberg import XbergReader
+from llama_index.node_parser.xberg import XbergNodeParser
+
+reader = XbergReader(
+    extraction_config=ExtractionConfig(chunking=ChunkingConfig(max_characters=1000, overlap=200))
+)
+documents = reader.load_data("report.pdf")
+
+parser = XbergNodeParser()
+nodes = parser.get_nodes_from_documents(documents)
+```
+
+### IngestionPipeline
+
+Chain with `SentenceSplitter` to further split any oversized nodes:
+
+```python
+from llama_index.core.ingestion import IngestionPipeline
+from llama_index.core.node_parser import SentenceSplitter
+
+pipeline = IngestionPipeline(
+    transformations=[
+        XbergNodeParser(),
+        SentenceSplitter(chunk_size=512),  # Further split large nodes
+    ]
+)
+nodes = pipeline.run(documents=documents)
+```
+
+### VectorStoreIndex
+
+Using the `transformations` parameter:
+
+```python
+from llama_index.core import VectorStoreIndex
+
+index = VectorStoreIndex.from_documents(
+    documents,
+    transformations=[XbergNodeParser()],
+)
+```
+
+### Async
+
+```python
+nodes = await parser.aget_nodes_from_documents(documents)
+```
+
+## Behavior Notes
+
+- Chunks take priority over elements. When a document carries both
+  `_xberg_chunks` and `_xberg_elements`, the parser splits on chunks.
+- Documents without either metadata key pass through unchanged with a warning.
+  This is intentional — silently falling back would hide that you are not
+  getting structure-aware splitting.
+- Empty or whitespace-only chunks and elements are automatically skipped.

llama_index_node_parser_xberg-1.0.0/README.md

@@ -0,0 +1,131 @@
+# LlamaIndex Node Parser Xberg
+
+<div align="center" style="display: flex; flex-wrap: wrap; gap: 8px; justify-content: center; margin: 20px 0;">
+  <a href="https://pypi.org/project/llama-index-node-parser-xberg/">
+    <img src="https://img.shields.io/pypi/v/llama-index-node-parser-xberg?label=Node%20Parser&color=007ec6" alt="Node Parser">
+  </a>
+  <a href="https://pypi.org/project/xberg/">
+    <img src="https://img.shields.io/pypi/v/xberg?label=Xberg&color=007ec6" alt="Xberg">
+  </a>
+  <a href="https://github.com/xberg-io/llama-index-xberg/blob/main/LICENSE">
+    <img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License">
+  </a>
+  <a href="https://docs.xberg.io">
+    <img src="https://img.shields.io/badge/docs-xberg.io-blue" alt="Documentation">
+  </a>
+</div>
+
+<img width="3384" height="573" alt="Xberg Banner" src="https://github.com/user-attachments/assets/1b6c6ad7-3b6d-4171-b1c9-f2026cc9deb8" />
+
+<div align="center" style="margin-top: 20px;">
+  <a href="https://discord.gg/xt9WY3GnKR">
+    <img height="22" src="https://img.shields.io/badge/Discord-Join%20our%20community-7289da?logo=discord&logoColor=white" alt="Discord">
+  </a>
+</div>
+
+Structure-aware LlamaIndex node parser for xberg-extracted documents. It turns
+xberg's native **chunks** into nodes, and falls back to structural **elements**
+when chunks are absent.
+
+## Installation
+
+```bash
+pip install llama-index-node-parser-xberg
+```
+
+Requires `llama-index-core>=0.14.23,<0.15`. This package does not depend on
+`xberg` directly — `xberg` is a dependency of the reader
+(`llama-index-readers-xberg`), which produces the documents this parser splits.
+
+## Prerequisites
+
+> **This parser requires documents with `_xberg_chunks` or `_xberg_elements`
+> metadata.** These are produced by `XbergReader`. Prefer native chunking; use
+> element-based extraction when you want one node per structural element.
+> Documents carrying neither pass through unchanged with a warning.
+
+```python
+from xberg import ChunkingConfig, ExtractionConfig
+from llama_index.readers.xberg import XbergReader
+
+# Preferred: native semantic chunks with heading path and page span.
+reader = XbergReader(
+    extraction_config=ExtractionConfig(chunking=ChunkingConfig(max_characters=1000, overlap=200))
+)
+documents = reader.load_data("report.pdf")
+```
+
+## Features
+
+- Chunk-aware splitting — each xberg native chunk becomes a node, carrying `chunk_type`, `heading_path`, and page span
+- Element fallback — when no chunks are present, headings, paragraphs, tables, and code blocks each become a node
+- Source and prev/next relationships tracked via `NodeRelationship`
+- Graceful degradation — documents without chunk or element metadata pass through with a warning
+- Composes with other transformations (e.g., `SentenceSplitter`)
+- Async support via `aget_nodes_from_documents`
+- Serialization support (`to_dict` / `from_dict`)
+
+## Usage
+
+### Basic
+
+Full reader-to-nodes flow:
+
+```python
+from xberg import ChunkingConfig, ExtractionConfig
+from llama_index.readers.xberg import XbergReader
+from llama_index.node_parser.xberg import XbergNodeParser
+
+reader = XbergReader(
+    extraction_config=ExtractionConfig(chunking=ChunkingConfig(max_characters=1000, overlap=200))
+)
+documents = reader.load_data("report.pdf")
+
+parser = XbergNodeParser()
+nodes = parser.get_nodes_from_documents(documents)
+```
+
+### IngestionPipeline
+
+Chain with `SentenceSplitter` to further split any oversized nodes:
+
+```python
+from llama_index.core.ingestion import IngestionPipeline
+from llama_index.core.node_parser import SentenceSplitter
+
+pipeline = IngestionPipeline(
+    transformations=[
+        XbergNodeParser(),
+        SentenceSplitter(chunk_size=512),  # Further split large nodes
+    ]
+)
+nodes = pipeline.run(documents=documents)
+```
+
+### VectorStoreIndex
+
+Using the `transformations` parameter:
+
+```python
+from llama_index.core import VectorStoreIndex
+
+index = VectorStoreIndex.from_documents(
+    documents,
+    transformations=[XbergNodeParser()],
+)
+```
+
+### Async
+
+```python
+nodes = await parser.aget_nodes_from_documents(documents)
+```
+
+## Behavior Notes
+
+- Chunks take priority over elements. When a document carries both
+  `_xberg_chunks` and `_xberg_elements`, the parser splits on chunks.
+- Documents without either metadata key pass through unchanged with a warning.
+  This is intentional — silently falling back would hide that you are not
+  getting structure-aware splitting.
+- Empty or whitespace-only chunks and elements are automatically skipped.

llama_index_node_parser_xberg-1.0.0/llama_index/node_parser/xberg/__init__.py

@@ -0,0 +1,5 @@
+"""XbergNodeParser — element-aware node parser for xberg-extracted documents."""
+
+from llama_index.node_parser.xberg.base import XbergNodeParser
+
+__all__ = ["XbergNodeParser"]

llama_index_node_parser_xberg-1.0.0/llama_index/node_parser/xberg/base.py

@@ -0,0 +1,170 @@
+"""Structure-aware node parser for xberg-extracted documents."""
+
+import logging
+import sys
+from collections.abc import Sequence
+from typing import Any
+
+if sys.version_info >= (3, 12):
+    from typing import override
+else:
+    from typing_extensions import override
+
+from llama_index.core.node_parser import NodeParser
+from llama_index.core.schema import BaseNode, Document, NodeRelationship, TextNode
+from llama_index.core.utils import get_tqdm_iterable
+
+logger = logging.getLogger(__name__)
+
+_ELEMENT_METADATA_KEYS = ("element_type", "page_number", "element_index")
+_CHUNK_METADATA_KEYS = (
+    "chunk_type",
+    "heading_path",
+    "page_number",
+    "first_page",
+    "last_page",
+    "chunk_index",
+    "total_chunks",
+    "token_count",
+)
+
+_FORWARDED_KEYS = ("_xberg_chunks", "_xberg_elements")
+
+_MISSING_ELEMENTS_WARNING = (
+    "Document %s has no '_xberg_chunks' or '_xberg_elements' metadata. "
+    "Passing through unchanged. Use XbergReader with "
+    "ExtractionConfig(chunking=ChunkingConfig(...)) for native chunk nodes, or "
+    "ExtractionConfig(result_format='element_based') for element nodes."
+)
+
+
+class XbergNodeParser(NodeParser):
+    """Structure-aware node parser for xberg-extracted documents.
+
+    Turns xberg's output into individual ``TextNode`` objects, preserving
+    document structure through the RAG pipeline. It prefers xberg's native
+    **chunks** (``_xberg_chunks``) — semantic splits carrying heading path and
+    page span — and falls back to structural **elements** (``_xberg_elements``)
+    when chunks are absent.
+
+    Produce chunk-bearing documents with ``XbergReader`` configured with
+    ``ExtractionConfig(chunking=ChunkingConfig(...))``; element-bearing
+    documents with ``result_format="element_based"``. Documents carrying
+    neither pass through unchanged with a warning.
+    """
+
+    @classmethod
+    def class_name(cls) -> str:
+        """Return the unique class identifier for serialisation."""
+        return "XbergNodeParser"
+
+    @override
+    def _parse_nodes(
+        self,
+        nodes: Sequence[BaseNode],
+        show_progress: bool = False,
+        **kwargs: Any,
+    ) -> list[BaseNode]:
+        output: list[BaseNode] = []
+        nodes_with_progress = get_tqdm_iterable(nodes, show_progress, "Parsing nodes")
+
+        for node in nodes_with_progress:
+            chunks = node.metadata.get("_xberg_chunks")
+            if isinstance(chunks, list) and chunks:
+                output.extend(self._nodes_from_chunks(node, chunks))
+                continue
+
+            elements = node.metadata.get("_xberg_elements")
+            if isinstance(elements, list) and elements:
+                output.extend(self._nodes_from_elements(node, elements))
+                continue
+
+            logger.warning(_MISSING_ELEMENTS_WARNING, node.node_id)
+            output.append(node)
+
+        return output
+
+    def _new_text_node(self, text: str, index: int, source: BaseNode, metadata: dict[str, Any]) -> TextNode:
+        """Build a child ``TextNode`` inheriting formatting from its source."""
+        return TextNode(
+            text=text,
+            id_=self.id_func(index, source),
+            metadata=metadata,
+            excluded_llm_metadata_keys=list(source.excluded_llm_metadata_keys),
+            metadata_separator=source.metadata_separator,
+            metadata_template=source.metadata_template,
+            text_template=source.text_template,
+            relationships={NodeRelationship.SOURCE: source.as_related_node_info()},
+        )
+
+    def _nodes_from_chunks(self, node: BaseNode, chunks: list[dict[str, Any]]) -> list[TextNode]:
+        """Split a chunk-bearing Document into one TextNode per non-empty chunk."""
+        excluded_embed = list(node.excluded_embed_metadata_keys) + list(_CHUNK_METADATA_KEYS)
+        result: list[TextNode] = []
+        idx = 0
+        for chunk in chunks:
+            text = chunk.get("content", "")
+            if not text.strip():
+                continue
+            meta = chunk.get("metadata", {})
+            text_node = self._new_text_node(
+                text,
+                idx,
+                node,
+                {
+                    "chunk_type": chunk.get("chunk_type", "unknown"),
+                    "heading_path": meta.get("heading_path", []),
+                    "page_number": meta.get("first_page"),
+                    "first_page": meta.get("first_page"),
+                    "last_page": meta.get("last_page"),
+                    "chunk_index": meta.get("chunk_index"),
+                    "total_chunks": meta.get("total_chunks"),
+                    "token_count": meta.get("token_count"),
+                },
+            )
+            text_node.excluded_embed_metadata_keys = excluded_embed
+            result.append(text_node)
+            idx += 1
+        return result
+
+    def _nodes_from_elements(self, node: BaseNode, elements: list[dict[str, Any]]) -> list[TextNode]:
+        """Split an element-bearing Document into one TextNode per non-empty element."""
+        excluded_embed = list(node.excluded_embed_metadata_keys) + list(_ELEMENT_METADATA_KEYS)
+        result: list[TextNode] = []
+        idx = 0
+        for el in elements:
+            text = el.get("text", "")
+            if not text.strip():
+                continue
+            el_meta = el.get("metadata", {})
+            text_node = self._new_text_node(
+                text,
+                idx,
+                node,
+                {
+                    "element_type": el.get("element_type", "unknown"),
+                    "page_number": el_meta.get("page_number"),
+                    "element_index": el_meta.get("element_index"),
+                },
+            )
+            text_node.excluded_embed_metadata_keys = excluded_embed
+            result.append(text_node)
+            idx += 1
+        return result
+
+    @staticmethod
+    def _strip_forwarded_metadata(nodes: list[BaseNode]) -> list[BaseNode]:
+        """Remove reader forwarding keys from child TextNodes only.
+
+        Passthrough documents keep their metadata untouched.
+        """
+        for node in nodes:
+            if node.source_node is not None:
+                for key in _FORWARDED_KEYS:
+                    node.metadata.pop(key, None)
+        return nodes
+
+    @override
+    def _postprocess_parsed_nodes(self, nodes: list[BaseNode], parent_doc_map: dict[str, Document]) -> list[BaseNode]:
+        nodes = super()._postprocess_parsed_nodes(nodes, parent_doc_map)
+        return self._strip_forwarded_metadata(nodes)

llama_index_node_parser_xberg-1.0.0/pyproject.toml

@@ -0,0 +1,66 @@
+[build-system]
+build-backend = "hatchling.build"
+requires = ["hatchling"]
+
+[project]
+name = "llama-index-node-parser-xberg"
+version = "1.0.0"
+description = "Structure-aware LlamaIndex node parser that turns xberg native chunks and elements into nodes"
+readme = "README.md"
+keywords = ["ai", "chunking", "document-structure", "xberg", "llamaindex", "llm", "node-parser", "rag"]
+license = "MIT"
+maintainers = [{ name = "xberg", email = "contact@xberg.io" }]
+authors = [{ name = "xberg", email = "contact@xberg.io" }]
+requires-python = ">=3.10"
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Intended Audience :: Science/Research",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+  "Topic :: Text Processing :: General",
+  "Topic :: Text Processing :: Indexing",
+  "Typing :: Typed",
+]
+dependencies = ["llama-index-core>=0.14.23,<0.15"]
+urls.Homepage = "https://github.com/xberg-io/xberg/tree/main/integrations/python/llama-index/node_parsers/llama-index-node-parser-xberg"
+urls.Issues = "https://github.com/xberg-io/xberg/issues"
+urls.Repository = "https://github.com/xberg-io/xberg/tree/main/integrations/python/llama-index/node_parsers/llama-index-node-parser-xberg"
+
+[dependency-groups]
+dev = ["pytest>=9", "pytest-asyncio>=0.24", "pytest-cov>=6"]
+
+[tool.hatch]
+build.targets.sdist.include = ["llama_index/"]
+build.targets.wheel.include = ["llama_index/"]
+
+[tool.mypy]
+disallow_untyped_defs = true
+exclude = ["_static", "build", "examples", "notebooks", "venv"]
+ignore_missing_imports = true
+python_version = "3.10"
+
+[tool.pytest]
+ini_options.testpaths = ["tests"]
+ini_options.asyncio_mode = "auto"
+
+[tool.coverage]
+run.source = ["llama_index/node_parser/xberg"]
+report.fail_under = 80
+
+[tool.llamahub]
+contains_example = false
+import_path = "llama_index.node_parser.xberg"
+class_authors.XbergNodeParser = "v-tan"
+
+[tool.uv]
+# xberg ships as a pre-release (1.0.0rcN) until the 1.0.0 GA; persist prerelease
+# resolution so the lockfile is authoritative and `uv run` does not re-resolve. ~keep
+prerelease = "allow"