Feat: persist sealed runs to SQLite

.env.example

@@ -28,5 +28,11 @@ LLM_APP_NAME=AI_Survey_Simulator
 FRONTEND_BACKEND_BASE_URL=http://localhost:8000
 FRONTEND_WEBSOCKET_URL=ws://localhost:8000/ws/conversation
 
+# Persistence (SQLite)
+# Local default:
+DB_PATH=.localdata/converta.db
+# Hugging Face Spaces recommended:
+# DB_PATH=/data/converta/converta.db
+
 # Logging
 LOG_LEVEL=INFO

README.md

@@ -45,6 +45,9 @@ LLM_APP_NAME=AI_Survey_Simulator
 
 Other environment values (ports, websocket URL, log level) are already set in `.env.example`.
 
+Persistence:
+- `DB_PATH` controls where sealed runs are stored (SQLite). Local default: `.localdata/converta.db`; HF Spaces: `/data/converta/converta.db`.
+
 ---
 
 ## 2. Install Python Dependencies

backend/api/analysis_routes.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import logging
 import io
 import re
 from datetime import datetime
@@ -11,9 +12,12 @@ from fastapi import APIRouter, File, Form, HTTPException, UploadFile
 from pydantic import BaseModel, Field
 
 from .conversation_service import run_resource_agent_analysis
+from .storage_service import get_run_store
 from config.settings import get_settings
+from backend.storage import RunRecord
 
 router = APIRouter(prefix="", tags=["analysis"])
+logger = logging.getLogger(__name__)
 
 
 class ExportMessage(BaseModel):
@@ -30,6 +34,8 @@ class AnalyzeTextRequest(BaseModel):
 
 
 class AnalyzeTextResponse(BaseModel):
+    run_id: Optional[str] = None
+    persisted: bool = False
     conversation_id: str
     messages: List[ExportMessage]
     resources: Dict[str, Any]
@@ -136,7 +142,48 @@ async def _analyze_from_text(*, text: str, conversation_id: str, source_name: Op
         settings=settings,
     )
 
