searchi/docs/MEDIA-FINAL-QUALITY.md

# Bounded media relevance improvement, 2026-10-14

This pass keeps Google EmbeddingGemma 2 and the existing shared engine. It
corrects one practical source of irrelevant results without another model,
reindexing, an absolute similarity cutoff, or a new ranking framework.

## Hybrid shortlist correction after the real screenshot review

The real screenshot exposed an additional defect: reciprocal-rank fusion gave
every semantic nearest neighbour a result rank even when its raw similarity
was far below a strong match. A mountain photo consequently appeared beneath
the supplier agreement for a cancellation query.

Hybrid search now keeps the strongest semantic cluster when the filtered,
file-deduplicated score list has one clearly separated tail: choose the largest
adjacent raw cosine gap, and prune after it only when that gap is **greater than
0.07**. Equal largest gaps within f32 rounding retain the complete list. The
0.07 gap is rounded upward from the maximum 0.0650497 observed among eight
previously frozen calibration absence requests; it is a relative decluttering
rule, **not an absolute cosine threshold or a confidence percentage**.
The [frozen policy](../tools/relevance-eval/policies/hybrid-tail-v1.json) records
the exact scope and calibration report hash.

All independent lexical matches, exact filename/identifier priority and the
best semantic candidate survive. Explicit raw semantic search is unchanged.
Filters and source checks still run before candidate limits; no index or model
is regenerated. Debug traces report `hybrid.semantic_shortlist` with before,
after and pruned counts.

Actual current Google CPU query results on the verified README fixture:

| Query | Raw semantic scores | Hybrid result |
| --- | --- | --- |
| `cancel the supplier partnership` | Agreement 0.820912; onboarding 0.660648; procurement 0.626666; mountain photo 0.528253 | Agreement retained; unrelated photos removed; 7 → 1 results |
| `mountains reflected in calm water` | Lake 0.753141; pier 0.684482; travel document 0.537812 | Two image results retained; unrelated documents removed |

The genuine query-role CPU integration passed in 7.61 seconds, covering raw API
preservation, actual PDF/photo retrieval, exact filename priority, PDF and size
filters, and limit one. Its ignored log `.searchi/qa/hybrid-tail-google-cpu.log`
has SHA-256 `bc920ba56bc5b4f89bb5ee8831420bf5c14964d2da5decb0b392482e12309d4e`.
The raw pre-change requests are preserved in
`.searchi/qa/readme-raw-relevance.json`, SHA-256
`4a017d8fee0d3762a806628e38a848ca9ca9cb052e92c1892f639efda3fde62d`.

A replay of existing genuine raw-score reports retained every previously
retrieved relevant top-five file in calibration, the previously evaluated
held-out report and the 61 ranked media-reference rows. Mean semantic
candidate counts changed from 11.6 to 5.0, 11.6 to 4.2 and 14.75 to 3.59,
respectively. This is score replay on known diagnostics, not newly independent
inference or a production relevance guarantee. The historical media reference
contains its documented audio preprocessing failure; no failed encoding is
silently credited as a positive. Forty text/code positive rows retain their
top semantic candidate by construction; **all 20 absence rows still retain a
neighbour**. The policy does not solve absence classification.

Three focused shortlist unit tests passed (weak-but-correct 0.6766, multiple
strong matches, flat/uniform/tied lists, one/two candidates and independent exact
lexical preservation). The full service library passed 45 tests with its two
explicitly provisioned/benchmark tests ignored; strict all-target Clippy passed.

## What changed

Explicit photo/image requests use image evidence; explicit video/film requests
use video-frame evidence. Spoken-topic requests retain speech-first retrieval
and raw-audio fallback while recognition is unavailable. Explicit music/audio
requests use actual audio evidence. If the requested channel is empty, semantic
search now returns empty instead of selecting an unrelated photo/document.
The independent exact filename/keyword lane remains available in hybrid search.

Ordinary subject queries stay general. Document/code/algorithm cues veto these
small intent hints. A mixed `photo or video` request stays general rather than
silently losing videos. `sound financial advice` is not an audio request.
The hints use word boundaries and English/German cues, not a claim of natural
language understanding. Debug traces report `explicit_source_channel` and
`requested_channel_empty`.

## Actual Google CPU evidence

