Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
55 changes: 55 additions & 0 deletions .tmp/proof/document-reindex-api.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@
Offline fixture capture, local SQLite and Chroma, fixed embeddings.
Slack authentication mocked; Slack API calls and Socket Mode blocked.

document-reindex-retrieval-before.json
POST /api/retrieval/preview {"question":"How do I reset VPN?"}
{"question":"How do I reset VPN?","channel_id":null,"top_k":5,"max_distance":null,"items":[]}

document-reindex-retrieval-after.json
POST /api/retrieval/preview {"question":"How do I reset VPN?"}
{"question":"How do I reset VPN?","channel_id":null,"top_k":5,"max_distance":null,"items":[{"content":"Reset VPN via IT portal.","metadata":{"chunk":0,"document_id":1,"source":"offline fixture","title":"VPN recovery guide"},"distance":1.0}]}

$ ['curl', '--max-time', '5', '-sS', '-i', 'http://127.0.0.1:18053/health']
HTTP/1.1 200 OK
date: Mon, 16 Nov 2026 02:16:49 GMT
server: uvicorn
content-length: 20
content-type: application/json

{"status":"healthy"}

$ ['curl', '--max-time', '5', '-sS', '-i', 'http://127.0.0.1:18053/api/documents?limit=20&offset=0']
HTTP/1.1 200 OK
date: Mon, 16 Nov 2026 02:16:49 GMT
server: uvicorn
content-length: 195
content-type: application/json

{"items":[{"id":1,"title":"VPN recovery guide","source":"offline fixture","created_at":"2026-11-16T01:35:07.372068","content_preview":"Reset VPN via IT portal."}],"total":1,"limit":20,"offset":0}

$ ['curl', '--max-time', '5', '-sS', '-i', 'http://127.0.0.1:18053/api/documents/1']
HTTP/1.1 200 OK
date: Mon, 16 Nov 2026 02:16:50 GMT
server: uvicorn
content-length: 185
content-type: application/json

{"id":1,"title":"VPN recovery guide","content":"Reset VPN via IT portal.","source":"offline fixture","created_at":"2026-11-16T01:35:07.372068","updated_at":"2026-11-16T01:35:07.372085"}

$ ['curl', '--max-time', '5', '-sS', '-i', '-X', 'POST', 'http://127.0.0.1:18053/api/documents/1/index']
HTTP/1.1 200 OK
date: Mon, 16 Nov 2026 02:16:50 GMT
server: uvicorn
content-length: 50
content-type: application/json

{"id":1,"message":"Document indexed successfully"}

$ ['curl', '--max-time', '5', '-sS', '-i', 'http://127.0.0.1:18053/api/retrieval/preview', '-H', 'Content-Type: application/json', '-d', '{"question":"How do I reset VPN?"}']
HTTP/1.1 200 OK
date: Mon, 16 Nov 2026 02:16:50 GMT
server: uvicorn
content-length: 241
content-type: application/json

{"question":"How do I reset VPN?","channel_id":null,"top_k":5,"max_distance":null,"items":[{"content":"Reset VPN via IT portal.","metadata":{"chunk":0,"document_id":1,"source":"offline fixture","title":"VPN recovery guide"},"distance":1.0}]}
280 changes: 280 additions & 0 deletions .tmp/proof/document-reindex-backend-tests.txt

Large diffs are not rendered by default.

26 changes: 26 additions & 0 deletions .tmp/proof/document-reindex-browser-failure.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
### Result
#25 [POST] http://127.0.0.1:18053/api/documents/1/index

General
status: [503] Service Unavailable
duration: 123ms
type: fetch
mimeType: application/json

Request headers
sec-ch-ua-platform: "macOS"
referer: http://127.0.0.1:3053/
user-agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) HeadlessChrome/157.0.0.0 Safari/537.36
sec-ch-ua: "Not-A.Brand";v="99", "Google Chrome";v="157", "Chromium";v="157"
sec-ch-ua-mobile: ?0

Response headers
access-control-allow-origin: *
content-length: 83
date: Mon, 16 Nov 2026 01:36:29 GMT
content-type: application/json
server: uvicorn
access-control-allow-credentials: true

