Ship floating launcher, automatic discovery and bounded media search improvements

docs/MEDIA-FINAL-QUALITY.md

@@ -0,0 +1,136 @@
+# 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.