From 87cb61c8b2b3783ccfc6ff98bad4a33344aed2e3 Mon Sep 17 00:00:00 2001 From: anti Date: Mon, 27 Apr 2026 17:44:53 -0400 Subject: [PATCH] feat(realism): synthetic-files browser API MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds GET /api/v1/realism/synthetic-files (paginated list, filters by decky_uuid, persona, content_class) and GET /api/v1/realism/synthetic-files/{uuid} (single row with last_body and a truncated:bool flag set when the stored body is at the 64KB cap). Repo gains count_synthetic_files() and get_synthetic_file(uuid). The list view drops last_body to keep the wire payload bounded; the detail endpoint is the only path that returns it. Read-only — orchestrator remains the sole writer. --- decnet/web/db/repository.py | 23 ++- decnet/web/db/sqlmodel_repo.py | 33 ++++ decnet/web/router/__init__.py | 2 + .../web/router/realism/api_synthetic_files.py | 99 ++++++++++++ tests/api/realism/test_synthetic_files_api.py | 146 ++++++++++++++++++ tests/realism/test_synthetic_files_repo.py | 36 +++++ 6 files changed, 337 insertions(+), 2 deletions(-) create mode 100644 decnet/web/router/realism/api_synthetic_files.py create mode 100644 tests/api/realism/test_synthetic_files_api.py diff --git a/decnet/web/db/repository.py b/decnet/web/db/repository.py index 869bacb1..41552afd 100644 --- a/decnet/web/db/repository.py +++ b/decnet/web/db/repository.py @@ -1130,16 +1130,35 @@ class BaseRepository(ABC): *, decky_uuid: Optional[str] = None, persona: Optional[str] = None, + content_class: Optional[str] = None, limit: int = 100, offset: int = 0, ) -> list[dict[str, Any]]: """Paginated synthetic_files newest-first. - Optional filters narrow to one decky and/or one persona, used by - the dashboard's "files this decky has grown" view. + Optional filters narrow to one decky, persona, and/or content + class — used by the dashboard's "files this decky has grown" + view. """ raise NotImplementedError + async def count_synthetic_files( + self, + *, + decky_uuid: Optional[str] = None, + persona: Optional[str] = None, + content_class: Optional[str] = None, + ) -> int: + """Total synthetic_files matching the same filters as + :meth:`list_synthetic_files`. Used to drive paginated UI.""" + raise NotImplementedError + + async def get_synthetic_file( + self, uuid: str, + ) -> Optional[dict[str, Any]]: + """Single synthetic_files row by uuid, or ``None``.""" + raise NotImplementedError + async def pick_random_synthetic_file_for_edit( self, decky_uuid: str, diff --git a/decnet/web/db/sqlmodel_repo.py b/decnet/web/db/sqlmodel_repo.py index 6b7eb9ec..a3843151 100644 --- a/decnet/web/db/sqlmodel_repo.py +++ b/decnet/web/db/sqlmodel_repo.py @@ -3365,6 +3365,7 @@ class SQLModelRepository(BaseRepository): *, decky_uuid: Optional[str] = None, persona: Optional[str] = None, + content_class: Optional[str] = None, limit: int = 100, offset: int = 0, ) -> list[dict[str, Any]]: @@ -3374,6 +3375,8 @@ class SQLModelRepository(BaseRepository): stmt = stmt.where(SyntheticFile.decky_uuid == decky_uuid) if persona is not None: stmt = stmt.where(SyntheticFile.persona == persona) + if content_class is not None: + stmt = stmt.where(SyntheticFile.content_class == content_class) stmt = ( stmt.order_by(desc(SyntheticFile.last_modified)) .offset(offset) @@ -3382,6 +3385,36 @@ class SQLModelRepository(BaseRepository): result = await session.execute(stmt) return [r.model_dump(mode="json") for r in result.scalars().all()] + async def count_synthetic_files( + self, + *, + decky_uuid: Optional[str] = None, + persona: Optional[str] = None, + content_class: Optional[str] = None, + ) -> int: + from sqlalchemy import func as _f + async with self._session() as session: + stmt = select(_f.count(SyntheticFile.uuid)) + if decky_uuid is not None: + stmt = stmt.where(SyntheticFile.decky_uuid == decky_uuid) + if persona is not None: + stmt = stmt.where(SyntheticFile.persona == persona) + if content_class is not None: + stmt = stmt.where(SyntheticFile.content_class == content_class) + result = await session.execute(stmt) + return int(result.scalar() or 0) + + async def get_synthetic_file( + self, uuid: str, + ) -> Optional[dict[str, Any]]: + async with self._session() as session: + stmt = select(SyntheticFile).where(SyntheticFile.uuid == uuid) + result = await session.execute(stmt) + row = result.scalars().first() + if row is None: + return None + return row.model_dump(mode="json") + async def pick_random_synthetic_file_for_edit( self, decky_uuid: str, diff --git a/decnet/web/router/__init__.py b/decnet/web/router/__init__.py index e7b5e065..00bea6cd 100644 --- a/decnet/web/router/__init__.py +++ b/decnet/web/router/__init__.py @@ -32,6 +32,7 @@ from .campaigns.api_events import router as campaign_events_router from .orchestrator.api_list_events import router as orchestrator_list_router from .orchestrator.api_events import router as orchestrator_events_router from .realism.api_personas import router as realism_personas_router +from .realism.api_synthetic_files import router as realism_synthetic_files_router from .transcripts import transcripts_router from .config.api_get_config import router as config_get_router from .config.api_update_config import router as config_update_router @@ -115,6 +116,7 @@ api_router.include_router(orchestrator_events_router) # "Persona Generation" page. The orchestrator reads from the same # on-disk JSON file directly (see decnet.realism.personas_pool). api_router.include_router(realism_personas_router) +api_router.include_router(realism_synthetic_files_router) # Observability api_router.include_router(stats_router) diff --git a/decnet/web/router/realism/api_synthetic_files.py b/decnet/web/router/realism/api_synthetic_files.py new file mode 100644 index 00000000..7b8b7e89 --- /dev/null +++ b/decnet/web/router/realism/api_synthetic_files.py @@ -0,0 +1,99 @@ +"""GET ``/api/v1/realism/synthetic-files`` — browse planted realism files. + +The orchestrator's realism worker grows synthetic files on each decky +(notes, TODOs, drafts, scripts, log lines, canary artifacts). The +:class:`~decnet.web.db.models.realism.SyntheticFile` table is the +canonical record of what's been planted where; this endpoint lets +operators inspect the lineage without ssh'ing into a decky. + +Read-only. No writes — the orchestrator is the sole writer; the +dashboard is observation surface only. + +The body preview (``last_body``) is repo-clipped at 64 KB +(:data:`SYNTHETIC_FILE_BODY_LIMIT`); when the original was larger the +detail response carries ``truncated: true`` so the operator knows what +they're looking at. +""" +from __future__ import annotations + +from typing import Any, Optional + +from fastapi import APIRouter, Depends, HTTPException, Query + +from decnet.telemetry import traced as _traced +from decnet.web.db.models.realism import SYNTHETIC_FILE_BODY_LIMIT +from decnet.web.dependencies import repo, require_viewer + +router = APIRouter() + + +@router.get( + "/realism/synthetic-files", + tags=["Realism"], + responses={ + 401: {"description": "Could not validate credentials"}, + 403: {"description": "Insufficient permissions"}, + 422: {"description": "Validation error"}, + }, +) +@_traced("api.realism.list_synthetic_files") +async def list_synthetic_files( + limit: int = Query(50, ge=1, le=500), + offset: int = Query(0, ge=0, le=2147483647), + decky_uuid: Optional[str] = Query(None, max_length=64), + persona: Optional[str] = Query(None, max_length=128), + content_class: Optional[str] = Query(None, max_length=32), + user: dict = Depends(require_viewer), +) -> dict[str, Any]: + """Paginated synthetic_files newest-first. + + Filters: ``decky_uuid``, ``persona``, ``content_class``. The list + response strips ``last_body`` to keep the payload bounded — fetch + the detail endpoint for the body preview. + """ + rows = await repo.list_synthetic_files( + decky_uuid=decky_uuid, + persona=persona, + content_class=content_class, + limit=limit, + offset=offset, + ) + total = await repo.count_synthetic_files( + decky_uuid=decky_uuid, + persona=persona, + content_class=content_class, + ) + # The list view doesn't need bodies; drop them so the response stays + # small even when 50 rows each carry ~64 KB. Detail endpoint returns + # the body. + for r in rows: + r.pop("last_body", None) + return {"total": total, "limit": limit, "offset": offset, "data": rows} + + +@router.get( + "/realism/synthetic-files/{uuid}", + tags=["Realism"], + responses={ + 401: {"description": "Could not validate credentials"}, + 403: {"description": "Insufficient permissions"}, + 404: {"description": "Synthetic file not found"}, + }, +) +@_traced("api.realism.get_synthetic_file") +async def get_synthetic_file( + uuid: str, + user: dict = Depends(require_viewer), +) -> dict[str, Any]: + """Return one synthetic_files row including the body preview. + + ``truncated`` is true when the stored body is at the cap — the + decky filesystem holds the canonical bytes; the master view is a + snapshot. + """ + row = await repo.get_synthetic_file(uuid) + if row is None: + raise HTTPException(status_code=404, detail="synthetic file not found") + body = row.get("last_body") or "" + row["truncated"] = len(body) >= SYNTHETIC_FILE_BODY_LIMIT + return row diff --git a/tests/api/realism/test_synthetic_files_api.py b/tests/api/realism/test_synthetic_files_api.py new file mode 100644 index 00000000..18105693 --- /dev/null +++ b/tests/api/realism/test_synthetic_files_api.py @@ -0,0 +1,146 @@ +"""GET /api/v1/realism/synthetic-files — paginated browser API.""" +from __future__ import annotations + +from unittest.mock import AsyncMock, patch + +import pytest +from fastapi import HTTPException + +from decnet.web.db.models.realism import SYNTHETIC_FILE_BODY_LIMIT + + +def _row(**over): + base = { + "uuid": "sf-1", + "decky_uuid": "d-1", + "path": "/home/admin/notes.txt", + "persona": "admin", + "content_class": "note", + "created_at": "2026-04-27T10:00:00+00:00", + "last_modified": "2026-04-27T10:00:00+00:00", + "edit_count": 0, + "content_hash": "deadbeef" * 8, + "last_body": "hello world", + } + base.update(over) + return base + + +@pytest.mark.asyncio +async def test_list_returns_paginated_envelope(): + from decnet.web.router.realism.api_synthetic_files import ( + list_synthetic_files, + ) + + rows = [_row(uuid=f"sf-{i}") for i in range(3)] + with patch( + "decnet.web.router.realism.api_synthetic_files.repo" + ) as mock_repo: + mock_repo.list_synthetic_files = AsyncMock(return_value=rows) + mock_repo.count_synthetic_files = AsyncMock(return_value=3) + + result = await list_synthetic_files( + limit=50, offset=0, + decky_uuid=None, persona=None, content_class=None, + user={"uuid": "u", "role": "viewer"}, + ) + + assert result["total"] == 3 + assert result["limit"] == 50 + assert result["offset"] == 0 + assert len(result["data"]) == 3 + # List view drops the body to keep the payload small. + for r in result["data"]: + assert "last_body" not in r + + +@pytest.mark.asyncio +async def test_list_forwards_filters_to_repo(): + from decnet.web.router.realism.api_synthetic_files import ( + list_synthetic_files, + ) + + with patch( + "decnet.web.router.realism.api_synthetic_files.repo" + ) as mock_repo: + mock_repo.list_synthetic_files = AsyncMock(return_value=[]) + mock_repo.count_synthetic_files = AsyncMock(return_value=0) + + await list_synthetic_files( + limit=10, offset=20, + decky_uuid="d-7", persona="alice", content_class="todo", + user={"uuid": "u", "role": "viewer"}, + ) + + mock_repo.list_synthetic_files.assert_awaited_once_with( + decky_uuid="d-7", persona="alice", content_class="todo", + limit=10, offset=20, + ) + mock_repo.count_synthetic_files.assert_awaited_once_with( + decky_uuid="d-7", persona="alice", content_class="todo", + ) + + +@pytest.mark.asyncio +async def test_get_detail_returns_body_with_truncated_false(): + from decnet.web.router.realism.api_synthetic_files import ( + get_synthetic_file, + ) + + with patch( + "decnet.web.router.realism.api_synthetic_files.repo" + ) as mock_repo: + mock_repo.get_synthetic_file = AsyncMock(return_value=_row( + last_body="short body", + )) + + result = await get_synthetic_file( + uuid="sf-1", + user={"uuid": "u", "role": "viewer"}, + ) + + assert result["last_body"] == "short body" + assert result["truncated"] is False + + +@pytest.mark.asyncio +async def test_get_detail_marks_truncated_when_at_cap(): + from decnet.web.router.realism.api_synthetic_files import ( + get_synthetic_file, + ) + + body = "X" * SYNTHETIC_FILE_BODY_LIMIT + with patch( + "decnet.web.router.realism.api_synthetic_files.repo" + ) as mock_repo: + mock_repo.get_synthetic_file = AsyncMock(return_value=_row( + last_body=body, + )) + + result = await get_synthetic_file( + uuid="sf-1", + user={"uuid": "u", "role": "viewer"}, + ) + + assert len(result["last_body"]) == SYNTHETIC_FILE_BODY_LIMIT + assert result["truncated"] is True + + +@pytest.mark.asyncio +async def test_get_detail_404_when_missing(): + from decnet.web.router.realism.api_synthetic_files import ( + get_synthetic_file, + ) + + with patch( + "decnet.web.router.realism.api_synthetic_files.repo" + ) as mock_repo: + mock_repo.get_synthetic_file = AsyncMock(return_value=None) + + with pytest.raises(HTTPException) as exc: + await get_synthetic_file( + uuid="missing", + user={"uuid": "u", "role": "viewer"}, + ) + + assert exc.value.status_code == 404 diff --git a/tests/realism/test_synthetic_files_repo.py b/tests/realism/test_synthetic_files_repo.py index 9b61b4b3..8a5f5a24 100644 --- a/tests/realism/test_synthetic_files_repo.py +++ b/tests/realism/test_synthetic_files_repo.py @@ -114,3 +114,39 @@ async def test_pick_random_returns_eligible_row(repo): assert picked is not None assert picked["content_class"] == "todo" assert picked["path"] == "/home/admin/TODO.md" + + +@pytest.mark.asyncio +async def test_count_synthetic_files_respects_filters(repo): + await repo.record_synthetic_file(_row(decky="d1", path="/a", cls="todo")) + await repo.record_synthetic_file(_row(decky="d1", path="/b", cls="note")) + await repo.record_synthetic_file(_row(decky="d2", path="/c", cls="todo")) + assert await repo.count_synthetic_files() == 3 + assert await repo.count_synthetic_files(decky_uuid="d1") == 2 + assert await repo.count_synthetic_files(content_class="todo") == 2 + assert await repo.count_synthetic_files( + decky_uuid="d1", content_class="note", + ) == 1 + + +@pytest.mark.asyncio +async def test_list_filters_by_content_class(repo): + await repo.record_synthetic_file(_row(decky="d1", path="/a", cls="todo")) + await repo.record_synthetic_file(_row(decky="d1", path="/b", cls="note")) + rows = await repo.list_synthetic_files(content_class="todo") + assert len(rows) == 1 + assert rows[0]["content_class"] == "todo" + + +@pytest.mark.asyncio +async def test_get_synthetic_file_returns_row(repo): + uuid = await repo.record_synthetic_file(_row(decky="d1", path="/a")) + got = await repo.get_synthetic_file(uuid) + assert got is not None + assert got["uuid"] == uuid + assert got["path"] == "/a" + + +@pytest.mark.asyncio +async def test_get_synthetic_file_returns_none_when_missing(repo): + assert await repo.get_synthetic_file("does-not-exist") is None