open/portfolio-optimiser
1
0
Fork 0
Code Issues Releases 1 Activity

fix(semretrieval): refuse a non-finite embedding instead of scoring it (kø-(l)/S3.1 MINOR)

Browse source 
`cosine`'s docstring claimed its guard was load-bearing because "a NaN reaching the
ranking sort key would corrupt ordering silently rather than failing loudly" — but the
guard tested `norm == 0.0` only, which a NaN or inf norm passes straight through. The
claim was prose, not behaviour.

Measured, not assumed: `cosine(unit, nan_vector)` AND `cosine(unit, inf_vector)` both
returned `nan`, and a NaN sort key made ranking INPUT-ORDER-DEPENDENT — six permutations
of the same three candidates produced four distinct orderings. That defeats the total
order `HybridRanker` documents ("`id` makes the result independent of input order").

Refuse rather than coerce, and deliberately NOT symmetric with the zero-norm branch: a
zero vector is a legitimate handled state (`FakeEmbedder` returns `np.zeros` by design),
whereas a non-finite component only ever means the INJECTED embedder is broken. Scoring
it `0.0` would launder that into "no semantic similarity" while ranking proceeded on a
forged signal — validation, never repair, mirroring `read_spend`.

Reachable via the documented `Embedder` extension point, not the shipped fake; scoped to
the norms (90% principle — a finite-normed dot-product overflow is not chased).

Also corrects `docs/extending.md`, which stated `SEMANTIC_WEIGHT_DEFAULT = 0.5` while the
code has said `0.25` since the weight was lowered.

625 -> 630 tests. Load-bearing MEASURED against the WHOLE suite, five mutations all red:
detach the guard entirely · coerce to 0.0 instead of raising · check only the first norm ·
drop "non-finite" from the message · (control) detach the zero-norm branch, which fails
ONLY the zero-norm test — the new guard does not mask the existing one.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018V9vNBmxAmgJ2JMoHByiHS
This commit is contained in:
Kjell Tore Guttormsen 2026-08-03 21:48:50 +02:00
commit c02c1addba
4 changed files with 132 additions and 3 deletions
Download patch file Download diff file Expand all files Collapse all files

10
docs/extending.md
View file

@ -194,7 +194,15 @@ protocols and the store delegates to them:
with a `rank` method to replace ranking wholesale.
- **`Embedder`** — `__call__(features) -> np.ndarray`. `HybridRanker(embedder, similarity, weight)`
blends `weight * cosine + (1 - weight) * structural`; both terms live in `[0, 1]`, so `weight`
means what it reads as (`SEMANTIC_WEIGHT_DEFAULT = 0.5`).
means what it reads as (`SEMANTIC_WEIGHT_DEFAULT = 0.25`).
**Your vectors must be finite.** `cosine` raises `ValueError` on a NaN or infinite norm rather
than scoring it — a non-finite score compares `False` against everything, which leaves the
ranking in whatever order the input happened to arrive in and defeats the total order
`HybridRanker` otherwise guarantees. A zero vector is fine and scores `0.0`; the asymmetry is
deliberate, because zero is a state the shipped `FakeEmbedder` produces on purpose whereas
non-finite only ever means the embedder is broken. Coercing it to `0.0` would hide that as
"no semantic similarity" and let ranking proceed on a forged signal.
```python
store.retriever = HybridRanker(MyEmbedder(), similarity, weight=0.3)