+    persisted = False
+    run_id = None
+    try:
+        store = get_run_store()
+        run_id = conversation_id
+        config_snapshot: Dict[str, Any] = {
+            "llm": {
+                "backend": settings.llm.backend,
+                "host": settings.llm.host,
+                "model": settings.llm.model,
+                "timeout": settings.llm.timeout,
+                "max_retries": settings.llm.max_retries,
+                "retry_delay": settings.llm.retry_delay,
+            },
+            "text_analysis": {
+                "source_name": source_name,
+            },
+        }
+        record = RunRecord(
+            run_id=run_id,
+            mode="text_analysis",
+            status="completed",
+            created_at=exported_at,
+            ended_at=exported_at,
+            sealed_at=exported_at,
+            title=None,
+            input_summary=source_name,
+            config=config_snapshot,
+            messages=transcript,
+            analyses={"resource_agent_v2": resources},
+            persona_snapshots={},
+        )
+        await store.save_sealed_run(record)
+        persisted = True
+    except Exception as e:
+        logger.error(f"Failed to persist sealed text analysis {conversation_id}: {e}")
+        persisted = False
+        run_id = None
+
     return AnalyzeTextResponse(
+        run_id=run_id,
+        persisted=persisted,
         conversation_id=conversation_id,
         messages=ui_messages,
         resources=resources,
@@ -208,4 +255,3 @@ async def analyze_file(
         conversation_id=cid,
         source_name=inferred_name,
     )
-

backend/api/conversation_service.py

@@ -40,6 +40,8 @@ from backend.core.conversation_manager import ConversationManager  # noqa: E402
 from backend.core.llm_client import create_llm_client  # noqa: E402
 from backend.core.persona_system import PersonaSystem  # noqa: E402
 from .conversation_ws import ConnectionManager  # noqa: E402
+from .storage_service import get_run_store  # noqa: E402
+from backend.storage import RunRecord  # noqa: E402
 
 # Setup logging
 logger = logging.getLogger(__name__)
@@ -821,6 +823,7 @@ class ConversationService:
         if not conv_info:
             return
         try:
+            seal_timestamp = datetime.now().isoformat()
             parsed = await run_resource_agent_analysis(
                 transcript=transcript,
                 llm_backend=conv_info.llm_backend,
@@ -828,9 +831,66 @@ class ConversationService:
                 model=conv_info.model,
                 settings=self.settings,
             )
+
+            persisted = False
+            run_id = None
+            try:
+                store = get_run_store()
+                mode = "human_to_ai" if conversation_id in self.active_human_chats else "ai_to_ai"
+
+                persona_snapshots: Dict[str, Dict[str, Any]] = {}
+                try:
+                    surveyor_persona = self.persona_system.get_persona(conv_info.surveyor_persona_id) or {}
+                    patient_persona = self.persona_system.get_persona(conv_info.patient_persona_id) or {}
+                    persona_snapshots = {
+                        "surveyor": {"persona_id": conv_info.surveyor_persona_id, "persona_version_id": None, "snapshot": surveyor_persona},
+                        "patient": {"persona_id": conv_info.patient_persona_id, "persona_version_id": None, "snapshot": patient_persona},
+                    }
+                except Exception:
+                    persona_snapshots = {}
+
+                config_snapshot: Dict[str, Any] = {
+                    "llm": {
+                        "backend": conv_info.llm_backend,
+                        "host": conv_info.host,
+                        "model": conv_info.model,
+                        "timeout": self.settings.llm.timeout,
+                        "max_retries": self.settings.llm.max_retries,
+                        "retry_delay": self.settings.llm.retry_delay,
+                    },
+                    "personas": {
+                        "surveyor_persona_id": conv_info.surveyor_persona_id,
+                        "patient_persona_id": conv_info.patient_persona_id,
+                        "surveyor_prompt_addition": getattr(conv_info, "surveyor_prompt_addition", None),
+                        "patient_prompt_addition": getattr(conv_info, "patient_prompt_addition", None),
+                    },
+                }
+
+                run_id = conversation_id
+                record = RunRecord(
+                    run_id=run_id,
+                    mode=mode,
+                    status="completed",
+                    created_at=getattr(conv_info, "created_at").isoformat(),
+                    ended_at=seal_timestamp,
+                    sealed_at=seal_timestamp,
+                    title=None,
+                    input_summary=None,
+                    config=config_snapshot,
+                    messages=transcript,
+                    analyses={"resource_agent_v2": parsed},
+                    persona_snapshots=persona_snapshots,
+                )
+                await store.save_sealed_run(record)
+                persisted = True
+            except Exception as e:
+                logger.error(f"Failed to persist sealed run {conversation_id}: {e}")
+
             await self.websocket_manager.send_to_conversation(conversation_id, {
                 "type": "resource_agent_result",
                 "conversation_id": conversation_id,
+                "run_id": run_id if persisted else None,
+                "persisted": persisted,
                 "data": parsed,
                 "timestamp": datetime.now().isoformat(),
             })

backend/api/export_routes.py

@@ -28,6 +28,11 @@ class ExportRequest(BaseModel):
     resources: Dict[str, Any] = Field(default_factory=dict, description="Resource agent output + evidence_catalog")
 
 
+def _filename(conversation_id: str, exported_at: str, ext: str) -> str:
+    safe_ts = exported_at.replace(":", "-")
+    return f"converta_{conversation_id}_{safe_ts}.{ext.lstrip('.')}"
+
+
 def _safe_join(values: Any, sep: str = "; ") -> str:
     if not values:
         return ""
@@ -48,8 +53,7 @@ def _extract_evidence_ids(evidence: Any) -> List[str]:
     return evidence_ids
 
 
-@router.post("/export/json")
-async def export_json(payload: ExportRequest) -> Response:
+def _export_json_bytes(payload: ExportRequest) -> bytes:
     exported_at = payload.exported_at or datetime.now().isoformat()
     export_obj = {
         "conversation_id": payload.conversation_id,
@@ -57,19 +61,12 @@ async def export_json(payload: ExportRequest) -> Response:
         "messages": [m.model_dump() for m in payload.messages],
         "resources": payload.resources,
     }
-    data = json.dumps(export_obj, ensure_ascii=False, indent=2).encode("utf-8")
-    filename = f"converta_{payload.conversation_id}_{exported_at.replace(':', '-')}.json"
-    headers = {"Content-Disposition": f'attachment; filename="{filename}"'}
-    return Response(content=data, media_type="application/json", headers=headers)
+    return json.dumps(export_obj, ensure_ascii=False, indent=2).encode("utf-8")
 
 
-@router.post("/export/xlsx")
-async def export_xlsx(payload: ExportRequest) -> Response:
-    try:
-        from openpyxl import Workbook
-        from openpyxl.styles import Alignment, Font
-    except Exception as e:
-        raise HTTPException(status_code=500, detail=f"openpyxl not available: {e}")
+def _export_xlsx_bytes(payload: ExportRequest) -> bytes:
+    from openpyxl import Workbook
+    from openpyxl.styles import Alignment, Font
 
     exported_at = payload.exported_at or datetime.now().isoformat()
     wb = Workbook()
@@ -108,6 +105,7 @@ async def export_xlsx(payload: ExportRequest) -> Response:
     evidence_catalog = payload.resources.get("evidence_catalog") or {}
     ws_ev = add_sheet("EvidenceCatalog", ["evidence_id", "message_index", "sentence_index", "sentence_text"])
     if isinstance(evidence_catalog, dict):
+
         def sort_key(item):
             _, val = item
             if not isinstance(val, dict):
@@ -119,12 +117,14 @@ async def export_xlsx(payload: ExportRequest) -> Response:
         for evidence_id, entry in sorted(evidence_catalog.items(), key=sort_key):
             if not isinstance(entry, dict):
                 continue
-            ws_ev.append([
-                str(evidence_id),
-                entry.get("message_index", ""),
-                entry.get("sentence_index", ""),
-                entry.get("text", "") or "",
-            ])
+            ws_ev.append(
+                [
+                    str(evidence_id),
+                    entry.get("message_index", ""),
+                    entry.get("sentence_index", ""),
+                    entry.get("text", "") or "",
+                ]
+            )
 
     ws_hs = add_sheet("HealthSituations", ["index", "code", "summary", "confidence", "evidence_ids"])
     health_situations = payload.resources.get("health_situations") or []
@@ -133,13 +133,15 @@ async def export_xlsx(payload: ExportRequest) -> Response:
             if not isinstance(item, dict):
                 continue
             evidence_ids = _extract_evidence_ids(item.get("evidence"))
-            ws_hs.append([
-                idx,
-                item.get("code", "") or "",
-                item.get("summary", "") or "",
-                item.get("confidence", ""),
-                _safe_join(evidence_ids),
-            ])
+            ws_hs.append(
+                [
+                    idx,
+                    item.get("code", "") or "",
+                    item.get("summary", "") or "",
+                    item.get("confidence", ""),
+                    _safe_join(evidence_ids),
+                ]
+            )
 
     ws_care = add_sheet("CareExperience", ["tone", "summary", "confidence", "reasons", "evidence_ids"])
     care = payload.resources.get("care_experience") or {}
@@ -149,13 +151,15 @@ async def export_xlsx(payload: ExportRequest) -> Response:
             if not isinstance(box, dict):
                 continue
             evidence_ids = _extract_evidence_ids(box.get("evidence"))
-            ws_care.append([
-                tone,
-                box.get("summary", "") or "",
-                box.get("confidence", ""),
-                _safe_join(box.get("reasons") or [], sep=" | "),
-                _safe_join(evidence_ids),
-            ])
+            ws_care.append(
+                [
+                    tone,
+                    box.get("summary", "") or "",
+                    box.get("confidence", ""),
+                    _safe_join(box.get("reasons") or [], sep=" | "),
+                    _safe_join(evidence_ids),
+                ]
+            )
 
     ws_td = add_sheet("TopDownCodes", ["category", "index", "code", "summary", "confidence", "evidence_ids"])
     top_down = payload.resources.get("top_down_codes") or {}
@@ -167,14 +171,16 @@ async def export_xlsx(payload: ExportRequest) -> Response:
                 if not isinstance(item, dict):
                     continue
                 evidence_ids = _extract_evidence_ids(item.get("evidence"))
-                ws_td.append([
-                    str(category),
-                    idx,
-                    item.get("code", "") or "",
-                    item.get("summary", "") or "",
-                    item.get("confidence", ""),
-                    _safe_join(evidence_ids),
-                ])
+                ws_td.append(
+                    [
+                        str(category),
+                        idx,
+                        item.get("code", "") or "",
+                        item.get("summary", "") or "",
+                        item.get("confidence", ""),
+                        _safe_join(evidence_ids),
+                    ]
+                )
 
     for ws in wb.worksheets:
         for row in ws.iter_rows(min_row=2):
@@ -183,13 +189,30 @@ async def export_xlsx(payload: ExportRequest) -> Response:
 
     buf = io.BytesIO()
     wb.save(buf)
-    data = buf.getvalue()
+    return buf.getvalue()
 
-    filename = f"converta_{payload.conversation_id}_{exported_at.replace(':', '-')}.xlsx"
+
+@router.post("/export/json")
+async def export_json(payload: ExportRequest) -> Response:
+    exported_at = payload.exported_at or datetime.now().isoformat()
+    data = _export_json_bytes(payload)
+    filename = _filename(payload.conversation_id, exported_at, "json")
+    headers = {"Content-Disposition": f'attachment; filename="{filename}"'}
+    return Response(content=data, media_type="application/json", headers=headers)
+
+
+@router.post("/export/xlsx")
+async def export_xlsx(payload: ExportRequest) -> Response:
+    try:
+        data = _export_xlsx_bytes(payload)
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"openpyxl not available: {e}")
+
+    exported_at = payload.exported_at or datetime.now().isoformat()
+    filename = _filename(payload.conversation_id, exported_at, "xlsx")
     headers = {"Content-Disposition": f'attachment; filename="{filename}"'}
     return Response(
         content=data,
         media_type="application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
         headers=headers,
     )
