folio-resolve 0.1.0__tar.gz

folio_resolve-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,51 @@
+name: Publish to PyPI
+
+# Publishes folio-resolve to PyPI via PyPI Trusted Publishing (OIDC) — no API
+# tokens or secrets are stored in this repo. Fires when a GitHub Release is
+# published, or manually via workflow_dispatch.
+#
+# One-time PyPI setup (owner, before the first release):
+#   PyPI -> project "folio-resolve" -> Publishing -> add a Trusted Publisher:
+#     Owner: damienriehl / Repository: folio-resolve
+#     Workflow: publish.yml / Environment: pypi
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  build:
+    name: Build sdist + wheel
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # required for Trusted Publishing (OIDC)
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

folio_resolve-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.py[cod]
+.venv/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+*.egg-info/
+dist/
+build/
+.folio/

folio_resolve-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Damien Riehl
+
+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.

folio_resolve-0.1.0/PKG-INFO

@@ -0,0 +1,169 @@
+Metadata-Version: 2.4
+Name: folio-resolve
+Version: 0.1.0
+Summary: Shared FOLIO source-text-to-concept resolution engine: scorer, span decomposition, gates, alias blocklist, domain-prior judge, and annotate primitives.
+Project-URL: Homepage, https://github.com/damienriehl/folio-resolve
+Project-URL: Repository, https://github.com/damienriehl/folio-resolve
+Project-URL: Issues, https://github.com/damienriehl/folio-resolve/issues
+Author: Damien Riehl
+License: MIT
+License-File: LICENSE
+Keywords: entity-matching,entity-resolution,folio,legal,nlp,ontology,taxonomy
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Legal Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Text Processing :: Linguistic
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: pydantic<3.0,>=2.7
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: embedding
+Requires-Dist: faiss-cpu<2.0,>=1.8; extra == 'embedding'
+Requires-Dist: numpy<3.0,>=1.26; extra == 'embedding'
+Requires-Dist: sentence-transformers<4.0,>=3.0; extra == 'embedding'
+Provides-Extra: folio
+Requires-Dist: folio-python[search]>=0.1.5; extra == 'folio'
+Provides-Extra: spacy
+Requires-Dist: spacy<4.0,>=3.7; extra == 'spacy'
+Description-Content-Type: text/markdown
+
+# folio-resolve
+
+**The shared FOLIO source-text→concept matching engine.** One pinned, MIT-licensed Python library
+that maps arbitrary source text (book headings, deposition transcripts, intake narratives, task
+titles) to concepts in [FOLIO](https://folio.openlegalstandard.org) — the open legal ontology of
+18,000+ concepts.
+
+> This is a **lift-and-improve** extraction. The matching intelligence already existed across
+> `folio-mapper`, `folio-enrich`, and `folio-insights` — but it had **diverged** (enrich literally
+> forked mapper's scorer) and was informally shared through a fragile `sys.path` hack. `folio-resolve`
+> is the single source of truth those repos now pin, plus the capabilities the recorded failures demanded.
+
+---
+
+## Why this exists
+
+Three repos independently built the same engine and drifted apart:
+
+- **folio-mapper** wrote the canonical, word-order-invariant scorer + a 4-stage pipeline + a FAISS embedding index.
+- **folio-enrich** *copied* mapper's scorer (its `search.py` says "ported from folio-mapper" in the code) and added an Aho-Corasick entity ruler, a reconciler, a domain-prior judge, and a feature-rich annotate/feedback UI.
+- **folio-insights** `sys.path`-imports **both** siblings at runtime — documented as fragile.
+
+A book-annotation review (Ch02) then surfaced failures that no amount of local patching would fix:
+place-names over-scoring (Slovenia → 99 units), homonyms (Action ≠ Auction), conjoined compound
+headings that match nothing, metadata tagged as substance, and pure-semantic maps with no shared
+label token (Presumptions → Litigation Burdens of Proof). Those became this library's new capabilities.
+
+## What it does
+
+| Capability | Module | Solves |
+|---|---|---|
+| Word-order-invariant relevance scoring | `scoring` | "arbitration rules" = "rules of arbitration" |
+| Multi-strategy label search + legal expansions | `scoring`, `pipeline` | recall on paraphrases |
+| Pure-Python Aho-Corasick entity ruler | `entity_ruler`, `matching` | trusted exact-label spans, no spaCy/C deps |
+| Candidate reconciliation (ruler + LLM + semantic) | `reconciler` | one clean candidate set with provenance |
+| **Span decomposition** (conjunction split + shared head) | `decompose` | "Findings of Fact **and** Conclusions of Law" → both siblings |
+| **Place-name / short-label gates** | `gates` | kills Slovenia→99 and Presumptions→Northern Mariana Islands@90 |
+| **Alias/homonym blocklist** | `blocklist` | deterministic Action ≠ Auction guard |
+| **Metadata/front-matter exclusion** | `sources` | never tag the copyright page |
+| **Multi-tag domain prior** (auto-suggest + validate/add) | `domain_prior` | Defenses → *Litigation* Defenses; corpus carries many subjects |
+| **Score calibration** (weak-band recalibration) | `calibration` | verdict-labeled score→P(correct) fit |
+| LLM judge interface + domain-prior prompts | `judge` | context-aware disambiguation, verdict enforcement |
+| **Annotate primitives** (confidence, per-tag verdicts, notes, reject/restore, insights) | `annotate` | the self-improving feedback loop, as a library |
+| 4-stage pipeline: filter → expand → rank → judge | `pipeline` | the build-once-use-many entry point |
+
+## Personas
+
+- **Book-extraction pipelines** (`folio-insights`, `books`) — offline, CLI-first tagging of treatise text.
+- **Intake / matter classifiers** (`alea-intake`, `mootloop`) — narrative → FOLIO concepts for routing.
+- **Interactive mappers** (`folio-mapper`, `clio-skills`) — a UI over the library's ranked candidates.
+- **The FOLIO ontology team** — a reference implementation of "good" source-text→concept matching.
+
+## Use cases
+
+- Tag a chapter of a litigation treatise with FOLIO concepts, with a litigation domain prior so
+  "Defenses" resolves to *Litigation Defenses*, not the generic sense.
+- Resolve a compound heading like *"Proposed Findings of Fact and Conclusions of Law"* to the two
+  sibling concepts it actually names.
+- Suggest the subject tags for a corpus ("Personal Injury Depositions" → *Personal Injury* +
+  *Deposition*) and let a human validate/add via a FOLIO taxonomy-tree picker.
+- Feed a reviewer's `wrong` verdict on a homonym straight into the alias blocklist so the mistake
+  never recurs — the self-improving loop.
+
+## Install
+
+```bash
+uv add folio-resolve                 # core (pure-Python, only pydantic)
+uv add "folio-resolve[folio]"        # + folio-python live ontology adapter
+uv add "folio-resolve[embedding]"    # + sentence-transformers / faiss for the semantic path
+uv add "folio-resolve[spacy]"        # + optional spaCy ruler adapter
+```
+
+The **core is pure-Python** — the scorer, decomposition, gates, blocklist, domain-prior, reconciler,
+calibration, and annotate primitives depend on nothing heavier than `pydantic`. FAISS,
+sentence-transformers, spaCy, and folio-python live behind `Protocol` seams with working pure-Python
+defaults, so the whole test suite runs with no model downloads and no network.
+
+## Bring Your Own Key (BYOK)
+
+`folio-resolve` is **key-agnostic** — it never reads an env var, instantiates a provider SDK, or makes
+a network call on its own. The **zero-key deterministic core** (ruler, scoring, decomposition, gates,
+blocklist, metadata exclusion, calibration, annotate) runs fully offline and free. Three optional stages
+accept a provider through a `typing.Protocol` seam you fill with an object you construct:
+
+| Stage | Protocol | Buys you | Absent → |
+|---|---|---|---|
+| **Judge** | `Judge.complete(system, user) -> str` | context-aware disambiguation + verdict enforcement | items pass through **unjudged** |
+| **Embeddings** | `EmbeddingProvider` (`embed`/`embed_batch`/`dimension`) | semantic recall for no-shared-token maps | local `all-MiniLM-L6-v2` default (no key), or skipped |
+| **Domain-prior suggestions** | `DomainPriorSuggester(ontology)` | auto-suggest corpus subject tags | supply tags manually |
+
+You own the key, the vendor (OpenAI / Gemini / Anthropic / local), and the spend. The library ships the
+judge **prompt builders** and **deterministic verdict enforcement**; you supply only the raw model call.
+Graceful degradation is the default — no key means deterministic-only output with items marked
+`unjudged`, never a crash. Reference cost: **≈ $0.12 / chapter on `gemini-2.5-flash-lite`** (~1,875
+calls, ~652K tokens, 464 units). Full guide, env-var conventions, and a minimal wiring example per
+vendor: **[docs/BYOK.md](docs/BYOK.md)**.
+
+## Quick start
+
+```python
+from folio_resolve import InMemoryOntology, Concept, MatchPipeline, DomainPrior
+
+ontology = InMemoryOntology([
+    Concept(iri="R-defenses", label="Litigation Defenses", branch="Objectives"),
+    Concept(iri="R-arb", label="Arbitration Rules", branch="Service"),
+])
+pipe = MatchPipeline(ontology=ontology)
+
+# word-order-invariant
+pipe.match("rules of arbitration")        # -> Arbitration Rules
+
+# domain prior threads a subject into the (optional) judge
+prior = DomainPrior.from_manifest_subjects("treatise", [("R-lit", "Litigation")])
+pipe.match("Defenses", domain_prior=prior)
+```
+
+## Development
+
+```bash
+uv sync --extra dev
+uv run pytest          # full suite, pure-Python, no network
+uv run mypy src        # strict
+uv run ruff check
+```
+
+## License & attribution
+
+MIT — see [LICENSE](LICENSE). Every extracted component and dependency is logged in
+[THIRD-PARTY.md](THIRD-PARTY.md). The migration schedule for consumer repos is in
+[docs/migration/SCHEDULE.md](docs/migration/SCHEDULE.md).

folio_resolve-0.1.0/README.md

@@ -0,0 +1,130 @@
+# folio-resolve
+
+**The shared FOLIO source-text→concept matching engine.** One pinned, MIT-licensed Python library
+that maps arbitrary source text (book headings, deposition transcripts, intake narratives, task
+titles) to concepts in [FOLIO](https://folio.openlegalstandard.org) — the open legal ontology of
+18,000+ concepts.
+
+> This is a **lift-and-improve** extraction. The matching intelligence already existed across
+> `folio-mapper`, `folio-enrich`, and `folio-insights` — but it had **diverged** (enrich literally
+> forked mapper's scorer) and was informally shared through a fragile `sys.path` hack. `folio-resolve`
+> is the single source of truth those repos now pin, plus the capabilities the recorded failures demanded.
+
+---
+
+## Why this exists
+
+Three repos independently built the same engine and drifted apart:
+
+- **folio-mapper** wrote the canonical, word-order-invariant scorer + a 4-stage pipeline + a FAISS embedding index.
+- **folio-enrich** *copied* mapper's scorer (its `search.py` says "ported from folio-mapper" in the code) and added an Aho-Corasick entity ruler, a reconciler, a domain-prior judge, and a feature-rich annotate/feedback UI.
+- **folio-insights** `sys.path`-imports **both** siblings at runtime — documented as fragile.
+
+A book-annotation review (Ch02) then surfaced failures that no amount of local patching would fix:
+place-names over-scoring (Slovenia → 99 units), homonyms (Action ≠ Auction), conjoined compound
+headings that match nothing, metadata tagged as substance, and pure-semantic maps with no shared
+label token (Presumptions → Litigation Burdens of Proof). Those became this library's new capabilities.
+
+## What it does
+
+| Capability | Module | Solves |
+|---|---|---|
+| Word-order-invariant relevance scoring | `scoring` | "arbitration rules" = "rules of arbitration" |
+| Multi-strategy label search + legal expansions | `scoring`, `pipeline` | recall on paraphrases |
+| Pure-Python Aho-Corasick entity ruler | `entity_ruler`, `matching` | trusted exact-label spans, no spaCy/C deps |
+| Candidate reconciliation (ruler + LLM + semantic) | `reconciler` | one clean candidate set with provenance |
+| **Span decomposition** (conjunction split + shared head) | `decompose` | "Findings of Fact **and** Conclusions of Law" → both siblings |
+| **Place-name / short-label gates** | `gates` | kills Slovenia→99 and Presumptions→Northern Mariana Islands@90 |
+| **Alias/homonym blocklist** | `blocklist` | deterministic Action ≠ Auction guard |
+| **Metadata/front-matter exclusion** | `sources` | never tag the copyright page |
+| **Multi-tag domain prior** (auto-suggest + validate/add) | `domain_prior` | Defenses → *Litigation* Defenses; corpus carries many subjects |
+| **Score calibration** (weak-band recalibration) | `calibration` | verdict-labeled score→P(correct) fit |
+| LLM judge interface + domain-prior prompts | `judge` | context-aware disambiguation, verdict enforcement |
+| **Annotate primitives** (confidence, per-tag verdicts, notes, reject/restore, insights) | `annotate` | the self-improving feedback loop, as a library |
+| 4-stage pipeline: filter → expand → rank → judge | `pipeline` | the build-once-use-many entry point |
+
+## Personas
+
+- **Book-extraction pipelines** (`folio-insights`, `books`) — offline, CLI-first tagging of treatise text.
+- **Intake / matter classifiers** (`alea-intake`, `mootloop`) — narrative → FOLIO concepts for routing.
+- **Interactive mappers** (`folio-mapper`, `clio-skills`) — a UI over the library's ranked candidates.
+- **The FOLIO ontology team** — a reference implementation of "good" source-text→concept matching.
+
+## Use cases
+
+- Tag a chapter of a litigation treatise with FOLIO concepts, with a litigation domain prior so
+  "Defenses" resolves to *Litigation Defenses*, not the generic sense.
+- Resolve a compound heading like *"Proposed Findings of Fact and Conclusions of Law"* to the two
+  sibling concepts it actually names.
+- Suggest the subject tags for a corpus ("Personal Injury Depositions" → *Personal Injury* +
+  *Deposition*) and let a human validate/add via a FOLIO taxonomy-tree picker.
+- Feed a reviewer's `wrong` verdict on a homonym straight into the alias blocklist so the mistake
+  never recurs — the self-improving loop.
+
+## Install
+
+```bash
+uv add folio-resolve                 # core (pure-Python, only pydantic)
+uv add "folio-resolve[folio]"        # + folio-python live ontology adapter
+uv add "folio-resolve[embedding]"    # + sentence-transformers / faiss for the semantic path
+uv add "folio-resolve[spacy]"        # + optional spaCy ruler adapter
+```
+
+The **core is pure-Python** — the scorer, decomposition, gates, blocklist, domain-prior, reconciler,
+calibration, and annotate primitives depend on nothing heavier than `pydantic`. FAISS,
+sentence-transformers, spaCy, and folio-python live behind `Protocol` seams with working pure-Python
+defaults, so the whole test suite runs with no model downloads and no network.
+
+## Bring Your Own Key (BYOK)
+
+`folio-resolve` is **key-agnostic** — it never reads an env var, instantiates a provider SDK, or makes
+a network call on its own. The **zero-key deterministic core** (ruler, scoring, decomposition, gates,
+blocklist, metadata exclusion, calibration, annotate) runs fully offline and free. Three optional stages
+accept a provider through a `typing.Protocol` seam you fill with an object you construct:
+
+| Stage | Protocol | Buys you | Absent → |
+|---|---|---|---|
+| **Judge** | `Judge.complete(system, user) -> str` | context-aware disambiguation + verdict enforcement | items pass through **unjudged** |
+| **Embeddings** | `EmbeddingProvider` (`embed`/`embed_batch`/`dimension`) | semantic recall for no-shared-token maps | local `all-MiniLM-L6-v2` default (no key), or skipped |
+| **Domain-prior suggestions** | `DomainPriorSuggester(ontology)` | auto-suggest corpus subject tags | supply tags manually |
+
+You own the key, the vendor (OpenAI / Gemini / Anthropic / local), and the spend. The library ships the
+judge **prompt builders** and **deterministic verdict enforcement**; you supply only the raw model call.
+Graceful degradation is the default — no key means deterministic-only output with items marked
+`unjudged`, never a crash. Reference cost: **≈ $0.12 / chapter on `gemini-2.5-flash-lite`** (~1,875
+calls, ~652K tokens, 464 units). Full guide, env-var conventions, and a minimal wiring example per
+vendor: **[docs/BYOK.md](docs/BYOK.md)**.
+
+## Quick start
+
+```python
+from folio_resolve import InMemoryOntology, Concept, MatchPipeline, DomainPrior
+
+ontology = InMemoryOntology([
+    Concept(iri="R-defenses", label="Litigation Defenses", branch="Objectives"),
+    Concept(iri="R-arb", label="Arbitration Rules", branch="Service"),
+])
+pipe = MatchPipeline(ontology=ontology)
+
+# word-order-invariant
+pipe.match("rules of arbitration")        # -> Arbitration Rules
+
+# domain prior threads a subject into the (optional) judge
+prior = DomainPrior.from_manifest_subjects("treatise", [("R-lit", "Litigation")])
+pipe.match("Defenses", domain_prior=prior)
+```
+
+## Development
+
+```bash
+uv sync --extra dev
+uv run pytest          # full suite, pure-Python, no network
+uv run mypy src        # strict
+uv run ruff check
+```
+
+## License & attribution
+
+MIT — see [LICENSE](LICENSE). Every extracted component and dependency is logged in
+[THIRD-PARTY.md](THIRD-PARTY.md). The migration schedule for consumer repos is in
+[docs/migration/SCHEDULE.md](docs/migration/SCHEDULE.md).

folio_resolve-0.1.0/THIRD-PARTY.md

@@ -0,0 +1,58 @@
+# Third-Party Components & Attribution
+
+`folio-resolve` is MIT-licensed. This file logs (1) the internal components lifted into this
+package and (2) every third-party dependency with its license, per house policy.
+
+## Components extracted from sibling repos (lift-and-improve)
+
+All three source repos are Damien Riehl's own MIT-licensed projects; this is a consolidation, not
+a third-party incorporation. Logged here for provenance.
+
+| Component | Source repo · file | Reused as |
+|---|---|---|
+| Word-order-invariant scorer (`_compute_relevance_score`, `_word_overlap`, `_tokenize`, `_content_words`, `LEGAL_TERM_EXPANSIONS`, `SEARCH_STOPWORDS`, `BRANCH_SIGNAL_WORDS`) | folio-mapper · `backend/app/services/folio_service.py` | `scoring.py` |
+| Multi-strategy search term generation | folio-mapper · `_generate_search_terms`; folio-enrich · `folio/search.py` (itself "ported from folio-mapper") | `scoring.generate_search_terms`, `pipeline.py` |
+| 4-stage pipeline (filter → expand → rank → judge) | folio-mapper · `backend/app/services/pipeline/` | `pipeline.py` |
+| LLM judge verdict enforcement + 90+/70-89/50-69 calibration prompt | folio-mapper · `pipeline/stage3_judge.py`, `pipeline/prompts.py` | `judge.py` |
+| FAISS embedding index (IndexFlatIP, `all-MiniLM-L6-v2`, disk cache) | folio-mapper · `embedding/folio_index.py` | `embedding.py` (Protocol + optional adapter) |
+| Aho-Corasick matcher (containment-aware overlap, word boundaries) | folio-enrich · `matching/aho_corasick.py` | `matching/aho_corasick.py` (reimplemented pure-Python; C dep dropped) |
+| Entity ruler + pattern builder (label_type-encoded IDs) | folio-enrich · `entity_ruler/{ruler,pattern_builder}.py` | `entity_ruler.py` |
+| Reconciler (diminishing boost, ruler-only gate, embedding triage) | folio-enrich · `reconciliation/reconciler.py` | `reconciler.py` |
+| Domain-prior judge (contextual rerank + branch judge threading document_type) | folio-enrich · `llm/prompts/contextual_rerank.py`, `concept/branch_judge.py` | `judge.py`, `domain_prior.py` |
+| Ontology-neutral spec layer (FOLIO_SPEC + CANON_SPEC, lemma denylist) | folio-enrich · `ontology/spec.py` | `spec.py` |
+| Annotate models (Span, StageEvent, FeedbackItem, Annotation, FeedbackEntry, InsightsSummary) | folio-enrich · `models/annotation.py`, `models/feedback.py` | `annotate/models.py` |
+| Feedback store + insights aggregation | folio-enrich · `storage/feedback_store.py` | `annotate/feedback_store.py` |
+| Reject/restore/promote/cascade/bulk-reject lifecycle | folio-enrich · `api/routes/enrich.py` | `annotate/lifecycle.py` |
+| Boundary-sweep span layout | folio-enrich · `frontend/index.html:renderAnnotatedText` | `annotate/render.py` (ported to Python) |
+
+New in this package (no prior implementation): `decompose.py`, `gates.py`, `blocklist.py`,
+`sources.py`, the multi-tag `domain_prior.py`, `calibration.py`, and the per-tag `TagVerdict`.
+
+## Runtime dependencies
+
+| Package | License | Used for | Tier |
+|---|---|---|---|
+| [pydantic](https://github.com/pydantic/pydantic) | MIT | annotate data models | core (required) |
+| [folio-python](https://pypi.org/project/folio-python/) | MIT | live FOLIO ontology + `search_by_label` | optional (`folio` extra) |
+| [faiss-cpu](https://github.com/facebookresearch/faiss) | MIT | ANN index for the semantic path | optional (`embedding` extra) |
+| [sentence-transformers](https://github.com/UKPLab/sentence-transformers) | Apache-2.0 | `all-MiniLM-L6-v2` local embeddings | optional (`embedding` extra) |
+| [numpy](https://numpy.org) | BSD-3-Clause | vector math for embeddings | optional (`embedding` extra) |
+| [spaCy](https://github.com/explosion/spaCy) | MIT | optional EntityRuler adapter | optional (`spacy` extra) |
+
+The **pure-Python Aho-Corasick** implementation in `matching/aho_corasick.py` deliberately removes
+the `pyahocorasick` (BSD-3) C-extension dependency that folio-enrich required.
+
+## Dev dependencies
+
+| Package | License |
+|---|---|
+| [pytest](https://github.com/pytest-dev/pytest) | MIT |
+| [pytest-asyncio](https://github.com/pytest-dev/pytest-asyncio) | Apache-2.0 |
+| [mypy](https://github.com/python/mypy) | MIT |
+| [ruff](https://github.com/astral-sh/ruff) | MIT |
+
+## Ontology data
+
+FOLIO (Federated Open Legal Information Ontology) — CC-BY-4.0, © SALI Alliance. This package does
+not vendor FOLIO; it is fetched at runtime via `folio-python`. Consumers displaying FOLIO concepts
+should carry the CC-BY attribution.