searchi/README.md

# searchi

**Find what matters. Locally.**

Local desktop search for Windows, macOS and Linux, under active development.
Production readiness is tracked in [the roadmap](docs/ROADMAP.md).

![searchi finding a supplier agreement and its matching passage](docs/screenshots/search-light.png)

*The production UI searching real fixture files with Google EmbeddingGemma 2.
Captured on Windows with CPU inference in the read-only local browser capture harness;
native window chrome is omitted.*

## What works

Search combines instant indexed filenames, SQLite FTS5 content retrieval, and
**real Google EmbeddingGemma 2** vectors in a persisted HNSW index. PDF pages,
DOCX paragraphs and text passages retain their source locations. The same
shared Rust service now indexes **images, video frames, movie soundtracks,
audio and music**: actual pixels and sound enter Google's media projector in
the same 768-dimensional space as text queries. No generated captions,
simulated embeddings, replacement model, or Granola service is required.
Existing artist/title tags contribute keyword matches.

The desktop is the primary interface. It automatically prepares verified local
models, indexes selected folders, and prewarms its query worker. Image previews
and audio/video controls use narrowly scoped local assets; timestamp results
seek inside the preview without autoplay. Open file launches the default
application, whose exact opening position is not controlled by Searchi.
The CLI provides the same retrieval engine without a GUI.

**Media search is experimental.** File retrieval works on the independent seed
corpus, but precise spoken-topic timestamps, music hard negatives, and no-answer
handling still need improvement. Nearest-neighbor results are not calibrated
confidence. Video frames are sampled across the movie; every fleeting scene is
not guaranteed. Audio windows cover the primary stream within explicit resource
limits. See [actual media quality and failures](docs/MEDIA-QUALITY.md).

Production supports compiled hardware acceleration with CPU fallback. All
Windows VM tests use CPU only. Files, extracted text, metadata and embeddings
stay local; treat the index as sensitive. Initial verified model provisioning
requires approximately 865 MB of downloads. Search performs no remote inference.

## See searchi working

### A familiar dark theme