-

backend/api/main.py

@@ -32,7 +32,10 @@ from .conversation_routes import router as conversation_router  # noqa: E402
 from .persona_routes import router as persona_router  # noqa: E402
 from .export_routes import router as export_router  # noqa: E402
 from .analysis_routes import router as analysis_router  # noqa: E402
+from .run_routes import router as run_router  # noqa: E402
+from .run_export_routes import router as run_export_router  # noqa: E402
 from .conversation_service import initialize_conversation_service  # noqa: E402
+from .storage_service import initialize_run_store  # noqa: E402
 from backend.core.auth import COOKIE_NAME, INTERNAL_HEADER, get_app_password, verify_session_token  # noqa: E402
 
 # Load application settings
@@ -67,6 +70,8 @@ app.include_router(conversation_router)
 app.include_router(persona_router)
 app.include_router(export_router)
 app.include_router(analysis_router)
+app.include_router(run_router)
+app.include_router(run_export_router)
 
 @app.middleware("http")
 async def auth_middleware(request: Request, call_next):
@@ -102,6 +107,7 @@ async def startup_event():
 
     # Initialize conversation service with WebSocket manager and settings
     initialize_conversation_service(manager, settings)
+    await initialize_run_store(settings)
 
     logger.info("API startup complete")
 

backend/api/run_export_routes.py

