docsmind 0.6.0__tar.gz → 0.8.0__tar.gz

{docsmind-0.6.0 → docsmind-0.8.0}/.gitignore

@@ -1,3 +1,5 @@
+data/
+
 # --- Python ---
 __pycache__/
 *.py[cod]

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

@@ -2,6 +2,67 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.8.0] - 2026-11-12
+
+### Added
+
+- Change Analyzer rebuilt as a code-driven pipeline (`agent/subagents/change_analysis/`) that the
+  Mind starts with `delegate`. Given the current and the previous version, it:
+  1. normalizes both texts and diffs them in code (headers, footers and page numbers removed);
+  2. checks that they are versions of one document and which is newer (a small model call);
+  3. scans for changes with one long-context call per part, streaming rows into the table;
+  4. verifies every compliance-relevant row (new, modified or removed, normative, with a
+     requirement) in a small tool loop, and re-checks the quoted proof against the stored text
+     in code: passages must be verbatim, pages must hold them, and a "new" or "removed" claim
+     must be absent from the other version. A check that goes wrong (no usable answer, an error,
+     a proof that is not in the text) is started again, up to `CHANGE_VERIFY_MAX_RETRIES` times.
+     Rows without proof are dropped: they are not in the table, the report or the database;
+  5. searches for a changelog in parallel (in the documents, and online for public ones) and
+     checks the entries that no row explains;
+  6. writes a report: narrative from the model, every countable section built by code. Page
+     references in it ("A p.12") are clickable and open that page of that version; in the Mind's
+     answer they become `[S#]` citations.
+- Change tables are stored (migration `0005`: `change_analyses`, `change_rows`) with a verified
+  flag, proof passages with pages and a human approved flag. Run `docsmind db upgrade`.
+- Routes `/api/changes`: read an analysis, add, edit and delete rows, Excel export.
+- Tools: `page_vision` (a vision model reads a page image), `load_table` (xlsx/csv from a URL,
+  parsed in code) for the Change Analyzer; `export_excel` for the Mind.
+- `docsmind diff` now prints the table and report; `--actionable` and `--xlsx` options.
+- Config: the `change_*` settings (see `.env.example`). Dependency: `openpyxl`.
+
+### Changed
+
+- `compare()` / `acompare()` return a `ChangeResult` (message, analysis, rows). The two versions
+  may be given in either order.
+
+### Removed
+
+- The `researcher` subagent (code, prompt, tests and UI). `change_analyzer` is now the only
+  subagent.
+- The generic subagent loop and `agent_subagent_max_steps`; the Change Analyzer has its own limits.
+
+
+## [0.7.0] - 2026-11-12
+
+### Added
+
+- Change Analyzer can now look for a published changelog online when the documents themselves
+  contain none, using two new subagent-only tools:
+  - `web_search`: searches the web via Tavily, optionally limited to given domains. Only offered
+    when `DOCSMIND_WEB_SEARCH_API_KEY` is set.
+  - `fetch_url`: reads a public web page as text. Hardened for model-supplied URLs (http(s) on
+    ports 80/443 only, no credentials, no private/loopback addresses on any redirect hop,
+    bounded size and time).
+- Config: `web_search_api_key`, `web_timeout_s`, `web_fetch_max_bytes` (documented in
+  `.env.example`).
+- Implementation brief for the Change Analyzer (`docs/`) and unit tests for the web tools.
+
+### Changed
+
+- Change Analyzer prompt and tool list updated to use the web tools as a fallback, preferring
+  the publisher's own domain.
+- Rebuilt the bundled frontend UI assets.
+
 ## [0.6.0] - 2026-11-10
 
 ### Added

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: docsmind
-Version: 0.6.0
+Version: 0.8.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
@@ -22,6 +22,7 @@ Requires-Dist: alembic>=1.13
 Requires-Dist: asyncpg>=0.29
 Requires-Dist: httpx>=0.27
 Requires-Dist: imagehash>=4.3
+Requires-Dist: openpyxl>=3.1
 Requires-Dist: pgvector>=0.2.5
 Requires-Dist: pillow>=10.0
 Requires-Dist: pydantic-settings>=2.2