![The same real document search in searchi's dark theme](docs/screenshots/search-dark.png)

Light and dark themes follow the operating system preference. The selected
result retains its source location and extracted passage. Matching query words
are highlighted in results and previews. A small, collapsed **Why this result?**
detail is available when you want the explanation.

### Find a photo from what you remember

![A natural-language search finding the mountain lake photo](docs/screenshots/media-search.png)

Actual image pixels are indexed by the Google model. The selected photo is
loaded from the indexed fixture file for preview.

### Understand where the time goes

![searchi's detailed performance panel showing real search and inference timings](docs/screenshots/performance-details.png)

Normal searches show a compact timing summary. Optional performance details
break down the real request into measured stages, including worker inference,
retrieval, filtering and ranking.

The [capture workflow](tools/desktop-capture/README.md) and
[capture manifest](docs/screenshots/capture-manifest.json) record the queries,
runtime, measured responses and image hashes. The photo sources and licenses
are listed in [the media fixture documentation](fixtures/media/README.md).
These browser captures supplement the open native desktop QA gates.

## Copy-and-paste setup prompt

```text
Set up Searchi from https://tea.karlcom.de/karl/searchi.git in a new searchi
folder, or reuse the checkout without overwriting local changes. Read AGENTS.md,
SKILLS.md, docs/ROADMAP.md, docs/BUILDING.md and apps/desktop/README.md first.
Inspect the OS/tools. Install supported missing prerequisites: Git, stable Rust,
Node.js 24 LTS, Python 3.11+, CMake, native C/C++ tools and Tauri dependencies.
Preserve credentials and never print secrets. Prefer established Rust crates
and portable native tools; keep engine APIs shared by CLI and desktop.
For Karl's Windows VM set SEARCHI_FORCE_CPU=1 and
WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS='--disable-gpu --disable-accelerated-video-decode'
before tests or launch. Never enable a GPU provider in that VM.
From the repository root:
python tools/embeddinggemma2/build_runtime.py --backend cpu --jobs 2
python tools/embeddinggemma2/stage_runtime.py --backend cpu
python tools/media-runtime/provision.py --stage
The decoder manifest supports Windows/Linux x86-64 and ARM64; macOS decoder
packaging is still a gate. On unsupported hosts report the real blocker and
use explicitly verified native tools only when their provenance is known.
Run cargo test --workspace --locked, cargo fmt --all --check and
cargo clippy --workspace --all-targets --locked -- -D warnings.
Run cargo test --manifest-path apps/desktop/src-tauri/Cargo.toml --locked.
In apps/desktop run npm ci, npm test, npm run format:check and npm run build.
Launch the real app with npm run tauri -- dev. Allow automatic verified Google
model setup and retained-worker warmup. Never substitute another model or mocks.
Ask which folders I want indexed; don't index my whole home automatically.
Verify filename/content/image/music/video searches and persistence on selected
files. Inspect media failure reports and actual preview seeking. Read
MEDIA-QUALITY.md before claiming precise speech timestamps or reliable absence.
Report actual checks and blockers. Do not publish a release or claim production
readiness, GPU validation, native visual QA, or untested OS coverage.
```

This is developer setup, not an installer. The worker builder also accepts
`auto`, `metal`, `vulkan` and `cuda`; each requires its platform SDK and separate
hardware validation. Standalone FFmpeg/FFprobe and notices are staged for the
desktop; end users should not install tools or configure decoder paths.

## Headless setup

Build with `cargo build --release --locked -p searchi-cli`. No Node, Tauri,
WebView or display server is needed. Build the native Google worker separately,
and provision verified assets and FFmpeg tools:

```sh
python tools/embeddinggemma2/build_runtime.py --backend cpu --jobs 2
python tools/media-runtime/provision.py
cargo run -p searchi-cli -- setup --model-dir .searchi/models/embeddinggemma2
cargo run -p searchi-cli -- index --db searchi.sqlite --root /path/to/files
```

On native Linux, unified document/media indexing and hybrid search use:

```sh
./target/release/searchi embed --db searchi.sqlite --model-dir .searchi/models/embeddinggemma2 --embedding-worker .searchi/runtime/cpu/searchi-gemma-worker --ffmpeg .searchi/media-runtime/bin/ffmpeg --ffprobe .searchi/media-runtime/bin/ffprobe --cpu-threads 1
./target/release/searchi search --db searchi.sqlite 'the recording about orange soil' --model-dir .searchi/models/embeddinggemma2 --embedding-worker .searchi/runtime/cpu/searchi-gemma-worker --cpu-threads 1
```

These are current interfaces, not executed Linux release evidence. Windows uses
`Release/searchi-gemma-worker.exe` and `ffmpeg.exe`/`ffprobe.exe` instead.
`embed` includes media by default and reports failures. Use `--text-only`
explicitly for document-only vectors. `setup` provisions Google assets, not
worker/decoder executables. Installed release CLIs discover decoders under
`media-runtime/bin` beside the CLI; explicit paired paths or
`SEARCHI_FFMPEG_PATH`/`SEARCHI_FFPROBE_PATH` override discovery. Search never
silently downloads missing helpers. CLI invocations load their own worker;
the desktop retains a prewarmed worker for interactive queries.

## Search performance

Normal searches show result counts, measured search time and time until results
are displayed. Enable **Performance details** in desktop settings to
inspect UI scheduling, native queue/lock time, keyword retrieval, actual Google
query inference, ANN/cache/filter work and ranking. Export the current trace as
local JSON for comparison; tracing sends no telemetry and excludes search text
and file paths. Nested stages and parallel retrieval lanes overlap.

For headless diagnostics, append `--performance --json` for basic metrics or
`--debug-performance --json` for the detailed response. Plain `--json` retains
the existing results-array format. See [timing boundaries, trace schema and
reproducible measurements](docs/PERFORMANCE.md).

## Development and release

The Rust engine, service, media adapter and CLI live under `crates/`; the Tauri
shell is `apps/desktop`. SQLite, image/jpeg-decoder, USearch/NumKong, and Tauri
provide established storage, decoding, ANN/SIMD and desktop facilities.
Extraction and inference use bounded isolated work with explicit errors.

```sh
cargo test --workspace --locked
cargo fmt --all --check
cargo clippy --workspace --all-targets --locked -- -D warnings
cargo run -p searchi-cli -- --help
```

See [desktop setup](apps/desktop/README.md), [build/platform constraints](docs/BUILDING.md),
[semantic bounds](docs/SEMANTIC.md), [executed validation](docs/VALIDATION.md),
and [brand direction](docs/BRAND.md). Native visual QA, operating-system builds,
macOS decoder packaging, installers, licensing distribution, signatures,
upgrades and representative production quality remain release gates.
Cross-platform source support does not mean signed macOS installers can be
built on Windows. CI declarations are not evidence of executed platform jobs.

Record benchmark hardware, corpus, cold/warm state and p95 latency. Never ship
signing credentials in source control. Licensed under [MIT](LICENSE).
Repository author: Karl.