docsmind 0.4.0__tar.gz → 0.6.0__tar.gz

{docsmind-0.4.0 → docsmind-0.6.0}/CHANGELOG.md

@@ -2,6 +2,63 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.6.0] - 2026-11-10
+
+### Added
+
+- Workspace: clicking a source card or citation chip opens the cited PDF page in a side panel
+  next to the chat.
+- Images/Tables galleries: full-view lightbox (blurred backdrop, arrow-key navigation) with
+  the full image caption beneath.
+- Chunk preview shows the embedding vector on one truncated line, expandable to the full
+  vector (`GET /api/documents/{version_id}/chunks/{chunk_id}/embedding`; chunk list now
+  includes `embedding_model`, `embedding_dims`, `embedding_preview`).
+- Agents: clicking a node opens a details panel next to the graph, like the source panel in the
+  Workspace. For an agent (the Mind, subagents, router and planner) it shows the description,
+  model, step budget, tools, the full system prompt (formatted or raw, with copy), the context
+  blocks the harness adds and a description of the user prompt. For a tool it shows the
+  description the model reads, which agents can use it and its arguments (type, required,
+  default, constraints) with the JSON Schema. Tool chips and "Available to" chips navigate
+  between panels; Escape or clicking the empty graph closes it.
+
+### Changed
+
+- `GET /api/agent`: every agent and stage now includes `system_prompt`, `context` (blocks with
+  `label`, `text`, `cached`) and `user_prompt`; every tool now includes `instructions` (the
+  description sent to the model) and `parameters` (its JSON Schema), in addition to `name` and
+  `description`.
+
+### Fixed
+
+- Image captions are now shown in the gallery and refresh when a captioning job finishes.
+- Captioning prompt no longer marks logos and banners as "decorative".
+
+## [0.5.0] - 2026-11-02
+
+### Changed
+
+- Agents view is now an interactive graph: the Mind in the centre, its tools around it, and the
+  subagents with their own tools beyond. Hover (or tap) a node for its description. Names are
+  shown as "Change Analyzer", not `change_analyzer`; the router and planner appear as dashed
+  stages of the Mind (one model call, no tools), not as subagents.
+- `GET /api/agent`: `tools` are now `{name, description}` objects (plain-language summaries),
+  and a new `stages` list describes the router and planner.
+
+### Added
+
+- On-demand enrichment for both pending roadmap items:
+  - Embeddings: estimate by token count, confirmation step, resumable run (`docsmind embed`,
+    `POST /api/enrichment/embeddings/{estimate,run}`).
+  - Image captioning: estimate by image count/resolution + output-token range, confirmation step,
+    resumable run (`docsmind caption`, `POST /api/enrichment/captions/{estimate,run}`).
+- Enrichment status + background jobs API:
+  `GET /api/enrichment/status`, `GET /api/enrichment/jobs/{job_id}`,
+  `POST /api/enrichment/jobs/{job_id}/cancel`.
+- Frontend Document details now shows "not embedded yet" / "not captioned yet" alerts with
+  estimate-and-proceed dialogs and job progress/cancel controls.
+- Hybrid retrieval path: keyword search fused with vector similarity when embeddings are present,
+  with automatic fallback to keyword-only when embeddings or API access are unavailable.
+
 ## [0.4.0] - 2026-10-31
 
 ### Added