@@ -89,7 +90,7 @@ will perform specialized tasks.
 | ✅ 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 (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 |
+| ✅ Change analysis | Compare two versions: a table of changes (new, modified, removed, editorial, relocated) with compliance requirements, each compliance-relevant row verified against the text with verbatim proof; a report; Excel export. `docsmind diff`, or ask the Mind in chat |
 | 🚧 DOCX/text parsers, S3/Supabase blob storage | Planned |
 
 ## Install
@@ -202,7 +203,7 @@ docsmind chat                                              # REPL, keeps the con
 ```python
 result = dm.chat_result("What are our data retention obligations?")
 print(result.answer, result.citations)
-change_set = dm.compare(v1.id, v2.id)   # planned (diffra)
+result = dm.compare(v2.id, v1.id)       # ChangeResult: message, analysis, rows (current, previous)
 ```
 
 ## How the Mind works
@@ -221,8 +222,8 @@ Question -> Orchestrator --simple--> Executor <-> Tools / Subagents -> Answer
 - **Executor**: a bounded tool loop (`search`, `grep`, `read_pages`, `get_outline`,
   `list_documents`, `delegate`). The last step forces an answer; tool errors go back to the
   model, not the user; old tool results are elided when the context grows.
-- **Subagents** (`researcher`, `change_analyzer`): fresh context, a subset of the tools, run in
-  parallel, cannot delegate further.
+- **Subagents** (`change_analyzer`): see [Change analysis](#change-analysis). It cannot delegate
+  further.
 - **Harness**: deterministic code, not another agent. It orders the prompt stable-first so the
   prefix caches, summarizes long histories, and saves durable notes to memory after each answer.
 - **Citations**: tools register passages as `S1, S2, ...`; the model cites `[S#]`; invented
@@ -230,6 +231,38 @@ Question -> Orchestrator --simple--> Executor <-> Tools / Subagents -> Answer
   untrusted data, never as instructions.
 - **Search** is Postgres full-text (ranked) plus exact-text grep; when embeddings exist, semantic vector matches are fused in via reciprocal rank fusion.
 
+### Change analysis
+
+The Change Analyzer compares the **current** version (A) with the **previous** one (B). The Mind
+starts it with `delegate`; the steps run in code, with models used inside them:
+
+1. **Prepare** (code): headers, footers and page numbers are removed, the texts are split into
+   sentences and diffed. Identical texts stop here. Below `CHANGE_DIFF_THRESHOLD` of changed
+   sentences the scan sees A plus the diff, otherwise A and B in full; long documents are split
+   into parts.
+2. **Versions check** (small model): are these versions of one document, which is newer, is it
+   public? Unrelated documents stop here.
+3. **Scan** (one long-context call per part): rows stream into the table as JSONL. A cut-off or
+   broken call is relaunched with the rows so far.
+4. **Verify**: every compliance-relevant row (new/modified/removed, with a normative
+   requirement) gets its own small tool loop. Code then re-checks what the model claims: proof
+   passages must be verbatim in the stored text, the page must hold the passage, and a "new" or
+   "removed" clause must be absent from the other version. A check that goes wrong is started
+   again (up to `CHANGE_VERIFY_MAX_RETRIES`). Rows without proof are dropped: not in the table,
+   the report or the database.
+5. **Changelog** (in parallel with the scan): looked for in the documents and, for public ones,
+   online. Entries that no row explains are checked against both versions.
+6. **Report**: the narrative is written by the model, every countable section by code. Page
+   references ("A p.12") are clickable; in the Mind's answer they are `[S#]` citations.
+
+```bash
+docsmind diff <version-a> <version-b> [--actionable] [--xlsx table.xlsx]   # order does not matter
+```
+
+The table, report and row edits are served by `GET /api/changes`, `GET /api/changes/{id}`,
+`POST|PATCH|DELETE /api/changes/{id}/rows[/{row_id}]` and `GET /api/changes/{id}/export.xlsx`.
+Tuning: the `CHANGE_*` settings in `.env.example`. Needs `docsmind db upgrade` (migration 0005).
+
 ### On-demand enrichment
 
 Embeddings and image captions are **not** created during ingest. They are opt-in because they call paid APIs.
@@ -254,11 +287,13 @@ HTTP:
 - `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`,
+`LLM_MODEL`), `AGENT_MAX_STEPS`, `AGENT_MEMORY_ENABLED`,
 `OPENAI_REASONING_EFFORT`, `OPENAI_BASE_URL`. See `.env.example`.
 
 HTTP: `POST /api/chat` streams Server-Sent Events (`route`, `plan`, `tool_start`, `tool_end`,
-`subagent_start`, `subagent_end`, `token`, `note`, `answer`, `error`, `done`);
+`subagent_start`, `subagent_end`, `analysis_start`, `analysis_status`, `change_row`,
+`change_row_update`, `change_row_removed`, `analysis_done`, `token`, `note`, `answer`, `error`,
+`done`);
 `GET /api/conversations[/{id}]`, `DELETE /api/conversations/{id}`, `GET /api/agent`.
 
 ## How ingestion works