@@ -0,0 +1,72 @@
+"""Export sealed runs using server-canonical persisted data."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any, Dict, List
+
+from fastapi import APIRouter, HTTPException
+from fastapi.responses import Response
+
+from .export_routes import ExportMessage, ExportRequest, _export_json_bytes, _export_xlsx_bytes, _filename
+from .storage_service import get_run_store
+
+router = APIRouter(prefix="", tags=["runs", "export"])
+
+
+def _payload_from_run(*, run_id: str, messages: List[Dict[str, Any]], resources: Dict[str, Any]) -> ExportRequest:
+    exported_at = datetime.now().isoformat()
+    export_messages = [
+        ExportMessage(
+            role=str(m.get("role") or ""),
+            persona=m.get("persona"),
+            time=m.get("timestamp"),
+            text=str(m.get("content") or ""),
+        )
+        for m in (messages or [])
+    ]
+    return ExportRequest(
+        conversation_id=run_id,
+        exported_at=exported_at,
+        messages=export_messages,
+        resources=resources or {},
+    )
+
+
+@router.get("/runs/{run_id}/export/json")
+async def export_run_json(run_id: str) -> Response:
+    store = get_run_store()
+    record = await store.get_run(run_id)
+    if record is None:
+        raise HTTPException(status_code=404, detail="Run not found")
+
+    resources = record.analyses.get("resource_agent_v2") or {}
+    payload = _payload_from_run(run_id=record.run_id, messages=record.messages, resources=resources)
+    data = _export_json_bytes(payload)
+    filename = _filename(payload.conversation_id, payload.exported_at or datetime.now().isoformat(), "json")
+    headers = {"Content-Disposition": f'attachment; filename="{filename}"'}
+    return Response(content=data, media_type="application/json", headers=headers)
+
+
+@router.get("/runs/{run_id}/export/xlsx")
+async def export_run_xlsx(run_id: str) -> Response:
+    store = get_run_store()
+    record = await store.get_run(run_id)
+    if record is None:
+        raise HTTPException(status_code=404, detail="Run not found")
+
+    resources = record.analyses.get("resource_agent_v2") or {}
+    payload = _payload_from_run(run_id=record.run_id, messages=record.messages, resources=resources)
+    try:
+        data = _export_xlsx_bytes(payload)
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"openpyxl not available: {e}")
+
+    filename = _filename(payload.conversation_id, payload.exported_at or datetime.now().isoformat(), "xlsx")
+    headers = {"Content-Disposition": f'attachment; filename="{filename}"'}
+    return Response(
+        content=data,
+        media_type="application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+        headers=headers,
+    )
+

backend/api/run_routes.py

@@ -0,0 +1,89 @@
+"""Run history endpoints (sealed runs only)."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from fastapi import APIRouter, HTTPException, Query
+from pydantic import BaseModel
+
+from .storage_service import get_run_store
+
+router = APIRouter(prefix="", tags=["runs"])
+
+
+class RunSummaryResponse(BaseModel):
+    run_id: str
+    mode: str
+    status: str
+    created_at: str
+    ended_at: str
+    title: Optional[str] = None
+    input_summary: Optional[str] = None
+
+
+class RunMessageResponse(BaseModel):
+    role: str
+    persona: Optional[str] = None
+    time: Optional[str] = None
+    text: str
+
+
+class RunRecordResponse(BaseModel):
+    run_id: str
+    conversation_id: str
+    mode: str
+    status: str
+    created_at: str
+    ended_at: str
+    sealed_at: str
+    title: Optional[str] = None
+    input_summary: Optional[str] = None
+    config: Dict[str, Any]
+    messages: List[RunMessageResponse]
+    resources: Dict[str, Any]
+
+
+@router.get("/runs", response_model=List[RunSummaryResponse])
+async def list_runs(
+    mode: Optional[str] = Query(default=None),
+    limit: int = Query(default=50, ge=1, le=200),
+    offset: int = Query(default=0, ge=0),
+) -> List[RunSummaryResponse]:
+    store = get_run_store()
+    rows = await store.list_runs(mode=mode, limit=limit, offset=offset)
+    return [RunSummaryResponse(**row.__dict__) for row in rows]
+
+
+@router.get("/runs/{run_id}", response_model=RunRecordResponse)
+async def get_run(run_id: str) -> RunRecordResponse:
+    store = get_run_store()
+    record = await store.get_run(run_id)
+    if record is None:
+        raise HTTPException(status_code=404, detail="Run not found")
+
+    resources = record.analyses.get("resource_agent_v2") or {}
+    messages = [
+        RunMessageResponse(
+            role=str(m.get("role") or ""),
+            persona=m.get("persona"),
+            time=m.get("timestamp"),
+            text=str(m.get("content") or ""),
+        )
+        for m in (record.messages or [])
+    ]
+    return RunRecordResponse(
+        run_id=record.run_id,
+        conversation_id=record.run_id,
+        mode=record.mode,
+        status=record.status,
+        created_at=record.created_at,
+        ended_at=record.ended_at,
+        sealed_at=record.sealed_at,
+        title=record.title,
+        input_summary=record.input_summary,
+        config=record.config,
+        messages=messages,
+        resources=resources,
+    )
+

