searchi/crates/searchi-service/README.md

Shared hybrid retrieval

HybridSearch combines genuine lexical and Google multimodal retrieval. The CLI and desktop use the same service; it has no desktop-shell dependency.

search, search_semantic and search_semantic_with_origin preserve grouped parent files. ANN candidates expand until enough unique eligible parents exist or the complete bounded eligible chunk set is requested. Filename/type/folder, size/date/duration and explicit source filters apply before ANN top-k. Media candidate filesystem metadata is checked once per parent per query. Ninety-six near-identical video vectors cannot hide a second eligible parent (regression tested). HNSW remains approximate retrieval, not an exact recall guarantee.

Explicit spoken/audio wording prefers actual audio-source vectors, preserving exact lexical filename priority. Conservative English/German token cues detect requests such as “someone mentions”, “spoken”, “audio”, “jemand erwähnt” and “Gespräch”. Visual/document cues veto automatic routing. This finite parser is not language understanding; paraphrases, negation and mixed intents can remain ambiguous. If the preferred lane has no eligible results, ordinary retrieval is used. SemanticOrigin::All bypasses the hint; Audio, Image, Video and Text select an explicit channel without fallback or reembedding.

Persisted custom sampling limits can be reopened without generating embeddings again only when the complete model and preprocessing fingerprint matches. The custom suffix must contain the eight valid numeric sampling limits. Model or preprocessing changes never silently reuse incompatible vectors.

search_measured(query,limit,options,debug) returns SearchResponse with results and monotonic total milliseconds/result count. Basic mode stores no trace. search_traced(...,&mut TraceCollector,parent) shares the native request clock so queue/lock time and actual engine stages remain comparable. Debug mode adds bounded nested spans for lexical SQL, query embedding, worker diagnostics, filtered eligibility and its cache, ANN read/checksum/deserialization/search passes, parent materialization and validation, and rank fusion. Static stage names and numerical counters exclude query/source text and paths. Worker-local microsecond counters have a separate clock and are not aligned request spans.

Measured/source APIs retain existing result behavior except the explicit spoken/audio preference. Debug instrumentation does not change vector policy. Audio timestamps represent segment starts, not exact word locations. Smaller windows alone have not demonstrated accurate spoken navigation. No-answer calibration, music discrimination, exact spoken positions, process isolation, unchanged-vector reuse and production platform checks remain release gates.

Exact artist/title constraints use the core's normalized structured probe keys before ANN limits and in the eligibility cache key. Metadata-only writes advance a separate durable metadata epoch so warmed readers cannot retain old eligibility. They do not change source-corpus revisions during the indexer's own probe publication. Empty metadata-only hybrid requests use core results without model inference. These explicit constraints do not establish abstention for free-form topic queries.

Optional speech evidence

Attach a verified searchi_speech::SpeechWorker through with_speech_provider. BudgetedSpeechProvider admits one background thread per contiguous window; its admission time remains separate from native VAD/ASR/load/transport metrics. Aborted acceleration and CPU retry cost is aggregated separately as fallback_us. Recognition consumes at most thirty seconds of mono 16-kHz PCM, with two-second window overlap and an explicit 1024-window source ceiling. Four-hour default media fits the contiguous policy. Recognition never receives reference captions.

Speech uses decode_audio_aligned: source-frame timestamps preserve positive track origins, internal gaps, seeks and tails. Its CPU FFmpeg regression compares actual samples against known fixture clocks. Raw Google audio preprocessing is unchanged. DTW first/last point spans may have equal start/end; no invented duration is added. These functional contracts do not prove general timestamp accuracy.

Raw media, speech and document passages have independent completed source tasks. Adding/upgrading speech or retrying its failures reuses compatible verified raw vectors. Speech task identity includes native recognition assets/policy, aligned decoder policy, input SHA-256, title, maximum duration and maximum file bytes; raw sampling changes do not force speech recognition. Failed speech tasks publish explicit partial coverage while retaining raw evidence, and remain retryable. A genuine Google inference failure still aborts semantic publication.

SpeechProvider returns bounded recognized passages and numeric metrics. Google EmbeddingGemma 2 alone embeds those passages. Spoken-intent requests prefer semantic_speech, falling back to raw audio; music and sound requests use audio. Source locations retain timestamp_ms; recognized snippets are identified as local_speech_recognition, not exact document bytes. speech_excerpt_matching binds an issued result's recognized text when timestamps repeat, verifies current media SHA-256/revision and serves only active indexed evidence.

speech_policy_key and EmbeddingStatus.corpus_revision provide the stable (policy, source revision) automatic-retry key. Generation IDs and metadata-only updates must not trigger an endless retry loop. Status includes active speech policy and bounded explicit failures. Native interaction, full speech quality, other-platform execution and GPU evidence remain separate release gates.

Actual ASR/Google integration is an explicit ignored test: cargo test -p searchi-service --test speech_google_cpu -- --ignored --nocapture --test-threads=1. Provide verified SEARCHI_SPEECH_WORKER, SEARCHI_SPEECH_BASE, SEARCHI_SPEECH_VAD, Google model/worker variables, CPU FFmpeg/FFprobe helpers and a real short WAV in SEARCHI_TEST_SPEECH_AUDIO; Windows VM execution requires SEARCHI_FORCE_CPU=1. This tests publication/reuse and evidence binding, not independent relevance.