Run `response-body 25` to read the response body.
{"detail":{"message":"Document saved but indexing is unavailable","document_id":1}}
26 changes: 26 additions & 0 deletions .tmp/proof/document-reindex-browser-success.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
### Result
#26 [POST] http://127.0.0.1:18053/api/documents/1/index

General
status: [200] OK
duration: 90ms
type: fetch
mimeType: application/json

Request headers
sec-ch-ua-platform: "macOS"
referer: http://127.0.0.1:3053/
user-agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) HeadlessChrome/157.0.0.0 Safari/537.36
sec-ch-ua: "Not-A.Brand";v="99", "Google Chrome";v="157", "Chromium";v="157"
sec-ch-ua-mobile: ?0

Response headers
access-control-allow-origin: *
content-length: 50
date: Mon, 16 Nov 2026 01:36:46 GMT
content-type: application/json
server: uvicorn
access-control-allow-credentials: true

Run `response-body 26` to read the response body.
{"id":1,"message":"Document indexed successfully"}
Binary file added .tmp/proof/document-reindex-error.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
51 changes: 51 additions & 0 deletions .tmp/proof/document-reindex-frontend-tests.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@
[test-frontend] $ bun run test
$ bun test --preload ./tests/setup.ts
bun test v1.3.5 (1e86cebd)

tests/documents.test.tsx:
(pass) documents load on opening the tab, search only on submit, and retain the applied query while paging [329.42ms]
(pass) document client encodes literal search text, keeps source filters, and omits blank queries [0.26ms]
(pass) documents show loading, retry the submitted query after a list error, and distinguish empty searches [28.26ms]
(pass) documents render saved content as text and retry detail failures without losing results [60.22ms]
(pass) documents ignore stale successful and failed list responses after a newer search [20.04ms]
(pass) documents ignore late details after another selection, a page change, and clearing a search [198.86ms]
(pass) documents abort requests on leaving the tab and ignore late responses when reopened [21.95ms]

tests/document-indexing.test.tsx:
(pass) re-indexing requires an explicit click, posts the saved ID once while pending, and keeps the content visible [50.22ms]
(pass) re-indexing reports a safe failure for 404 and retries the same saved document [307.03ms]
(pass) re-indexing reports a safe failure for 422 and retries the same saved document [70.49ms]
(pass) re-indexing reports a safe failure for 503 and retries the same saved document [21.88ms]
(pass) re-indexing reports a safe failure for network and retries the same saved document [23.60ms]
(pass) re-indexing ignores a late success after a selection change [63.04ms]
(pass) re-indexing ignores a late failure after a selection change [109.90ms]
(pass) re-indexing ignores a late success after a search change [52.82ms]
(pass) re-indexing ignores a late failure after a search change [42.73ms]
(pass) re-indexing ignores a late success after a page change [263.83ms]
(pass) re-indexing ignores a late failure after a page change [98.40ms]
(pass) re-indexing ignores a late success after a tab change [42.44ms]
(pass) re-indexing ignores a late failure after a tab change [37.68ms]

tests/retrieval.test.tsx:
(pass) retrieval waits for a non-blank question and submits trimmed optional scope [13.61ms]
(pass) retrieval omits blank scope, preserves rank and raw distances, and shows an unset cutoff [7.13ms]
(pass) retrieval disables inputs and duplicate submissions while loading [6.24ms]
(pass) retrieval shows an empty result and a zero distance cutoff [27.24ms]
(pass) retrieval replaces a failed request with a successful retry [14.17ms]
(pass) retrieval clears old results when the question or channel changes [387.87ms]
(pass) retrieval aborts on leaving the tab and ignores late responses after reopening [40.56ms]
(pass) retrieval renders chunk and metadata markup as text [14.04ms]

tests/conversations.test.tsx:
(pass) loads only on opening the tab and paginates summaries and chronological turns independently [169.04ms]
(pass) shows loading, an empty page and a list error with a working retry [6.52ms]
(pass) retries missing conversation details without discarding the list [48.23ms]
(pass) ignores stale detail responses after selecting another conversation [25.13ms]
(pass) ignores stale errors after leaving and reopening the tab [14.87ms]
(pass) renders stored markup as text and supports missing metadata [18.46ms]
(pass) encodes conversation IDs in detail request paths [1.76ms]

