DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.
Python ai-agentsai-tutorclawbotcli-tooldeepresearchinteractive-learninglearningmulti-agent-systemsrag
"""
Book Engine API Router
======================
REST + WebSocket endpoints for the ``BookEngine``. Phase 1 surface:
create / confirm / compile / read / delete + a per-book event stream.
"""
from __future__ import annotations
import asyncio
import hashlib
import logging
import time
from typing import Any
from fastapi import APIRouter, HTTPException, Query, Response, WebSocket, WebSocketDisconnect
from pydantic import BaseModel, Field
from deeptutor.api.utils.http_headers import content_disposition
from deeptutor.book import progress as progress_ops
from deeptutor.book.errors import BookPausedError
from deeptutor.book.export import export_filename, render_book_markdown
from deeptutor.book.models import (
BlockType,
BookProposal,
ContentType,
LearningCapture,
LearningCaptureStatus,
Spine,
)
from deeptutor.book.storage import get_book_storage
from deeptutor.book.streaming import SOURCE as BOOK_SOURCE
from deeptutor.multi_user.audit import log_admin_action, log_usage
from deeptutor.multi_user.book_access import (
ResolvedBook,
accessible_books,
can_create_book,
resolve_book,
)
from deeptutor.multi_user.context import get_current_user
from deeptutor.multi_user.identity import remove_book_permission_overrides
from deeptutor.runtime.stream_bus import StreamBus
router = APIRouter()
ws_router = APIRouter()
logger = logging.getLogger(__name__)
def get_book_engine():
"""Resolve the large compilation engine only when a book route uses it."""
from deeptutor.book.engine import get_book_engine as resolve
return resolve()
def _book_paused_http(exc: BookPausedError) -> HTTPException:
return HTTPException(
status_code=409,
detail={"code": "book_paused", "message": str(exc)},
)
# ─────────────────────────────────────────────────────────────────────────────
# Request / response models
# ─────────────────────────────────────────────────────────────────────────────
class CreateBookRequest(BaseModel):
source_refs: list[dict[str, Any]] = Field(default_factory=list, max_length=32)
user_intent: str = Field(default="")
chat_session_id: str = Field(default="")
chat_selections: list[dict[str, Any]] = Field(default_factory=list)
notebook_refs: list[dict[str, Any]] = Field(default_factory=list)
knowledge_bases: list[str] = Field(default_factory=list)
question_categories: list[int] = Field(default_factory=list)
question_entries: list[int] = Field(default_factory=list)
language: str = Field(default="en")
fallback_language: str = Field(default="en")
depth: str = Field(default="standard")
class ConfirmProposalRequest(BaseModel):
book_id: str
proposal: dict[str, Any] | None = None # full edited BookProposal payload
expected_revision: int | None = Field(default=None, ge=1)
class ConfirmSpineRequest(BaseModel):
book_id: str
spine: dict[str, Any] | None = None
auto_compile: bool = True
block_types: list[str] | None = None
expected_revision: int | None = Field(default=None, ge=1)
class CompilePageRequest(BaseModel):
book_id: str
page_id: str
force: bool = False
expected_revision: int | None = Field(default=None, ge=1)
class RegenerateBlockRequest(BaseModel):
book_id: str
page_id: str
block_id: str
params_override: dict[str, Any] | None = None
expected_revision: int | None = Field(default=None, ge=1)
class InsertBlockRequest(BaseModel):
book_id: str
page_id: str
block_type: str
params: dict[str, Any] | None = None
position: int | None = None
compile_now: bool = True
expected_revision: int | None = Field(default=None, ge=1)
class DeleteBlockRequest(BaseModel):
book_id: str
page_id: str
block_id: str
expected_revision: int | None = Field(default=None, ge=1)
class MoveBlockRequest(BaseModel):
book_id: str
page_id: str
block_id: str
new_position: int
expected_revision: int | None = Field(default=None, ge=1)
class ChangeBlockTypeRequest(BaseModel):
book_id: str
page_id: str
block_id: str
new_type: str
params_override: dict[str, Any] | None = None
expected_revision: int | None = Field(default=None, ge=1)
class DeepDiveRequest(BaseModel):
book_id: str
parent_page_id: str
topic: str
block_id: str | None = None
content_type: str = "concept"
expected_revision: int | None = Field(default=None, ge=1)
class QuizAttemptRequest(BaseModel):
book_id: str
page_id: str
block_id: str
question_id: str = ""
user_answer: str = ""
# ``None`` = revealed but not graded (a written answer the reader skipped
# self-assessing). Distinct from ``False``, which means they got it wrong.
is_correct: bool | None = None
submission_id: str = Field(default="", max_length=200)
def _focus_check_question(
questions: list[dict[str, Any]], requested_id: str, block_id: str
) -> tuple[str, dict[str, Any]] | None:
"""Resolve the durable question behind a Focus-Check submission."""
for index, question in enumerate(questions):
if not isinstance(question, dict):
continue
question_id = str(question.get("question_id") or "").strip()
if requested_id and question_id == requested_id:
return question_id, question
if not requested_id and not question_id:
return f"{block_id}:{index + 1}", question
if requested_id:
return requested_id, {}
return None
def _verified_choice_grade(question: dict[str, Any], user_answer: str) -> bool | None:
"""A linked Book answer is trusted only when the stored key can grade it."""
question_type = str(question.get("question_type") or "").strip().lower().replace(" ", "_")
if question_type not in {"choice", "multiple_choice", "multiple-choice", "mcq"}:
return None
options = question.get("options")
if not isinstance(options, dict):
return None
answer = user_answer.strip().upper()
keys = {str(key).strip().upper(): str(label).strip() for key, label in options.items()}
correct_text = str(question.get("correct_answer") or "").strip()
correct = correct_text.upper()
if correct not in keys:
matching = [
key for key, label in keys.items() if label.casefold() == correct_text.casefold()
]
if len(matching) != 1:
return None
correct = matching[0]
if answer not in keys:
return None
return answer == correct
class UpdateBlockRequest(BaseModel):
book_id: str
page_id: str
block_id: str
title: str | None = None
body: str | None = None
expected_revision: int | None = Field(default=None, ge=1)
class ProgressRequest(BaseModel):
book_id: str
page_id: str
class SupplementRequest(BaseModel):
book_id: str
page_id: str
topic: str
expected_revision: int | None = Field(default=None, ge=1)
class PageChatSessionRequest(BaseModel):
book_id: str
page_id: str
session_id: str
class RebuildBookRequest(BaseModel):
book_id: str
auto_compile: bool = True
block_types: list[str] | None = None
expected_revision: int | None = Field(default=None, ge=1)
class ResumeBookRequest(BaseModel):
book_id: str
expected_revision: int | None = Field(default=None, ge=1)
class PauseBookRequest(BaseModel):
book_id: str
expected_revision: int | None = Field(default=None, ge=1)
def _auth_enabled() -> bool:
from deeptutor.services.auth import AUTH_ENABLED
return bool(AUTH_ENABLED)
def _resolve_book_or_404(
book_id: str,
*,
edit: bool = False,
delete: bool = False,
) -> ResolvedBook:
resolved = resolve_book(book_id)
# Several embedders and focused tests run the router without auth and
# inject an engine directly. Preserve that single-user extension point.
if resolved is None and not _auth_enabled():
engine = get_book_engine()
if engine.load_book(book_id) is not None:
storage = getattr(engine, "storage", get_book_storage())
resolved = ResolvedBook(
engine=engine,
source="own",
permission="edit",
can_edit=True,
can_delete=True,
learning=storage,
)
if resolved is None:
raise HTTPException(status_code=404, detail="Book not found")
# Denials deliberately use the same 404 as an unknown id so an untrusted
# caller cannot probe which shared books exist.
if edit and not resolved.can_edit:
raise HTTPException(status_code=404, detail="Book not found")
if delete and not resolved.can_delete:
raise HTTPException(status_code=404, detail="Book not found")
return resolved
def _book_payload(book: Any, resolved: ResolvedBook) -> dict[str, Any]:
data = book.model_dump(mode="json")
data.update(resolved.capabilities())
if resolved.is_shared:
metadata = dict(data.get("metadata") or {})
metadata["page_chat_sessions"] = resolved.learning.load_page_chat_sessions(book.id)
data["metadata"] = metadata
return data
def _claim_content_mutation(
resolved: ResolvedBook,
book_id: str,
expected_revision: int | None,
action: str,
*,
extra: dict[str, Any] | None = None,
strict: bool = True,
) -> int:
"""Reserve the next canonical revision before a content mutation.
Shared editors must prove which snapshot they edited. Personal books and
admin operations stay backward compatible, but still advance the token so
a later shared editor detects the intervening change.
``strict=False`` is for *generation commands* — compile this chapter,
pause, resume. Those overwrite nobody's writing: a chapter shell fills
itself in, and two readers both asking for it is not a conflict (the
engine coalesces them onto one run). Guarding them was actively harmful,
because generation advances the revision itself: ``confirm_spine`` claims
a token and then queues the compile that the very next request has to
match, so the first chapter of every book failed with a conflict against
its own predecessor. They still claim a revision — a later shared edit
should know the book moved — they just do not refuse a stale one.
"""
book = resolved.engine.load_book(book_id)
if book is None:
raise HTTPException(status_code=404, detail="Book not found")
current = max(1, int(book.revision or 1))
if strict and resolved.is_shared and expected_revision is None:
raise HTTPException(
status_code=409,
detail={
"code": "book_revision_required",
"message": "Refresh the shared book before editing.",
"current_revision": current,
},
)
if strict and expected_revision is not None and expected_revision != current:
raise HTTPException(
status_code=409,
detail={
"code": "book_revision_conflict",
# A personal book has no collaborators, so blaming one was a
# lie the reader could not act on. Same guard, honest cause:
# their view is simply behind the book.
"message": (
"The book was updated by another collaborator."
if resolved.is_shared
else "This book changed since your last action — reloading the latest version."
),
"expected_revision": expected_revision,
"current_revision": current,
},
)
book.revision = current + 1
book.updated_at = time.time()
storage = getattr(resolved.engine, "storage", None)
if storage is None:
# Lightweight embedded engines used by SDK hosts may not expose their
# persistence object; they are single-user and have no shared writes.
return current
storage.save_book(book)
summary = {
"book_id": book_id,
"action": action,
"before_revision": current,
"after_revision": book.revision,
**(extra or {}),
}
if resolved.is_shared:
log_usage("book", book_id, "shared_edit", summary)
elif get_current_user().is_admin:
log_admin_action("book_edit", summary=summary)
return book.revision
def _normalize_block_types(values: list[str]) -> list[str]:
normalized = [BlockType.SECTION.value]
seen = {BlockType.SECTION}
for value in values:
try:
block_type = BlockType(value.strip().lower())
except ValueError:
continue
if block_type in seen:
continue
seen.add(block_type)
normalized.append(block_type.value)
return normalized
def _persist_requested_block_types(
resolved: ResolvedBook,
book_id: str,
requested: list[str] | None,
) -> None:
if requested is None:
return
book = resolved.engine.load_book(book_id)
if book is None:
raise HTTPException(status_code=404, detail="Book not found")
metadata = dict(book.metadata or {})
if requested:
metadata["block_types"] = _normalize_block_types(requested)
else:
metadata.pop("block_types", None)
book.metadata = metadata
book.updated_at = time.time()
storage = getattr(resolved.engine, "storage", None) or get_book_storage()
storage.save_book(book)
def _normalize_capture_text(value: str) -> str:
return " ".join((value or "").strip().split())
def _build_capture_hash(book_id: str, page_id: str, block_id: str, locator: str, text: str) -> str:
payload = "|".join(
[
book_id,
page_id,
block_id,
locator,
_normalize_capture_text(text),
],
).encode("utf-8")
return hashlib.sha256(payload).hexdigest()
def _coerce_capture_status(raw: str | None) -> LearningCaptureStatus | None:
if raw is None:
return None
try:
return LearningCaptureStatus(raw)
except ValueError as exc:
raise HTTPException(
status_code=400,
detail=f"Invalid capture status: {raw}",
) from exc
_CAPTURE_TRANSITIONS: dict[LearningCaptureStatus, set[LearningCaptureStatus]] = {
LearningCaptureStatus.CAPTURED: {
LearningCaptureStatus.CAPTURED,
LearningCaptureStatus.DRAFTED,
LearningCaptureStatus.PENDING_CONFIRMATION,
LearningCaptureStatus.APPROVED,
LearningCaptureStatus.REJECTED,
},
LearningCaptureStatus.DRAFTED: {
LearningCaptureStatus.DRAFTED,
LearningCaptureStatus.PENDING_CONFIRMATION,
LearningCaptureStatus.APPROVED,
LearningCaptureStatus.REJECTED,
},
LearningCaptureStatus.PENDING_CONFIRMATION: {
LearningCaptureStatus.PENDING_CONFIRMATION,
LearningCaptureStatus.APPROVED,
LearningCaptureStatus.REJECTED,
},
LearningCaptureStatus.APPROVED: {
LearningCaptureStatus.APPROVED,
LearningCaptureStatus.DELIVERED,
},
LearningCaptureStatus.DELIVERED: {
LearningCaptureStatus.DELIVERED,
LearningCaptureStatus.IMPORTED,
},
LearningCaptureStatus.IMPORTED: {LearningCaptureStatus.IMPORTED},
LearningCaptureStatus.REJECTED: {LearningCaptureStatus.REJECTED},
}
def _is_capture_transition_allowed(
current: LearningCaptureStatus,
requested: LearningCaptureStatus,
) -> bool:
return requested in _CAPTURE_TRANSITIONS.get(current, set())
def _derive_capture_title_values(
resolved: ResolvedBook,
book_id: str,
page_id: str,
block_id: str,
) -> tuple[str, str, str]:
engine = resolved.engine
book = engine.load_book(book_id)
if book is None:
raise HTTPException(status_code=404, detail="Book not found")
page = engine.load_page(book_id, page_id)
if page is None:
raise HTTPException(status_code=404, detail="Page not found")
spine = engine.load_spine(book_id)
chapter_title = page.title
if spine is not None and page.chapter_id:
for chapter in spine.chapters:
if chapter.id == page.chapter_id:
chapter_title = chapter.title
break
base_locator = f"/books/{book_id}/pages/{page_id}"
source_locator = f"{base_locator}/block/{block_id}" if block_id else base_locator
return book.title, chapter_title, source_locator
def _find_capture_duplicate(
storage: Any,
book_id: str,
page_id: str,
content_hash: str,
) -> LearningCapture | None:
for capture in storage.load_learning_captures(book_id):
if capture.page_id != page_id:
continue
if capture.content_hash != content_hash:
continue
if capture.status == LearningCaptureStatus.REJECTED:
continue
return capture
return None
class LearningCaptureCreateRequest(BaseModel):
page_id: str
block_id: str = ""
source_text: str
context_before: str = ""
context_after: str = ""
source_locator: str = ""
book_title: str = ""
chapter_title: str = ""
user_note: str = ""
status: str | None = None
class LearningCaptureUpdateRequest(BaseModel):
status: str | None = None
user_note: str | None = None
rejected_reason: str | None = None
def _capture_payload(capture: LearningCapture) -> dict[str, object]:
return capture.model_dump(mode="json")
# ─────────────────────────────────────────────────────────────────────────────
# REST endpoints
# ─────────────────────────────────────────────────────────────────────────────
@router.get("/books/health")
async def health_check() -> dict[str, str]:
return {"status": "healthy", "service": "book"}
@router.get("/books/estimate-basis")
async def estimate_basis(depth: str = "standard") -> dict[str, Any]:
"""Per-chapter generation cost, keyed by content type.
The spine editor sums this over whatever chapters currently exist, so the
estimate stays live while the user edits without a request per keystroke —
and stays honest, because the numbers come from the same templates the
architect plans from.
"""
from deeptutor.book.estimate import chapter_basis
return {"depth": depth, "basis": chapter_basis(depth)}
@router.get("/books/block-types")
async def block_types() -> dict[str, list[dict[str, str | bool]]]:
from deeptutor.book.agents.page_planner import (
PLANNABLE_BLOCK_TYPES,
PLANNER_DEFAULT_BLOCK_TYPES,
)
return {
"block_types": [
{
"value": block_type.value,
"planner_default": block_type in PLANNER_DEFAULT_BLOCK_TYPES,
}
for block_type in sorted(PLANNABLE_BLOCK_TYPES, key=lambda item: item.value)
]
}
@router.get("/books")
async def list_books() -> dict[str, Any]:
def _collect() -> list[dict[str, Any]]:
books: list[dict[str, Any]] = []
for book, resolved in accessible_books():
data = _book_payload(book, resolved)
# Lets the library card say "continue reading" and show how far in
# the reader is, instead of treating every book as untouched.
data["reading"] = resolved.reading_summary(book)
data["generation"] = resolved.engine.generation_overview(book)
books.append(data)
return books
# One manifest read per book plus one progress read per book — off-loop.
return {
"books": await asyncio.to_thread(_collect),
"can_create": can_create_book(),
}
@router.get("/books/{book_id}/learning-captures")
async def list_learning_captures(
book_id: str,
status: str | None = Query(default=None),
) -> dict[str, Any]:
resolved = _resolve_book_or_404(book_id)
parsed_status = _coerce_capture_status(status) if status is not None else None
storage = resolved.learning
captures = storage.load_learning_captures(book_id, status=parsed_status)
return {"captures": [_capture_payload(capture) for capture in captures]}
@router.post("/books/{book_id}/learning-captures")
async def create_learning_capture(
book_id: str,
req: LearningCaptureCreateRequest,
) -> dict[str, Any]:
resolved = _resolve_book_or_404(book_id)
engine = resolved.engine
page = engine.load_page(book_id, req.page_id)
if page is None:
raise HTTPException(status_code=404, detail="Page not found")
source_text = _normalize_capture_text(req.source_text)
if not source_text:
raise HTTPException(status_code=400, detail="source_text is required")
book_title, chapter_title, default_source_locator = _derive_capture_title_values(
resolved=resolved,
book_id=book_id,
page_id=req.page_id,
block_id=req.block_id,
)
source_locator = req.source_locator.strip() or default_source_locator
status = _coerce_capture_status(req.status) or LearningCaptureStatus.CAPTURED
content_hash = _build_capture_hash(
book_id,
req.page_id,
req.block_id,
source_locator,
source_text,
)
storage = resolved.learning
duplicate = _find_capture_duplicate(storage, book_id, req.page_id, content_hash)
if duplicate is not None:
return {"capture": _capture_payload(duplicate)}
capture = LearningCapture(
book_id=book_id,
page_id=req.page_id,
block_id=req.block_id,
source_text=source_text,
context_before=_normalize_capture_text(req.context_before),
context_after=_normalize_capture_text(req.context_after),
source_locator=source_locator,
book_title=req.book_title or book_title,
chapter_title=req.chapter_title or chapter_title,
user_note=req.user_note.strip(),
content_hash=content_hash,
status=status,
)
storage.upsert_learning_capture(capture)
return {"capture": _capture_payload(capture)}
@router.patch("/books/{book_id}/learning-captures/{capture_id}")
async def update_learning_capture(
book_id: str,
capture_id: str,
req: LearningCaptureUpdateRequest,
) -> dict[str, Any]:
resolved = _resolve_book_or_404(book_id)
storage = resolved.learning
capture = storage.load_learning_capture(book_id, capture_id)
if capture is None:
raise HTTPException(status_code=404, detail="Learning capture not found")
requested_status = _coerce_capture_status(req.status) if req.status is not None else None
if requested_status is not None and not _is_capture_transition_allowed(
capture.status,
requested_status,
):
raise HTTPException(
status_code=400,
detail=(f"Invalid state transition: {capture.status} -> {requested_status}"),
)
changed = False
updated = capture.model_copy(deep=True)
if requested_status is not None and requested_status != capture.status:
updated.status = requested_status
changed = True
if req.user_note is not None and req.user_note != capture.user_note:
updated.user_note = req.user_note
changed = True
if req.rejected_reason is not None and req.rejected_reason != capture.rejected_reason:
updated.rejected_reason = req.rejected_reason
changed = True
if not changed:
return {"capture": _capture_payload(capture)}
updated.version = capture.version + 1
updated.updated_at = time.time()
storage.upsert_learning_capture(updated)
return {"capture": _capture_payload(updated)}
def _page_summary(page) -> dict[str, Any]:
"""Page metadata without block payloads.
A compiled page carries its full rendered content — SVG, Mermaid, prose —
so a book's blocks run to hundreds of kilobytes. Views that only need the
chapter list (sidebar, library, progress) ask for summaries instead.
"""
data = page.model_dump(mode="json")
blocks = data.pop("blocks", []) or []
data["block_count"] = len(blocks)
data["blocks"] = []
return data
@router.get("/books/{book_id}")
async def get_book(book_id: str, include_blocks: bool = True) -> dict[str, Any]:
resolved = _resolve_book_or_404(book_id)
engine = resolved.engine
book = engine.load_book(book_id)
if book is None:
raise HTTPException(status_code=404, detail="Book not found")
# Opening a book is the correctly-scoped moment to notice that its
# compilation died with a previous process and pick it back up.
if not resolved.is_shared:
await engine.maybe_resume_on_open(book_id)
book = engine.load_book(book_id) or book
def _read() -> tuple[Any, list[Any], Any]:
return (
engine.load_spine(book_id),
engine.list_pages(book_id),
resolved.load_progress(book_id),
)
# A compiled book is hundreds of KB across one file per page.
spine, pages, progress = await asyncio.to_thread(_read)
return {
"book": _book_payload(book, resolved),
"spine": spine.model_dump(mode="json") if spine else None,
"pages": [
(p.model_dump(mode="json") if include_blocks else _page_summary(p)) for p in pages
],
"progress": progress.model_dump(mode="json"),
"generation": engine.generation_summary(book_id, book=book, pages=pages),
}
@router.get("/books/{book_id}/spine")
async def get_spine(book_id: str) -> dict[str, Any]:
engine = _resolve_book_or_404(book_id).engine
spine = engine.load_spine(book_id)
if spine is None:
raise HTTPException(status_code=404, detail="Spine not found")
return {"spine": spine.model_dump(mode="json")}
@router.get("/books/{book_id}/pages/{page_id}")
async def get_page(book_id: str, page_id: str) -> dict[str, Any]:
engine = _resolve_book_or_404(book_id).engine
page = engine.load_page(book_id, page_id)
if page is None:
raise HTTPException(status_code=404, detail="Page not found")
return {"page": page.model_dump(mode="json")}
@router.delete("/books/{book_id}")
async def delete_book(book_id: str) -> dict[str, Any]:
resolved = _resolve_book_or_404(book_id, delete=True)
engine = resolved.engine
ok = engine.delete_book(book_id)
if not ok:
raise HTTPException(status_code=404, detail="Book not found")
if get_current_user().is_admin:
affected = remove_book_permission_overrides(book_id)
log_admin_action(
"book_delete",
summary={"book_id": book_id, "acl_users_cleaned": len(affected)},
)
return {"deleted": True, "book_id": book_id}
@router.post("/books")
async def create_book(req: CreateBookRequest) -> dict[str, Any]:
"""Stage 1: capture inputs + run IdeationAgent."""
if not req.user_intent.strip():
raise HTTPException(status_code=400, detail="user_intent is required")
if not can_create_book():
raise HTTPException(status_code=403, detail="Book creation is not allowed")
engine = get_book_engine()
try:
book, proposal = await engine.create_book(
user_intent=req.user_intent,
source_refs=req.source_refs,
chat_session_id=req.chat_session_id,
chat_selections=req.chat_selections,
notebook_refs=req.notebook_refs,
knowledge_bases=req.knowledge_bases,
question_categories=req.question_categories,
question_entries=req.question_entries,
language=req.language,
fallback_language=req.fallback_language,
depth=req.depth,
)
except Exception as exc: # noqa: BLE001
logger.error(f"create_book failed: {exc}", exc_info=True)
raise HTTPException(status_code=500, detail=str(exc))
return {
"book": book.model_dump(mode="json"),
"proposal": proposal.model_dump(mode="json"),
}
@router.post("/books/confirm-proposal")
async def confirm_proposal(req: ConfirmProposalRequest) -> dict[str, Any]:
"""Stage 2: user confirms (and possibly edits) the proposal → SpineAgent."""
resolved = _resolve_book_or_404(req.book_id, edit=True)
engine = resolved.engine
revision = _claim_content_mutation(
resolved,
req.book_id,
req.expected_revision,
"confirm_proposal",
)
edited: BookProposal | None = None
if req.proposal:
try:
edited = BookProposal.model_validate(req.proposal)
except Exception as exc:
raise HTTPException(status_code=400, detail=f"Invalid proposal: {exc}")
try:
book, spine = await engine.confirm_proposal(book_id=req.book_id, edited_proposal=edited)
except ValueError as exc:
raise HTTPException(status_code=404, detail=str(exc))
except Exception as exc: # noqa: BLE001
logger.error(f"confirm_proposal failed: {exc}", exc_info=True)
raise HTTPException(status_code=500, detail=str(exc))
return {
"book": book.model_dump(mode="json"),
"spine": spine.model_dump(mode="json"),
"book_revision": revision,
}
@router.post("/books/confirm-spine")
async def confirm_spine(req: ConfirmSpineRequest) -> dict[str, Any]:
"""Stage 3: user confirms the spine → create pending page shells."""
resolved = _resolve_book_or_404(req.book_id, edit=True)
engine = resolved.engine
revision = _claim_content_mutation(
resolved,
req.book_id,
req.expected_revision,
"confirm_spine",
)
edited: Spine | None = None
if req.spine:
try:
edited = Spine.model_validate(req.spine)
except Exception as exc:
raise HTTPException(status_code=400, detail=f"Invalid spine: {exc}")
_persist_requested_block_types(resolved, req.book_id, req.block_types)
try:
pages = await engine.confirm_spine(
book_id=req.book_id,
edited_spine=edited,
auto_compile=req.auto_compile,
)
except ValueError as exc:
raise HTTPException(status_code=404, detail=str(exc))
except Exception as exc: # noqa: BLE001
logger.error(f"confirm_spine failed: {exc}", exc_info=True)
raise HTTPException(status_code=500, detail=str(exc))
return {"pages": [p.model_dump(mode="json") for p in pages], "book_revision": revision}
@router.post("/books/compile-page")
async def compile_page(req: CompilePageRequest) -> dict[str, Any]:
"""Drive the compiler for the page the user just opened (current-page priority)."""
resolved = _resolve_book_or_404(req.book_id, edit=True)
engine = resolved.engine
revision = _claim_content_mutation(
resolved,
req.book_id,
req.expected_revision,
"compile_page",
extra={"page_id": req.page_id, "force": req.force},
# Generation command, not an edit — see `_claim_content_mutation`.
strict=False,
)
try:
page = await engine.compile_page(book_id=req.book_id, page_id=req.page_id, force=req.force)
except BookPausedError as exc:
raise _book_paused_http(exc)
except ValueError as exc:
raise HTTPException(status_code=404, detail=str(exc))
except Exception as exc: # noqa: BLE001
logger.error(f"compile_page failed: {exc}", exc_info=True)
raise HTTPException(status_code=500, detail=str(exc))
return {"page": page.model_dump(mode="json"), "book_revision": revision}
@router.post("/books/regenerate-block")
async def regenerate_block(req: RegenerateBlockRequest) -> dict[str, Any]:
resolved = _resolve_book_or_404(req.book_id, edit=True)
engine = resolved.engine
revision = _claim_content_mutation(
resolved,
req.book_id,
req.expected_revision,
"regenerate_block",
extra={"page_id": req.page_id, "block_id": req.block_id},
)
try:
block = await engine.regenerate_block(
book_id=req.book_id,
page_id=req.page_id,
block_id=req.block_id,
params_override=req.params_override,
)
except BookPausedError as exc:
raise _book_paused_http(exc)
except Exception as exc: # noqa: BLE001
logger.error(f"regenerate_block failed: {exc}", exc_info=True)
raise HTTPException(status_code=500, detail=str(exc))
if block is None:
raise HTTPException(status_code=404, detail="Block not found")
return {"block": block.model_dump(mode="json"), "book_revision": revision}
def _coerce_block_type(name: str) -> BlockType:
try:
return BlockType(name)
except ValueError as exc:
raise HTTPException(status_code=400, detail=f"Unknown block type: {name}") from exc
def _coerce_content_type(name: str) -> ContentType:
try:
return ContentType(name)
except ValueError as exc:
raise HTTPException(status_code=400, detail=f"Unknown content type: {name}") from exc
@router.post("/books/insert-block")
async def insert_block(req: InsertBlockRequest) -> dict[str, Any]:
resolved = _resolve_book_or_404(req.book_id, edit=True)
engine = resolved.engine
revision = _claim_content_mutation(
resolved,
req.book_id,
req.expected_revision,
"insert_block",
extra={"page_id": req.page_id, "block_type": req.block_type},
)
block_type = _coerce_block_type(req.block_type)
try:
block = await engine.insert_block(
book_id=req.book_id,
page_id=req.page_id,
block_type=block_type,
params=req.params,
position=req.position,
compile_now=req.compile_now,
)
except BookPausedError as exc:
raise _book_paused_http(exc)
except Exception as exc: # noqa: BLE001
logger.error(f"insert_block failed: {exc}", exc_info=True)
raise HTTPException(status_code=500, detail=str(exc))
if block is None:
raise HTTPException(status_code=404, detail="Page or chapter not found")
return {"block": block.model_dump(mode="json"), "book_revision": revision}
@router.post("/books/delete-block")
async def delete_block(req: DeleteBlockRequest) -> dict[str, Any]:
resolved = _resolve_book_or_404(req.book_id, edit=True)
engine = resolved.engine
revision = _claim_content_mutation(
resolved,
req.book_id,
req.expected_revision,
"delete_block",
extra={"page_id": req.page_id, "block_id": req.block_id},
)
ok = await engine.delete_block(book_id=req.book_id, page_id=req.page_id, block_id=req.block_id)
if not ok:
raise HTTPException(status_code=404, detail="Block not found")
return {"ok": True, "book_revision": revision}
@router.post("/books/move-block")
async def move_block(req: MoveBlockRequest) -> dict[str, Any]:
resolved = _resolve_book_or_404(req.book_id, edit=True)
engine = resolved.engine
revision = _claim_content_mutation(
resolved,
req.book_id,
req.expected_revision,
"move_block",
extra={"page_id": req.page_id, "block_id": req.block_id},
)
ok = await engine.move_block(
book_id=req.book_id,
page_id=req.page_id,
block_id=req.block_id,
new_position=req.new_position,
)
if not ok:
raise HTTPException(status_code=404, detail="Block not found")
return {"ok": True, "book_revision": revision}
@router.post("/books/change-block-type")
async def change_block_type(req: ChangeBlockTypeRequest) -> dict[str, Any]:
resolved = _resolve_book_or_404(req.book_id, edit=True)
engine = resolved.engine
revision = _claim_content_mutation(
resolved,
req.book_id,
req.expected_revision,
"change_block_type",
extra={"page_id": req.page_id, "block_id": req.block_id},
)
new_type = _coerce_block_type(req.new_type)
try:
block = await engine.change_block_type(
book_id=req.book_id,
page_id=req.page_id,
block_id=req.block_id,
new_type=new_type,
params_override=req.params_override,
)
except BookPausedError as exc:
raise _book_paused_http(exc)
except Exception as exc: # noqa: BLE001
logger.error(f"change_block_type failed: {exc}", exc_info=True)
raise HTTPException(status_code=500, detail=str(exc))
if block is None:
raise HTTPException(status_code=404, detail="Block not found")
return {"block": block.model_dump(mode="json"), "book_revision": revision}
@router.post("/books/deep-dive")
async def deep_dive(req: DeepDiveRequest) -> dict[str, Any]:
resolved = _resolve_book_or_404(req.book_id, edit=True)
engine = resolved.engine
revision = _claim_content_mutation(
resolved,
req.book_id,
req.expected_revision,
"deep_dive",
extra={"page_id": req.parent_page_id, "topic": req.topic},
)
content_type = _coerce_content_type(req.content_type)
try:
page = await engine.create_deep_dive_subpage(
book_id=req.book_id,
parent_page_id=req.parent_page_id,
topic=req.topic,
block_id=req.block_id,
content_type=content_type,
)
except BookPausedError as exc:
raise _book_paused_http(exc)
except Exception as exc: # noqa: BLE001
logger.error(f"deep_dive failed: {exc}", exc_info=True)
raise HTTPException(status_code=500, detail=str(exc))
if page is None:
raise HTTPException(status_code=404, detail="Parent page not found")
return {"page": page.model_dump(mode="json"), "book_revision": revision}
@router.post("/books/quiz-attempt")
async def quiz_attempt(req: QuizAttemptRequest) -> dict[str, Any]:
resolved = _resolve_book_or_404(req.book_id)
book = resolved.engine.load_book(req.book_id)
page = next(
(item for item in resolved.engine.list_pages(req.book_id) if item.id == req.page_id), None
)
block = page.block_by_id(req.block_id) if page is not None else None
questions = (
[item for item in block.payload.get("questions", []) if isinstance(item, dict)]
if block is not None
else []
)
resolved_question = _focus_check_question(questions, req.question_id, req.block_id)
current_progress = resolved.load_progress(req.book_id)
previous_attempts = len(current_progress.quiz_attempts)
try:
progress = progress_ops.record_attempt(
current_progress,
page_id=req.page_id,
block_id=req.block_id,
question_id=req.question_id,
user_answer=req.user_answer,
is_correct=req.is_correct,
page_to_chapter={
page.id: page.chapter_id
for page in resolved.engine.list_pages(req.book_id)
if page.chapter_id
},
submission_id=req.submission_id.strip(),
)
except ValueError as exc:
raise HTTPException(status_code=409, detail=str(exc)) from exc
if len(progress.quiz_attempts) != previous_attempts:
resolved.learning.save_progress(progress)
if req.is_correct is not None and resolved_question is not None and book is not None:
question_id, question = resolved_question
verified_grade = _verified_choice_grade(question, req.user_answer)
trusted_linkage = verified_grade is not None and verified_grade == req.is_correct
try:
from deeptutor.services.session import get_sqlite_session_store
store = get_sqlite_session_store()
metadata = book.metadata if isinstance(book.metadata, dict) else {}
page_sessions = metadata.get("page_chat_sessions")
session_id = str(
(page_sessions.get(req.page_id) if isinstance(page_sessions, dict) else "")
or book.chat_session_id
or ""
).strip()
has_session = bool(session_id and await store.get_session(session_id) is not None)
from deeptutor.learning.assessment import (
AssessmentRecord,
is_correct_to_result,
record_assessment,
)
matching_attempts = [
attempt
for attempt in progress.quiz_attempts
if attempt.block_id == req.block_id and attempt.question_id == req.question_id
]
latest_attempt = next(
(
attempt
for attempt in matching_attempts
if req.submission_id and attempt.submission_id == req.submission_id
),
matching_attempts[-1],
)
attempt_count = matching_attempts.index(latest_attempt) + 1
await record_assessment(
AssessmentRecord(
session_id=session_id if has_session else "",
origin_type="conversation" if has_session else "document_analysis",
origin_ref=session_id if has_session else f"book:{req.book_id}",
turn_id=req.block_id,
question_id=question_id,
question=str(question.get("question") or block.title or "Focus check"),
question_type=str(question.get("question_type") or ""),
options=question.get("options") or {},
correct_answer=str(question.get("correct_answer") or ""),
explanation=str(question.get("explanation") or ""),
difficulty=str(question.get("difficulty") or ""),
user_answer=req.user_answer,
is_correct=bool(req.is_correct),
result=is_correct_to_result(bool(req.is_correct)),
source="book",
assessment_type="focus_check",
material_id=req.book_id,
material_title=book.title,
section_id=req.page_id,
section_title=page.title if page is not None else "",
mastery_path_id=(
str(question.get("mastery_path_id") or "") if trusted_linkage else ""
),
knowledge_point_id=(
str(question.get("knowledge_point_id") or "") if trusted_linkage else ""
),
attempt_count=attempt_count,
attempt_id=(
f"book:{req.book_id}:{req.block_id}:{question_id}:"
f"{latest_attempt.submission_id or f'{latest_attempt.timestamp:.9f}'}"
),
)
)
except Exception as exc:
logger.warning(
"Failed to sync Focus-Check %s to question bank for book %s",
req.question_id,
req.book_id,
exc_info=True,
)
raise HTTPException(
status_code=500, detail="Failed to save Focus-Check evidence"
) from exc
return {"progress": progress.model_dump(mode="json")}
@router.post("/books/update-block")
async def update_block(req: UpdateBlockRequest) -> dict[str, Any]:
"""Edit a block's prose in place.
Scoped deliberately narrow — title and body only. Fixing a typo shouldn't
require regenerating a whole block and hoping for a better roll, but a book
is not a document editor either; substantial rewrites belong in Co-Writer.
"""
resolved = _resolve_book_or_404(req.book_id, edit=True)
engine = resolved.engine
revision = _claim_content_mutation(
resolved,
req.book_id,
req.expected_revision,
"update_block",
extra={"page_id": req.page_id, "block_id": req.block_id},
)
block = await engine.update_block(
book_id=req.book_id,
page_id=req.page_id,
block_id=req.block_id,
title=req.title,
body=req.body,
)
if block is None:
raise HTTPException(status_code=404, detail="Block not found or not editable")
return {"block": block.model_dump(mode="json"), "book_revision": revision}
@router.post("/books/progress/visit")
async def mark_visited(req: ProgressRequest) -> dict[str, Any]:
"""Remember the reader's position so the book can be resumed later."""
resolved = _resolve_book_or_404(req.book_id)
progress = resolved.load_progress(req.book_id)
if progress_ops.mark_visited(progress, req.page_id):
resolved.learning.save_progress(progress)
return {"progress": progress.model_dump(mode="json")}
@router.post("/books/progress/bookmark")
async def toggle_bookmark(req: ProgressRequest) -> dict[str, Any]:
resolved = _resolve_book_or_404(req.book_id)
progress = resolved.load_progress(req.book_id)
progress_ops.toggle_bookmark(progress, req.page_id)
resolved.learning.save_progress(progress)
return {"progress": progress.model_dump(mode="json")}
@router.get("/books/{book_id}/export")
async def export_book(book_id: str) -> Response:
"""Download the whole book as a single Markdown file."""
engine = _resolve_book_or_404(book_id).engine
book = engine.load_book(book_id)
if book is None:
raise HTTPException(status_code=404, detail="Book not found")
markdown = await asyncio.to_thread(
lambda: render_book_markdown(book, engine.load_spine(book_id), engine.list_pages(book_id))
)
return Response(
content=markdown,
media_type="text/markdown; charset=utf-8",
headers={
"Content-Disposition": content_disposition(
export_filename(book), disposition="attachment"
)
},
)
@router.get("/books/{book_id}/health")
async def book_health(book_id: str) -> dict[str, Any]:
resolved = _resolve_book_or_404(book_id)
engine = resolved.engine
if resolved.is_shared and not resolved.can_edit:
# Drift detection persists stale-page state on the canonical Book. A
# read-only collaborator may inspect it, but must not mutate it merely
# by opening the health banner.
book = engine.load_book(book_id)
stale_page_ids = list(book.stale_page_ids) if book is not None else []
drift = {
"book_id": book_id,
"has_drift": bool(stale_page_ids),
"new_kbs": [],
"removed_kbs": [],
"changed_kbs": [],
"stale_page_ids": stale_page_ids,
"cached": True,
}
else:
drift = engine.kb_drift_report(book_id)
log = engine.log_health(book_id)
generation = engine.generation_summary(book_id)
return {"kb_drift": drift, "log_health": log, "generation": generation}
@router.post("/books/{book_id}/refresh-fingerprints")
async def refresh_fingerprints(
book_id: str,
force: bool = False,
expected_revision: int | None = Query(default=None, ge=1),
) -> dict[str, Any]:
"""Mark the current KB state as seen.
409s while pages the last drift flagged are still awaiting recompilation.
``force=true`` dismisses them anyway — stale detection over-marks on
purpose when an anchor cannot be resolved, so the user needs a way out.
"""
resolved = _resolve_book_or_404(book_id, edit=True)
engine = resolved.engine
revision = _claim_content_mutation(
resolved,
book_id,
expected_revision,
"refresh_fingerprints",
extra={"force": force},
)
try:
result = engine.refresh_kb_fingerprints(book_id, force=force)
except ValueError as exc:
raise HTTPException(status_code=409, detail=str(exc)) from exc
if result is None:
raise HTTPException(status_code=404, detail="Book not found")
return {**result, "book_revision": revision}
@router.post("/books/supplement")
async def supplement(req: SupplementRequest) -> dict[str, Any]:
resolved = _resolve_book_or_404(req.book_id, edit=True)
engine = resolved.engine
revision = _claim_content_mutation(
resolved,
req.book_id,
req.expected_revision,
"supplement",
extra={"page_id": req.page_id, "topic": req.topic},
)
try:
block = await engine.supplement_for_weakness(
book_id=req.book_id,
page_id=req.page_id,
topic=req.topic,
)
except BookPausedError as exc:
raise _book_paused_http(exc)
except Exception as exc: # noqa: BLE001
logger.error(f"supplement failed: {exc}", exc_info=True)
raise HTTPException(status_code=500, detail=str(exc))
if block is None:
raise HTTPException(status_code=404, detail="Page not found")
return {"block": block.model_dump(mode="json"), "book_revision": revision}
@router.post("/books/page-chat-session")
async def set_page_chat_session(req: PageChatSessionRequest) -> dict[str, Any]:
resolved = _resolve_book_or_404(req.book_id)
engine = resolved.engine
if resolved.is_shared:
book = engine.load_book(req.book_id)
page = engine.load_page(req.book_id, req.page_id)
if book is not None and page is not None and req.session_id.strip():
resolved.learning.set_page_chat_session(req.book_id, req.page_id, req.session_id)
log_usage("book", req.book_id, "page_chat", {"page_id": req.page_id})
book = book.model_copy(deep=True)
else:
book = None
else:
book = engine.set_page_chat_session(
book_id=req.book_id,
page_id=req.page_id,
session_id=req.session_id,
)
if book is None:
raise HTTPException(status_code=404, detail="Book or page not found")
from deeptutor.book.chat_sessions import tag_book_chat_session
from deeptutor.services.session import get_session_store
# The conversation names its book too, so the sidebar can file it there.
await tag_book_chat_session(
get_session_store(),
book_id=req.book_id,
page_id=req.page_id,
session_id=req.session_id.strip(),
)
return {"book": _book_payload(book, resolved)}
@router.post("/books/resume")
async def resume_book(req: ResumeBookRequest) -> dict[str, Any]:
"""Re-queue unfinished pages without discarding what already compiled."""
resolved = _resolve_book_or_404(req.book_id, edit=True)
engine = resolved.engine
revision = _claim_content_mutation(
resolved,
req.book_id,
req.expected_revision,
"resume",
strict=False,
)
try:
pages = await engine.resume_book(book_id=req.book_id)
except ValueError as exc:
raise HTTPException(status_code=404, detail=str(exc))
except Exception as exc: # noqa: BLE001
logger.error(f"resume_book failed: {exc}", exc_info=True)
raise HTTPException(status_code=500, detail=str(exc))
return {"pages": [p.model_dump(mode="json") for p in pages], "book_revision": revision}
@router.post("/books/pause")
async def pause_book(req: PauseBookRequest) -> dict[str, Any]:
"""Persist a manual pause, cancel in-flight work, and keep completed output."""
resolved = _resolve_book_or_404(req.book_id, edit=True)
engine = resolved.engine
revision = _claim_content_mutation(
resolved,
req.book_id,
req.expected_revision,
"pause",
strict=False,
)
try:
pages = await engine.pause_book(book_id=req.book_id)
except ValueError as exc:
raise HTTPException(status_code=404, detail=str(exc))
except Exception as exc: # noqa: BLE001
logger.error(f"pause_book failed: {exc}", exc_info=True)
raise HTTPException(status_code=500, detail=str(exc))
return {"pages": [p.model_dump(mode="json") for p in pages], "book_revision": revision}
@router.post("/books/rebuild")
async def rebuild_book(req: RebuildBookRequest) -> dict[str, Any]:
resolved = _resolve_book_or_404(req.book_id, edit=True)
engine = resolved.engine
revision = _claim_content_mutation(
resolved,
req.book_id,
req.expected_revision,
"rebuild",
)
_persist_requested_block_types(resolved, req.book_id, req.block_types)
try:
pages = await engine.rebuild_book(book_id=req.book_id, auto_compile=req.auto_compile)
except ValueError as exc:
raise HTTPException(status_code=404, detail=str(exc))
except Exception as exc: # noqa: BLE001
logger.error(f"rebuild_book failed: {exc}", exc_info=True)
raise HTTPException(status_code=500, detail=str(exc))
return {"pages": [p.model_dump(mode="json") for p in pages], "book_revision": revision}
# ─────────────────────────────────────────────────────────────────────────────
# WebSocket – streamed Book events
# ─────────────────────────────────────────────────────────────────────────────
def _serialize_event(event) -> dict[str, Any]:
return {
"type": event.type.value if hasattr(event.type, "value") else str(event.type),
"source": event.source,
"stage": event.stage,
"content": event.content,
"metadata": event.metadata or {},
"seq": event.seq,
"timestamp": event.timestamp,
}
class _SocketFanout:
"""Forwards several buses into one socket, at most one task per bus.
A client watching a book needs events from two places: the book's
long-lived stream (background compilation) and, while a book is still being
created, a connection-scoped stream (no book id exists yet). Both are
attached here; neither producer needs to know a socket is listening.
Attaching is idempotent — re-subscribing to a book already being forwarded
is a no-op rather than a second, duplicating reader.
"""
def __init__(self, send) -> None:
self._send = send
self._tasks: dict[int, asyncio.Task[None]] = {}
def attach(self, bus: StreamBus, *, after_seq: int = 0) -> None:
key = id(bus)
existing = self._tasks.get(key)
if existing is not None and not existing.done():
return
self._tasks[key] = asyncio.create_task(self._forward(bus, after_seq=after_seq))
async def _forward(self, bus: StreamBus, *, after_seq: int) -> None:
async for event in bus.subscribe(after_seq=after_seq):
if event.source != BOOK_SOURCE:
continue
await self._send(_serialize_event(event))
async def close(self) -> None:
for task in self._tasks.values():
task.cancel()
for task in self._tasks.values():
try:
await task
except (asyncio.CancelledError, Exception):
pass
self._tasks.clear()
@ws_router.websocket("/books")
async def book_websocket(ws: WebSocket) -> None:
"""Streaming endpoint.
Two kinds of client message:
**Subscribe** — attach this socket to a book's long-lived stream. Recent
history is replayed on attach, so a reader who refreshes mid-compilation
catches up instead of watching a frozen page::
{"type": "subscribe", "book_id": "..."}
**Actions** — run an engine operation and reply with a single result::
{"type": "create", ...CreateBookRequest fields}
{"type": "confirm_proposal", "book_id": "...", "proposal": {...}}
{"type": "confirm_spine", "book_id": "...", "spine": {...}, "auto_compile": true}
{"type": "compile_page", "book_id": "...", "page_id": "...", "force": false}
{"type": "regenerate_block", "book_id": "...", "page_id": "...", "block_id": "..."}
Actions publish into the book's own stream (see :mod:`deeptutor.book.event_hub`),
so their progress reaches *every* subscriber, and work they leave running in
the background keeps streaming long after the action has replied. The socket
only ever closes streams it created itself.
"""
from deeptutor.api.routers.auth import ws_auth_failed, ws_require_auth
from deeptutor.book.event_hub import get_book_bus
from deeptutor.multi_user.context import reset_current_user
user_token = await ws_require_auth(ws)
if user_token is ws_auth_failed:
return
await ws.accept()
closed = False
async def send(data: dict[str, Any]) -> None:
nonlocal closed
if closed:
return
try:
await ws.send_json(data)
except Exception:
closed = True
fanout = _SocketFanout(send)
# Book creation has no book id to stream into yet, so ideation events go
# through a connection-scoped bus. It is the only bus this socket owns.
creation_bus = StreamBus()
fanout.attach(creation_bus)
try:
while not closed:
try:
data = await ws.receive_json()
except WebSocketDisconnect:
break
except Exception as exc:
await send({"type": "error", "content": f"Bad message: {exc}"})
continue
msg_type = str(data.get("type") or "").strip()
if not msg_type:
await send({"type": "error", "content": "Missing 'type' field"})
continue
book_id = str(data.get("book_id") or "").strip()
resolved: ResolvedBook | None = None
if book_id:
try:
resolved = _resolve_book_or_404(book_id)
except HTTPException:
await send({"type": "error", "content": f"Book not found: {book_id}"})
continue
activity = None
try:
from deeptutor.services.workspace.activity import acquire_activity
from deeptutor.services.workspace.context import (
current_workspace_id,
resolve_workspace_scope,
)
from deeptutor.services.workspace.models import WorkspaceError
activity = acquire_activity()
if (
msg_type != "subscribe"
and resolve_workspace_scope(current_workspace_id()).archived
):
raise WorkspaceError("Restore this workspace before changing its data.")
if msg_type == "subscribe":
if not book_id:
await send({"type": "error", "content": "subscribe requires book_id"})
else:
bus = get_book_bus(book_id)
try:
requested_cursor = max(0, int(data.get("after_seq") or 0))
except (TypeError, ValueError):
requested_cursor = 0
reset_cursor = requested_cursor > bus.latest_seq
effective_cursor = 0 if reset_cursor else requested_cursor
# Acknowledge the effective cursor before replay starts,
# so the client can reset stale local state first.
await send(
{
"type": "subscribed",
"book_id": book_id,
"latest_seq": bus.latest_seq,
"reset": reset_cursor,
}
)
fanout.attach(bus, after_seq=effective_cursor)
elif msg_type == "create":
if not can_create_book():
await send({"type": "error", "content": "Book creation is not allowed"})
continue
engine = get_book_engine()
book, proposal = await engine.create_book(
user_intent=str(data.get("user_intent") or ""),
source_refs=data.get("source_refs") or [],
chat_session_id=str(data.get("chat_session_id") or ""),
chat_selections=data.get("chat_selections") or [],
notebook_refs=data.get("notebook_refs") or [],
knowledge_bases=data.get("knowledge_bases") or [],
question_categories=[
int(c) for c in (data.get("question_categories") or [])
],
question_entries=[int(e) for e in (data.get("question_entries") or [])],
language=str(data.get("language") or "en"),
fallback_language=str(data.get("fallback_language") or "en"),
depth=str(data.get("depth") or "standard"),
stream=creation_bus,
)
# From here on this book has a stream of its own.
created_bus = get_book_bus(book.id)
fanout.attach(created_bus, after_seq=created_bus.latest_seq)
await send(
{
"type": "create_result",
"book": book.model_dump(mode="json"),
"proposal": proposal.model_dump(mode="json"),
}
)
elif msg_type == "confirm_proposal":
if resolved is None or not resolved.can_edit:
raise ValueError("Book not found")
engine = resolved.engine
action_bus = get_book_bus(book_id)
fanout.attach(action_bus, after_seq=action_bus.latest_seq)
revision = _claim_content_mutation(
resolved,
book_id,
data.get("expected_revision"),
"confirm_proposal",
)
edited: BookProposal | None = None
if data.get("proposal"):
edited = BookProposal.model_validate(data["proposal"])
book, spine = await engine.confirm_proposal(
book_id=book_id,
edited_proposal=edited,
)
await send(
{
"type": "confirm_proposal_result",
"book": book.model_dump(mode="json"),
"spine": spine.model_dump(mode="json"),
"book_revision": revision,
}
)
elif msg_type == "confirm_spine":
if resolved is None or not resolved.can_edit:
raise ValueError("Book not found")
engine = resolved.engine
action_bus = get_book_bus(book_id)
fanout.attach(action_bus, after_seq=action_bus.latest_seq)
revision = _claim_content_mutation(
resolved,
book_id,
data.get("expected_revision"),
"confirm_spine",
)
edited_spine: Spine | None = None
if data.get("spine"):
edited_spine = Spine.model_validate(data["spine"])
pages = await engine.confirm_spine(
book_id=book_id,
edited_spine=edited_spine,
auto_compile=bool(data.get("auto_compile", True)),
)
await send(
{
"type": "confirm_spine_result",
"pages": [p.model_dump(mode="json") for p in pages],
"book_revision": revision,
}
)
elif msg_type == "compile_page":
if resolved is None or not resolved.can_edit:
raise ValueError("Book not found")
engine = resolved.engine
action_bus = get_book_bus(book_id)
fanout.attach(action_bus, after_seq=action_bus.latest_seq)
revision = _claim_content_mutation(
resolved,
book_id,
data.get("expected_revision"),
"compile_page",
extra={"page_id": str(data.get("page_id") or "")},
strict=False,
)
page = await engine.compile_page(
book_id=book_id,
page_id=str(data.get("page_id") or ""),
force=bool(data.get("force", False)),
)
await send(
{
"type": "compile_page_result",
"page": page.model_dump(mode="json"),
"book_revision": revision,
}
)
elif msg_type == "regenerate_block":
if resolved is None or not resolved.can_edit:
raise ValueError("Book not found")
engine = resolved.engine
action_bus = get_book_bus(book_id)
fanout.attach(action_bus, after_seq=action_bus.latest_seq)
revision = _claim_content_mutation(
resolved,
book_id,
data.get("expected_revision"),
"regenerate_block",
extra={
"page_id": str(data.get("page_id") or ""),
"block_id": str(data.get("block_id") or ""),
},
)
block = await engine.regenerate_block(
book_id=book_id,
page_id=str(data.get("page_id") or ""),
block_id=str(data.get("block_id") or ""),
params_override=data.get("params_override"),
)
await send(
{
"type": "regenerate_block_result",
"block": block.model_dump(mode="json") if block else None,
"book_revision": revision,
}
)
else:
await send({"type": "error", "content": f"Unknown message type: {msg_type}"})
except BookPausedError as exc:
await send(
{
"type": "error",
"content": str(exc),
"status": 409,
"code": "book_paused",
}
)
except HTTPException as exc:
detail = exc.detail
payload: dict[str, Any] = {
"type": "error",
"content": (
str(detail.get("message") or detail.get("code") or "Book action failed")
if isinstance(detail, dict)
else str(detail)
),
"status": exc.status_code,
}
if isinstance(detail, dict):
payload.update(
{key: detail[key] for key in ("code", "current_revision") if key in detail}
)
await send(payload)
except Exception as exc:
logger.error(f"book ws action {msg_type} failed: {exc}", exc_info=True)
await send({"type": "error", "content": str(exc)})
finally:
if activity is not None:
activity.close()
except WebSocketDisconnect:
pass
except Exception as exc:
logger.error(f"Book WS connection error: {exc}", exc_info=True)
finally:
closed = True
await fanout.close()
await creation_bus.close()
try:
await ws.close()
except Exception:
logger.debug("Book WebSocket was already closed", exc_info=True)
if user_token is not None:
try:
reset_current_user(user_token)
except Exception:
logger.debug("Could not reset Book WebSocket user context", exc_info=True)