The isolated integration fixture contains the existing licensed, SHA-locked
cat photo `fixtures/media/assets/image01.jpg`, copied into a temporary owned
index. It uses the normal native Google runtime with `SEARCHI_FORCE_CPU=1`,
one inference thread, actual image encoding, persisted ANN retrieval and the
query-role worker. No fabricated vectors or labels enter inference.

| Check | Unrestricted real-model channel | Corrected automatic routing |
| --- | --- | --- |
| Six requests for absent audio/music/speech/video channels, EN/DE | 6/6 returned the unrelated photo | 0/6 returned a semantic result |
| Three photo/general cat requests, EN/DE | Actual image indexed | 3/3 retained the correct photo |
| Exact `cat.jpg` | Independent lexical lane | Exact filename retained |

`explicit_media_requests_do_not_fall_back_to_unrelated_channels` passed in
82.63 seconds including indexing, model loading and all assertions. This is
functional correctness evidence, not a search-latency benchmark or a large
collection quality score. Raw log: ignored `.searchi/qa/media-final-routing.log`,
SHA-256 `14d452192315fb1ddfd0b0df1448ffc475876af57a767546b36f68f17771b83d`.

The existing actual Google code-versus-licensed-audio regression also passed
in 81.72 seconds: an explicit code query retained its indexed implementation
while real audio remained an eligible independent channel. Its ignored log
`.searchi/qa/media-final-code-veto.log` has SHA-256
`04d8f42ed8e872f22607c2fe4fb45e0d5149d4b42539b3346abd18ebb224e137`.
All three focused routing unit tests passed after the mixed-channel/algorithm/
sound-adjective fixes, including the English/German ambiguity cases.

Reproduce with the verified Google/model and FFmpeg environment described in
SKILLS.md:

```powershell
$env:SEARCHI_FORCE_CPU = '1'
cargo test -p searchi-service --test routing_google_cpu explicit_media_requests_do_not_fall_back --locked -- --ignored --nocapture --test-threads=1
cargo test -p searchi-service --lib routing::tests --locked
```

## Limits and music decision

These changes reject wrong channels and trim clearly separated weak tails;
they are not calibrated detection that a particular
subject is absent within a populated channel. An indexed audio collection can
still return an unrelated nearest performance for an absent musical instrument;
photos/videos have the same limitation within their own channel. Speech without
recognized passages retains raw audio fallback. Do not advertise a confidence
percentage or perfect no-answer detection.

Existing exact artist/title metadata filters remain the reliable identity path.
The previous independently frozen music comparison improved 8/14 to 11/14 first
hits using literal embedded tag fields, but regressed one positive, fell to 5/14
with misleading tags, and failed all four no-answer cases. That unconditional
field-max policy remains unintegrated: it does not justify shipping a universal
music-recognition improvement. See MUSIC-METADATA.md and
fixtures/music-validation-v1/README.md. This pass adds no hosted music lookup,
fingerprinting service, generated labels, or extra model downloads.

Existing image evidence and video scene sampling are retained. Spoken timing
and recovery are recorded separately in SPEECH-FINAL-QUALITY.md. Media remains
usable with explicit limits; this bounded pass does not invent a new overall
quality rating or extend the agreed release scope.

## 0.1.9: primary matches and related suggestions

The frozen shared-engine presentation rule now keeps weaker semantic neighbors
under expandable **Related suggestions** instead of promoting every nearest
neighbor as a primary match. It preserves exact filename/keyword matches and
access to lower-scoring genuine sources. See [semantic evidence](SEMANTIC-EVIDENCE.md)
for the frozen policy and [blind results](../fixtures/absence-v3/evaluation-summary.json).

Actual Google CPU evaluation covered all 36 assets without extraction or
semantic/speech failures. Primary false neighbors on absent requests fell from
16/16 to 4/16 against the previous-rule replay. All 16 positive requests retained
their expected source within five accessible results, but only 10/16 had a
correct primary first result; five required expanding related suggestions.
Both music identity requests still ranked the wrong recording first in raw
retrieval. Related grouping makes this uncertainty visible; it does not fix
music recognition, infer precise words/timestamps or prove requested facts exist.
All absent requests still retained related candidates.

The policy was frozen before blind evaluation and was not retuned on the result.
Small corpus, publisher-based media labels and one independent AI annotator
limit generalization. Package/startup verification for 0.1.9 passed; final public verification is
recorded in ROADMAP.md.