backend/api/storage_service.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+import logging
+from typing import Optional
+
+from config.settings import AppSettings, get_settings
+from backend.storage import SQLiteRunStore
+
+logger = logging.getLogger(__name__)
+
+run_store: Optional[SQLiteRunStore] = None
+
+
+def get_run_store() -> SQLiteRunStore:
+    if run_store is None:
+        raise RuntimeError("RunStore not initialized")
+    return run_store
+
+
+async def initialize_run_store(settings: Optional[AppSettings] = None) -> None:
+    global run_store
+    resolved = settings or get_settings()
+    store = SQLiteRunStore(resolved.db.path)
+    await store.init()
+    run_store = store
+    logger.info("RunStore initialized")
+

backend/storage/__init__.py

@@ -0,0 +1,5 @@
+from .models import RunRecord, RunSummary
+from .sqlite_run_store import SQLiteRunStore
+
+__all__ = ["RunRecord", "RunSummary", "SQLiteRunStore"]
+

backend/storage/models.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional
+
+
+@dataclass(frozen=True)
+class RunSummary:
+    run_id: str
+    mode: str
+    status: str
+    created_at: str
+    ended_at: str
+    title: Optional[str] = None
+    input_summary: Optional[str] = None
+
+
+@dataclass(frozen=True)
+class RunRecord:
+    run_id: str
+    mode: str
+    status: str
+    created_at: str
+    ended_at: str
+    sealed_at: str
+    config: Dict[str, Any]
+    messages: List[Dict[str, Any]]
+    analyses: Dict[str, Dict[str, Any]]
+    persona_snapshots: Dict[str, Dict[str, Any]]
+    title: Optional[str] = None
+    input_summary: Optional[str] = None
+

backend/storage/sqlite_run_store.py

