neuroskill-search

# NeuroSkill `search` and `compare` Commands --- ## LLM Tool Calls When calling these commands via the LLM `skill` tool, use `command` + `args`: ```json {"command": "search", "args": {"start_utc": 1740412800, "end_utc": 1740415500, "k": 5}} {"command": "compare", "args": {"a_start_utc": 1740380100, "a_end_utc": 1740382665, "b_start_utc": 1740412800, "b_end_utc": 1740415510}} ``` ### Cross-Modal Follow-Ups After a `search` returns neighbor timestamps, you can bridge to other modalities: - **See what was on screen** at a neural-search hit: `{"command": "screenshots_around", "args": {"timestamp": <neighbor_timestamp_unix>}}` - **Find labels near** a neural-search hit: `{"command": "search_labels", "args": {"query": "focus"}}` filtered by time - **Full graph search** from a text description to EEG to labels: `{"command": "interactive_search", "args": {"query": "deep focus"}}` --- ## `search` — Neural Similarity Search Find EEG moments from your entire history that are neurally similar to a query range. Uses approximate nearest-neighbor (ANN) search over the 5-second embedding HNSW index. Auto-range: when no `--start`/`--end` flags are given, the CLI automatically uses your most recent session and prints a `rerun:` line you can copy-paste. ```bash npx neuroskill search # auto: last session, k=5 npx neuroskill search --k 10 # 10 nearest neighbors npx neuroskill search --start 1740412800 --end 1740415500 npx neuroskill search --start 1740412800 --end 1740415500 --k 20 npx neuroskill search --json | jq '.result.results | length' npx neuroskill search --json | jq '.result.results[0].neighbors[0]' ``` **HTTP (daemon API):** ```bash curl -s -X POST http://127.0.0.1:$PORT/v1/search/eeg \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"startUtc":1740412800,"endUtc":1740415500,"k":5}' ``` ### JSON Response ```jsonc { "command": "search", "ok": true, "result": { "query_count": 541, "searched_days": ["20260224", "20260223"], "analysis": { "distance_stats": { "min": 0.0231, "mean": 0.1842, "max": 0.3901, "stddev": 0.0612 }, "time_span_hours": 744.3, "neighbor_metrics": { "focus": 0.67, "relaxation": 0.43, "hr": 67.4 }, "temporal_distribution": { "8": 142, "9": 198 }, "top_days": [["20260222", 312], ["20260221", 289]] }, "results": [ { "timestamp_unix": 1740412800, "neighbors": [ { "distance": 0.0231, "timestamp_unix": 1740320040, "date": "20260222", "device_name": "Muse-A1B2", "labels": [{ "text": "morning focus block" }], "metrics": { "focus": 0.73, "relaxation": 0.41, "hr": 66.2, "rel_alpha": 0.34 } } ] } ] } } ``` ### Hidden Fields (visible only with `--full` or `--json`) | Hidden field | Contents | |---|---| | `result.results[]` | Full list of query epochs with complete `neighbors[]` arrays | | `result.analysis.temporal_distribution` | Hour-of-day match counts as raw numbers | | `result.analysis.top_days` | `[["YYYYMMDD", count], …]` | ```bash npx neuroskill search --json | jq '.result.results | length' npx neuroskill search --json | jq '.result.results[0].neighbors' npx neuroskill search --json | jq '[.result.results[].neighbors[]] | sort_by(.distance) | .[0]' npx neuroskill search --json | jq '.result.analysis.temporal_distribution' ``` > **Note:** Only epochs with computed EEG embeddings are searched. Use `embedding-count` to check coverage. Background re-embedding runs automatically when the device is idle (configurable in Settings → EEG Model). --- ## `compare` — A/B Session Comparison Side-by-side A/B comparison of two sessions. Returns averaged metrics for both ranges, delta values, and trend direction for every metric. Also enqueues a 3D UMAP projection. Auto-range: uses your last two sessions as A (older) and B (newer). ```bash npx neuroskill compare # auto: last 2 sessions npx neuroskill compare --a-start 1740380100 --a-end 1740382665 \ --b-start 1740412800 --b-end 1740415510 npx neuroskill compare --json npx neuroskill compare --json | jq '{a_focus: .a.focus, b_focus: .b.focus}' npx neuroskill compare --json | jq '.insights.deltas.focus' npx neuroskill compare --json | jq '.insights.improved' npx neuroskill compare --json | jq '.insights.declined' ``` **HTTP (daemon API):** ```bash curl -s -X POST http://127.0.0.1:$PORT/v1/analysis/compare \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "aStartUtc": 1740380100, "aEndUtc": 1740382665, "bStartUtc": 1740412800, "bEndUtc": 1740415510 }' | jq '{a_focus: .a.focus, b_focus: .b.focus}' ``` ### JSON Response ```jsonc { "ok": true, "a": { "focus": 0.62, "relaxation": 0.45, "hr": 72.1, "n_epochs": 513 /* ... */ }, "b": { "focus": 0.71, "relaxation": 0.38, "hr": 68.4, "n_epochs": 541 /* ... */ }, "sleep_a": { "total_epochs": 0 /* ... */ }, "sleep_b": { "total_epochs": 0 /* ... */ }, "insights": { "n_epochs_a": 513, "n_epochs_b": 541, "deltas": { "focus": { "a": 0.62, "b": 0.71, "abs": 0.09, "pct": 14.5, "direction": "up" }, "relaxation": { "a": 0.45, "b": 0.38, "abs": -0.07, "pct": -15.6, "direction": "down" } }, "improved": ["focus", "meditation", "engagement"], "declined": ["relaxation", "hr"] }, "umap": { "queued": true, "job_id": 5, "estimated_secs": 14, "n_a": 513, "n_b": 541 } } ``` ### Hidden Fields | Hidden field | Contents | |---|---| | `a` / `b` | All ~50 averaged metrics for each session | | `sleep_a` / `sleep_b` | Full sleep staging summary for each range | | `insights.deltas` | Full delta table for every metric | | `umap` | Enqueued job info — use with `umap` command | ```bash npx neuroskill compare --json | jq '.a' # all metrics for A npx neuroskill compare --json | jq '.b' # all metrics for B npx neuroskill compare --json | jq '.insights.deltas' # every metric delta npx neuroskill compare --json | jq '.insights.deltas | to_entries | sort_by(.value.pct) | reverse' npx neuroskill compare --json | jq '.umap.job_id' # use with umap --json ```