rankweave 0.1.0__tar.gz

rankweave-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,26 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: python -m pip install --upgrade pip
+      - run: pip install -e ".[dev]"
+      - run: python -m ruff check .
+      - run: python -m pytest -q

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

@@ -0,0 +1,26 @@
+name: publish
+
+on:
+  push:
+    branches: ["publish-release"]
+  workflow_dispatch: {}
+
+permissions:
+  contents: read
+
+jobs:
+  pypi:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install --upgrade build twine
+      - run: python -m build
+      - run: twine check dist/*
+      - name: Upload to PyPI
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PIPY_TOKEN }}
+        run: twine upload --non-interactive --disable-progress-bar dist/*

rankweave-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.pytest_cache/
+.ruff_cache/
+.venv/
+venv/
+.coverage
+htmlcov/

rankweave-0.1.0/AGENTS.md

@@ -0,0 +1,45 @@
+# AGENTS.md — rankweave
+
+Operating guide for automated agents working in this repo.
+
+## What this is
+
+`rankweave` is a **pure-Python, stdlib-only** library for
+language-agnostic hybrid-retrieval score fusion, extracted unchanged
+in behavior from
+[ContextualWisdomLab/naruon](https://github.com/ContextualWisdomLab/naruon)
+Context Search under the lab's ONE SOURCE MULTI USE convention
+(standalone product *and* submodule-importable).
+
+## Hard rules
+
+- **No dependencies.** The library imports only the Python standard
+  library. Do not add a runtime dependency; if you think you need one,
+  the feature probably belongs in the consumer, not here.
+- **Store-agnostic.** rankweave never talks to a database, an
+  embedding provider, or a search index. It fuses scores and normalizes
+  query text. Keep SQL, HTTP, and ORM concerns out.
+- **Behavior parity with naruon.** This is an extraction, not a fork.
+  A behavior change here must be mirrored in naruon's
+  `services/hybrid_retrieval` (and vice versa) until naruon consumes
+  this package directly. Prefer additive, backward-compatible changes.
+- **Permissive license only** (Apache-2.0). Any added code or asset must
+  be compatible.
+- **Research-grounded defaults.** Numeric defaults (alpha=0.7, eta=60,
+  the theoretical bounds) trace to the papers in `docs/research/`.
+  Changing a default requires citing the evidence.
+
+## Develop
+
+```bash
+pip install -e ".[dev]"
+python -m pytest -q          # no external services required
+python -m ruff check .
+```
+
+## Layout
+
+- `src/rankweave/score_fusion.py` — TM2C2 + RRF fusion primitives.
+- `src/rankweave/query_normalization.py` — NFC query normalization.
+- `tests/` — behavior tests (hand-computed expected values).
+- `docs/research/` — paper PDFs + citation manifest.

rankweave-0.1.0/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to rankweave are documented here. The format
+follows [Keep a Changelog](https://keepachangelog.com/), and the
+project adheres to [Semantic Versioning](https://semver.org/).
+
+## [0.1.0] — 2026-07-11
+
+Initial extraction from
+[ContextualWisdomLab/naruon](https://github.com/ContextualWisdomLab/naruon)
+Context Search, unchanged in behavior (ONE SOURCE MULTI USE).
+
+### Added
+- `fuse_channel_scores` — fuse one candidate's lexical + dense channel
+  evidence into a single bounded score under the selected strategy.
+- `FusionSettings` — immutable strategy + parameters (`convex_combination`
+  default with `semantic_weight_alpha=0.7`; `reciprocal_rank_fusion`
+  with `rank_constant_eta=60`).
+- `convex_combination_score`, `reciprocal_rank_fusion_score`,
+  `theoretical_min_max_normalize` — the underlying fusion primitives.
+- `normalize_search_text` — NFC compose + whitespace-collapse +
+  length-cap for the query side of a language-agnostic lexical channel.
+- `WORD_SIMILARITY_THEORETICAL_BOUNDS`, `COSINE_DISTANCE_THEORETICAL_BOUNDS`.
+- 27 unit tests; no dependencies (stdlib only); typed (`py.typed`).
+- Research grounding + paper manifest under `docs/research/`.

rankweave-0.1.0/LICENSE

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

rankweave-0.1.0/PKG-INFO

@@ -0,0 +1,128 @@
+Metadata-Version: 2.4
+Name: rankweave
+Version: 0.1.0
+Summary: Language-agnostic hybrid-retrieval score fusion (TM2C2 + RRF) and Unicode query normalization — pure-Python, store-agnostic.
+Project-URL: Homepage, https://github.com/ContextualWisdomLab/rankweave
+Project-URL: Source, https://github.com/ContextualWisdomLab/rankweave
+Project-URL: Issues, https://github.com/ContextualWisdomLab/rankweave/issues
+Author: Contextual Wisdom Lab
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: dense-retrieval,hybrid-search,information-retrieval,lexical-retrieval,pg_trgm,pgvector,rank-fusion,reciprocal-rank-fusion,rrf
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Topic :: Text Processing :: Indexing
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# rankweave
+
+**Language-agnostic hybrid-retrieval score fusion — pure-Python, store-agnostic.**
+
+`rankweave` decides *how to combine* the scores from a lexical channel
+(character-trigram / BM25 / learned-sparse) and a semantic channel
+(dense embeddings) into one ranking. It ships two research-grounded
+fusion strategies and the query-side Unicode normalization that makes
+character-level lexical matching language-agnostic. It has **no
+dependencies** (stdlib only) and **no opinion about your store** — bring
+your own channels; rankweave fuses their scores.
+
+It is extracted, unchanged in behavior, from the Context Search engine of
+[naruon](https://github.com/ContextualWisdomLab/naruon), following the
+lab's ONE SOURCE MULTI USE convention: standalone product *and*
+submodule-importable.
+
+## Why
+
+A convex combination of **theoretically** min-max normalized scores
+(TM2C2) beats Reciprocal Rank Fusion in- and out-of-domain, is robust
+for `alpha ∈ [0.6, 0.8]` with no training data, and — unlike rank
+fusion — preserves the score distribution (Bruch, Gai & Ingber 2023).
+RRF remains available for channels that expose only ranks. See
+[`docs/research/`](docs/research/) for the grounding.
+
+## Install
+
+```bash
+pip install rankweave
+```
+
+## Quickstart
+
+```python
+from rankweave import FusionSettings, fuse_channel_scores, normalize_search_text
+
+# 1) Normalize the query the same way you normalize indexed documents
+#    (NFC compose; do accent-folding + lowercasing on the store side too).
+query = normalize_search_text("  Trần Hưng Đạo 회의  ")   # -> "Trần Hưng Đạo 회의"
+
+# 2) Run your own lexical + dense channels, then fuse per candidate.
+settings = FusionSettings()                 # TM2C2, semantic weight alpha = 0.7
+score = fuse_channel_scores(
+    word_similarity_score=0.62,             # lexical channel score in [0, 1]
+    cosine_distance=0.30,                   # dense channel distance in [0, 2]
+    channel_ranks={"lexical": 1, "dense": 1},
+    settings=settings,
+)                                            # -> bounded [0, 1] fused score
+```
+
+A channel that did not return a candidate contributes its theoretical
+minimum (absent evidence is the infimum, not an imputed value). Pass
+`FusionSettings(strategy_name="reciprocal_rank_fusion")` to fuse by rank
+instead — then only `channel_ranks` matters.
+
+## API
+
+| Symbol | Purpose |
+|---|---|
+| `FusionSettings` | Immutable strategy + parameters (`strategy_name`, `semantic_weight_alpha`, `rank_constant_eta`). |
+| `fuse_channel_scores(...)` | Fuse one candidate's channel evidence into a single score under the chosen strategy. |
+| `convex_combination_score(...)` | TM2C2 over already-normalized `[0, 1]` scores. |
+| `reciprocal_rank_fusion_score(ranks, eta=60)` | RRF over 1-based per-channel ranks. |
+| `theoretical_min_max_normalize(score, bounds)` | Scale a score to `[0, 1]` using a scoring function's theoretical bounds. |
+| `normalize_search_text(text)` | NFC-compose + whitespace-collapse + length-cap a query. |
+| `WORD_SIMILARITY_THEORETICAL_BOUNDS`, `COSINE_DISTANCE_THEORETICAL_BOUNDS` | `(lower, upper)` tuples for the common lexical/dense pairing. |
+
+## The normalization contract
+
+Character-trigram lexical retrieval is language-agnostic only if query
+and documents fold **identically**. `normalize_search_text` owns the
+query side (NFC). Do accent-folding + lowercasing on the **store** side,
+in one place, and call it from both — e.g. a PostgreSQL `IMMUTABLE`
+wrapper `lower(unaccent(normalize(text, NFC)))` used in a `pg_trgm` GiST
+expression index. rankweave stays out of your store so the two sides
+cannot silently diverge.
+
+## Research grounding
+
+- **Bruch, Gai & Ingber (2023).** *An Analysis of Fusion Functions for
+  Hybrid Retrieval.* ACM TOIS 42(1). arXiv:2210.11934. — TM2C2 > RRF;
+  theoretical-normalization stability; the fusion desiderata
+  (monotonicity, homogeneity, boundedness, Lipschitz continuity,
+  sample efficiency) this library's defaults satisfy.
+- **Cormack, Clarke & Büttcher (2009).** *Reciprocal Rank Fusion
+  outperforms Condorcet and individual Rank Learning Methods.* SIGIR
+  2009. — RRF definition, η = 60.
+- **UAX #15**, Unicode Normalization Forms — NFC composition.
+
+PDFs and a citation manifest live in [`docs/research/`](docs/research/).
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+python -m pytest -q          # 27 tests, no external services
+python -m ruff check .
+```
+
+## License
+
+Apache-2.0 — see [LICENSE](LICENSE).

rankweave-0.1.0/README.md

@@ -0,0 +1,103 @@
+# rankweave
+
+**Language-agnostic hybrid-retrieval score fusion — pure-Python, store-agnostic.**
+
+`rankweave` decides *how to combine* the scores from a lexical channel
+(character-trigram / BM25 / learned-sparse) and a semantic channel
+(dense embeddings) into one ranking. It ships two research-grounded
+fusion strategies and the query-side Unicode normalization that makes
+character-level lexical matching language-agnostic. It has **no
+dependencies** (stdlib only) and **no opinion about your store** — bring
+your own channels; rankweave fuses their scores.
+
+It is extracted, unchanged in behavior, from the Context Search engine of
+[naruon](https://github.com/ContextualWisdomLab/naruon), following the
+lab's ONE SOURCE MULTI USE convention: standalone product *and*
+submodule-importable.
+
+## Why
+
+A convex combination of **theoretically** min-max normalized scores
+(TM2C2) beats Reciprocal Rank Fusion in- and out-of-domain, is robust
+for `alpha ∈ [0.6, 0.8]` with no training data, and — unlike rank
+fusion — preserves the score distribution (Bruch, Gai & Ingber 2023).
+RRF remains available for channels that expose only ranks. See
+[`docs/research/`](docs/research/) for the grounding.
+
+## Install
+
+```bash
+pip install rankweave
+```
+
+## Quickstart
+
+```python
+from rankweave import FusionSettings, fuse_channel_scores, normalize_search_text
+
+# 1) Normalize the query the same way you normalize indexed documents
+#    (NFC compose; do accent-folding + lowercasing on the store side too).
+query = normalize_search_text("  Trần Hưng Đạo 회의  ")   # -> "Trần Hưng Đạo 회의"
+
+# 2) Run your own lexical + dense channels, then fuse per candidate.
+settings = FusionSettings()                 # TM2C2, semantic weight alpha = 0.7
+score = fuse_channel_scores(
+    word_similarity_score=0.62,             # lexical channel score in [0, 1]
+    cosine_distance=0.30,                   # dense channel distance in [0, 2]
+    channel_ranks={"lexical": 1, "dense": 1},
+    settings=settings,
+)                                            # -> bounded [0, 1] fused score
+```
+
+A channel that did not return a candidate contributes its theoretical
+minimum (absent evidence is the infimum, not an imputed value). Pass
+`FusionSettings(strategy_name="reciprocal_rank_fusion")` to fuse by rank
+instead — then only `channel_ranks` matters.
+
+## API
+
+| Symbol | Purpose |
+|---|---|
+| `FusionSettings` | Immutable strategy + parameters (`strategy_name`, `semantic_weight_alpha`, `rank_constant_eta`). |
+| `fuse_channel_scores(...)` | Fuse one candidate's channel evidence into a single score under the chosen strategy. |
+| `convex_combination_score(...)` | TM2C2 over already-normalized `[0, 1]` scores. |
+| `reciprocal_rank_fusion_score(ranks, eta=60)` | RRF over 1-based per-channel ranks. |
+| `theoretical_min_max_normalize(score, bounds)` | Scale a score to `[0, 1]` using a scoring function's theoretical bounds. |
+| `normalize_search_text(text)` | NFC-compose + whitespace-collapse + length-cap a query. |
+| `WORD_SIMILARITY_THEORETICAL_BOUNDS`, `COSINE_DISTANCE_THEORETICAL_BOUNDS` | `(lower, upper)` tuples for the common lexical/dense pairing. |
+
+## The normalization contract
+
+Character-trigram lexical retrieval is language-agnostic only if query
+and documents fold **identically**. `normalize_search_text` owns the
+query side (NFC). Do accent-folding + lowercasing on the **store** side,
+in one place, and call it from both — e.g. a PostgreSQL `IMMUTABLE`
+wrapper `lower(unaccent(normalize(text, NFC)))` used in a `pg_trgm` GiST
+expression index. rankweave stays out of your store so the two sides
+cannot silently diverge.
+
+## Research grounding
+
+- **Bruch, Gai & Ingber (2023).** *An Analysis of Fusion Functions for
+  Hybrid Retrieval.* ACM TOIS 42(1). arXiv:2210.11934. — TM2C2 > RRF;
+  theoretical-normalization stability; the fusion desiderata
+  (monotonicity, homogeneity, boundedness, Lipschitz continuity,
+  sample efficiency) this library's defaults satisfy.
+- **Cormack, Clarke & Büttcher (2009).** *Reciprocal Rank Fusion
+  outperforms Condorcet and individual Rank Learning Methods.* SIGIR
+  2009. — RRF definition, η = 60.
+- **UAX #15**, Unicode Normalization Forms — NFC composition.
+
+PDFs and a citation manifest live in [`docs/research/`](docs/research/).
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+python -m pytest -q          # 27 tests, no external services
+python -m ruff check .
+```
+
+## License
+
+Apache-2.0 — see [LICENSE](LICENSE).

rankweave-0.1.0/docs/research/README.md

@@ -0,0 +1,41 @@
+# Research grounding — rankweave
+
+rankweave's defaults are not arbitrary; each is the published,
+empirically-supported choice. This directory preserves the source
+material so the grounding travels with the code.
+
+## Papers
+
+| File | Citation | License / redistribution |
+|---|---|---|
+| `pdfs/bruch-gai-ingber-2023-analysis-fusion-functions-hybrid-retrieval.pdf` | Bruch, S., Gai, S., & Ingber, A. (2023). *An Analysis of Fusion Functions for Hybrid Retrieval.* ACM Transactions on Information Systems 42(1). arXiv:2210.11934. | cite-only pending license confirmation |
+| `pdfs/cormack-clarke-buettcher-2009-reciprocal-rank-fusion.pdf` | Cormack, G. V., Clarke, C. L. A., & Büttcher, S. (2009). *Reciprocal Rank Fusion outperforms Condorcet and individual Rank Learning Methods.* SIGIR 2009. | cite-only pending license confirmation |
+
+Standards: **UAX #15 — Unicode Normalization Forms** (Unicode
+Consortium), the basis for `normalize_search_text`'s NFC step.
+
+## What each grounds
+
+- **Bruch, Gai & Ingber 2023** → the **default strategy**. TM2C2 (a
+  convex combination of *theoretically* min-max normalized scores)
+  outperforms Reciprocal Rank Fusion in- and out-of-domain (their
+  Tables 2–4); the choice of normalization is immaterial for a convex
+  combination (§4.2); `alpha ∈ [0.6, 0.8]` is a robust range needing no
+  training data (we default to 0.7). Their five desiderata —
+  monotonicity, homogeneity, boundedness, Lipschitz continuity, sample
+  efficiency — are exactly the properties `convex_combination_score`
+  provides and `reciprocal_rank_fusion_score` (a function of ranks,
+  not scores) does not.
+- **Cormack, Clarke & Büttcher 2009** → the **RRF alternative** and its
+  `eta = 60` default.
+- **UAX #15** → NFC composition, so decomposed Vietnamese/Korean input
+  matches composed indexed text.
+
+## PDF preservation note
+
+Git LFS is intentionally **not** used; PDFs are committed as regular
+binaries. Where a PDF is absent, it is because the authoring
+environment's network policy blocked the source host (e.g. arxiv.org);
+the citation + arXiv id above make the drop mechanical from a
+network-allowed session. Only permissively-redistributable PDFs are
+committed; others stay cite-only until their license is confirmed.

rankweave-0.1.0/pyproject.toml

@@ -0,0 +1,56 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "rankweave"
+version = "0.1.0"
+description = "Language-agnostic hybrid-retrieval score fusion (TM2C2 + RRF) and Unicode query normalization — pure-Python, store-agnostic."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "Apache-2.0"
+license-files = ["LICENSE"]
+authors = [{ name = "Contextual Wisdom Lab" }]
+keywords = [
+    "information-retrieval",
+    "hybrid-search",
+    "rank-fusion",
+    "reciprocal-rank-fusion",
+    "rrf",
+    "dense-retrieval",
+    "lexical-retrieval",
+    "pgvector",
+    "pg_trgm",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Text Processing :: Indexing",
+    "Topic :: Scientific/Engineering :: Information Analysis",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/ContextualWisdomLab/rankweave"
+Source = "https://github.com/ContextualWisdomLab/rankweave"
+Issues = "https://github.com/ContextualWisdomLab/rankweave/issues"
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "ruff>=0.6"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/rankweave"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]

rankweave-0.1.0/src/rankweave/__init__.py

@@ -0,0 +1,62 @@
+"""rankweave — language-agnostic hybrid-retrieval score fusion.
+
+Pure-Python (stdlib-only) fusion of lexical and semantic retrieval
+channels, plus Unicode NFC query normalization. Store-agnostic: bring
+your own dense (embedding) and lexical (character-trigram / BM25 /
+learned-sparse) channels; rankweave decides how to combine their
+scores.
+
+Two fusion strategies, research-grounded (see ``docs/research/``):
+
+- ``convex_combination`` (default, "TM2C2") — Bruch, Gai & Ingber
+  2023 (arXiv:2210.11934): a convex combination of theoretically
+  min-max normalized scores; robust, distribution-preserving, no
+  training data needed.
+- ``reciprocal_rank_fusion`` — Cormack, Clarke & Büttcher 2009: the
+  non-parametric rank-only alternative.
+
+Quickstart::
+
+    from rankweave import FusionSettings, fuse_channel_scores
+
+    settings = FusionSettings()  # TM2C2, alpha=0.7
+    score = fuse_channel_scores(
+        word_similarity_score=0.62,   # lexical channel, [0, 1]
+        cosine_distance=0.30,         # dense channel, [0, 2]
+        channel_ranks={"lexical": 1, "dense": 1},
+        settings=settings,
+    )
+"""
+
+from rankweave.query_normalization import (
+    DEFAULT_MAX_QUERY_CHARACTER_LENGTH,
+    normalize_search_text,
+)
+from rankweave.score_fusion import (
+    CONVEX_COMBINATION_STRATEGY,
+    COSINE_DISTANCE_THEORETICAL_BOUNDS,
+    RECIPROCAL_RANK_STRATEGY,
+    WORD_SIMILARITY_THEORETICAL_BOUNDS,
+    FusionSettings,
+    convex_combination_score,
+    fuse_channel_scores,
+    reciprocal_rank_fusion_score,
+    theoretical_min_max_normalize,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "CONVEX_COMBINATION_STRATEGY",
+    "COSINE_DISTANCE_THEORETICAL_BOUNDS",
+    "DEFAULT_MAX_QUERY_CHARACTER_LENGTH",
+    "RECIPROCAL_RANK_STRATEGY",
+    "WORD_SIMILARITY_THEORETICAL_BOUNDS",
+    "FusionSettings",
+    "convex_combination_score",
+    "fuse_channel_scores",
+    "normalize_search_text",
+    "reciprocal_rank_fusion_score",
+    "theoretical_min_max_normalize",
+    "__version__",
+]

rankweave-0.1.0/src/rankweave/query_normalization.py

@@ -0,0 +1,44 @@
+"""Query-side text normalization for language-agnostic search.
+
+Character-trigram lexical retrieval is language-agnostic only if the
+query and the indexed documents fold *identically*. This module owns
+the query-side half of that contract; the store side must mirror it.
+
+1. **Unicode NFC composition (UAX #15).** Vietnamese and Korean text
+   arrives in mixed composed/decomposed forms depending on the source
+   platform (macOS filenames and some webmail clients emit NFD), so
+   both sides must compose before comparison.
+2. **Accent folding + lowercasing belong on the store side.** Do them
+   where the documents are indexed so the indexed expression and the
+   bound query parameter go through the identical path — for example a
+   PostgreSQL ``IMMUTABLE`` wrapper
+   ``lower(unaccent(normalize(text, NFC)))`` used in a ``pg_trgm``
+   GiST expression index. Keep that transform in one place and call it
+   from both sides.
+
+Only whitespace shaping and NFC are done here; anything that depends
+on the store's runtime (accent dictionaries, collations) stays on the
+store side so it cannot silently diverge.
+"""
+
+import unicodedata
+
+DEFAULT_MAX_QUERY_CHARACTER_LENGTH = 1000
+
+
+def normalize_search_text(
+    raw_text: str,
+    *,
+    max_characters: int = DEFAULT_MAX_QUERY_CHARACTER_LENGTH,
+) -> str:
+    """Compose the query to NFC and collapse insignificant whitespace.
+
+    ``max_characters`` caps pathological queries; set it to match the
+    store-side bound. Returns the composed, whitespace-collapsed,
+    length-capped query text.
+    """
+    if max_characters < 1:
+        raise ValueError("max_characters must be >= 1")
+    composed_text = unicodedata.normalize("NFC", raw_text)
+    collapsed_text = " ".join(composed_text.split())
+    return collapsed_text[:max_characters]

rankweave-0.1.0/src/rankweave/score_fusion.py

@@ -0,0 +1,160 @@
+"""Fusion functions for hybrid (lexical + semantic) retrieval.
+
+Default strategy: a convex combination of theoretically min-max
+normalized channel scores ("TM2C2"; Bruch, Gai & Ingber 2023,
+*An Analysis of Fusion Functions for Hybrid Retrieval*, ACM TOIS
+42(1), arXiv:2210.11934). Their analysis shows TM2C2 outperforms
+Reciprocal Rank Fusion in- and out-of-domain, is robust for alpha in
+[0.6, 0.8] without training data, and — unlike RRF — preserves the
+score distribution (Lipschitz continuity).
+
+Reciprocal Rank Fusion (Cormack, Clarke & Büttcher 2009,
+*Reciprocal Rank Fusion outperforms Condorcet and individual Rank
+Learning Methods*, SIGIR) is the non-parametric alternative for
+channels that expose only ranks (learned-sparse or external
+channels), selected via ``FusionSettings.strategy_name``.
+
+The convex strategy assumes each channel score has *theoretical*
+bounds, so no per-query data-dependent normalization is needed. Two
+bound constants ship for the common lexical+dense pairing, but they
+are just ``(lower, upper)`` tuples — pass your own to
+``theoretical_min_max_normalize`` for any bounded scoring function:
+
+- ``WORD_SIMILARITY_THEORETICAL_BOUNDS``  = (0.0, 1.0) — e.g. a
+  character-trigram word-similarity such as PostgreSQL ``pg_trgm``.
+- ``COSINE_DISTANCE_THEORETICAL_BOUNDS`` = (0.0, 2.0) — cosine
+  distance for unit-norm vectors, e.g. a pgvector ``<=>`` channel;
+  fuse_channel_scores inverts it so smaller distance scores higher.
+"""
+
+from dataclasses import dataclass
+
+WORD_SIMILARITY_THEORETICAL_BOUNDS = (0.0, 1.0)
+COSINE_DISTANCE_THEORETICAL_BOUNDS = (0.0, 2.0)
+
+CONVEX_COMBINATION_STRATEGY = "convex_combination"
+RECIPROCAL_RANK_STRATEGY = "reciprocal_rank_fusion"
+
+_SUPPORTED_STRATEGY_NAMES = frozenset(
+    {CONVEX_COMBINATION_STRATEGY, RECIPROCAL_RANK_STRATEGY}
+)
+
+
+@dataclass(frozen=True)
+class FusionSettings:
+    """Tunable fusion parameters (immutable; construct one per query set)."""
+
+    strategy_name: str = CONVEX_COMBINATION_STRATEGY
+    # Weight of the semantic channel; 0.7 is the midpoint of the
+    # robust [0.6, 0.8] range reported by Bruch et al. (2023).
+    semantic_weight_alpha: float = 0.7
+    # RRF eta; 60 per Cormack et al. (2009).
+    rank_constant_eta: int = 60
+
+    def __post_init__(self) -> None:
+        if self.strategy_name not in _SUPPORTED_STRATEGY_NAMES:
+            raise ValueError(
+                "strategy_name must be one of "
+                f"{sorted(_SUPPORTED_STRATEGY_NAMES)}, got {self.strategy_name!r}"
+            )
+        if not 0.0 <= self.semantic_weight_alpha <= 1.0:
+            raise ValueError("semantic_weight_alpha must be within [0, 1]")
+        if self.rank_constant_eta < 1:
+            raise ValueError("rank_constant_eta must be >= 1")
+
+
+def theoretical_min_max_normalize(
+    score: float, bounds: tuple[float, float]
+) -> float:
+    """Scale a score to [0, 1] using the scoring function's theoretical bounds.
+
+    Using theoretical rather than observed bounds keeps the transform
+    stable across queries and candidate sets (Bruch et al. 2023, §4.2).
+    Out-of-range inputs (floating-point drift) are clamped.
+    """
+    lower_bound, upper_bound = bounds
+    if upper_bound <= lower_bound:
+        raise ValueError("bounds must satisfy upper > lower")
+    normalized = (score - lower_bound) / (upper_bound - lower_bound)
+    return min(1.0, max(0.0, normalized))
+
+
+def convex_combination_score(
+    semantic_score: float | None,
+    lexical_score: float | None,
+    semantic_weight_alpha: float,
+) -> float:
+    """TM2C2 fusion over already-normalized [0, 1] channel scores.
+
+    A channel absent for a candidate (e.g. no embedding stored yet)
+    contributes its theoretical minimum, 0 — absent evidence is the
+    infimum, not a missing value to impute.
+    """
+    semantic_component = semantic_score if semantic_score is not None else 0.0
+    lexical_component = lexical_score if lexical_score is not None else 0.0
+    return (
+        semantic_weight_alpha * semantic_component
+        + (1.0 - semantic_weight_alpha) * lexical_component
+    )
+
+
+def reciprocal_rank_fusion_score(
+    channel_ranks: dict[str, int], rank_constant_eta: int = 60
+) -> float:
+    """RRF over 1-based per-channel ranks: sum of 1 / (eta + rank)."""
+    if rank_constant_eta < 1:
+        raise ValueError("rank_constant_eta must be >= 1")
+    fused_score = 0.0
+    for channel_name, one_based_rank in channel_ranks.items():
+        if one_based_rank < 1:
+            raise ValueError(
+                f"rank for channel {channel_name!r} must be >= 1,"
+                f" got {one_based_rank}"
+            )
+        fused_score += 1.0 / (rank_constant_eta + one_based_rank)
+    return fused_score
+
+
+def fuse_channel_scores(
+    *,
+    word_similarity_score: float | None,
+    cosine_distance: float | None,
+    channel_ranks: dict[str, int],
+    settings: FusionSettings,
+) -> float:
+    """Fuse one candidate's channel evidence into a single score.
+
+    ``word_similarity_score`` and ``cosine_distance`` are the raw
+    channel outputs (None when the channel did not produce this
+    candidate); ``channel_ranks`` are the candidate's 1-based ranks in
+    the channels that returned it, used by the RRF strategy.
+    """
+    if settings.strategy_name == RECIPROCAL_RANK_STRATEGY:
+        if not channel_ranks:
+            return 0.0
+        return reciprocal_rank_fusion_score(
+            channel_ranks, settings.rank_constant_eta
+        )
+
+    normalized_lexical_score = (
+        theoretical_min_max_normalize(
+            word_similarity_score, WORD_SIMILARITY_THEORETICAL_BOUNDS
+        )
+        if word_similarity_score is not None
+        else None
+    )
+    # Cosine *distance* decreases as relevance increases; invert inside
+    # the theoretical [0, 2] range so 1.0 means identical direction.
+    normalized_semantic_score = (
+        1.0
+        - theoretical_min_max_normalize(
+            cosine_distance, COSINE_DISTANCE_THEORETICAL_BOUNDS
+        )
+        if cosine_distance is not None
+        else None
+    )
+    return convex_combination_score(
+        normalized_semantic_score,
+        normalized_lexical_score,
+        settings.semantic_weight_alpha,
+    )

rankweave-0.1.0/tests/test_fusion.py

@@ -0,0 +1,204 @@
+import math
+
+import pytest
+
+from rankweave import (
+    COSINE_DISTANCE_THEORETICAL_BOUNDS,
+    WORD_SIMILARITY_THEORETICAL_BOUNDS,
+    FusionSettings,
+    convex_combination_score,
+    fuse_channel_scores,
+    normalize_search_text,
+    reciprocal_rank_fusion_score,
+    theoretical_min_max_normalize,
+)
+from rankweave.score_fusion import (
+    CONVEX_COMBINATION_STRATEGY,
+    RECIPROCAL_RANK_STRATEGY,
+)
+
+
+class TestNormalizeSearchText:
+    def test_composes_decomposed_hangul_to_nfc(self):
+        # U+1112 U+1161 U+11AB (decomposed jamo) -> U+D55C
+        decomposed_hangul = "\u1112\u1161\u11ab"
+        assert normalize_search_text(decomposed_hangul) == "\ud55c"
+
+    def test_composes_decomposed_vietnamese_diacritics(self):
+        # "a" + combining circumflex + combining grave -> U+1EA7
+        decomposed_vietnamese = "Tra\u0302\u0300n"
+        assert normalize_search_text(decomposed_vietnamese) == "Tr\u1ea7n"
+
+    def test_collapses_whitespace_and_strips(self):
+        assert normalize_search_text("  hello \t world \n") == "hello world"
+
+    def test_caps_pathological_query_length(self):
+        assert len(normalize_search_text("가" * 5000)) == 1000
+
+    def test_keeps_cjk_text_intact_without_tokenization(self):
+        korean_query = "다음주 회의 일정"
+        assert normalize_search_text(korean_query) == korean_query
+
+    def test_max_characters_override(self):
+        assert len(normalize_search_text("a" * 50, max_characters=10)) == 10
+
+    def test_rejects_non_positive_max_characters(self):
+        with pytest.raises(ValueError):
+            normalize_search_text("hello", max_characters=0)
+
+
+class TestTheoreticalMinMaxNormalize:
+    def test_word_similarity_bounds_map_to_unit_interval(self):
+        assert theoretical_min_max_normalize(
+            0.0, WORD_SIMILARITY_THEORETICAL_BOUNDS
+        ) == 0.0
+        assert theoretical_min_max_normalize(
+            1.0, WORD_SIMILARITY_THEORETICAL_BOUNDS
+        ) == 1.0
+        assert theoretical_min_max_normalize(
+            0.25, WORD_SIMILARITY_THEORETICAL_BOUNDS
+        ) == pytest.approx(0.25)
+
+    def test_cosine_distance_bounds_map_to_unit_interval(self):
+        assert theoretical_min_max_normalize(
+            0.0, COSINE_DISTANCE_THEORETICAL_BOUNDS
+        ) == 0.0
+        assert theoretical_min_max_normalize(
+            2.0, COSINE_DISTANCE_THEORETICAL_BOUNDS
+        ) == 1.0
+        assert theoretical_min_max_normalize(
+            0.5, COSINE_DISTANCE_THEORETICAL_BOUNDS
+        ) == pytest.approx(0.25)
+
+    def test_clamps_floating_point_drift(self):
+        assert theoretical_min_max_normalize(
+            1.0000001, WORD_SIMILARITY_THEORETICAL_BOUNDS
+        ) == 1.0
+        assert theoretical_min_max_normalize(
+            -0.0000001, WORD_SIMILARITY_THEORETICAL_BOUNDS
+        ) == 0.0
+
+    def test_rejects_inverted_bounds(self):
+        with pytest.raises(ValueError):
+            theoretical_min_max_normalize(0.5, (1.0, 0.0))
+
+
+class TestConvexCombinationScore:
+    def test_hand_computed_fusion(self):
+        # alpha * semantic + (1 - alpha) * lexical
+        fused_score = convex_combination_score(0.8, 0.5, 0.7)
+        assert fused_score == pytest.approx(0.7 * 0.8 + 0.3 * 0.5)
+
+    def test_missing_channel_contributes_theoretical_minimum(self):
+        assert convex_combination_score(None, 0.5, 0.7) == pytest.approx(0.15)
+        assert convex_combination_score(0.8, None, 0.7) == pytest.approx(0.56)
+        assert convex_combination_score(None, None, 0.7) == 0.0
+
+    def test_alpha_extremes_select_single_channel(self):
+        assert convex_combination_score(0.9, 0.4, 1.0) == pytest.approx(0.9)
+        assert convex_combination_score(0.9, 0.4, 0.0) == pytest.approx(0.4)
+
+    def test_monotone_in_each_channel(self):
+        base_score = convex_combination_score(0.5, 0.5, 0.7)
+        assert convex_combination_score(0.6, 0.5, 0.7) > base_score
+        assert convex_combination_score(0.5, 0.6, 0.7) > base_score
+
+    def test_bounded_in_unit_interval(self):
+        assert 0.0 <= convex_combination_score(1.0, 1.0, 0.7) <= 1.0
+        assert 0.0 <= convex_combination_score(0.0, 0.0, 0.7) <= 1.0
+
+
+class TestReciprocalRankFusionScore:
+    def test_hand_computed_rrf(self):
+        fused_score = reciprocal_rank_fusion_score(
+            {"lexical_email": 1, "dense_email": 3}, rank_constant_eta=60
+        )
+        assert fused_score == pytest.approx(1.0 / 61.0 + 1.0 / 63.0)
+
+    def test_lower_rank_scores_higher(self):
+        better_ranked = reciprocal_rank_fusion_score({"channel": 1})
+        worse_ranked = reciprocal_rank_fusion_score({"channel": 10})
+        assert better_ranked > worse_ranked
+
+    def test_more_channels_score_higher(self):
+        single_channel = reciprocal_rank_fusion_score({"a": 5})
+        two_channels = reciprocal_rank_fusion_score({"a": 5, "b": 5})
+        assert two_channels > single_channel
+
+    def test_rejects_invalid_rank_and_eta(self):
+        with pytest.raises(ValueError):
+            reciprocal_rank_fusion_score({"a": 0})
+        with pytest.raises(ValueError):
+            reciprocal_rank_fusion_score({"a": 1}, rank_constant_eta=0)
+
+
+class TestFusionSettings:
+    def test_defaults_follow_research_grounding(self):
+        settings = FusionSettings()
+        assert settings.strategy_name == CONVEX_COMBINATION_STRATEGY
+        assert settings.semantic_weight_alpha == 0.7
+        assert settings.rank_constant_eta == 60
+
+    def test_rejects_unknown_strategy(self):
+        with pytest.raises(ValueError):
+            FusionSettings(strategy_name="borda_count")
+
+    def test_rejects_out_of_range_alpha(self):
+        with pytest.raises(ValueError):
+            FusionSettings(semantic_weight_alpha=1.5)
+
+
+class TestFuseChannelScores:
+    def test_convex_strategy_normalizes_and_inverts_distance(self):
+        settings = FusionSettings()
+        fused_score = fuse_channel_scores(
+            word_similarity_score=0.5,
+            cosine_distance=0.4,
+            channel_ranks={"lexical_email": 1, "dense_email": 1},
+            settings=settings,
+        )
+        expected_semantic = 1.0 - 0.4 / 2.0  # 0.8
+        assert fused_score == pytest.approx(0.7 * expected_semantic + 0.3 * 0.5)
+
+    def test_identical_vectors_and_exact_word_match_score_one(self):
+        settings = FusionSettings()
+        fused_score = fuse_channel_scores(
+            word_similarity_score=1.0,
+            cosine_distance=0.0,
+            channel_ranks={"lexical_email": 1, "dense_email": 1},
+            settings=settings,
+        )
+        assert fused_score == pytest.approx(1.0)
+
+    def test_rrf_strategy_uses_ranks_only(self):
+        settings = FusionSettings(strategy_name=RECIPROCAL_RANK_STRATEGY)
+        fused_score = fuse_channel_scores(
+            word_similarity_score=0.99,
+            cosine_distance=0.01,
+            channel_ranks={"lexical_email": 2, "dense_email": 4},
+            settings=settings,
+        )
+        assert fused_score == pytest.approx(1.0 / 62.0 + 1.0 / 64.0)
+
+    def test_rrf_strategy_with_no_ranks_scores_zero(self):
+        settings = FusionSettings(strategy_name=RECIPROCAL_RANK_STRATEGY)
+        assert (
+            fuse_channel_scores(
+                word_similarity_score=None,
+                cosine_distance=None,
+                channel_ranks={},
+                settings=settings,
+            )
+            == 0.0
+        )
+
+    def test_lexical_only_candidate_is_finite_and_positive(self):
+        settings = FusionSettings()
+        fused_score = fuse_channel_scores(
+            word_similarity_score=0.6,
+            cosine_distance=None,
+            channel_ranks={"lexical_email": 1},
+            settings=settings,
+        )
+        assert math.isfinite(fused_score)
+        assert fused_score == pytest.approx(0.3 * 0.6)