DeskPilot — Local‑first Desktop Filing Copilot

Project write‑up, formatted in Markdown

1) Inspiration

Our Desktops kept turning into junk drawers—screenshots, homework, invoices—despite having “good” folder structures. We wanted a helper that:

Watches the Windows Desktop and pops up a “File Pilot” window for each new file.
Suggests a destination only from a user‑maintained whitelist of folders.
- Each folder has a short description (e.g., “study notes for EECS”, “invoices”).
- Suggestions are restricted to this whitelist for safety and control.
Shows a rationale and confidence for every suggestion.
Per‑file actions: Accept (move), Decline (choose a whitelist folder), or Ignore.
In‑app Move Log lists every action; each row has an Undo button that restores the file.
Safe moves with Windows‑style de‑dupe names (e.g., file (2).pdf).
Everything runs locally; no file contents are uploaded.

Endpoints

Endpoint	Purpose
`/health`	Instant health check (never blocks)
`/suggest`	Returns folder, confidence, and rationale
`/feedback`	Learns from accept/decline (updates weights)
`/whitelist/*`	Add, remove, clear, and reindex whitelist

Storage

Signals are combined into a single score per whitelisted folder:

Extension signal: folders that previously received this file extension
Token signal: folders associated with name tokens (e.g., “invoice”, “EECS”)
Recent signal: where similar items went recently
Semantic signal: cosine similarity between (a) an embedding of the file name/keywords and (b) an embedding of the folder’s description (MiniLM all‑MiniLM‑L6‑v2)
Content peek (conditional): for .txt/.docx only, and only if the filename signal is weak; we read a tiny snippet and add some content tokens at a lower weight (+ 0.20·w). No content is stored.

Confidence is derived from the margin between the top two folder scores.

Explainability: rationale strings list which signals fired (e.g., “semantic match to Invoices…”, “extension .pdf seen before”).

Accept → strengthen weights for the chosen folder.
Decline → user picks the correct whitelist folder; shift weights toward that folder.
Recent tuples get a small nudge to bias near‑future suggestions.

Challenge	Fix
Hidden agent crashes with `pythonw.exe`	Launch `python.exe` in a minimized window and redirect stdout/stderr to a log file.
First‑run model download stalls (sentence‑transformers)	Extend startup wait; build the embedding index lazily on the first `/suggest` call.
State pitfalls in uAgents storage	Never store the embedding model or numpy arrays in KV; keep them in‑process memory only. Persist only JSON‑safe data (rules, whitelist). Rebuild index on demand.

Local‑first + small models often beat cloud LLMs for trust, privacy, and latency.
Explainability and Undo are as critical as raw accuracy for adoption.
Health checks must be instant; do expensive work lazily.
Simple online learning (tiny weights) personalizes quickly without complexity.

Confidence thresholding: auto‑file when very confident; prompt otherwise.
System‑tray notifications with inline actions.
Signed installer and autostart; optional portable mode.
(Future exploration) On‑device LLM for richer folder description understanding.