docctl 0.1.0__tar.gz

docctl-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Georges Alkhouri
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

docctl-0.1.0/MANIFEST.in

@@ -0,0 +1,13 @@
+include LICENSE
+include README.md
+include pyproject.toml
+graft src
+prune .github
+prune benchmarks
+prune build
+prune dist
+prune docs
+prune scripts
+prune tests
+global-exclude __pycache__
+global-exclude *.py[cod]

docctl-0.1.0/PKG-INFO

@@ -0,0 +1,195 @@
+Metadata-Version: 2.4
+Name: docctl
+Version: 0.1.0
+Summary: CLI-first local document retrieval tool
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/GeorgesAlkhouri/docctl
+Project-URL: Repository, https://github.com/GeorgesAlkhouri/docctl
+Project-URL: Issues, https://github.com/GeorgesAlkhouri/docctl/issues
+Project-URL: Changelog, https://github.com/GeorgesAlkhouri/docctl/blob/main/CHANGELOG.md
+Keywords: cli,documents,local-first,retrieval,search
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Text Processing
+Classifier: Topic :: Utilities
+Requires-Python: <3.14,>=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: chromadb>=0.5.23
+Requires-Dist: llama-index-core>=0.11.23
+Requires-Dist: python-docx
+Requires-Dist: pdfplumber
+Requires-Dist: pypdf
+Requires-Dist: reportlab
+Requires-Dist: sentence-transformers>=3.3.1
+Requires-Dist: typer>=0.12.5
+Dynamic: license-file
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/GeorgesAlkhouri/docctl/main/docs/assets/docctl_logo_dark.png" />
+    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/GeorgesAlkhouri/docctl/main/docs/assets/docctl_logo_light.png" />
+    <img alt="docctl logo" src="https://raw.githubusercontent.com/GeorgesAlkhouri/docctl/main/docs/assets/docctl_logo_light.png" width="560" />
+  </picture>
+</p>
+
+<p align="center">
+  Local-first CLI for agent and human document retrieval with provenance-grounded answers,
+  local vector-store, and predictable machine-readable output.
+</p>
+
+<p align="center">
+  <a href="https://github.com/GeorgesAlkhouri/docctl/actions/workflows/ci.yml">
+    <img alt="CI" src="https://img.shields.io/github/actions/workflow/status/GeorgesAlkhouri/docctl/ci.yml?branch=main&style=for-the-badge&label=ci&logo=githubactions&logoColor=white" />
+  </a>
+  <a href="https://github.com/GeorgesAlkhouri/docctl/actions/workflows/security-trivy.yml">
+    <img alt="Trivy" src="https://img.shields.io/github/actions/workflow/status/GeorgesAlkhouri/docctl/security-trivy.yml?branch=main&style=for-the-badge&label=trivy&logo=githubactions&logoColor=white" />
+  </a>
+  <a href="https://sonarcloud.io/summary/new_code?id=GeorgesAlkhouri_docctl">
+    <img alt="Quality Gate" src="https://img.shields.io/sonar/quality_gate/GeorgesAlkhouri_docctl?server=https%3A%2F%2Fsonarcloud.io&style=for-the-badge&label=quality%20gate&logo=sonar&logoColor=white" />
+  </a>
+  <a href="https://codecov.io/gh/GeorgesAlkhouri/docctl">
+    <img alt="Codecov" src="https://img.shields.io/codecov/c/github/GeorgesAlkhouri/docctl?style=for-the-badge&logo=codecov&logoColor=white&label=codecov" />
+  </a>
+</p>
+
+<p align="center">
+  <a href="https://www.python.org/downloads/">
+    <img alt="Python 3.12 | 3.13" src="https://img.shields.io/badge/python-3.12%20%7C%203.13-3776AB?style=for-the-badge&logo=python&logoColor=white" />
+  </a>
+  <a href="https://github.com/GeorgesAlkhouri/docctl">
+    <img alt="Local-first" src="https://img.shields.io/badge/local--first-no%20cloud%20required-2EA44F?style=for-the-badge&logo=homeassistant&logoColor=white" />
+  </a>
+  <a href="https://docs.trychroma.com/">
+    <img alt="Chroma" src="https://img.shields.io/badge/chroma-vector%20store-FF6F00?style=for-the-badge&logo=sqlite&logoColor=white" />
+  </a>
+</p>
+
+## Why docctl
+- Optimized for agentic retrieval loops with fast multi-step questions and answers.
+- Runs locally with a persistent Chroma-backed index.
+- Ingests `.pdf`, `.docx`, `.txt`, and `.md` with provenance metadata (`doc_id`, `source`, `title`).
+- Uses sentence-aware chunking for better retrieval quality.
+- Supports deterministic `--json` output for automation and agents.
+- Exposes stable CLI workflows for ingest, search, diagnostics, and inventory.
+
+## Agent Integration
+Use [SKILL.md](https://github.com/GeorgesAlkhouri/docctl/blob/main/SKILL.md) when you want an agent to drive `docctl` end-to-end.
+The skill makes `session` for fast iterative retrieval.
+
+## Quickstart
+Requirements:
+- Python 3.12 or 3.13
+- `uv`
+
+```bash
+# 1) Install dependencies
+uv sync --frozen --dev
+
+# 2) Verify CLI
+uv run docctl --help
+
+# 3) Ingest supported files
+uv run docctl ingest ./docs --recursive --approve-write --allow-model-download
+
+# 4) Search indexed content
+uv run docctl search "security gateway diagnostics" --top-k 5 --allow-model-download
+
+# 5) Show one chunk by id (replace with an id from search output)
+uv run docctl show <chunk_id_from_search> --allow-model-download
+```
+
+After the first public release, install from PyPI with:
+
+```bash
+pip install docctl
+```
+
+## Command Overview
+| Command | Purpose |
+|---|---|
+| `docctl ingest <path>` | Ingest one supported file or a directory of supported files (mutates local index state). |
+| `docctl search <query>` | Search indexed content with optional metadata filters. |
+| `docctl show <chunk_id>` | Show one indexed chunk by exact id. |
+| `docctl stats` | Show index statistics. |
+| `docctl catalog` | Show index summary and per-document inventory. |
+| `docctl doctor` | Run local diagnostics for index and embedding setup. |
+| `docctl session` | Run a read-only NDJSON request session on stdin/stdout. |
+
+## JSON and Session Mode
+Use `--json` for deterministic machine-readable output:
+
+```bash
+uv run docctl --json search "security gateway diagnostics" --top-k 5 --allow-model-download
+```
+
+Use `session` for NDJSON request/response flows. For agents, this is the preferred fast path whenever one workflow needs two or more read operations:
+
+```bash
+cat <<'EOF' | uv run docctl session --allow-model-download
+{"id":"q1","op":"search","query":"security gateway diagnostics","top_k":5}
+{"id":"q2","op":"catalog"}
+EOF
+```
+
+## Configuration
+Global options:
+- `--index-path` (default: `.docctl`)
+- `--collection` (default: `default`)
+- `--json` (deterministic JSON payloads on stdout)
+- `--verbose` (extra diagnostics)
+
+Model downloads are explicit:
+- Use `--allow-model-download` when embedding artifacts are not already available.
+
+Mutation boundaries:
+- `ingest` is mutating.
+- `search`, `show`, `stats`, `catalog`, `doctor`, and `session` are read-only.
+
+## Development
+Run core quality checks:
+
+```bash
+make lint
+make format-check
+make typecheck
+make security-lint
+make import-lint
+make test
+make test-cov
+make check-markdown-links
+```
+
+Apply formatting fixes:
+
+```bash
+make format
+```
+
+Build release artifacts locally:
+
+```bash
+make build-dist
+make check-dist
+make release-dry-run
+```
+
+## Documentation Map
+- [ARCHITECTURE.md](https://github.com/GeorgesAlkhouri/docctl/blob/main/ARCHITECTURE.md)
+- [docs/design-docs/index.md](https://github.com/GeorgesAlkhouri/docctl/blob/main/docs/design-docs/index.md)
+- [docs/product-specs/index.md](https://github.com/GeorgesAlkhouri/docctl/blob/main/docs/product-specs/index.md)
+- [docs/references/index.md](https://github.com/GeorgesAlkhouri/docctl/blob/main/docs/references/index.md)
+- [SECURITY.md](https://github.com/GeorgesAlkhouri/docctl/blob/main/SECURITY.md) (canonical vulnerability disclosure policy)
+- [docs/RELIABILITY.md](https://github.com/GeorgesAlkhouri/docctl/blob/main/docs/RELIABILITY.md)
+- [docs/SECURITY.md](https://github.com/GeorgesAlkhouri/docctl/blob/main/docs/SECURITY.md) (internal implementation security guardrails)
+- [docs/PLANS.md](https://github.com/GeorgesAlkhouri/docctl/blob/main/docs/PLANS.md)
+
+## Contributing
+For implementation and validation workflow, start with:
+1. [AGENTS.md](https://github.com/GeorgesAlkhouri/docctl/blob/main/AGENTS.md)
+2. [ARCHITECTURE.md](https://github.com/GeorgesAlkhouri/docctl/blob/main/ARCHITECTURE.md)
+3. The indexed docs under `docs/` listed above.

docctl-0.1.0/README.md

@@ -0,0 +1,164 @@
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/GeorgesAlkhouri/docctl/main/docs/assets/docctl_logo_dark.png" />
+    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/GeorgesAlkhouri/docctl/main/docs/assets/docctl_logo_light.png" />
+    <img alt="docctl logo" src="https://raw.githubusercontent.com/GeorgesAlkhouri/docctl/main/docs/assets/docctl_logo_light.png" width="560" />
+  </picture>
+</p>
+
+<p align="center">
+  Local-first CLI for agent and human document retrieval with provenance-grounded answers,
+  local vector-store, and predictable machine-readable output.
+</p>
+
+<p align="center">
+  <a href="https://github.com/GeorgesAlkhouri/docctl/actions/workflows/ci.yml">
+    <img alt="CI" src="https://img.shields.io/github/actions/workflow/status/GeorgesAlkhouri/docctl/ci.yml?branch=main&style=for-the-badge&label=ci&logo=githubactions&logoColor=white" />
+  </a>
+  <a href="https://github.com/GeorgesAlkhouri/docctl/actions/workflows/security-trivy.yml">
+    <img alt="Trivy" src="https://img.shields.io/github/actions/workflow/status/GeorgesAlkhouri/docctl/security-trivy.yml?branch=main&style=for-the-badge&label=trivy&logo=githubactions&logoColor=white" />
+  </a>
+  <a href="https://sonarcloud.io/summary/new_code?id=GeorgesAlkhouri_docctl">
+    <img alt="Quality Gate" src="https://img.shields.io/sonar/quality_gate/GeorgesAlkhouri_docctl?server=https%3A%2F%2Fsonarcloud.io&style=for-the-badge&label=quality%20gate&logo=sonar&logoColor=white" />
+  </a>
+  <a href="https://codecov.io/gh/GeorgesAlkhouri/docctl">
+    <img alt="Codecov" src="https://img.shields.io/codecov/c/github/GeorgesAlkhouri/docctl?style=for-the-badge&logo=codecov&logoColor=white&label=codecov" />
+  </a>
+</p>
+
+<p align="center">
+  <a href="https://www.python.org/downloads/">
+    <img alt="Python 3.12 | 3.13" src="https://img.shields.io/badge/python-3.12%20%7C%203.13-3776AB?style=for-the-badge&logo=python&logoColor=white" />
+  </a>
+  <a href="https://github.com/GeorgesAlkhouri/docctl">
+    <img alt="Local-first" src="https://img.shields.io/badge/local--first-no%20cloud%20required-2EA44F?style=for-the-badge&logo=homeassistant&logoColor=white" />
+  </a>
+  <a href="https://docs.trychroma.com/">
+    <img alt="Chroma" src="https://img.shields.io/badge/chroma-vector%20store-FF6F00?style=for-the-badge&logo=sqlite&logoColor=white" />
+  </a>
+</p>
+
+## Why docctl
+- Optimized for agentic retrieval loops with fast multi-step questions and answers.
+- Runs locally with a persistent Chroma-backed index.
+- Ingests `.pdf`, `.docx`, `.txt`, and `.md` with provenance metadata (`doc_id`, `source`, `title`).
+- Uses sentence-aware chunking for better retrieval quality.
+- Supports deterministic `--json` output for automation and agents.
+- Exposes stable CLI workflows for ingest, search, diagnostics, and inventory.
+
+## Agent Integration
+Use [SKILL.md](https://github.com/GeorgesAlkhouri/docctl/blob/main/SKILL.md) when you want an agent to drive `docctl` end-to-end.
+The skill makes `session` for fast iterative retrieval.
+
+## Quickstart
+Requirements:
+- Python 3.12 or 3.13
+- `uv`
+
+```bash
+# 1) Install dependencies
+uv sync --frozen --dev
+
+# 2) Verify CLI
+uv run docctl --help
+
+# 3) Ingest supported files
+uv run docctl ingest ./docs --recursive --approve-write --allow-model-download
+
+# 4) Search indexed content
+uv run docctl search "security gateway diagnostics" --top-k 5 --allow-model-download
+
+# 5) Show one chunk by id (replace with an id from search output)
+uv run docctl show <chunk_id_from_search> --allow-model-download
+```
+
+After the first public release, install from PyPI with:
+
+```bash
+pip install docctl
+```
+
+## Command Overview
+| Command | Purpose |
+|---|---|
+| `docctl ingest <path>` | Ingest one supported file or a directory of supported files (mutates local index state). |
+| `docctl search <query>` | Search indexed content with optional metadata filters. |
+| `docctl show <chunk_id>` | Show one indexed chunk by exact id. |
+| `docctl stats` | Show index statistics. |
+| `docctl catalog` | Show index summary and per-document inventory. |
+| `docctl doctor` | Run local diagnostics for index and embedding setup. |
+| `docctl session` | Run a read-only NDJSON request session on stdin/stdout. |
+
+## JSON and Session Mode
+Use `--json` for deterministic machine-readable output:
+
+```bash
+uv run docctl --json search "security gateway diagnostics" --top-k 5 --allow-model-download
+```
+
+Use `session` for NDJSON request/response flows. For agents, this is the preferred fast path whenever one workflow needs two or more read operations:
+
+```bash
+cat <<'EOF' | uv run docctl session --allow-model-download
+{"id":"q1","op":"search","query":"security gateway diagnostics","top_k":5}
+{"id":"q2","op":"catalog"}
+EOF
+```
+
+## Configuration
+Global options:
+- `--index-path` (default: `.docctl`)
+- `--collection` (default: `default`)
+- `--json` (deterministic JSON payloads on stdout)
+- `--verbose` (extra diagnostics)
+
+Model downloads are explicit:
+- Use `--allow-model-download` when embedding artifacts are not already available.
+
+Mutation boundaries:
+- `ingest` is mutating.
+- `search`, `show`, `stats`, `catalog`, `doctor`, and `session` are read-only.
+
+## Development
+Run core quality checks:
+
+```bash
+make lint
+make format-check
+make typecheck
+make security-lint
+make import-lint
+make test
+make test-cov
+make check-markdown-links
+```
+
+Apply formatting fixes:
+
+```bash
+make format
+```
+
+Build release artifacts locally:
+
+```bash
+make build-dist
+make check-dist
+make release-dry-run
+```
+
+## Documentation Map
+- [ARCHITECTURE.md](https://github.com/GeorgesAlkhouri/docctl/blob/main/ARCHITECTURE.md)
+- [docs/design-docs/index.md](https://github.com/GeorgesAlkhouri/docctl/blob/main/docs/design-docs/index.md)
+- [docs/product-specs/index.md](https://github.com/GeorgesAlkhouri/docctl/blob/main/docs/product-specs/index.md)
+- [docs/references/index.md](https://github.com/GeorgesAlkhouri/docctl/blob/main/docs/references/index.md)
+- [SECURITY.md](https://github.com/GeorgesAlkhouri/docctl/blob/main/SECURITY.md) (canonical vulnerability disclosure policy)
+- [docs/RELIABILITY.md](https://github.com/GeorgesAlkhouri/docctl/blob/main/docs/RELIABILITY.md)
+- [docs/SECURITY.md](https://github.com/GeorgesAlkhouri/docctl/blob/main/docs/SECURITY.md) (internal implementation security guardrails)
+- [docs/PLANS.md](https://github.com/GeorgesAlkhouri/docctl/blob/main/docs/PLANS.md)
+
+## Contributing
+For implementation and validation workflow, start with:
+1. [AGENTS.md](https://github.com/GeorgesAlkhouri/docctl/blob/main/AGENTS.md)
+2. [ARCHITECTURE.md](https://github.com/GeorgesAlkhouri/docctl/blob/main/ARCHITECTURE.md)
+3. The indexed docs under `docs/` listed above.

docctl-0.1.0/pyproject.toml

@@ -0,0 +1,152 @@
+[build-system]
+requires = ["setuptools>=82", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "docctl"
+version = "0.1.0"
+description = "CLI-first local document retrieval tool"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.12,<3.14"
+keywords = ["cli", "documents", "local-first", "retrieval", "search"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Text Processing",
+  "Topic :: Utilities",
+]
+dependencies = [
+  "chromadb>=0.5.23",
+  "llama-index-core>=0.11.23",
+  "python-docx",
+  "pdfplumber",
+  "pypdf",
+  "reportlab",
+  "sentence-transformers>=3.3.1",
+  "typer>=0.12.5",
+]
+
+[project.urls]
+Homepage = "https://github.com/GeorgesAlkhouri/docctl"
+Repository = "https://github.com/GeorgesAlkhouri/docctl"
+Issues = "https://github.com/GeorgesAlkhouri/docctl/issues"
+Changelog = "https://github.com/GeorgesAlkhouri/docctl/blob/main/CHANGELOG.md"
+
+[project.scripts]
+docctl = "docctl.cli:main"
+
+[dependency-groups]
+dev = [
+  "bandit>=1.9.4",
+  "import-linter>=2.7",
+  "mypy>=1.15.0",
+  "python-semantic-release>=10.5.3,<11",
+  "pytest>=8.3.4",
+  "pytest-cov>=6.1.1",
+  "ruff>=0.11.0",
+  "twine>=6.1.0,<7",
+]
+
+[tool.uv]
+package = true
+
+[tool.semantic_release]
+allow_zero_version = true
+major_on_zero = false
+commit_message = "chore(release): {version}\n\nAutomatically generated by python-semantic-release"
+commit_parser = "conventional"
+tag_format = "v{version}"
+version_toml = ["pyproject.toml:project.version"]
+build_command = "uv lock && git add uv.lock"
+
+[tool.semantic_release.branches.main]
+match = "main"
+prerelease = false
+
+[tool.semantic_release.changelog]
+mode = "update"
+
+[tool.semantic_release.changelog.default_templates]
+changelog_file = "CHANGELOG.md"
+output_format = "md"
+mask_initial_release = true
+
+[tool.semantic_release.commit_parser_options]
+minor_tags = ["feat"]
+patch_tags = ["fix", "perf"]
+allowed_tags = ["build", "chore", "ci", "docs", "feat", "fix", "perf", "refactor", "style", "test"]
+other_allowed_tags = ["build", "chore", "ci", "docs", "refactor", "style", "test"]
+default_bump_level = 0
+parse_squash_commits = true
+ignore_merge_commits = true
+
+[tool.semantic_release.remote]
+name = "origin"
+type = "github"
+ignore_token_for_push = false
+
+[tool.semantic_release.publish]
+dist_glob_patterns = ["dist/*"]
+upload_to_vcs_release = false
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+addopts = "-ra"
+
+[tool.ruff]
+target-version = "py312"
+line-length = 100
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = [
+  "E4",
+  "E7",
+  "E9",
+  "F",
+  "I",
+  "B",
+  "C90",
+  "RET",
+  "SIM",
+  "ARG",
+  "PLR0911",
+  "PLR0912",
+  "PLR0913",
+  "PLR0915",
+]
+
+[tool.ruff.lint.flake8-bugbear]
+extend-immutable-calls = ["typer.Argument", "typer.Option"]
+
+[tool.ruff.lint.mccabe]
+max-complexity = 8
+
+[tool.ruff.lint.pylint]
+max-args = 5
+max-positional-args = 4
+max-branches = 10
+max-locals = 12
+max-public-methods = 12
+max-returns = 5
+max-statements = 35
+max-nested-blocks = 4
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = ["ARG", "PLR0913", "PLR0915"]
+"src/docctl/cli.py" = ["PLR0913"]
+
+[tool.ruff.format]
+docstring-code-format = true
+
+[tool.mypy]
+python_version = "3.12"
+files = ["src"]
+ignore_missing_imports = true
+warn_unused_configs = true

docctl-0.1.0/setup.cfg

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

docctl-0.1.0/src/docctl/__init__.py

@@ -0,0 +1,4 @@
+"""docctl package."""
+
+__all__ = ["__version__"]
+__version__ = "0.1.0"

docctl-0.1.0/src/docctl/chunking.py

@@ -0,0 +1,79 @@
+"""Sentence-aware chunking for extracted documents."""
+
+from __future__ import annotations
+
+from llama_index.core.node_parser import SentenceSplitter
+from llama_index.core.schema import Document, MetadataMode
+
+from .ids import build_chunk_id
+from .models import ChunkMetadata, ChunkRecord, TextUnit
+
+
+def chunk_document_units(  # noqa: PLR0913 - explicit parameters keep the chunking API clear; wrapping into a config object here would add indirection without reducing complexity.
+    *,
+    doc_id: str,
+    source: str,
+    title: str,
+    units: list[TextUnit],
+    chunk_size: int = 220,
+    chunk_overlap: int = 40,
+) -> list[ChunkRecord]:
+    """Convert text units into sentence-aware chunks while preserving metadata.
+
+    Args:
+        doc_id: Stable identifier of the source document.
+        source: Source path or URI associated with the document.
+        title: Human-readable title associated with the document.
+        units: Extracted text units.
+        chunk_size: Maximum target size for each chunk in characters.
+            Smaller values create more, shorter chunks.
+        chunk_overlap: Number of trailing characters repeated from one chunk
+            into the next chunk to preserve local context across boundaries.
+
+    Returns:
+        Deterministic chunk records with metadata and stable chunk identifiers.
+    """
+    documents = [
+        Document(
+            text=unit.text,
+            metadata={
+                "doc_id": doc_id,
+                "source": source,
+                "title": title,
+            },
+            id_=f"{doc_id}:unit",
+        )
+        for unit in units
+    ]
+
+    splitter = SentenceSplitter(chunk_size=chunk_size, chunk_overlap=chunk_overlap)
+    nodes = splitter.get_nodes_from_documents(documents)
+
+    records: list[ChunkRecord] = []
+    for node in nodes:
+        metadata = dict(node.metadata)
+
+        text = node.get_content(metadata_mode=MetadataMode.NONE).strip()
+        if not text:
+            continue
+        chunk_index = len(records) + 1
+
+        chunk_id = build_chunk_id(
+            doc_id=doc_id,
+            chunk_index=chunk_index,
+            text=text,
+        )
+        records.append(
+            ChunkRecord(
+                id=chunk_id,
+                text=text,
+                metadata=ChunkMetadata(
+                    doc_id=str(metadata.get("doc_id", doc_id)),
+                    source=str(metadata.get("source", source)),
+                    title=str(metadata.get("title", title)),
+                    section=metadata.get("section"),
+                ),
+            )
+        )
+
+    return records