@@ -296,7 +331,7 @@ heuristics that work on one PDF break on the next.
 | `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 |
+| `docsmind diff <a> <b> [--actionable] [--xlsx <file>]` | Compare two versions: change table, report, optional Excel file |
 
 ## Architecture
 

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

@@ -30,7 +30,7 @@ will perform specialized tasks.
 | ✅ 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 (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 |
+| ✅ Change analysis | Compare two versions: a table of changes (new, modified, removed, editorial, relocated) with compliance requirements, each compliance-relevant row verified against the text with verbatim proof; a report; Excel export. `docsmind diff`, or ask the Mind in chat |
 | 🚧 DOCX/text parsers, S3/Supabase blob storage | Planned |
 
 ## Install
@@ -143,7 +143,7 @@ docsmind chat                                              # REPL, keeps the con
 ```python
 result = dm.chat_result("What are our data retention obligations?")
 print(result.answer, result.citations)
-change_set = dm.compare(v1.id, v2.id)   # planned (diffra)
+result = dm.compare(v2.id, v1.id)       # ChangeResult: message, analysis, rows (current, previous)
 ```
 
 ## How the Mind works
@@ -162,8 +162,8 @@ Question -> Orchestrator --simple--> Executor <-> Tools / Subagents -> Answer
 - **Executor**: a bounded tool loop (`search`, `grep`, `read_pages`, `get_outline`,
   `list_documents`, `delegate`). The last step forces an answer; tool errors go back to the
   model, not the user; old tool results are elided when the context grows.
-- **Subagents** (`researcher`, `change_analyzer`): fresh context, a subset of the tools, run in
-  parallel, cannot delegate further.
+- **Subagents** (`change_analyzer`): see [Change analysis](#change-analysis). It cannot delegate
+  further.
 - **Harness**: deterministic code, not another agent. It orders the prompt stable-first so the
   prefix caches, summarizes long histories, and saves durable notes to memory after each answer.
 - **Citations**: tools register passages as `S1, S2, ...`; the model cites `[S#]`; invented
@@ -171,6 +171,38 @@ Question -> Orchestrator --simple--> Executor <-> Tools / Subagents -> Answer
   untrusted data, never as instructions.
 - **Search** is Postgres full-text (ranked) plus exact-text grep; when embeddings exist, semantic vector matches are fused in via reciprocal rank fusion.
 
+### Change analysis
+
+The Change Analyzer compares the **current** version (A) with the **previous** one (B). The Mind
+starts it with `delegate`; the steps run in code, with models used inside them:
+
+1. **Prepare** (code): headers, footers and page numbers are removed, the texts are split into
+   sentences and diffed. Identical texts stop here. Below `CHANGE_DIFF_THRESHOLD` of changed
+   sentences the scan sees A plus the diff, otherwise A and B in full; long documents are split
+   into parts.
+2. **Versions check** (small model): are these versions of one document, which is newer, is it
+   public? Unrelated documents stop here.
+3. **Scan** (one long-context call per part): rows stream into the table as JSONL. A cut-off or
+   broken call is relaunched with the rows so far.
+4. **Verify**: every compliance-relevant row (new/modified/removed, with a normative
+   requirement) gets its own small tool loop. Code then re-checks what the model claims: proof
+   passages must be verbatim in the stored text, the page must hold the passage, and a "new" or
+   "removed" clause must be absent from the other version. A check that goes wrong is started
+   again (up to `CHANGE_VERIFY_MAX_RETRIES`). Rows without proof are dropped: not in the table,
+   the report or the database.
+5. **Changelog** (in parallel with the scan): looked for in the documents and, for public ones,
+   online. Entries that no row explains are checked against both versions.
+6. **Report**: the narrative is written by the model, every countable section by code. Page
+   references ("A p.12") are clickable; in the Mind's answer they are `[S#]` citations.
+
+```bash
+docsmind diff <version-a> <version-b> [--actionable] [--xlsx table.xlsx]   # order does not matter
+```
+
+The table, report and row edits are served by `GET /api/changes`, `GET /api/changes/{id}`,
+`POST|PATCH|DELETE /api/changes/{id}/rows[/{row_id}]` and `GET /api/changes/{id}/export.xlsx`.
+Tuning: the `CHANGE_*` settings in `.env.example`. Needs `docsmind db upgrade` (migration 0005).
+
 ### On-demand enrichment
 
 Embeddings and image captions are **not** created during ingest. They are opt-in because they call paid APIs.
@@ -195,11 +227,13 @@ HTTP:
 - `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`,
+`LLM_MODEL`), `AGENT_MAX_STEPS`, `AGENT_MEMORY_ENABLED`,
 `OPENAI_REASONING_EFFORT`, `OPENAI_BASE_URL`. See `.env.example`.
 
 HTTP: `POST /api/chat` streams Server-Sent Events (`route`, `plan`, `tool_start`, `tool_end`,
-`subagent_start`, `subagent_end`, `token`, `note`, `answer`, `error`, `done`);
+`subagent_start`, `subagent_end`, `analysis_start`, `analysis_status`, `change_row`,
+`change_row_update`, `change_row_removed`, `analysis_done`, `token`, `note`, `answer`, `error`,
+`done`);
 `GET /api/conversations[/{id}]`, `DELETE /api/conversations/{id}`, `GET /api/agent`.
 
 ## How ingestion works
