Experimental/brain-of-reese

Fork 0

Files

T

ducoterra a19d78d284

Build and Push Containers / build-and-push-app (push) Successful in 1m57s

Details

Build and Push Containers / build-and-push-db (push) Failing after 13s

Details

phase: 122_image_documents

**Phase 122 (image documents) — final verification pass: all green. No code changes were needed; defects found: none.**

**Verified (implementation already complete in working tree, reviewed end-to-end):**
- Toggle (`BOR_IMAGES`/`BOR_IMAGE_EXTENSIONS`/`BOR_IMAGE_DIR`, off by default) + `GET /api/config` `images` flag
- Ingest: bytes digest, `image_dir` persistent copy, `content = summary = vision description` (chat-model call; only text embedded), fail-soft skip + `images_failed` counter
- Serve/display: `/api/documents/{id}/image` route (404 matrix), viewer `<img>` + description, Sources 48px lazy thumbnails, chat inline source figure (alt = summary), agent `read` marker
- Prune guard: images-off syncs never prune `is_image` docs

**Test / lint / coverage (exact commands & outcomes):**
- `uv run pytest` → exit 0 (green; note: pytest 9.1.1 `-q` omits the final count line in output — exit code authoritative)
- `uv run pytest --cov=app --cov-report=term-missing` → **2715 passed, exit 0, TOTAL 99%** (>90% gate)
- `uv run ruff check . && uv run pyright` → "All checks passed!" / "0 errors, 0 warnings, 0 informations"
- `uv run pytest tests/e2e/test_image_documents.py -v --no-cov` → **4 passed, exit 0** (isolation)

**Completion criteria:** (1) images=true → described/embedded/displayed docs: ✅ (E2E + integration) · (2) images=false byte-identical + image docs survive sync: ✅ (E2E negative app + unit/integration) · (3) viewer + chat rendering with alt text; failed description skips + logs, sync completes: ✅ · (4) test/lint/coverage gates: ✅ · (5) commit + phase move: deferred to harness per this pass's rules (working tree left uncommitted).

**Notable deviation (pre-existing, documented in code):** image route uses `require_user` (phase-79 posture, same gate as the document content endpoint) rather than the phase text's "public" parenthetical — matches the endpoint it mirrors.

**Next pending phase:** `123_chat_image_questions`.

2026-09-25 01:54:23 -04:00

3.3 KiB

Raw Blame History

Task 05 — RAG display: image docs in the chat sources + the agent read marker

Phase: 122_image_documents · Source: TODO.md:6 — "Images retrieved by the RAG should be shown in the chat nicely."

Objective

When a retrieved/agent-read document is an image, the chat shows it: the sources block renders a compact inline image with its summary as caption/alt, and the agent's read tool tells the model it is reading a generated image description.

Work

app/rag/retriever.py / app/api/chat.py — the sources frames the chat bubble renders (the SSE sources/related-doc frames and the agent-sourced doc list): add an OPTIONAL image_url field to the per-doc ref shape — populated (the /api/documents/{id}/image path) iff the doc row has is_image, absent otherwise (the omission rule — text-doc frames stay byte-identical). The retriever already has the Document row; the agent's doc refs (the read-tool results / source list) do too — set it at the frame-build sites (grep for the source-ref construction in both modules; one shared helper source_ref_with_image(doc, …) keeps the two sites in lockstep).
frontend/assets/app.js — the chat's sources block renderer: when a source ref carries image_url, render a compact inline <img> (max-height ~96px, object-fit: contain, the theme's surface, alt + visible caption = the doc summary — the "shown nicely" requirement) in place of / beside the existing doc chip text (keep the title + the existing chip affordance — the image is additive, not a replacement). A failed image load collapses to the plain chip (never a broken-image icon).
app/rag/agent.py — the read tool's result for an image doc: prefix the description with the marker line Image document — the text below is a description generated from the image: (a module constant) so the model reasons about what it is reading; non-image docs' results are byte-identical.
ASSUMPTION: the chat QUESTION side (users submitting images) is phase 123 — this task only covers RETRIEVED images in the answer's sources.
ASSUMPTION: the sources-frame image_url is the only new frame field — no doc-id leak beyond what the frame already carries (the path encodes the doc id, same as the content endpoint).

Testing & Quality

Integration: tests/integration/test_chat_api.py (extend, task 06) — a mocked grounded answer that includes an image doc in its sources → the SSE frame carries image_url for that ref only; a text-only grounding has NO image_url key anywhere (byte check).
Unit: tests/unit/test_image_documents.py (task 06) — the frame-helper (present/absent), the agent marker (image vs non-image result), house-style source assertions: the sources renderer reads image_url, sets alt, and falls back on image error.
E2E: test_image_documents.py scenario (task 06) — ask a question the mock LLM grounds on the fixture image doc → the chat sources block shows the inline image with its caption.
Coverage: >90% on the touched modules.

Completion Criteria

A chat answer grounded on an image doc shows the inline image + caption in its sources block; text-doc answers render byte-identically to before.
The agent read result for an image doc carries the marker; the model sees the description, not raw bytes.
uv run pytest green; uv run ruff check . && uv run pyright clean.

3.3 KiB Raw Blame History