omnichunk 2.1.2__tar.gz → 2.2.0__tar.gz

{omnichunk-2.1.2 → omnichunk-2.2.0}/CHANGELOG.md

@@ -5,7 +5,102 @@ This project follows [Keep a Changelog](https://keepachangelog.com/) and [Semant
 
 ## [Unreleased]
 
-No unreleased changes are staged yet for a new release.
+## [2.2.0] - 2026-10-25
+
+### Added
+- A separately licensed, checksum-pinned SQuAD 1.1 retrieval corpus with 96
+  human-annotated queries, article-disjoint splits and offline import tooling.
+- Frozen dense-vector retrieval and optional local-model preparation with exact
+  payload/model provenance and fail-closed token overflow checks.
+- Identity-safe `OmniChunkIngestionPipeline` for cached native LlamaIndex ingestion.
+- Recoverable indexing with `IndexJournal`, versioned dry-run `IndexPlan` JSON,
+  source/scope ownership, generation checks, persistent embedding reuse and
+  acknowledged bounded delivery. Pending operations survive process restarts;
+  unknown/permanent failures require explicit retry after intervention.
+- Optional native LangChain `OmniChunkTextSplitter` and LlamaIndex
+  `OmniChunkNodeParser`, preserving stable identity, complete provenance, caller
+  metadata and hierarchy relationships with cacheable transform configuration.
+- Optional Qdrant and pgvector sinks, executable integration recipes and a
+  minimum/current compatibility matrix with real local clients/PostgreSQL tests.
+- `chunks_to_pinecone_upsert_request()` places namespaces on the request envelope
+  and preserves complete chunk metadata within the vendor's flat metadata shape.
+- Dependency-free public retrieval ranking metrics (Recall@k, MRR@k and nDCG@k)
+  and canonical source-byte evidence precision, recall and IoU.
+- A versioned MIT-licensed synthetic retrieval corpus: 30 documents and 300
+  exact-span questions across English, Turkish and Japanese, with document-level
+  development/test separation and integrity validation.
+- A reproducible retrieval comparison runner with seven optional/built-in
+  chunkers, shared budgets, fixed lexical retrieval, per-query/slice diagnostics
+  and source/runtime fingerprints. CI preserves the full development report.
+
+### Fixed
+- Imported index plans cannot retain stale payloads when changing context policy.
+- Qdrant/pgvector/vector exports reject float32 overflow before remote mutation;
+  transient Qdrant gRPC failures remain retryable. Pinecone filter metadata rejects
+  reserved keys and numeric identifiers that would lose precision.
+- Retrieval corpus validation rejects ambiguous JSON and normalized cross-split
+  duplicates; comparator source-offset mapping is linear in document size.
+- Code windows now measure the configured character, non-whitespace-character or
+  tokenizer budget throughout AST grouping and splitting, preserving fitting
+  Unicode declarations. Complete source gaps count toward grouping, minimum-size
+  merges stay bounded, and transient token probes are not cached.
+- Prose splitting now respects paragraph, line/table-row and Unicode sentence
+  boundaries before word-level fallbacks. Node grouping counts the actual source
+  slice, including whitespace and nonadditive token costs; minimum-size merging
+  cannot exceed the configured maximum. Explicit prose overflow policies also
+  apply when the minimum size is zero. Transient token-budget probes are uncached
+  so large windows do not retain every growing source prefix.
+- Default sentence segmentation recognizes Turkish and other Unicode starters,
+  Japanese/Chinese punctuation without spaces, closing quotes and CRLF paragraphs
+  while preserving exact source coordinates.
+- Batch inputs now apply per-document options, matching asynchronous batch behavior.
+- Unbroken prose uses measured hard splits instead of producing hundreds of tiny
+  chunks; code hard splits preserve UTF-8 character boundaries.
+- Retrieval budget selection counts rendered context, rejects unknown size units
+  and refuses token budgeting for contextualized chunks without rendered counts.
+- Vector exports reject empty, inconsistent or non-finite embeddings. Streaming
+  exports detect dimension changes between batches.
+- LangChain/LlamaIndex exports carry native document IDs. Weaviate exports use
+  deterministic UUIDs; `weaviate_object_id()` maps chunk IDs for deletions.
+- Stores reject unknown SQLite schemas without overwriting their version marker.
+- JSON-RPC validates finite numbers/timeouts, safely serializes malformed Unicode
+  request IDs and refuses nonregular file inputs.
+- Release type checking now targets each interpreter in the validation matrix.
+- Python 3.10 documentation dependencies retain the highlighter API required by
+  its supported mkdocstrings release; newer Python versions remain unconstrained.
+
+### Documentation
+- Replaced the historical roadmap with an evidence-based enterprise plan,
+  competitor gaps, ordered milestones and measurable release criteria.
+- Kept the generated MkDocs API site, simplified navigation and improved runnable
+  examples for retrieval and the incremental indexing lifecycle.
+- Removed duplicate agent rule files and their synchronization tooling;
+  `AGENTS.md` is the sole agent instruction file. Removed `ARCHITECTURE.md`.
+
+### Compatibility
+- The delivery journal uses a separate versioned database from `ChunkStore`.
+  Rebuild into a new target when adopting its vendor identity mapping; keep the
+  old target for rollback. Delivery is at least once, and does not provide atomic
+  visibility across remote batches or enforce application authorization.
+- Native framework extras now include their verified splitter/parser dependencies;
+  minimum and current compatible versions are listed in the installation guide.
+- Exported native IDs change record identity for integrations that previously
+  generated random IDs. Rebuild or reconcile those external indexes before reuse.
+- Corrected splitting can change chunk boundaries and IDs; reindex affected
+  documents and apply removals. Exact chunk layouts are not a compatibility promise.
+- Invalid embeddings and incomplete rendered token metadata now fail explicitly.
+- No package version bump or release publication is included in these changes.
+
+## [2.1.4] - 2026-09-08
+
+### Fixed
+- Bumped package runtime version to `2.1.4`.
+- Publication metadata and changelog maintenance wording were aligned for post-
+  2.1.x release tracking.
+
+### Compatibility
+- No API/runtime behavior changes.
+- Backward-compatible maintenance release.
 
 ## [2.1.1] - 2026-09-08
 

{omnichunk-2.1.2 → omnichunk-2.2.0}/CONTRIBUTING.md

@@ -7,7 +7,7 @@ Thanks for contributing.
 1. Create a virtualenv and install dev dependencies:
 
 ```bash
-pip install -e ".[dev]"
+pip install -e ".[dev,docs,langchain,llamaindex]"
 ```
 
 2. Run tests:
@@ -28,9 +28,13 @@ plus a follow-up `pytest -m no_xdist` in series.
 ```bash
 ruff check src tests
 ruff format --check src tests
-mypy src/omnichunk
+mypy --python-version 3.12 src/omnichunk
 ```
 
+Use your installed interpreter's version as the mypy target. Optional dependency
+stubs can require newer syntax than the package's minimum Python version; CI runs
+the supported Python 3.10–3.13 matrix in matching environments.
+
 ## Development rules
 
 - Keep changes deterministic.
@@ -62,7 +66,7 @@ reconstruct the original binary container or notebook JSON.
 - [ ] Verified lint, formatting, and type checks
 - [ ] Updated docs/README if behavior changed
 - [ ] Preserved chunk invariants
-- [ ] Kept rule files synchronized (`AI_RULES.md`, `.cursorrules`, `.windsurfrules`, `CLAUDE.md`, `.github/copilot-instructions.md`)
+- [ ] Verified `mkdocs build --strict` if documentation or public APIs changed
 
 ## Commit style
 
@@ -88,7 +92,7 @@ release quality and roadmap priorities.
 - Set the version only in `src/omnichunk/_version.py`; Hatch derives package
   metadata from it. The release tag must match that version.
 - Run the full line-and-branch coverage gate (90%, no core exclusions), strict
-  MkDocs build, rule sync and benchmark checks. Validate the built wheel/sdist
+  MkDocs build and benchmark checks. Validate the built wheel/sdist
   with `python scripts/check_release.py --help` for the supported arguments.
 - Build and validate separate indexes before switching consumers across the
   [2.x migration](docs/migrations/v2.md); retain the old index for rollback.

{omnichunk-2.1.2 → omnichunk-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: omnichunk
-Version: 2.1.2
+Version: 2.2.0
 Summary: Structure-aware deterministic chunking for code, prose, and markup.
 Project-URL: Homepage, https://github.com/oguzhankir/omnichunk
 Project-URL: Documentation, https://oguzhankir.github.io/omnichunk/
@@ -24,9 +24,10 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Typing :: Typed
 Requires-Python: >=3.10
 Provides-Extra: all
-Requires-Dist: langchain-core>=0.2.0; extra == 'all'
+Requires-Dist: langchain-core<2,>=0.2.11; extra == 'all'
+Requires-Dist: langchain-text-splitters<2,>=0.2.2; extra == 'all'
 Requires-Dist: line-profiler>=4.1.0; extra == 'all'
-Requires-Dist: llama-index-core>=0.10.0; extra == 'all'
+Requires-Dist: llama-index-core<0.15,>=0.10.68.post1; extra == 'all'
 Requires-Dist: numpy>=1.24.0; extra == 'all'
 Requires-Dist: opentelemetry-api>=1.21.0; extra == 'all'
 Requires-Dist: py-spy>=0.3.14; extra == 'all'
@@ -114,7 +115,8 @@ Provides-Extra: docs
 Requires-Dist: mkdocs-material>=9.5.0; extra == 'docs'
 Requires-Dist: mkdocs>=1.6.0; extra == 'docs'
 Requires-Dist: mkdocstrings[python]>=0.25.0; extra == 'docs'
-Requires-Dist: pymdown-extensions>=10.0; extra == 'docs'
+Requires-Dist: pymdown-extensions<12.2,>=10.0; (python_version < '3.11') and extra == 'docs'
+Requires-Dist: pymdown-extensions>=10.0; (python_version >= '3.11') and extra == 'docs'
 Provides-Extra: docx
 Requires-Dist: python-docx>=1.0; extra == 'docx'
 Provides-Extra: formats
@@ -122,18 +124,23 @@ Requires-Dist: pypdf>=3.0; extra == 'formats'
 Requires-Dist: python-docx>=1.0; extra == 'formats'
 Provides-Extra: graph
 Provides-Extra: langchain
-Requires-Dist: langchain-core>=0.2.0; extra == 'langchain'
+Requires-Dist: langchain-core<2,>=0.2.11; extra == 'langchain'
+Requires-Dist: langchain-text-splitters<2,>=0.2.2; extra == 'langchain'
 Provides-Extra: llamaindex
-Requires-Dist: llama-index-core>=0.10.0; extra == 'llamaindex'
+Requires-Dist: llama-index-core<0.15,>=0.10.68.post1; extra == 'llamaindex'
 Provides-Extra: mcp
 Provides-Extra: otel
 Requires-Dist: opentelemetry-api>=1.21.0; extra == 'otel'
 Provides-Extra: pdf
 Requires-Dist: pypdf>=3.0; extra == 'pdf'
+Provides-Extra: pgvector
+Requires-Dist: psycopg[binary]<4,>=3.2.1; extra == 'pgvector'
 Provides-Extra: pinecone
 Provides-Extra: profiling
 Requires-Dist: line-profiler>=4.1.0; extra == 'profiling'
 Requires-Dist: py-spy>=0.3.14; extra == 'profiling'
+Provides-Extra: qdrant
+Requires-Dist: qdrant-client<2,>=1.12; extra == 'qdrant'
 Provides-Extra: rust
 Requires-Dist: maturin>=1.7.0; extra == 'rust'
 Provides-Extra: scipy
@@ -163,19 +170,23 @@ Description-Content-Type: text/markdown
 
 # Omnichunk
 
-Structure-aware chunking for code, prose and mixed documents. Chunks carry source
-ranges and context such as scopes, imports, headings and notebook cells, with
-helpers for indexing and retrieval workflows.
+Structure-aware chunking and index preparation for RAG. Turn code, prose and
+mixed documents into traceable chunks with explicit size budgets, source ranges
+and context such as scopes, imports, headings and notebook cells.
 
-**Development status:** the 2.0 foundation changes and 2.1 code-quality milestone
-are implemented in this checkout for the next **2.1.0** release. Read the
-[migration guide](docs/migrations/v2.md) before upgrading existing indexes.
-The [roadmap](ROADMAP.md) tracks verification, compatible additions through 3.0,
-and the 4.0 vision. This is unreleased work; the maintainer sets the release version
-in `src/omnichunk/_version.py` after validation.
+**Our goal:** make reliable chunking the simplest part of building a retrieval
+system. Preserve useful structure, explain every source span, update indexes
+without stale records, and demonstrate quality on reproducible retrieval tasks.
+The [roadmap](ROADMAP.md) defines the evidence required to get there.
+
+**Status:** the current source version is **2.1.4**, with hardening changes tracked
+in the [changelog](CHANGELOG.md). The package is classified as beta. Its enterprise
+readiness and superiority to other chunkers are goals to validate, not current
+certifications. Read the [migration guide](docs/migrations/v2.md) before upgrading
+existing indexes.
 
 [Documentation](https://oguzhankir.github.io/omnichunk/) ·
-[Architecture](ARCHITECTURE.md) · [Examples](examples/README.md) ·
+[Roadmap](ROADMAP.md) · [Examples](examples/README.md) ·
 [Changelog](CHANGELOG.md) · [Contributing](CONTRIBUTING.md)
 
 ## Installation
@@ -196,7 +207,7 @@ code uses a diagnosed fallback. Structural chunking requires no external service
 optional model/tokenizer integrations may download assets or use your callbacks.
 
 Other extras include `transformers`, `sentence-transformers`, `scipy`, `langchain`,
-`llamaindex`, `otel`, `docs`, `dev` and optional Rust build tooling (`rust`).
+`llamaindex`, `qdrant`, `pgvector`, `otel`, `docs`, `dev` and optional Rust build tooling (`rust`).
 See [installation details](docs/install.md) for the full grouping and limitations.
 
 ## Quick start
@@ -247,8 +258,12 @@ Context that will not fit is omitted by default, or rejected with
   storage, token-budget selection, exact/near deduplication, entity–chunk graphs,
   centrality/community analysis and heuristic/callback-based propositions.
 - **Integration:** synchronous/async/batch APIs, iterators, CLI, JSONL/CSV,
-  LangChain/LlamaIndex document conversion, vendor-shaped vector payloads,
+  native LangChain splitter and LlamaIndex node parser, document conversion,
+  vendor-shaped vector payloads,
   parser/formatter registration and optional OpenTelemetry.
+- **Recoverable indexing:** serializable change plans, a SQLite delivery journal,
+  acknowledged batches, persistent embedding reuse and scoped deletion. Optional
+  Qdrant and pgvector sinks resume pending writes after a process restart.
 
 Use `language_capabilities()` to distinguish detected languages, installed
 grammars, extraction queries and fallback behavior. The
@@ -256,6 +271,13 @@ grammars, extraction queries and fallback behavior. The
 Graph helpers provide entity relationships; they are not a complete GraphRAG
 retriever. PDF/DOCX support extracts text; it does not provide OCR or full layout.
 
+For recoverable index updates, follow the [indexing guide](docs/indexing.md) and run
+`python examples/14_recoverable_indexing.py`. It demonstrates a failed delivery,
+restart/replay, metadata updates without re-embedding and deletion. Delivery is
+at least once: applications own authorization, and sinks must make repeated
+upserts/deletes safe. Acknowledged delivery does not make a multi-batch remote
+update atomically visible to readers.
+
 ## Files, directories and CLI
 
 ```python
@@ -285,6 +307,13 @@ For reconstruction evaluation, `--source` must name the same canonical source
 that produced the chunks; combining unrelated files with one source is invalid.
 Current offline coherence/coverage metrics are heuristics, not retrieval scores.
 
+For source-labeled retrieval evaluation, use the
+[retrieval benchmark](benchmarks/README.md#retrieval-evaluation-and-tuning). It
+compares chunking settings under shared budgets and reports ranking/evidence
+metrics on a versioned, multilingual synthetic corpus. Tune on the development
+split before evaluating held-out documents; the initial offline lexical baseline
+does not establish production retrieval quality.
+
 ## Source ranges and context
 
 Each `Chunk` contains `text`, `contextualized_text`, `byte_range`, `line_range`,
@@ -342,6 +371,18 @@ Versioned JSON round-trips full chunk metadata. The
 [migration guide](docs/migrations/v2.md) includes legacy conversion and separate
 index rebuild/rollback examples.
 
+The local store transaction does not include a remote vector database. Persist
+pending deletions/upserts and retry them in your application; `stream_upsert()`
+yields payloads and does not acknowledge database writes. Framework exports carry
+native document IDs; Weaviate objects use deterministic UUIDs derived from chunk
+IDs. Use `weaviate_object_id(chunk_id)` when deleting those objects. Existing
+indexes created with autogenerated IDs need a rebuild or explicit reconciliation.
+
+`TokenBudgetOptimizer` budgets `contextualized_text`, including derived context.
+Reserve additional space for prompt instructions, citation labels and separators.
+Token counts follow the configured chunking tokenizer; estimated counts remain
+estimates and should not be treated as exact model limits.
+
 Semantic caches isolate provider, model revision and preprocessing. Give opaque
 callbacks an explicit stable fingerprint/revision for durable reuse. Parser and
 formatter plugins can be scoped through `PluginRegistry`.
@@ -354,12 +395,11 @@ standard MCP lifecycle support remains a later optional integration.
 ## Development and evaluation
 
 ```bash
-pip install -e ".[dev,docs]"
+pip install -e ".[dev,docs,langchain,llamaindex]"
 pytest -q
 ruff check src tests
 ruff format --check src tests
-mypy src/omnichunk
-python scripts/check_ai_rules_sync.py
+mypy --python-version 3.12 src/omnichunk
 python scripts/check_benchmarks.py --run-quality
 mkdocs build --strict
 ```
@@ -369,6 +409,9 @@ tests marked `slow`. Coverage measures all Python source with a 90% aggregate
 line-and-branch gate. The [roadmap](ROADMAP.md) separates local verification from
 the release matrix and publication checks.
 
+Match mypy's target to your Python interpreter; CI checks Python 3.10–3.13 with
+the optional dependency versions installable on each interpreter.
+
 [Benchmark instructions](benchmarks/README.md) explain reproducibility and the
 current comparison limitations. No universal speed or retrieval-quality leadership
 claim has been established.

{omnichunk-2.1.2 → omnichunk-2.2.0}/README.md

@@ -10,19 +10,23 @@
 
 # Omnichunk
 
-Structure-aware chunking for code, prose and mixed documents. Chunks carry source
-ranges and context such as scopes, imports, headings and notebook cells, with
-helpers for indexing and retrieval workflows.
+Structure-aware chunking and index preparation for RAG. Turn code, prose and
+mixed documents into traceable chunks with explicit size budgets, source ranges
+and context such as scopes, imports, headings and notebook cells.
 
-**Development status:** the 2.0 foundation changes and 2.1 code-quality milestone
-are implemented in this checkout for the next **2.1.0** release. Read the
-[migration guide](docs/migrations/v2.md) before upgrading existing indexes.
-The [roadmap](ROADMAP.md) tracks verification, compatible additions through 3.0,
-and the 4.0 vision. This is unreleased work; the maintainer sets the release version
-in `src/omnichunk/_version.py` after validation.
+**Our goal:** make reliable chunking the simplest part of building a retrieval
+system. Preserve useful structure, explain every source span, update indexes
+without stale records, and demonstrate quality on reproducible retrieval tasks.
+The [roadmap](ROADMAP.md) defines the evidence required to get there.
+
+**Status:** the current source version is **2.1.4**, with hardening changes tracked
+in the [changelog](CHANGELOG.md). The package is classified as beta. Its enterprise
+readiness and superiority to other chunkers are goals to validate, not current
+certifications. Read the [migration guide](docs/migrations/v2.md) before upgrading
+existing indexes.
 
 [Documentation](https://oguzhankir.github.io/omnichunk/) ·
-[Architecture](ARCHITECTURE.md) · [Examples](examples/README.md) ·
+[Roadmap](ROADMAP.md) · [Examples](examples/README.md) ·
 [Changelog](CHANGELOG.md) · [Contributing](CONTRIBUTING.md)
 
 ## Installation
@@ -43,7 +47,7 @@ code uses a diagnosed fallback. Structural chunking requires no external service
 optional model/tokenizer integrations may download assets or use your callbacks.
 
 Other extras include `transformers`, `sentence-transformers`, `scipy`, `langchain`,
-`llamaindex`, `otel`, `docs`, `dev` and optional Rust build tooling (`rust`).
+`llamaindex`, `qdrant`, `pgvector`, `otel`, `docs`, `dev` and optional Rust build tooling (`rust`).
 See [installation details](docs/install.md) for the full grouping and limitations.
 
 ## Quick start
@@ -94,8 +98,12 @@ Context that will not fit is omitted by default, or rejected with
   storage, token-budget selection, exact/near deduplication, entity–chunk graphs,
   centrality/community analysis and heuristic/callback-based propositions.
 - **Integration:** synchronous/async/batch APIs, iterators, CLI, JSONL/CSV,
-  LangChain/LlamaIndex document conversion, vendor-shaped vector payloads,
+  native LangChain splitter and LlamaIndex node parser, document conversion,
+  vendor-shaped vector payloads,
   parser/formatter registration and optional OpenTelemetry.
+- **Recoverable indexing:** serializable change plans, a SQLite delivery journal,
+  acknowledged batches, persistent embedding reuse and scoped deletion. Optional
+  Qdrant and pgvector sinks resume pending writes after a process restart.
 
 Use `language_capabilities()` to distinguish detected languages, installed
 grammars, extraction queries and fallback behavior. The
@@ -103,6 +111,13 @@ grammars, extraction queries and fallback behavior. The
 Graph helpers provide entity relationships; they are not a complete GraphRAG
 retriever. PDF/DOCX support extracts text; it does not provide OCR or full layout.
 
+For recoverable index updates, follow the [indexing guide](docs/indexing.md) and run
+`python examples/14_recoverable_indexing.py`. It demonstrates a failed delivery,
+restart/replay, metadata updates without re-embedding and deletion. Delivery is
+at least once: applications own authorization, and sinks must make repeated
+upserts/deletes safe. Acknowledged delivery does not make a multi-batch remote
+update atomically visible to readers.
+
 ## Files, directories and CLI
 
 ```python
@@ -132,6 +147,13 @@ For reconstruction evaluation, `--source` must name the same canonical source
 that produced the chunks; combining unrelated files with one source is invalid.
 Current offline coherence/coverage metrics are heuristics, not retrieval scores.
 
+For source-labeled retrieval evaluation, use the
+[retrieval benchmark](benchmarks/README.md#retrieval-evaluation-and-tuning). It
+compares chunking settings under shared budgets and reports ranking/evidence
+metrics on a versioned, multilingual synthetic corpus. Tune on the development
+split before evaluating held-out documents; the initial offline lexical baseline
+does not establish production retrieval quality.
+
 ## Source ranges and context
 
 Each `Chunk` contains `text`, `contextualized_text`, `byte_range`, `line_range`,
@@ -189,6 +211,18 @@ Versioned JSON round-trips full chunk metadata. The
 [migration guide](docs/migrations/v2.md) includes legacy conversion and separate
 index rebuild/rollback examples.
 
+The local store transaction does not include a remote vector database. Persist
+pending deletions/upserts and retry them in your application; `stream_upsert()`
+yields payloads and does not acknowledge database writes. Framework exports carry
+native document IDs; Weaviate objects use deterministic UUIDs derived from chunk
+IDs. Use `weaviate_object_id(chunk_id)` when deleting those objects. Existing
+indexes created with autogenerated IDs need a rebuild or explicit reconciliation.
+
+`TokenBudgetOptimizer` budgets `contextualized_text`, including derived context.
+Reserve additional space for prompt instructions, citation labels and separators.
+Token counts follow the configured chunking tokenizer; estimated counts remain
+estimates and should not be treated as exact model limits.
+
 Semantic caches isolate provider, model revision and preprocessing. Give opaque
 callbacks an explicit stable fingerprint/revision for durable reuse. Parser and
 formatter plugins can be scoped through `PluginRegistry`.
@@ -201,12 +235,11 @@ standard MCP lifecycle support remains a later optional integration.
 ## Development and evaluation
 
 ```bash
-pip install -e ".[dev,docs]"
+pip install -e ".[dev,docs,langchain,llamaindex]"
 pytest -q
 ruff check src tests
 ruff format --check src tests
-mypy src/omnichunk
-python scripts/check_ai_rules_sync.py
+mypy --python-version 3.12 src/omnichunk
 python scripts/check_benchmarks.py --run-quality
 mkdocs build --strict
 ```
@@ -216,6 +249,9 @@ tests marked `slow`. Coverage measures all Python source with a 90% aggregate
 line-and-branch gate. The [roadmap](ROADMAP.md) separates local verification from
 the release matrix and publication checks.
 
+Match mypy's target to your Python interpreter; CI checks Python 3.10–3.13 with
+the optional dependency versions installable on each interpreter.
+
 [Benchmark instructions](benchmarks/README.md) explain reproducibility and the
 current comparison limitations. No universal speed or retrieval-quality leadership
 claim has been established.