The Library browser
The Library tab is where you see every file Golden Retriever has ingested, which of them completed successfully, and what’s still missing. When something goes wrong — rate limits, unsupported formats, permission issues — the Library tells you which file failed and why.
The pipeline timeline banner
Section titled “The pipeline timeline banner”Whenever ingestion, embedding, upload, or any retry is running — no matter which button you pressed — a full-width banner sits at the top of the Library tab. It walks six stages:
- Scan — discovering files in your watched folders
- Ingest — chunking each file
- Extract — pulling plain-text content where possible
- Describe — generating visual or transcript descriptions for media
- Upload — sending source files to GCS when you’re on Vertex AI
- Embed — calling the embedding model and storing vectors
Completed steps turn green and tick. The current step is highlighted with its full label (“Embedding chunk 42 / 132”). A progress bar under the stepper moves in step-fraction. When Gemini’s free-tier pacing slows the run, an orange Free tier - slowed pill appears on the right of the banner.
Cancel stops the run between stages — the pipeline finishes the in-flight chunk, rolls up what it did, and resets. When the run ends, the banner persists with a green ✓ (success), orange ⚠ (completed with errors) or red ✗ (failed) state until you dismiss it with the × button.
Layout
Section titled “Layout”The Library uses three panes.
- Left — Folders list with Library Overview pinned at the top.
- Middle — Contents of the selected pane. In Overview mode this is the dashboard; when you click a folder, it becomes a table of files in that folder.
- Right — Details for the selected row. For Overview that’s a Health + Quick Actions panel; for a folder-selected file it’s a preview and per-chunk inspection.
You can drag any pane divider to resize.
Library Overview
Section titled “Library Overview”Click Library Overview (top of the folders list) to see the whole library at a glance.
The dashboard shows:
| Card | What it tells you |
|---|---|
| KPI tiles | Total files, chunks, how many have content (“Indexed”), how many have failed. |
| Files by Type | Per-format progress bars — green means every chunk of that type has content, yellow partial, red none. |
| Pipeline Status | Live state while ingestion is running, plus embedding progress and error counts. |
| Qdrant | Vector store health and total point count. |
The right-hand Health panel surfaces anything needing attention: a red card for failed chunks that opens the Failed Chunks drilldown, an orange card if Gemini has throttled ingestion with an Upgrade link.
Browsing a folder
Section titled “Browsing a folder”Click any folder in the sidebar to see its contents.
The middle table shows:
- Name — filename with a type icon.
- Type — PDF, IMAGE, VIDEO, AUDIO, CSV, etc.
- Chunks — how many chunks have content out of the total (e.g.
7 / 7or0 / 2). - Status — one of Indexed (green), Partial (yellow), Failed (red), Pending (grey).
Click any column header to sort. Drag column edges to resize. Use the Type filter (funnel icon, top right) to isolate one file type at a time, or flip Failures only to focus on what needs attention.
Inspecting a file
Section titled “Inspecting a file”Click any file in the table to open its detail pane on the right.
The pane contains:
- Summary — status, chunk count, type, size. Open launches the file in its default app. Reveal in Finder shows it in a Finder window.
- Preview — inline player or Quick Look. Images render directly; audio and video load with native macOS playback controls (play/pause/scrub/volume); PDFs and docs use Quick Look.
- Chunks — one card per chunk with badges (Described / Text / Embedded), the description or text content, and any error message.
When the file’s last ingestion failed, an orange banner appears at the top with the error and a Retry button that re-runs the pipeline on that file only.
Retrying failed content
Section titled “Retrying failed content”Three levels of retry, and two ways to get to the Failed Chunks drilldown.
Review every failure
Section titled “Review every failure”Click either of these to open the Failed Chunks pane:
- The red N chunks failed ingestion card in the Overview right panel (Health section).
- The Failed KPI tile in the Overview middle pane (shows a chevron when
failed > 0).
Each row shows the filename, location, and the exact error text returned by the pipeline — the same message you would have seen in Diagnostics, but pinned to the chunk that failed. Use the folder and open buttons on each row to jump to the file in Finder or open it in its default app.
Retry all failures
Section titled “Retry all failures”Click Retry All in the Failed Chunks header (or Retry Failed in the Overview right panel). This resets every failed chunk across the library and runs the full pipeline. The timeline banner stays visible above the pane so you can watch progress.
Retry one file
Section titled “Retry one file”Open the file’s detail pane and click Retry on the error banner. This resets only that file’s failed (and stuck-pending) chunks and runs the pipeline scoped to that file only — your other files are not touched.
Reprocess one file from scratch
Section titled “Reprocess one file from scratch”The ··· menu next to Open / Reveal in Finder has Reprocess from scratch. This clears every chunk for the file (not just failed ones), then re-runs the pipeline for that file. Use this when a previously-described file needs to pick up changes that retry won’t trigger — for example, after a transcription model or prompt update.
Rescan All
Section titled “Rescan All”Rescan All (Overview right panel) runs the full pipeline regardless of current state — useful when you’ve added new folders or want to re-check recent changes.
When Gemini’s rate limit hits
Section titled “When Gemini’s rate limit hits”Free-tier Gemini has a tight per-minute quota. When Golden Retriever detects a 429 response from Google, ingestion pauses across both embedding and media-description — a banner appears at the top of the Library tab telling you how long the pause lasts.
- Upgrade plan opens the right surface for your auth mode — Google AI Studio if you’re on a Gemini API key, Google Cloud quotas console if you’re on Vertex AI.
- Retry now clears the throttle window early if you know the reset has happened.
If nothing you do triggers a 429, you’ll never see the banner.
After upgrading: switch to Paid tier in Settings
Section titled “After upgrading: switch to Paid tier in Settings”Once you’ve enabled billing on your Gemini project, head to Settings → Cloud → Plan and switch from Free to Paid. That removes the precautionary inter-batch throttle that the free tier needs and stops the orange “Free tier — slowed” pill from appearing on the pipeline banner. You’ll still get a real throttle banner if Google sends a 429 — this only suppresses the preventative slowdown.
Transcription language
Section titled “Transcription language”Audio and video are transcribed by Google Gemini, which auto-detects the spoken language on each pass. The file detail pane shows the detected language under the file’s metadata (e.g. Italian with an “auto” pill). The detected language is cached on the file so chunks of the same file share it.
If Gemini gets the language wrong, open the file in the right pane, click Change on the Language row, pick the correct language, and confirm Retry. That re-transcribes just that file with your forced language hint and re-embeds it. Pick Auto-detect to clear the override and let Gemini decide again.
Every transcription event is logged under the transcription category in Settings → Diagnostics. If you’re filing a bug about a nonsensical transcript, attach the relevant transcribe_* entries.
Understanding chunk errors
Section titled “Understanding chunk errors”Chunks can fail for reasons that aren’t always Golden Retriever’s fault:
| Error shape | Likely cause | What to do |
|---|---|---|
Vertex AI error 400: API key not valid | Key was changed, revoked, or pasted with whitespace | Update it in Settings → Cloud |
Rate limited by Gemini — retry after Ns | Free tier quota exhausted | Wait or upgrade (see above) |
Visual description: … with 500 code | Transient Google outage | Click Retry; usually resolves |
Transcription: … on a known-language file | Wrong language hint cached, or Gemini failed on noisy audio | Use the Language picker on the file detail to pick the correct language and retry |
For anything else, the raw error text is kept verbatim in the chunk card so you can include it when filing a bug report.
What happened to “Watched Folders” in Settings?
Section titled “What happened to “Watched Folders” in Settings?”It moved. The Library tab is now the single place for content management — adding folders, seeing what’s indexed, removing things. Settings is for preferences only (Cloud, Preferences, Advanced, Diagnostics).