@@ -237,7 +271,7 @@ heuristics that work on one PDF break on the next.
 | `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 |
+| `docsmind diff <a> <b> [--actionable] [--xlsx <file>]` | Compare two versions: change table, report, optional Excel file |
 
 ## Architecture
 

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "docsmind"
-version = "0.6.0"
+version = "0.8.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"
@@ -39,6 +39,7 @@ dependencies = [
     "imagehash>=4.3",
     "rich>=13.7",
     "tiktoken>=0.7",
+    "openpyxl>=3.1",
 ]
 
 [project.optional-dependencies]

{docsmind-0.6.0 → docsmind-0.8.0}/src/docsmind/__init__.py

@@ -6,7 +6,7 @@ detail and may change without notice while the package is 0.x.
 
 from docsmind.client import Docsmind
 from docsmind.config import DocsmindConfig
-from docsmind.domain.changes import Change, ChangeSet, ImpactAssessment
+from docsmind.domain.changes import ChangeAnalysis, ChangeResult, ChangeRow
 from docsmind.domain.citations import Citation
 from docsmind.domain.documents import Chunk, Document, DocumentVersion, Section
 from docsmind.domain.tables import AgentTable
@@ -15,15 +15,15 @@ __version__ = "0.2.0"
 
 __all__ = [
     "AgentTable",
-    "Change",
-    "ChangeSet",
+    "ChangeAnalysis",
+    "ChangeResult",
+    "ChangeRow",
     "Chunk",
     "Citation",
     "Docsmind",
     "DocsmindConfig",
     "Document",
     "DocumentVersion",
-    "ImpactAssessment",
     "Section",
     "__version__",
 ]

docsmind-0.8.0/src/docsmind/adapters/storage/memory.py

@@ -0,0 +1,151 @@
+"""In-memory `ConversationStore` / `MemoryStore` / `ChangeStore`. Used by tests and by
+one-off scripts that don't want to touch Postgres; same contract as the
+Postgres versions."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any
+from uuid import UUID
+
+from docsmind.domain.agent import Conversation, MemoryItem, StoredMessage
+from docsmind.domain.changes import ChangeAnalysis, ChangeRow
+
+
+class InMemoryConversationStore:
+    def __init__(self) -> None:
+        self._conversations: dict[UUID, Conversation] = {}
+        self._messages: dict[UUID, list[StoredMessage]] = {}
+
+    async def create(self, title: str) -> Conversation:
+        conversation = Conversation(title=title[:120])
+        self._conversations[conversation.id] = conversation
+        self._messages[conversation.id] = []
+        return conversation
+
+    async def get(self, conversation_id: UUID) -> Conversation | None:
+        return self._conversations.get(conversation_id)
+
+    async def list(self, limit: int = 50) -> list[dict]:
+        rows = []
+        for c in sorted(self._conversations.values(), key=lambda c: c.updated_at, reverse=True):
+            msgs = self._messages[c.id]
+            last = next((m for m in reversed(msgs) if m.role == "assistant"), None)
+            rows.append(
+                {
+                    "id": c.id,
+                    "title": c.title,
+                    "created_at": c.created_at,
+                    "updated_at": c.updated_at,
+                    "message_count": len(msgs),
+                    "last_answer": last.content if last else None,
+                    "last_citations": last.citations if last else [],
+                }
+            )
+        return rows[:limit]
+
+    async def messages(self, conversation_id: UUID) -> list[StoredMessage]:
+        return list(self._messages.get(conversation_id, []))
+
+    async def append(self, conversation_id: UUID, messages: list[StoredMessage]) -> None:
+        stored = self._messages[conversation_id]
+        for m in messages:
+            stored.append(m.model_copy(update={"ordinal": len(stored)}))
+        self._conversations[conversation_id].updated_at = datetime.now(timezone.utc)
+
+    async def set_summary(self, conversation_id: UUID, summary: str, upto: int) -> None:
+        c = self._conversations[conversation_id]
+        c.summary = summary
+        c.summarized_upto = upto
+
+    async def delete(self, conversation_id: UUID) -> bool:
+        self._messages.pop(conversation_id, None)
+        return self._conversations.pop(conversation_id, None) is not None
+
+
+class InMemoryMemoryStore:
+    def __init__(self) -> None:
+        self._items: dict[str, MemoryItem] = {}
+
+    async def add(self, items: list[MemoryItem]) -> int:
+        added = 0
+        for item in items:
+            if item.key not in self._items:
+                self._items[item.key] = item
+                added += 1
+        return added
+
+    async def recall(self, *, version_ids: list[UUID] | None, limit: int) -> list[MemoryItem]:
+        items = [
+            i
+            for i in self._items.values()
+            if version_ids is None or i.kind == "fact" or i.version_id in version_ids
+        ]
+        items.sort(key=lambda i: i.created_at, reverse=True)
+        return items[:limit]
+
+
+class InMemoryChangeStore:
+    """`ChangeStore` in memory (tests, scripts). Same contract as `PostgresChangeStore`."""
+
+    def __init__(self) -> None:
+        self._analyses: dict[UUID, ChangeAnalysis] = {}
+        self._rows: dict[UUID, ChangeRow] = {}
+
+    async def create_analysis(self, analysis: ChangeAnalysis) -> None:
+        self._analyses[analysis.id] = analysis.model_copy(deep=True)
+
+    async def update_analysis(self, analysis_id: UUID, **fields: Any) -> None:
+        current = self._analyses[analysis_id]
+        self._analyses[analysis_id] = current.model_copy(update={**fields, "updated_at": datetime.now(timezone.utc)})
+
+    async def get_analysis(self, analysis_id: UUID) -> ChangeAnalysis | None:
+        found = self._analyses.get(analysis_id)
+        return found.model_copy(deep=True) if found else None
+
+    async def list_analyses(self, limit: int = 50) -> list[dict]:
+        newest = sorted(self._analyses.values(), key=lambda a: a.created_at, reverse=True)
+        return [
+            {
+                "id": a.id,
+                "status": a.status,
+                "mode": a.mode,
+                "diff_ratio": a.diff_ratio,
+                "created_at": a.created_at,
+                "updated_at": a.updated_at,
+                "current_version_id": a.current_version_id,
+                "previous_version_id": a.previous_version_id,
+                "row_count": sum(r.analysis_id == a.id for r in self._rows.values()),
+                "verified_count": sum(r.analysis_id == a.id and r.verified for r in self._rows.values()),
+            }
+            for a in newest[:limit]
+        ]
+
+    async def delete_analysis(self, analysis_id: UUID) -> bool:
+        for row_id in [r.id for r in self._rows.values() if r.analysis_id == analysis_id]:
+            del self._rows[row_id]
+        return self._analyses.pop(analysis_id, None) is not None
+
+    async def add_row(self, row: ChangeRow) -> ChangeRow:
+        ordinal = max((r.ordinal for r in self._rows.values() if r.analysis_id == row.analysis_id), default=-1) + 1
+        stored = row.model_copy(update={"ordinal": ordinal}, deep=True)
+        self._rows[stored.id] = stored
+        return stored.model_copy(deep=True)
+
+    async def update_row(self, row_id: UUID, **fields: Any) -> ChangeRow | None:
+        current = self._rows.get(row_id)
+        if current is None:
+            return None
+        self._rows[row_id] = current.model_copy(update={**fields, "updated_at": datetime.now(timezone.utc)})
+        return self._rows[row_id].model_copy(deep=True)
+
+    async def get_row(self, row_id: UUID) -> ChangeRow | None:
+        found = self._rows.get(row_id)
+        return found.model_copy(deep=True) if found else None
+
+    async def delete_row(self, row_id: UUID) -> bool:
+        return self._rows.pop(row_id, None) is not None
+
+    async def list_rows(self, analysis_id: UUID) -> list[ChangeRow]:
+        rows = [r for r in self._rows.values() if r.analysis_id == analysis_id]
+        return [r.model_copy(deep=True) for r in sorted(rows, key=lambda r: r.ordinal)]

docsmind-0.8.0/src/docsmind/adapters/storage/postgres/change_store.py

@@ -0,0 +1,189 @@
+"""Postgres implementation of `ChangeStore`: change analyses and their rows."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any
+from uuid import UUID
+
+from sqlalchemy import delete, func, insert, select, text, update
+
+from docsmind.adapters.storage.postgres.engine import get_sessionmaker
+from docsmind.adapters.storage.postgres.tables import change_analyses as analyses_table
+from docsmind.adapters.storage.postgres.tables import change_rows as rows_table
+from docsmind.config import DocsmindConfig
+from docsmind.domain.changes import ChangeAnalysis, ChangeRow, Proof
+
+_ROW_FIELDS = {
+    "current_clause",
+    "previous_clause",
+    "change_description",
+    "nature",
+    "category",
+    "compliance_requirement",
+    "binding",
+    "applicability_scope",
+    "verified",
+    "proof",
+    "verification_note",
+    "approved",
+}
+_ANALYSIS_FIELDS = {
+    "status",
+    "mode",
+    "diff_ratio",
+    "public",
+    "verdict_note",
+    "changelog",
+    "report",
+    "meta",
+}
+
+
+def _now() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+def _row_from_db(row: Any) -> ChangeRow:
+    data = dict(row)
+    data["proof"] = [Proof(**p) for p in (data.get("proof") or [])]
+    return ChangeRow(**data)
+
+
+def _row_values(row: ChangeRow) -> dict[str, Any]:
+    return {
+        "id": row.id,
+        "analysis_id": row.analysis_id,
+        "ordinal": row.ordinal,
+        "current_clause": row.current_clause,
+        "previous_clause": row.previous_clause,
+        "change_description": row.change_description,
+        "nature": row.nature.value,
+        "category": row.category,
+        "compliance_requirement": row.compliance_requirement,
+        "binding": row.binding.value,
+        "applicability_scope": row.applicability_scope,
+        "verified": row.verified,
+        "proof": [p.model_dump(mode="json") for p in row.proof],
+        "verification_note": row.verification_note,
+        "approved": row.approved,
+        "origin": row.origin,
+        "created_at": row.created_at,
+        "updated_at": row.updated_at,
+    }
+
+
+def _plain(value: Any) -> Any:
+    """Enums and models to what JSONB/text columns take."""
+    if hasattr(value, "value"):
+        return value.value
+    if isinstance(value, list):
+        return [p.model_dump(mode="json") if hasattr(p, "model_dump") else p for p in value]
+    return value
+
+
+class PostgresChangeStore:
+    def __init__(self, config: DocsmindConfig) -> None:
+        self._sessionmaker = get_sessionmaker(config)
+
+    # -- analyses ---------------------------------------------------------------
+
+    async def create_analysis(self, analysis: ChangeAnalysis) -> None:
+        async with self._sessionmaker() as session:
+            await session.execute(insert(analyses_table).values(**analysis.model_dump()))
+            await session.commit()
+
+    async def update_analysis(self, analysis_id: UUID, **fields: Any) -> None:
+        unknown = set(fields) - _ANALYSIS_FIELDS
+        if unknown:
+            raise ValueError(f"Cannot update analysis fields: {sorted(unknown)}")
+        async with self._sessionmaker() as session:
+            await session.execute(
+                update(analyses_table)
+                .where(analyses_table.c.id == analysis_id)
+                .values(**{k: _plain(v) for k, v in fields.items()}, updated_at=_now())
+            )
+            await session.commit()
+
+    async def get_analysis(self, analysis_id: UUID) -> ChangeAnalysis | None:
+        async with self._sessionmaker() as session:
+            result = await session.execute(select(analyses_table).where(analyses_table.c.id == analysis_id))
+            row = result.mappings().first()
+        return ChangeAnalysis(**dict(row)) if row else None
+
+    _LIST_SQL = text(
+        """
+        SELECT a.id, a.status, a.mode, a.diff_ratio, a.created_at, a.updated_at,
+               a.current_version_id, a.previous_version_id,
+               dc.title AS current_title, vc.label AS current_label,
+               dp.title AS previous_title, vp.label AS previous_label,
+               (SELECT count(*) FROM change_rows r WHERE r.analysis_id = a.id) AS row_count,
+               (SELECT count(*) FROM change_rows r WHERE r.analysis_id = a.id AND r.verified) AS verified_count
+        FROM change_analyses a
+        JOIN document_versions vc ON vc.id = a.current_version_id
+        JOIN documents dc ON dc.id = vc.document_id
+        JOIN document_versions vp ON vp.id = a.previous_version_id
+        JOIN documents dp ON dp.id = vp.document_id
+        ORDER BY a.created_at DESC
+        LIMIT :limit
+        """
+    )
+
+    async def list_analyses(self, limit: int = 50) -> list[dict]:
+        async with self._sessionmaker() as session:
+            result = await session.execute(self._LIST_SQL, {"limit": limit})
+            return [dict(row) for row in result.mappings().all()]
+
+    async def delete_analysis(self, analysis_id: UUID) -> bool:
+        async with self._sessionmaker() as session:
+            result = await session.execute(delete(analyses_table).where(analyses_table.c.id == analysis_id))
+            await session.commit()
+            return result.rowcount > 0
+
+    # -- rows ----------------------------------------------------------------------
+
+    async def add_row(self, row: ChangeRow) -> ChangeRow:
+        async with self._sessionmaker() as session:
+            next_ordinal = (
+                await session.execute(
+                    select(func.coalesce(func.max(rows_table.c.ordinal), -1)).where(
+                        rows_table.c.analysis_id == row.analysis_id
+                    )
+                )
+            ).scalar_one() + 1
+            stored = row.model_copy(update={"ordinal": int(next_ordinal)})
+            await session.execute(insert(rows_table).values(**_row_values(stored)))
+            await session.commit()
+        return stored
+
+    async def update_row(self, row_id: UUID, **fields: Any) -> ChangeRow | None:
+        unknown = set(fields) - _ROW_FIELDS
+        if unknown:
+            raise ValueError(f"Cannot update row fields: {sorted(unknown)}")
+        async with self._sessionmaker() as session:
+            await session.execute(
+                update(rows_table)
+                .where(rows_table.c.id == row_id)
+                .values(**{k: _plain(v) for k, v in fields.items()}, updated_at=_now())
+            )
+            await session.commit()
+        return await self.get_row(row_id)
+
+    async def get_row(self, row_id: UUID) -> ChangeRow | None:
+        async with self._sessionmaker() as session:
+            result = await session.execute(select(rows_table).where(rows_table.c.id == row_id))
+            row = result.mappings().first()
+        return _row_from_db(row) if row else None
+
+    async def delete_row(self, row_id: UUID) -> bool:
+        async with self._sessionmaker() as session:
+            result = await session.execute(delete(rows_table).where(rows_table.c.id == row_id))
+            await session.commit()
+            return result.rowcount > 0
+
+    async def list_rows(self, analysis_id: UUID) -> list[ChangeRow]:
+        async with self._sessionmaker() as session:
+            result = await session.execute(
+                select(rows_table).where(rows_table.c.analysis_id == analysis_id).order_by(rows_table.c.ordinal)
+            )
+            return [_row_from_db(r) for r in result.mappings().all()]