From 70746ef428818b36e99904416b0be66c5531a6fb Mon Sep 17 00:00:00 2001 From: karl Date: Mon, 12 Oct 2026 20:04:20 +0200 Subject: [PATCH] docs: rewrite README for searchi users --- README.md | 252 +++++++++++++++++++++++------------------------------- 1 file changed, 106 insertions(+), 146 deletions(-) diff --git a/README.md b/README.md index bb61f93..384bc37 100644 --- a/README.md +++ b/README.md @@ -1,183 +1,143 @@ -# searchi +

+ searchi app icon +

-**Find what matters. Locally.** +

searchi

+

Find what matters. Locally.

+

Your documents, photos, music and movies. One place to search.

-Local desktop search for Windows, macOS and Linux, under active development. -Production readiness is tracked in [the roadmap](docs/ROADMAP.md). +You remember what was in the file. searchi helps you find it—even when you +don't remember what it was called. -![searchi finding a supplier agreement and its matching passage](docs/screenshots/search-light.png) +Search a filename, a phrase, or describe what you're looking for in your own +words. See the relevant passage or media preview alongside your results, +then open the file. Your files stay on your device. -*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.* +![searchi finding a supplier agreement and highlighting its matching passage](docs/screenshots/search-light.png) -## What works +*“cancel the supplier partnership” finds the agreement and brings its +termination passage into view.* -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. +## Find it your way -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. +| What you remember | What to try | +| --- | --- | +| The file's name | `Supplier agreement.pdf` | +| Words inside a document | `sixty days written notice` | +| What a document is about | `cancel the supplier partnership` | +| A photo's subject | `mountains reflected in calm water` | +| An artist or song title | `Nina Simone` or `Feeling Good`, if present in your music tags | +| A scene or sound | Try `rain and thunder` or `a boat crossing a lake` in experimental media search | -**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). +**Names, words and meaning work together.** Exact filenames help you get +straight to a known file. Content search finds the words inside it. Google +EmbeddingGemma 2 adds local semantic search for related meaning, images and +sound. -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. +Use **All files** to narrow results by folder, file extension, modification +date, file size or media duration. Choose a result to inspect it before opening. -## See searchi working +## A little less searching. A little more finding. -### A familiar dark theme +Matching words stand out in the results and document preview. PDF results +retain their page number; text results show the relevant passage. If you'd +like an explanation, expand the small **Why this result?** detail. -![The same real document search in searchi's dark theme](docs/screenshots/search-dark.png) +![searchi's dark theme with search results and a document passage](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. +Light and dark themes follow your system preference. Keyboard navigation, +short transitions and reduced-motion support keep the interface familiar +and comfortable. -### Find a photo from what you remember +![searchi finding and previewing a mountain lake photograph](docs/screenshots/media-search.png) -![A natural-language search finding the mountain lake photo](docs/screenshots/media-search.png) +*“mountains reflected in calm water” searches the pictures themselves, +so a useful filename isn't required.* -Actual image pixels are indexed by the Google model. The selected photo is -loaded from the indexed fixture file for preview. +Images open in the preview. Audio and video have playback controls, and +matching media segments can jump to their approximate location. Nothing +autoplays when you select a result. -### Understand where the time goes +## Get searchi -![searchi's detailed performance panel showing real search and inference timings](docs/screenshots/performance-details.png) +**searchi is in active development. Ready-to-install downloads have not been +published yet.** Windows, macOS and Linux are the intended desktop platforms; +packaged releases and platform testing are still being completed. -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. +Check the [releases page](https://tea.karlcom.de/karl/searchi/releases) for +published downloads. If you want to try the current source version, follow +the [build and launch instructions](docs/BUILDING.md). Building it currently +requires development tools. -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. +### Your first search -## Copy-and-paste setup prompt +Once searchi is running: -```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. -``` +1. Choose **Add folder**, browse to the folder you want to search, then choose + **Index folder**. +2. Start with a filename or words you remember. These searches become + available as files are indexed. +3. Let the local search model finish preparing in the background. First + setup downloads approximately **865 MB** and needs an internet connection. + The app shows its progress; semantic search becomes available when setup + and indexing finish. +4. Describe what you're looking for, select a result and inspect the preview. + Press **Enter** to open the selected file in its usual application. -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. +How quickly a folder becomes searchable depends on its size and contents. +The desktop keeps its search model warm for subsequent searches. +Use **Reindex** after adding or changing files in an indexed folder. -## Headless setup +## Private by design -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: +You choose the folders to index. File contents, previews and search processing +stay local. Your searches aren't sent to a cloud AI service. -```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 -``` +The model download happens during setup. Once it's ready, semantic inference +runs on your device. The local search index contains information from your +files, so protect it as you would the files themselves. -On native Linux, unified document/media indexing and hybrid search use: +## Documents and media -```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 -``` +| Files | Current support | +| --- | --- | +| Documents | PDF, DOCX, plain text, Markdown and source code | +| Photos | JPEG, PNG, WebP and BMP | +| Music and audio | MP3, FLAC, WAV, M4A, OGG, Opus, AAC and AIFF | +| Movies and video | MP4, MKV, MOV, AVI, WebM, M4V and MPEG | -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. +**Media search is experimental.** Image, audio and video search are implemented, +but relevance still needs improvement. Spoken topics can be missed, music +matches can be too broad, and video sampling can miss a brief scene. Media +timestamps identify approximate segments, rather than an exact spoken word. +Playback also depends on the formats your system supports; you can open a +file in its usual player if the preview cannot play it. -## Search performance +## Fast should feel fast -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. +Each search shows a compact result count and timing summary. Want to look +closer? Enable **Performance details** in settings for a breakdown of where +the time went. Copied timing reports exclude your search text and file paths. -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). +
+See the optional performance view -## Development and release +![searchi showing measured search timings in its optional performance panel](docs/screenshots/performance-details.png) -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 -``` +## Help shape searchi -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. +Found a problem, or searched for something that should have been easy to find? +[Report it or suggest an improvement](https://tea.karlcom.de/karl/searchi/issues). +Describe what you expected and what happened; use made-up examples if your +files contain private information. -Record benchmark hardware, corpus, cold/warm state and p95 latency. Never ship -signing credentials in source control. Licensed under [MIT](LICENSE). -Repository author: Karl. +For contributors: [building searchi and the headless Linux CLI](docs/BUILDING.md) +· [roadmap](docs/ROADMAP.md) · [search-quality evaluation](docs/MEDIA-QUALITY.md). + +The screenshots show the working interface searching real example files with +the local Google model. They are browser captures of the app interface; +operating-system window borders are omitted. [Photo credits](fixtures/media/README.md). + +Made by Karl. Open source under the [MIT license](LICENSE).