35 pass
0 fail
261 expect() calls
Ran 35 tests across 4 files. [3.41s]
Binary file added .tmp/proof/document-reindex-mobile.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
22 changes: 22 additions & 0 deletions .tmp/proof/document-reindex-runtime-tests.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
[test-runtime] $ node --test
✔ real Pi SQLite storage preserves answers, deduplicates retries, and retains conversation history (139.641791ms)
✔ outbox resumes after restart without regenerating answer; retry admits only one job (7.461334ms)
Warning: Detected unsettled top-level await at file:///Users/johnny/.paseo/worktrees/0x03bguv/spiffy-catfish/runtime/fixtures/interrupted.mjs:12
await answerJob(JSON.parse(process.argv[3]), {
^



✔ a process killed during generation resumes the admitted Pi submission (607.205292ms)
✔ pinned operator answer is delivered without calling the model (2.92625ms)
✔ model failure sends a persisted Slack failure notification (0.764ms)
✔ runtime starts with openai catalog and protects job routes (2035.927208ms)
✔ runtime starts with mimo catalog and protects job routes (878.3355ms)
ℹ tests 7
ℹ suites 0
ℹ pass 7
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 3118.980458
45 changes: 45 additions & 0 deletions .tmp/proof/document-reindex-sitecustomize.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
"""Local proof process only: deny Slack and use fixture Chroma embeddings."""
from pathlib import Path
from slack_sdk import WebClient
from slack_bolt.adapter.socket_mode import SocketModeHandler


def blocked(*args, **kwargs):
raise AssertionError("Live Slack calls and Socket Mode are forbidden in this proof process")


WebClient.auth_test = lambda *args, **kwargs: {
"ok": True, "bot_id": "BTEST", "user_id": "UTEST", "team_id": "TTEST",
}
WebClient.api_call = blocked
SocketModeHandler.start = blocked

import chromadb
from chromadb.config import Settings as ChromaSettings
from chromadb.telemetry.product.posthog import Posthog
from langchain_community.vectorstores import Chroma
from langchain_core.embeddings import Embeddings
from app.vector_store import vector_store

Posthog.capture = lambda *args, **kwargs: None
proof_dir = Path(__file__).resolve().parent


class FixedEmbeddings(Embeddings):
def embed_documents(self, texts):
# A marker file injects a recoverable provider failure for the transcript.
if (proof_dir / "fail-embedding").exists():
raise RuntimeError("Fixture embedding outage")
return [[float(len("Reset VPN via IT portal.") - len(text) + 1), 1.0] for text in texts]

def embed_query(self, text):
return [0.0, 1.0]


vector_store.vector_store = Chroma(
client=chromadb.PersistentClient(
path=str(proof_dir / "chroma"), settings=ChromaSettings(anonymized_telemetry=False),
),
collection_name="document-retry-proof", embedding_function=FixedEmbeddings(),
)
vector_store._initialized = True
Binary file added .tmp/proof/document-reindex-success.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
7 changes: 7 additions & 0 deletions docs/retrieval.md
Original file line number Diff line number Diff line change
Expand Up @@ -89,6 +89,13 @@ result at a width of 390 pixels.

## Retry saved document indexing

In the dashboard, open **Documents**, select a saved document and choose
**Re-index document**. Its content stays visible while indexing runs. The action
shows success or a retryable error and does not create another document. The
list shows saved records, not a persistent indexing status. Leaving the detail
view stops waiting for the result; work already started on the backend may still
finish. The configured embedding provider can charge for this operation.

`POST /api/documents/{document_id}/index` indexes the saved title, content and
source without creating or modifying a database record. Find the ID with
`GET /api/documents`. A missing record returns HTTP 404; invalid legacy title,
Expand Down
40 changes: 38 additions & 2 deletions frontend/components/documents-panel.tsx
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
'use client'

import { useEffect, useState } from 'react'
import { getDocument, listDocuments, type DocumentDetail, type DocumentListResponse } from '@/lib/api'
import { getDocument, listDocuments, reindexDocument, type DocumentDetail, type DocumentListResponse } from '@/lib/api'

const PAGE_SIZE = 20
const buttonClass = 'min-h-11 rounded-lg border border-gray-300 px-4 py-2 text-sm text-gray-700 hover:bg-gray-50 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-blue-600 disabled:opacity-40 disabled:cursor-not-allowed'
Expand All @@ -11,6 +11,41 @@ function formatDate(value?: string | null) {
return new Date(value).toLocaleDateString('en-AU', { day: 'numeric', month: 'short', year: 'numeric' })
}

function DocumentIndexAction({ documentId }: { documentId: number }) {
const [attempt, setAttempt] = useState(0)
const [phase, setPhase] = useState<'idle' | 'pending' | 'success' | 'error'>('idle')

useEffect(() => {
if (!attempt) return
let cancelled = false
const controller = new AbortController()
reindexDocument(documentId, controller.signal)
.then(() => { if (!cancelled) setPhase('success') })
.catch(() => { if (!cancelled) setPhase('error') })
return () => { cancelled = true; controller.abort() }
}, [attempt, documentId])

return (
<div className="mt-5 border-t border-blue-100 pt-4">
<p className="text-sm text-gray-600 mb-3">Re-index this saved content for retrieval. This uses the configured embedding provider and may incur a cost.</p>
<button type="button" className={buttonClass} disabled={phase === 'pending'}
onClick={() => {
if (phase === 'pending') return
setPhase('pending')
setAttempt((value) => value + 1)
}}>
{phase === 'pending' ? 'Re-indexing...' : 'Re-index document'}
</button>
<p role="status" className="text-sm text-gray-700 mt-3">
{phase === 'pending' && 'Indexing saved content...'}
{phase === 'success' && 'Document indexed successfully.'}
</p>
{phase === 'error' && <p role="alert" className="text-sm text-red-700 mt-3">Could not index this document. Your saved content is unchanged. Check that the document is still available and the indexing service is running, then try again.</p>}
<p className="text-xs text-gray-600 mt-3">Leaving this view stops waiting for the result. Indexing already started may still finish.</p>
</div>
)
}

export default function DocumentsPanel() {
const [draft, setDraft] = useState('')
const [request, setRequest] = useState({ query: '', offset: 0 })
Expand Down Expand Up @@ -58,7 +93,7 @@ export default function DocumentsPanel() {
<section aria-labelledby="documents-title" className="max-w-3xl mx-auto bg-white rounded-xl shadow-lg p-6 sm:p-8">
<h2 id="documents-title" className="text-2xl font-semibold text-gray-800 mb-2">Knowledge Base Documents</h2>
<p className="text-gray-600 mb-6">
Indexed documents used for retrieval-augmented generation. Select one to read its full content.
Saved documents for retrieval-augmented generation. Select one to read or re-index its content.
</p>
<form onSubmit={(event) => { event.preventDefault(); load(draft.trim()) }} className="mb-6">
<label htmlFor="document-search" className="block font-medium text-gray-800 mb-2">Search documents</label>
Expand Down Expand Up @@ -126,6 +161,7 @@ export default function DocumentsPanel() {
<h3 className="text-lg font-semibold text-gray-800 mb-1">{detail.title}</h3>
<p className="text-sm text-gray-600 mb-3">{detail.source}{formatDate(detail.created_at) && ` - ${formatDate(detail.created_at)}`}</p>
<p className="text-gray-700 whitespace-pre-wrap">{detail.content}</p>
<DocumentIndexAction key={detail.id} documentId={detail.id} />
</div>
)}
</section>
Expand Down
9 changes: 9 additions & 0 deletions frontend/lib/api.ts
Original file line number Diff line number Diff line change
Expand Up @@ -180,6 +180,15 @@ export async function getDocument(id: number, signal?: AbortSignal): Promise<Doc
return response.json()
}

export async function reindexDocument(id: number, signal?: AbortSignal): Promise<{ id: number; message: string }> {
const response = await fetch(`${API_BASE_URL}/api/documents/${id}/index`, {
method: 'POST',
signal,
})
if (!response.ok) throw new Error(`API error: ${response.status}`)
return response.json()
}

export async function addDocument(doc: DocumentRequest): Promise<{ id: number; message: string }> {
const response = await fetch(`${API_BASE_URL}/api/documents`, {
method: 'POST',
Expand Down
Loading
Loading