@@ -0,0 +1,310 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+import aiosqlite
+
+from .models import RunRecord, RunSummary
+
+
+class SQLiteRunStore:
+    def __init__(self, db_path: str):
+        self.db_path = str(db_path)
+
+    async def init(self) -> None:
+        Path(self.db_path).expanduser().resolve().parent.mkdir(parents=True, exist_ok=True)
+        async with aiosqlite.connect(self.db_path) as db:
+            await db.execute("PRAGMA foreign_keys=ON;")
+            await db.execute(
+                """
+                CREATE TABLE IF NOT EXISTS runs (
+                    run_id TEXT PRIMARY KEY,
+                    mode TEXT NOT NULL,
+                    status TEXT NOT NULL,
+                    created_at TEXT NOT NULL,
+                    ended_at TEXT NOT NULL,
+                    title TEXT,
+                    input_summary TEXT,
+                    config_json TEXT NOT NULL,
+                    sealed_at TEXT NOT NULL
+                );
+                """
+            )
+            await db.execute(
+                "CREATE INDEX IF NOT EXISTS runs_mode_created_at ON runs(mode, created_at DESC);"
+            )
+            await db.execute(
+                "CREATE INDEX IF NOT EXISTS runs_created_at ON runs(created_at DESC);"
+            )
+            await db.execute(
+                """
+                CREATE TABLE IF NOT EXISTS run_messages (
+                    run_id TEXT NOT NULL,
+                    message_index INTEGER NOT NULL,
+                    role TEXT NOT NULL,
+                    persona_label TEXT,
+                    content TEXT NOT NULL,
+                    timestamp TEXT,
+                    PRIMARY KEY (run_id, message_index),
+                    FOREIGN KEY (run_id) REFERENCES runs(run_id) ON DELETE CASCADE
+                );
+                """
+            )
+            await db.execute(
+                """
+                CREATE TABLE IF NOT EXISTS run_analyses (
+                    run_id TEXT NOT NULL,
+                    analysis_key TEXT NOT NULL,
+                    schema_version TEXT,
+                    prompt_version TEXT,
+                    result_json TEXT NOT NULL,
+                    PRIMARY KEY (run_id, analysis_key),
+                    FOREIGN KEY (run_id) REFERENCES runs(run_id) ON DELETE CASCADE
+                );
+                """
+            )
+            await db.execute(
+                """
+                CREATE TABLE IF NOT EXISTS run_persona_snapshots (
+                    run_id TEXT NOT NULL,
+                    role TEXT NOT NULL,
+                    persona_id TEXT,
+                    persona_version_id TEXT,
+                    snapshot_json TEXT NOT NULL,
+                    PRIMARY KEY (run_id, role),
+                    FOREIGN KEY (run_id) REFERENCES runs(run_id) ON DELETE CASCADE
+                );
+                """
+            )
+            await db.commit()
+
+    async def save_sealed_run(self, record: RunRecord) -> None:
+        Path(self.db_path).expanduser().resolve().parent.mkdir(parents=True, exist_ok=True)
+        async with aiosqlite.connect(self.db_path) as db:
+            await db.execute("PRAGMA foreign_keys=ON;")
+            await db.execute("BEGIN;")
+            try:
+                await db.execute(
+                    """
+                    INSERT INTO runs (
+                        run_id, mode, status, created_at, ended_at,
+                        title, input_summary, config_json, sealed_at
+                    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?);
+                    """,
+                    (
+                        record.run_id,
+                        record.mode,
+                        record.status,
+                        record.created_at,
+                        record.ended_at,
+                        record.title,
+                        record.input_summary,
+                        json.dumps(record.config, ensure_ascii=False),
+                        record.sealed_at,
+                    ),
+                )
+
+                if record.messages:
+                    await db.executemany(
+                        """
+                        INSERT INTO run_messages (
+                            run_id, message_index, role, persona_label, content, timestamp
+                        ) VALUES (?, ?, ?, ?, ?, ?);
+                        """,
+                        [
+                            (
+                                record.run_id,
+                                int(msg.get("index")),
+                                str(msg.get("role") or ""),
+                                msg.get("persona"),
+                                str(msg.get("content") or ""),
+                                msg.get("timestamp"),
+                            )
+                            for msg in record.messages
+                            if isinstance(msg.get("index"), int)
+                        ],
+                    )
+
+                if record.analyses:
+                    await db.executemany(
+                        """
+                        INSERT INTO run_analyses (
+                            run_id, analysis_key, schema_version, prompt_version, result_json
+                        ) VALUES (?, ?, ?, ?, ?);
+                        """,
+                        [
+                            (
+                                record.run_id,
+                                key,
+                                (val or {}).get("schema_version"),
+                                (val or {}).get("analysis_prompt_version"),
+                                json.dumps(val or {}, ensure_ascii=False),
+                            )
+                            for key, val in record.analyses.items()
+                        ],
+                    )
+
+                if record.persona_snapshots:
+                    await db.executemany(
+                        """
+                        INSERT INTO run_persona_snapshots (
+                            run_id, role, persona_id, persona_version_id, snapshot_json
+                        ) VALUES (?, ?, ?, ?, ?);
+                        """,
+                        [
+                            (
+                                record.run_id,
+                                role,
+                                (snap or {}).get("persona_id"),
+                                (snap or {}).get("persona_version_id"),
+                                json.dumps((snap or {}).get("snapshot") or {}, ensure_ascii=False),
+                            )
+                            for role, snap in record.persona_snapshots.items()
+                        ],
+                    )
+
+                await db.commit()
+            except Exception:
+                await db.execute("ROLLBACK;")
+                raise
+
+    async def list_runs(
+        self,
+        *,
+        mode: Optional[str] = None,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> List[RunSummary]:
+        limit = max(1, min(int(limit), 200))
+        offset = max(0, int(offset))
+
+        async with aiosqlite.connect(self.db_path) as db:
+            await db.execute("PRAGMA foreign_keys=ON;")
+            if mode:
+                rows = await db.execute_fetchall(
+                    """
+                    SELECT run_id, mode, status, created_at, ended_at, title, input_summary
+                    FROM runs
+                    WHERE mode = ?
+                    ORDER BY created_at DESC
+                    LIMIT ? OFFSET ?;
+                    """,
+                    (mode, limit, offset),
+                )
+            else:
+                rows = await db.execute_fetchall(
+                    """
+                    SELECT run_id, mode, status, created_at, ended_at, title, input_summary
+                    FROM runs
+                    ORDER BY created_at DESC
+                    LIMIT ? OFFSET ?;
+                    """,
+                    (limit, offset),
+                )
+
+        return [
+            RunSummary(
+                run_id=row[0],
+                mode=row[1],
+                status=row[2],
+                created_at=row[3],
+                ended_at=row[4],
+                title=row[5],
+                input_summary=row[6],
+            )
+            for row in rows
+        ]
+
+    async def get_run(self, run_id: str) -> Optional[RunRecord]:
+        async with aiosqlite.connect(self.db_path) as db:
+            await db.execute("PRAGMA foreign_keys=ON;")
+            row = await db.execute_fetchone(
+                """
+                SELECT run_id, mode, status, created_at, ended_at, title, input_summary, config_json, sealed_at
+                FROM runs
+                WHERE run_id = ?;
+                """,
+                (run_id,),
+            )
+            if not row:
+                return None
+
+            message_rows = await db.execute_fetchall(
+                """
+                SELECT message_index, role, persona_label, content, timestamp
+                FROM run_messages
+                WHERE run_id = ?
+                ORDER BY message_index ASC;
+                """,
+                (run_id,),
+            )
+            analysis_rows = await db.execute_fetchall(
+                """
+                SELECT analysis_key, result_json
+                FROM run_analyses
+                WHERE run_id = ?;
+                """,
+                (run_id,),
+            )
+            snapshot_rows = await db.execute_fetchall(
+                """
+                SELECT role, persona_id, persona_version_id, snapshot_json
+                FROM run_persona_snapshots
+                WHERE run_id = ?;
+                """,
+                (run_id,),
+            )
+
+        messages: List[Dict[str, Any]] = []
+        for (idx, role, persona, content, ts) in message_rows:
+            messages.append(
+                {
+                    "index": idx,
+                    "role": role,
+                    "persona": persona,
+                    "content": content,
+                    "timestamp": ts,
+                }
+            )
+
+        analyses: Dict[str, Dict[str, Any]] = {}
+        for (analysis_key, result_json) in analysis_rows:
+            try:
+                analyses[str(analysis_key)] = json.loads(result_json or "{}")
+            except Exception:
+                analyses[str(analysis_key)] = {}
+
+        persona_snapshots: Dict[str, Dict[str, Any]] = {}
+        for (role, persona_id, persona_version_id, snapshot_json) in snapshot_rows:
+            try:
+                snapshot = json.loads(snapshot_json or "{}")
+            except Exception:
+                snapshot = {}
+            persona_snapshots[str(role)] = {
+                "persona_id": persona_id,
+                "persona_version_id": persona_version_id,
+                "snapshot": snapshot,
+            }
+
+        try:
+            config = json.loads(row[7] or "{}")
+        except Exception:
+            config = {}
+
+        return RunRecord(
+            run_id=row[0],
+            mode=row[1],
+            status=row[2],
+            created_at=row[3],
+            ended_at=row[4],
+            title=row[5],
+            input_summary=row[6],
+            config=config,
+            sealed_at=row[8],
+            messages=messages,
+            analyses=analyses,
+            persona_snapshots=persona_snapshots,
+        )
+

config/settings.py

@@ -59,12 +59,26 @@ class FrontendSettings(BaseSettings):
     )
 
 
