Wishlist — natural-language Q&A over the archive

​

Motivating queries

• “when is my car insurance due?”
• “what was the total utilities amount paid in month of November last year?”
• “who signed the lease amendment?”

​

Design

​

Layer 1: retrieval — FTS5 + optional embeddings

​

Layer 2: constrained prompt + JSON extraction

You are answering a question over the operator's personal document
archive. You may ONLY use the excerpts below. If the answer isn't in
them, respond with {"answer": null, "reason": "no_matching_content"}.

Question: {{ question }}

Documents:
{% for d in docs %}
--- doc {{ d.id }} "{{ d.title }}" ({{ d.date }})
{{ d.excerpt }}
{% endfor %}

Return JSON: {answer, cited_doc_ids, confidence}.

• Excerpts, not full text. Snippet extraction reuses the search path’s FTS5 highlight. Keeps prompts small + hides the rest of the archive from the LLM even when the operator’s endpoint is their own local Ollama.
• Cited doc ids. The response must name the docs it read. Answers without citations get discarded. This is the load-bearing hallucination-check.
• Confidence field. Low-confidence answers (”< 0.5”) render as “I found some possibly-related docs; check them yourself” with the citations linked.

​

Layer 3: aggregation queries via structured extraction

Extract every payment record you can find. Return
[{doc_id, amount_cents, currency, paid_on}].

​

Layer 4: HTTP surface

POST /api/ask
  {
    "question": "when is my car insurance due?",
    "max_docs": 10                (optional, default 8)
  }
  →
  {
    "answer": "Your car insurance is due 2026-03-14.",
    "cited_doc_ids": [42, 91],
    "confidence": 0.87,
    "excerpts": [
      {"doc_id": 42, "snippet": "...policy expires <mark>2026-03-14</mark>..."}
    ],
    "elapsed_ms": 620
  }

​

Layer 5: MCP tool

​

Wire prerequisites

• #128 (sqlite-vec) landed. Semantic recall is optional but a big win.
• LLM endpoint acknowledged. Same llm.endpoint_url + llm.egress_ack config the classifier uses.
• New config: ASK_MAX_TOKENS (default 4096), ASK_TIMEOUT (default 30s), ASK_MAX_DOCS (default 8, cap 20). Everything goes through the existing settings table via the setup wizard.

​

Privacy invariants

• documents.content never leaves the server outside the LLM request. The response we cache locally is the LLM’s answer + the ids, not the excerpts we shipped.
• The excerpt window is bounded (default 400 chars per doc); we never send the whole document.
• A doc marked sensitivity IN ('confidential','restricted') is excluded from the retrieval pool by default. An override header or setting can flip that for personal instances; the archive admin explicitly toggles it.

​

What NOT to build

• Chat history. One question, one answer, no context carry. Multi-turn is a v2; single-shot covers the motivating queries.
• Fine-tuning. The LLM never sees the archive as training data.
• Automatic re-answer on doc mutation. Answers are a query-time computation; caching stale answers to a mutable archive is a correctness footgun.

​

Rollout order

1. Design doc lands ✅ (this file).
2. #128 sqlite-vec extension + embedding-at-ingest job.
3. POST /api/ask handler wiring FTS5 → prompt → LLM → JSON parse → cite-check.
4. MCP tool alias.
5. SPA route (Search screen grows an “Ask” tab).
6. Operator docs (how to bring up a local Ollama for offline use).