{docsmind-0.4.0 → docsmind-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: docsmind
-Version: 0.4.0
+Version: 0.6.0
 Summary: Chat with your documents. Version-aware retrieval, change analysis, and an editable table workspace, backed by Postgres/pgvector.
 Project-URL: Homepage, https://github.com/yauheniya-ai/docsmind
 Project-URL: Repository, https://github.com/yauheniya-ai/docsmind
@@ -45,6 +45,8 @@ Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
 Requires-Dist: pytest>=8.0; extra == 'dev'
 Requires-Dist: ruff>=0.5; extra == 'dev'
 Requires-Dist: testcontainers[postgres]>=4.4; extra == 'dev'
+Provides-Extra: langfuse
+Requires-Dist: langfuse>=2.0; extra == 'langfuse'
 Provides-Extra: mlflow
 Requires-Dist: mlflow>=2.14; extra == 'mlflow'
 Provides-Extra: openai
@@ -85,8 +87,8 @@ will perform specialized tasks.
 | ✅ Table extraction | Extract and store tables skipping repeating ones (e.g. headers or footers) |
 | ✅ server + UI | FastAPI backend (`docsmind serve`) + React UI (`frontend/`): add documents, browse indexed content, image and table galleries |
 | ✅ Chat agent (the Mind) | Routes each question, plans complex ones, searches/reads your documents with tools, delegates to subagents, and answers with verified `[S#]` citations. Streams to the UI over SSE; conversations are saved |
-| 🚧 Image captioning | Images are extracted and stored; vision captioning is next |
-| 🚧 Embeddings + hybrid search | Chunks are stored without embeddings for now |
+| ✅ Image captioning (on demand) | The UI/CLI shows what's uncaptioned, estimates cost from image count/resolution, asks for confirmation, then captions only what's missing |
+| ✅ Embeddings + hybrid search (on demand) | The UI/CLI shows what's unembedded, estimates cost from token counts, asks for confirmation, then embeds only what's missing; search uses keyword+semantic fusion when available |
 | 🚧 Change analysis (diffra) | `docsmind diff` exists as a command, without an implementation yet |
 | 🚧 DOCX/text parsers, S3/Supabase blob storage | Planned |
 
@@ -99,7 +101,7 @@ pip install "docsmind[all]"
 ```
 
 Extras: `docsmind[openai]`, `docsmind[anthropic]`, `docsmind[server]` (FastAPI, serves the bundled UI),
-`docsmind[mlflow]` (tracing/eval export). Requires Python 3.10+.
+`docsmind[mlflow]` / `docsmind[langfuse]` (tracing/eval export, planned). Requires Python 3.10+.
 
 ## Quickstart
 
@@ -226,7 +228,30 @@ Question -> Orchestrator --simple--> Executor <-> Tools / Subagents -> Answer
 - **Citations**: tools register passages as `S1, S2, ...`; the model cites `[S#]`; invented
   handles are dropped and the rest renumbered by first appearance. Document text is treated as
   untrusted data, never as instructions.
-- **Search** is Postgres full-text (ranked) plus exact-text grep until embeddings land.
+- **Search** is Postgres full-text (ranked) plus exact-text grep; when embeddings exist, semantic vector matches are fused in via reciprocal rank fusion.
+
+### On-demand enrichment
+
+Embeddings and image captions are **not** created during ingest. They are opt-in because they call paid APIs.
+
+- In the **Document details** page, warning cards show what's missing ("not embedded yet" / "not captioned yet").
+- Clicking **Estimate & run** opens a confirmation dialog with model, token/image counts, and estimated USD cost.
+- Running is idempotent and resumable: it only processes missing rows; cancel/retry is safe.
+
+From CLI:
+
+```bash
+docsmind embed [--version-id <id>] [-y]
+docsmind caption [--version-id <id>] [-y]
+```
+
+HTTP:
+
+- `GET /api/enrichment/status`
+- `POST /api/enrichment/{embeddings|captions}/estimate`
+- `POST /api/enrichment/{embeddings|captions}/run`
+- `GET /api/enrichment/jobs/{job_id}`
+- `POST /api/enrichment/jobs/{job_id}/cancel`
 
 Tuning (all `DOCSMIND_*`): `AGENT_FAST_MODEL` (router/summarizer/memory model, defaults to
 `LLM_MODEL`), `AGENT_MAX_STEPS`, `AGENT_SUBAGENT_MAX_STEPS`, `AGENT_MEMORY_ENABLED`,
@@ -269,6 +294,8 @@ heuristics that work on one PDF break on the next.
 | `docsmind doctor` | Check your setup |
 | `docsmind serve [--host] [--port] [--reload]` | Run the FastAPI backend for the `frontend/` UI |
 | `docsmind chat [question] [-c <collection>]` | Ask the Mind once, or start a REPL that keeps the conversation |
+| `docsmind embed [--version-id <id>] [-y]` | Estimate cost and create missing embeddings on demand |
+| `docsmind caption [--version-id <id>] [-y]` | Estimate cost and create missing image captions on demand |
 | `docsmind diff` | Planned |
 
 ## Architecture
@@ -319,7 +346,7 @@ over `/api/*`, and loads extracted images/tables straight from disk via `/blobs/
 ### Design notes
 
 - **Ports and adapters, once.** `domain/ports.py` defines every external dependency as a
-  `Protocol`. The core never imports `openai`, `anthropic` or `mlflow` directly. Only
+  `Protocol`. The core never imports `openai`, `anthropic`, `mlflow` or `langfuse` directly. Only
   adapters do, and lazily, so a bare `pip install docsmind` doesn't pull in SDKs you're
   not using.
 - **Text and images share one retrieval path.** An image becomes a chunk

{docsmind-0.4.0 → docsmind-0.6.0}/README.md

@@ -28,8 +28,8 @@ will perform specialized tasks.
 | ✅ Table extraction | Extract and store tables skipping repeating ones (e.g. headers or footers) |
 | ✅ server + UI | FastAPI backend (`docsmind serve`) + React UI (`frontend/`): add documents, browse indexed content, image and table galleries |
 | ✅ Chat agent (the Mind) | Routes each question, plans complex ones, searches/reads your documents with tools, delegates to subagents, and answers with verified `[S#]` citations. Streams to the UI over SSE; conversations are saved |
-| 🚧 Image captioning | Images are extracted and stored; vision captioning is next |
-| 🚧 Embeddings + hybrid search | Chunks are stored without embeddings for now |
+| ✅ Image captioning (on demand) | The UI/CLI shows what's uncaptioned, estimates cost from image count/resolution, asks for confirmation, then captions only what's missing |
+| ✅ Embeddings + hybrid search (on demand) | The UI/CLI shows what's unembedded, estimates cost from token counts, asks for confirmation, then embeds only what's missing; search uses keyword+semantic fusion when available |
 | 🚧 Change analysis (diffra) | `docsmind diff` exists as a command, without an implementation yet |
 | 🚧 DOCX/text parsers, S3/Supabase blob storage | Planned |
 
@@ -42,7 +42,7 @@ pip install "docsmind[all]"
 ```
 
 Extras: `docsmind[openai]`, `docsmind[anthropic]`, `docsmind[server]` (FastAPI, serves the bundled UI),
-`docsmind[mlflow]` (tracing/eval export). Requires Python 3.10+.
+`docsmind[mlflow]` / `docsmind[langfuse]` (tracing/eval export, planned). Requires Python 3.10+.
 
 ## Quickstart
 
@@ -169,7 +169,30 @@ Question -> Orchestrator --simple--> Executor <-> Tools / Subagents -> Answer
 - **Citations**: tools register passages as `S1, S2, ...`; the model cites `[S#]`; invented
   handles are dropped and the rest renumbered by first appearance. Document text is treated as
   untrusted data, never as instructions.
-- **Search** is Postgres full-text (ranked) plus exact-text grep until embeddings land.
+- **Search** is Postgres full-text (ranked) plus exact-text grep; when embeddings exist, semantic vector matches are fused in via reciprocal rank fusion.
+
+### On-demand enrichment
+
+Embeddings and image captions are **not** created during ingest. They are opt-in because they call paid APIs.
+
+- In the **Document details** page, warning cards show what's missing ("not embedded yet" / "not captioned yet").
+- Clicking **Estimate & run** opens a confirmation dialog with model, token/image counts, and estimated USD cost.
+- Running is idempotent and resumable: it only processes missing rows; cancel/retry is safe.
+
+From CLI:
+
+```bash
+docsmind embed [--version-id <id>] [-y]
+docsmind caption [--version-id <id>] [-y]
+```
+
+HTTP:
+
+- `GET /api/enrichment/status`
+- `POST /api/enrichment/{embeddings|captions}/estimate`
+- `POST /api/enrichment/{embeddings|captions}/run`
+- `GET /api/enrichment/jobs/{job_id}`
+- `POST /api/enrichment/jobs/{job_id}/cancel`
 
 Tuning (all `DOCSMIND_*`): `AGENT_FAST_MODEL` (router/summarizer/memory model, defaults to
 `LLM_MODEL`), `AGENT_MAX_STEPS`, `AGENT_SUBAGENT_MAX_STEPS`, `AGENT_MEMORY_ENABLED`,
@@ -212,6 +235,8 @@ heuristics that work on one PDF break on the next.
 | `docsmind doctor` | Check your setup |
 | `docsmind serve [--host] [--port] [--reload]` | Run the FastAPI backend for the `frontend/` UI |
 | `docsmind chat [question] [-c <collection>]` | Ask the Mind once, or start a REPL that keeps the conversation |
+| `docsmind embed [--version-id <id>] [-y]` | Estimate cost and create missing embeddings on demand |
+| `docsmind caption [--version-id <id>] [-y]` | Estimate cost and create missing image captions on demand |
 | `docsmind diff` | Planned |
 
 ## Architecture
@@ -262,7 +287,7 @@ over `/api/*`, and loads extracted images/tables straight from disk via `/blobs/
 ### Design notes
 
 - **Ports and adapters, once.** `domain/ports.py` defines every external dependency as a
-  `Protocol`. The core never imports `openai`, `anthropic` or `mlflow` directly. Only
+  `Protocol`. The core never imports `openai`, `anthropic`, `mlflow` or `langfuse` directly. Only
   adapters do, and lazily, so a bare `pip install docsmind` doesn't pull in SDKs you're
   not using.
 - **Text and images share one retrieval path.** An image becomes a chunk

{docsmind-0.4.0 → docsmind-0.6.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "docsmind"
-version = "0.4.0"
+version = "0.6.0"
 description = "Chat with your documents. Version-aware retrieval, change analysis, and an editable table workspace, backed by Postgres/pgvector."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -46,6 +46,7 @@ openai = ["openai>=1.30"]
 anthropic = ["anthropic>=0.34"]
 server = ["fastapi>=0.111", "uvicorn[standard]>=0.30", "python-multipart>=0.0.9"]
 mlflow = ["mlflow>=2.14"]
+langfuse = ["langfuse>=2.0"]
 dev = ["pytest>=8.0", "pytest-asyncio>=0.23", "testcontainers[postgres]>=4.4", "ruff>=0.5", "mypy>=1.10"]
 all = ["docsmind[openai,anthropic,server]"]
 

docsmind-0.6.0/src/docsmind/adapters/embeddings/__init__.py

@@ -0,0 +1,22 @@
+"""Embedding providers. Today: OpenAI (and OpenAI-compatible gateways)."""
+
+from __future__ import annotations
+
+from docsmind.config import DocsmindConfig
+from docsmind.domain.errors import EnrichmentConfigurationError
+
+
+def create_embedder(config: DocsmindConfig):
+    if config.embedding_provider == "openai":
+        from docsmind.adapters.embeddings.openai_embeddings import OpenAIEmbedder
+
+        return OpenAIEmbedder(
+            api_key=config.openai_api_key,
+            model=config.embedding_model,
+            dimensions=config.embedding_dimensions,
+            base_url=config.openai_base_url,
+            batch_size=config.embedding_batch_size,
+        )
+    raise EnrichmentConfigurationError(
+        f"Unknown embedding_provider {config.embedding_provider!r}. Supported: openai."
+    )

docsmind-0.6.0/src/docsmind/adapters/embeddings/openai_embeddings.py

@@ -0,0 +1,79 @@
+"""OpenAI (and OpenAI-compatible) embeddings adapter. Satisfies `domain.ports.Embedder`."""
+
+from __future__ import annotations
+
+from docsmind.domain.errors import EnrichmentConfigurationError
+
+# The API rejects inputs over 8191 tokens; page chunks are far smaller, but a
+# dense page of tiny text can get there. Truncate rather than fail the batch.
+MAX_INPUT_TOKENS = 8000
+_MAX_REQUEST_TOKENS = 250_000  # API limit is 300k tokens per request
+
+
+class OpenAIEmbedder:
+    def __init__(
+        self,
+        *,
+        api_key: str | None,
+        model: str,
+        dimensions: int,
+        base_url: str | None = None,
+        batch_size: int = 64,
+        timeout: float = 120.0,
+    ) -> None:
+        if not api_key:
+            raise EnrichmentConfigurationError(
+                "OpenAI API key is not set. Add DOCSMIND_OPENAI_API_KEY to your .env to create embeddings."
+            )
+        try:
+            from openai import AsyncOpenAI
+        except ImportError as exc:  # pragma: no cover - import guard
+            raise EnrichmentConfigurationError(
+                'The openai package is not installed. Run `pip install "docsmind[openai]"`.'
+            ) from exc
+        self.model_name = model
+        self.dimensions = dimensions
+        self._batch_size = max(1, batch_size)
+        self._client = AsyncOpenAI(api_key=api_key, base_url=base_url, max_retries=4, timeout=timeout)
+
+    async def embed(self, texts: list[str]) -> list[list[float]]:
+        vectors: list[list[float]] = []
+        for batch in self._batches([_truncate(t) for t in texts]):
+            kwargs: dict = {"model": self.model_name, "input": batch}
+            # Only the v3 models accept (and need) a `dimensions` argument.
+            if "text-embedding-3" in self.model_name:
+                kwargs["dimensions"] = self.dimensions
+            response = await self._client.embeddings.create(**kwargs)
+            ordered = sorted(response.data, key=lambda d: d.index)
+            vectors.extend([list(d.embedding) for d in ordered])
+        if len(vectors) != len(texts):
+            raise RuntimeError(f"Embeddings API returned {len(vectors)} vectors for {len(texts)} inputs.")
+        return vectors
+
+    def _batches(self, texts: list[str]):
+        batch: list[str] = []
+        tokens = 0
+        for text in texts:
+            estimate = max(1, len(text) // 3)  # conservative: ~3 chars/token
+            if batch and (len(batch) >= self._batch_size or tokens + estimate > _MAX_REQUEST_TOKENS):
+                yield batch
+                batch, tokens = [], 0
+            batch.append(text)
+            tokens += estimate
+        if batch:
+            yield batch
+
+
+def _truncate(text: str) -> str:
+    # The API also rejects empty strings; a single space embeds harmlessly.
+    text = text if text.strip() else " "
+    try:
+        import tiktoken
+
+        encoding = tiktoken.get_encoding("cl100k_base")
+        tokens = encoding.encode(text, disallowed_special=())
+        if len(tokens) > MAX_INPUT_TOKENS:
+            return encoding.decode(tokens[:MAX_INPUT_TOKENS])
+        return text
+    except Exception:  # noqa: BLE001 - fall back to a character cap
+        return text[: MAX_INPUT_TOKENS * 3]

{docsmind-0.4.0 → docsmind-0.6.0}/src/docsmind/adapters/storage/postgres/repository.py

@@ -12,9 +12,10 @@ part of what it does, not the whole of it.
 
 from __future__ import annotations
 
+import json
 from uuid import UUID
 
-from sqlalchemy import bindparam, delete, func, insert, select, text
+from sqlalchemy import Text, bindparam, cast, delete, func, insert, select, text
 from sqlalchemy.dialects.postgresql import ARRAY
 from sqlalchemy.dialects.postgresql import UUID as PGUUID
 
@@ -46,6 +47,9 @@ from docsmind.domain.documents import (
     ParsedDocument,
 )
 
+# How many leading vector components `get_chunks` returns as a preview.
+_EMBEDDING_PREVIEW_DIMS = 16
+
 
 class PostgresRepository:
     def __init__(self, config: DocsmindConfig) -> None:
@@ -205,21 +209,38 @@ class PostgresRepository:
         chunk_types: list[str] | None = None,
         limit: int = 10,
     ) -> list[Chunk]:
-        # TODO: reciprocal rank fusion of a vector KNN query and a
-        # plainto_tsquery match against `chunks.tsv`, per the design from
-        # earlier in this conversation. Not implemented yet — this is the
-        # next piece after captioning/embedding actually populate `embedding`.
-        raise NotImplementedError(
-            "hybrid_search isn't wired up yet — chunks currently have no "
-            "embeddings to search over. See adapters/embeddings/ (not yet "
-            "built) and enrichment/caption.py (not yet built)."
+        """Keyword (full-text) and vector (cosine) results fused with
+        reciprocal rank fusion. Falls back to whichever leg has results."""
+        from docsmind.domain.documents import ChunkType
+        from docsmind.retrieval.fusion import reciprocal_rank_fusion
+        from docsmind.retrieval.keyword import build_tsquery
+
+        pool = max(limit * 3, 20)
+        tsquery = build_tsquery(query)
+        keyword = (
+            await self.keyword_search(tsquery, version_ids=version_ids, limit=pool) if tsquery else []
         )
+        vector = await self.vector_search(query_embedding, version_ids=version_ids, limit=pool)
+        fused = reciprocal_rank_fusion([keyword, vector], limit=limit * 3 if chunk_types else limit)
+        if chunk_types:
+            fused = [r for r in fused if r.get("chunk_type", "text") in chunk_types][:limit]
+        return [
+            Chunk(
+                id=r["chunk_id"],
+                version_id=r["version_id"],
+                chunk_type=ChunkType(r.get("chunk_type", "text")),
+                content=r["content"],
+                page_start=r["page_start"],
+                page_end=r["page_end"],
+            )
+            for r in fused
+        ]
 
     # -- agent retrieval ------------------------------------------------------
-    # Read-only queries the Mind's tools run. Keyword (Postgres full-text)
-    # search only for now: chunks don't have embeddings yet, so `hybrid_search`
-    # above is still a stub. When embeddings land, add the vector leg here and
-    # fuse it with this one — the tools call these methods, not SQL.
+    # Read-only queries the Mind's tools run: keyword (Postgres full-text) and,
+    # once chunks have embeddings (see `enrichment/`), vector search. Fusion of
+    # the two lives in `retrieval/fusion.py`; the tools call these methods,
+    # not SQL.
 
     async def list_catalog(self, version_ids: list[UUID] | None = None) -> list[dict]:
         """One row per version (optionally restricted), with the page count
@@ -260,7 +281,7 @@ class PostgresRepository:
 
     _SEARCH_SQL = text(
         """
-        SELECT c.id AS chunk_id, c.version_id, c.page_start, c.page_end, c.content,
+        SELECT c.id AS chunk_id, c.version_id, c.page_start, c.page_end, c.content, c.chunk_type,
                ts_rank_cd(c.tsv, q.query, 32) AS rank
         FROM chunks c, to_tsquery('english', :query) AS q(query)
         WHERE c.tsv @@ q.query
@@ -330,6 +351,185 @@ class PostgresRepository:
             result = await session.execute(stmt)
             return [dict(row) for row in result.mappings().all()]
 
+    # -- vector search + on-demand enrichment ---------------------------------
+    # Embeddings and image captions are created on demand (`enrichment/`), so
+    # every read here has to cope with "nothing embedded yet".
+
+    _STATUS_SQL = text(
+        """
+        SELECT v.id AS version_id,
+          (SELECT count(*) FROM chunks c
+            WHERE c.version_id = v.id AND c.content <> '') AS chunks_total,
+          (SELECT count(*) FROM chunks c
+            WHERE c.version_id = v.id AND c.content <> ''
+              AND c.embedding IS NOT NULL AND c.embedding_model = :model) AS chunks_embedded,
+          (SELECT count(*) FROM images i WHERE i.version_id = v.id) AS images_total,
+          (SELECT count(*) FROM images i
+            WHERE i.version_id = v.id AND i.caption IS NOT NULL) AS images_captioned
+        FROM document_versions v
+        WHERE CAST(:filter_versions AS boolean) IS FALSE OR v.id = ANY(:version_ids)
+        """
+    ).bindparams(bindparam("version_ids", type_=ARRAY(PGUUID(as_uuid=True))))
+
+    async def enrichment_status(self, model: str, version_ids: list[UUID] | None = None) -> list[dict]:
+        """Per-version counts: embeddable chunks (non-empty text) and how many
+        already carry an embedding from `model`; images and how many have a
+        caption (an empty caption means "looked at, nothing worth saying")."""
+        async with self._sessionmaker() as session:
+            result = await session.execute(
+                self._STATUS_SQL,
+                {"model": model, "filter_versions": version_ids is not None, "version_ids": version_ids or []},
+            )
+            return [dict(row) for row in result.mappings().all()]
+
+    _TO_EMBED_SQL = text(
+        """
+        SELECT c.id, c.content
+        FROM chunks c
+        WHERE c.content <> ''
+          AND (c.embedding IS NULL OR c.embedding_model IS DISTINCT FROM :model)
+          AND (CAST(:filter_versions AS boolean) IS FALSE OR c.version_id = ANY(:version_ids))
+          AND (CAST(:after AS uuid) IS NULL OR c.id > CAST(:after AS uuid))
+        ORDER BY c.id
+        LIMIT :limit
+        """
+    ).bindparams(
+        bindparam("version_ids", type_=ARRAY(PGUUID(as_uuid=True))),
+        bindparam("after", type_=PGUUID(as_uuid=True)),
+    )
+
+    async def fetch_chunks_to_embed(
+        self,
+        model: str,
+        *,
+        version_ids: list[UUID] | None = None,
+        after_id: UUID | None = None,
+        limit: int = 200,
+    ) -> list[dict]:
+        """Chunks that still need an embedding from `model`, ordered by id.
+        Pass the last id as `after_id` to page through without writing; when
+        writing as you go, just ask for the first page again each time."""
+        async with self._sessionmaker() as session:
+            result = await session.execute(
+                self._TO_EMBED_SQL,
+                {
+                    "model": model,
+                    "filter_versions": version_ids is not None,
+                    "version_ids": version_ids or [],
+                    "after": after_id,
+                    "limit": limit,
+                },
+            )
+            return [dict(row) for row in result.mappings().all()]
+
+    async def save_embeddings(self, items: list[tuple[UUID, list[float]]], model: str) -> None:
+        if not items:
+            return
+        stmt = (
+            chunks_table.update()
+            .where(chunks_table.c.id == bindparam("b_id"))
+            .values(embedding=bindparam("b_embedding"), embedding_model=bindparam("b_model"))
+        )
+        async with self._sessionmaker() as session:
+            await session.execute(
+                stmt, [{"b_id": cid, "b_embedding": vec, "b_model": model} for cid, vec in items]
+            )
+            await session.commit()
+
+    async def count_embedded(self, model: str, version_ids: list[UUID] | None = None) -> int:
+        stmt = select(func.count()).select_from(chunks_table).where(
+            chunks_table.c.embedding.is_not(None), chunks_table.c.embedding_model == model
+        )
+        if version_ids is not None:
+            stmt = stmt.where(chunks_table.c.version_id.in_(version_ids))
+        async with self._sessionmaker() as session:
+            return int((await session.execute(stmt)).scalar_one())
+
+    async def vector_search(
+        self,
+        embedding: list[float],
+        *,
+        model: str | None = None,
+        version_ids: list[UUID] | None = None,
+        limit: int = 10,
+    ) -> list[dict]:
+        """Nearest chunks by cosine distance, same row shape as `keyword_search`.
+
+        Queries `embedding::halfvec(N)` because that is what the HNSW index is
+        built on (migration 0001) — pgvector indexes cap at 2000 dimensions
+        for `vector` but 4000 for `halfvec`.
+        """
+        dims = int(self.config.embedding_dimensions)
+        literal = "[" + ",".join(f"{x:.7g}" for x in embedding) + "]"
+        sql = text(
+            f"""
+            SELECT c.id AS chunk_id, c.version_id, c.page_start, c.page_end, c.content, c.chunk_type,
+                   (c.embedding::halfvec({dims}) <=> CAST(:q AS halfvec({dims}))) AS distance
+            FROM chunks c
+            WHERE c.embedding IS NOT NULL
+              AND (CAST(:model AS text) IS NULL OR c.embedding_model = CAST(:model AS text))
+              AND (CAST(:filter_versions AS boolean) IS FALSE OR c.version_id = ANY(:version_ids))
+            ORDER BY c.embedding::halfvec({dims}) <=> CAST(:q AS halfvec({dims}))
+            LIMIT :limit
+            """
+        ).bindparams(bindparam("version_ids", type_=ARRAY(PGUUID(as_uuid=True))))
+        async with self._sessionmaker() as session:
+            result = await session.execute(
+                sql,
+                {
+                    "q": literal,
+                    "model": model,
+                    "filter_versions": version_ids is not None,
+                    "version_ids": version_ids or [],
+                    "limit": limit,
+                },
+            )
+            return [dict(row) for row in result.mappings().all()]
+
+    async def fetch_images_to_caption(
+        self, *, version_ids: list[UUID] | None = None, after_id: UUID | None = None, limit: int = 200
+    ) -> list[dict]:
+        stmt = (
+            select(
+                images_table.c.id,
+                images_table.c.version_id,
+                images_table.c.page_number,
+                images_table.c.uri,
+                images_table.c.width,
+                images_table.c.height,
+                images_table.c.format,
+            )
+            .where(images_table.c.caption.is_(None))
+            .order_by(images_table.c.id)
+            .limit(limit)
+        )
+        if version_ids is not None:
+            stmt = stmt.where(images_table.c.version_id.in_(version_ids))
+        if after_id is not None:
+            stmt = stmt.where(images_table.c.id > after_id)
+        async with self._sessionmaker() as session:
+            result = await session.execute(stmt)
+            return [dict(row) for row in result.mappings().all()]
+
+    async def save_caption(self, image_id: UUID, caption: str, model: str) -> None:
+        """Record a caption and make it searchable: the image's chunk gets the
+        caption as its content (the generated `tsv` follows) and loses any old
+        embedding so the next embed run picks it up. An empty caption just
+        marks the image as handled (too small, or decorative)."""
+        async with self._sessionmaker() as session:
+            await session.execute(
+                images_table.update()
+                .where(images_table.c.id == image_id)
+                .values(caption=caption, caption_model=model, captioned_at=func.now())
+            )
+            if caption:
+                await session.execute(
+                    chunks_table.update()
+                    .where(chunks_table.c.image_id == image_id, chunks_table.c.chunk_type == "image")
+                    .values(content=caption, embedding=None, embedding_model=None)
+                )
+            await session.commit()
+
     # -- read helpers, mainly for sanity-checking what actually landed -------
 
     async def count_chunks(self, version_id: UUID) -> int:
@@ -465,7 +665,11 @@ class PostgresRepository:
     async def get_chunks(self, version_id: UUID, *, page: int | None = None) -> list[dict]:
         """Chunks for one version, in page order. Pass `page` to see only
         one page's chunk(s) — most pages are exactly one chunk; a dense page
-        may be several."""
+        may be several.
+
+        Embedded chunks also carry `embedding_model`, `embedding_dims` and a
+        short `embedding_preview` (the first few components); the full vector
+        is served by `get_chunk_embedding`, so listing stays small."""
         async with self._sessionmaker() as session:
             stmt = (
                 select(
@@ -475,6 +679,9 @@ class PostgresRepository:
                     chunks_table.c.image_id,
                     chunks_table.c.page_start,
                     chunks_table.c.page_end,
+                    chunks_table.c.embedding_model,
+                    # pgvector's text form ("[0.1,0.2,...]") is valid JSON.
+                    cast(chunks_table.c.embedding, Text).label("embedding_text"),
                 )
                 .where(chunks_table.c.version_id == version_id)
                 .order_by(chunks_table.c.page_start)
@@ -482,7 +689,28 @@ class PostgresRepository:
             if page is not None:
                 stmt = stmt.where(chunks_table.c.page_start == page)
             result = await session.execute(stmt)
-            return [dict(row) for row in result.mappings().all()]
+            rows = []
+            for row in result.mappings().all():
+                item = dict(row)
+                raw = item.pop("embedding_text")
+                if raw is None:
+                    item["embedding_dims"] = None
+                    item["embedding_preview"] = None
+                else:
+                    vector = json.loads(raw)
+                    item["embedding_dims"] = len(vector)
+                    item["embedding_preview"] = vector[:_EMBEDDING_PREVIEW_DIMS]
+                rows.append(item)
+            return rows
+
+    async def get_chunk_embedding(self, version_id: UUID, chunk_id: UUID) -> list[float] | None:
+        """The full embedding vector of one chunk, or None if it has none."""
+        async with self._sessionmaker() as session:
+            stmt = select(cast(chunks_table.c.embedding, Text)).where(
+                chunks_table.c.version_id == version_id, chunks_table.c.id == chunk_id
+            )
+            raw = (await session.execute(stmt)).scalar_one_or_none()
+            return None if raw is None else json.loads(raw)
 
     async def get_images(self, version_id: UUID) -> list[dict]:
         """Saved images for one version, in page order — `uri` is a