+class DBSettings(BaseSettings):
+    """Configuration for persistent storage."""
+
+    path: str = ".localdata/converta.db"
+
+    model_config = SettingsConfigDict(
+        env_prefix="DB_",
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+    )
+
+
 class AppSettings(BaseSettings):
     """Aggregate configuration exposed to the application."""
 
     api: APISettings = APISettings()
     llm: LLMSettings = LLMSettings()
     frontend: FrontendSettings = FrontendSettings()
+    db: DBSettings = DBSettings()
     log_level: str = "INFO"
 
     model_config = SettingsConfigDict(

docs/development.md

@@ -77,7 +77,7 @@ The UI also includes a **Configuration** view that lets you select personas and
 
 ## Notes on Persistence (HF)
 
-Hugging Face Spaces provide a persistent volume (typically mounted at `/data` in Docker Spaces). This repo does not yet persist app data there; future work (persona editing + conversation history) should store shared artifacts under `/data` and treat repo YAML under `data/` as defaults.
+Hugging Face Spaces provide a persistent volume (typically mounted at `/data` in Docker Spaces). This repo persists sealed runs (conversation finished + analysis succeeded) to SQLite at `DB_PATH` (recommended on HF: `/data/converta/converta.db`).
 
 ## Roadmap & Next Steps
 

docs/hf.md

@@ -18,6 +18,7 @@ In Space → Settings → Variables and secrets:
 - `LLM_MODEL`: e.g. `google/gemini-3-flash-preview`
 - `LLM_SITE_URL`: `https://huggingface.co/spaces/MikelWL/ConverTA` (optional)
 - `LLM_APP_NAME`: `ConverTA` (optional)
+- `DB_PATH`: `/data/converta/converta.db`
 - `FRONTEND_WEBSOCKET_URL`: `ws://127.0.0.1:7860/api/ws/conversation`
 - `FRONTEND_BACKEND_BASE_URL`: `http://127.0.0.1:7860/api` (optional)
 

docs/overview.md

@@ -59,8 +59,9 @@ These settings are currently stored in the browser (local-only) and apply to the
 
 ## Export & Persistence Notes
 
-- Exports (Excel + JSON) are generated on demand from the current UI transcript + analysis state.
-- Completed conversations are not persisted server-side yet; persistent history is a future roadmap item.
+- Sealed runs (conversation finished + analysis succeeded) are persisted to `DB_PATH` (HF Spaces should use `/data/...`).
+- AI↔AI runs stopped by the user are not sealed and are not persisted.
+- Exports (Excel + JSON) are generated from server-canonical persisted run data when available (with a client-side fallback).
 
 ## Access Control (Prototype)
 

docs/persistence.md

@@ -342,7 +342,6 @@ Recommended UI structure:
 2. Reload history via API and confirm:
    - transcript message count and ordering match the original UI
    - analysis boxes match the original output
-3. Edit a persona, run a new session, and confirm:
-   - the new run uses the updated persona
-   - the old run still replays with the old persona snapshot (no drift)
-4. Restart the container/app and confirm history remains available.
+3. Stop an AI↔AI session mid-run and confirm it does **not** appear in history (not sealed → not persisted).
+4. Export a completed run via API and confirm the file downloads from `/api/runs/{run_id}/export/*` (server-canonical).
+5. Restart the container/app and confirm history remains available.

frontend/pages/main_page.py

@@ -187,6 +187,9 @@ def get_main_page_html(auth_enabled: bool = False) -> str:
             const conversationIdRef = useRef(null); // AI↔AI live session id
             const humanConversationIdRef = useRef(null); // Human↔Surveyor live session id
             const analysisConversationIdRef = useRef(null); // Upload Text analysis id
+            const mainRunIdRef = useRef(null);
+            const humanRunIdRef = useRef(null);
+            const analysisRunIdRef = useRef(null);
             const liveKindRef = useRef('main'); // main|human
             const transcriptContainerRef = useRef(null);
             const stickToBottomRef = useRef(true);
@@ -257,8 +260,10 @@ def get_main_page_html(auth_enabled: bool = False) -> str:
                 const id = kind === 'human' ? `human_conv_${Date.now()}` : `react_conv_${Date.now()}`;
                 if (kind === 'human') {
                     humanConversationIdRef.current = id;
+                    humanRunIdRef.current = null;
                 } else {
                     conversationIdRef.current = id;
+                    mainRunIdRef.current = null;
                 }
                 const wsScheme = window.location.protocol === 'https:' ? 'wss' : 'ws';
                 const token = loadSessionToken();
@@ -335,6 +340,13 @@ def get_main_page_html(auth_enabled: bool = False) -> str:
                     }
                 }
                 else if (message.type === 'resource_agent_result') {
+                    if (message.persisted && message.run_id) {
+                        if (liveKindRef.current === 'human') {
+                            humanRunIdRef.current = message.run_id;
+                        } else {
+                            mainRunIdRef.current = message.run_id;
+                        }
+                    }
                     if (liveKindRef.current === 'human') {
                         setHumanResources(message.data || null);
                         setHumanStatus('complete');
@@ -521,6 +533,7 @@ def get_main_page_html(auth_enabled: bool = False) -> str:
 
                 const conversationId = `analysis_${Date.now()}`;
                 analysisConversationIdRef.current = conversationId;
+                analysisRunIdRef.current = null;
 
                 try {
                     const fd = new FormData();
@@ -535,6 +548,11 @@ def get_main_page_html(auth_enabled: bool = False) -> str:
                     }
                     const data = await res.json();
                     analysisConversationIdRef.current = data.conversation_id || conversationId;
+                    if (data.persisted && data.run_id) {
+                        analysisRunIdRef.current = data.run_id;
+                    } else {
+                        analysisRunIdRef.current = null;
+                    }
                     setAnalysisMessages(data.messages || []);
                     setAnalysisResources(data.resources || null);
                     setAnalysisStatus('complete');
@@ -596,12 +614,41 @@ def get_main_page_html(auth_enabled: bool = False) -> str:
 
             const downloadExport = async (format) => {
                 if (!activeResources || activeStatus !== 'complete') return;
+                const exportedAt = new Date().toISOString();
+                const runId = activePage === 'analyze'
+                    ? analysisRunIdRef.current
+                    : (activePage === 'human' ? humanRunIdRef.current : mainRunIdRef.current);
+
+                if (runId) {
+                    const endpoint = format === 'xlsx'
+                        ? `/api/runs/${runId}/export/xlsx`
+                        : `/api/runs/${runId}/export/json`;
+                    const fallbackExt = format === 'xlsx' ? 'xlsx' : 'json';
+                    const res = await authedFetch(endpoint, { method: 'GET' });
+                    if (!res.ok) {
+                        const msg = await res.text().catch(() => '');
+                        console.error('Export failed:', res.status, msg);
+                        return;
+                    }
+                    const blob = await res.blob();
+                    const url = window.URL.createObjectURL(blob);
+                    const a = document.createElement('a');
+                    a.href = url;
+                    const cd = res.headers.get('content-disposition') || '';
+                    const match = cd.match(/filename=\"?([^\"]+)\"?/i);
+                    a.download = match?.[1] || `converta_${runId}_${exportedAt.replaceAll(':', '-')}.${fallbackExt}`;
+                    document.body.appendChild(a);
+                    a.click();
+                    a.remove();
+                    window.URL.revokeObjectURL(url);
+                    return;
+                }
+
                 const conversationId = activePage === 'analyze'
                     ? (analysisConversationIdRef.current || `analysis_${Date.now()}`)
                     : (activePage === 'human'
                         ? (humanConversationIdRef.current || `human_conv_${Date.now()}`)
                         : (conversationIdRef.current || `react_conv_${Date.now()}`));
-                const exportedAt = new Date().toISOString();
 
                 const payload = {
                     conversation_id: conversationId,

frontend/react_gradio_hybrid.py

@@ -21,6 +21,7 @@ from websocket_manager import WebSocketManager
 from backend.api.main import app as backend_app
 from backend.api.conversation_ws import manager as backend_ws_manager
 from backend.api.conversation_service import initialize_conversation_service
+from backend.api.storage_service import initialize_run_store
 from backend.core.auth import (
     COOKIE_NAME,
     INTERNAL_HEADER,
@@ -48,6 +49,7 @@ app.mount("/api", backend_app)
 @app.on_event("startup")
 async def initialize_backend_services():
     initialize_conversation_service(backend_ws_manager, settings)
+    await initialize_run_store(settings)
 
 
 # Enable CORS for local development