Skip to content

DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.

42.0 KB
Raw Blame
from __future__ import annotations

import asyncio
from contextlib import contextmanager
from datetime import datetime
import json
import logging
from pathlib import Path
import re
import traceback
from typing import TYPE_CHECKING, AsyncGenerator, Literal
import urllib.parse
import uuid

from fastapi import APIRouter, File, HTTPException, UploadFile
from fastapi.responses import Response, StreamingResponse
from pydantic import BaseModel, ConfigDict, Field

# ``docx_converter`` imports python-docx lazily, so this stays import-cheap.
from deeptutor.co_writer.docx_converter import (
    DocxConversionError,
    docx_to_markdown,
    markdown_to_docx,
)
from deeptutor.co_writer.storage import (
    CoWriterDocument,
    CoWriterDocumentSummary,
    get_co_writer_storage,
)
from deeptutor.runtime.stream_bus import StreamBus
from deeptutor.services.config import PROJECT_ROOT, load_config_with_main
from deeptutor.services.model_selection.runtime import (
    activate_llm_selection,
    reset_llm_selection,
)
from deeptutor.services.settings.interface_settings import get_response_language

if TYPE_CHECKING:
    from deeptutor.co_writer.edit_agent import EditAgent

router = APIRouter()

# Initialize logger with config
config = load_config_with_main("main.yaml", PROJECT_ROOT)
log_dir = config.get("paths", {}).get("user_log_dir") or config.get("logging", {}).get("log_dir")
logger = logging.getLogger(__name__)

_edit_agent: "EditAgent | None" = None


def _current_language() -> str:
    # Prefer UI settings, fall back to main.yaml system.language
    return get_response_language(default=config.get("system", {}).get("language", "en"))


def get_edit_agent() -> EditAgent:
    """
    Get the singleton EditAgent instance with refreshed configuration.

    Uses a singleton pattern with refresh_config() to ensure:
    1. Efficient reuse of the agent instance
    2. Latest LLM configuration from Settings is always used
    """
    global _edit_agent
    from deeptutor.co_writer.edit_agent import EditAgent

    lang = _current_language()
    if _edit_agent is None or getattr(_edit_agent, "language", None) != lang:
        _edit_agent = EditAgent(language=lang)
    # Refresh config to pick up any changes from Settings
    _edit_agent.refresh_config()
    return _edit_agent


class LLMSelectionPayload(BaseModel):
    model_config = ConfigDict(extra="forbid")

    profile_id: str
    model_id: str
    reasoning_effort: str | None = None


def _validated_llm_selection(payload: LLMSelectionPayload | None) -> dict[str, str] | None:
    """Normalize and authorize a Co-Writer model selection.

    Ordinary users must receive a concrete granted model, mirroring Chat turn
    admission instead of silently falling back to the deployment's admin LLM.
    """
    from deeptutor.multi_user.context import get_current_user
    from deeptutor.multi_user.model_access import (
        apply_allowed_llm_selection,
        has_capability_access,
        redacted_model_access,
    )
    from deeptutor.multi_user.personal_models import merge_personal_llm_profiles
    from deeptutor.services.config import get_model_catalog_service
    from deeptutor.services.model_selection import (
        LLMSelection,
        apply_llm_selection_to_catalog,
    )

    raw = payload.model_dump(exclude_none=True) if payload is not None else None
    try:
        selection = LLMSelection.from_payload(raw)
        if selection is None and not get_current_user().is_admin:
            if not has_capability_access("llm"):
                raise PermissionError(
                    "No LLM model is assigned to your account. Please contact an administrator."
                )
            assigned = next(
                (item for item in redacted_model_access().get("llm", []) if item.get("available")),
                None,
            )
            if assigned is None:
                raise PermissionError(
                    "No LLM model is assigned to your account. Please contact an administrator."
                )
            selection = LLMSelection(
                profile_id=str(assigned["profile_id"]),
                model_id=str(assigned["model_id"]),
            )

        if selection is None:
            return None

        authorized = apply_allowed_llm_selection(selection.to_dict())
        catalog = merge_personal_llm_profiles(get_model_catalog_service().load())
        apply_llm_selection_to_catalog(catalog, LLMSelection.from_payload(authorized))
        return LLMSelection.from_payload(authorized).to_dict()
    except PermissionError as exc:
        raise HTTPException(status_code=403, detail=str(exc)) from None
    except ValueError as exc:
        raise HTTPException(status_code=422, detail=str(exc)) from None


@contextmanager
def _selected_edit_agent(
    llm_selection: dict[str, str] | None,
    *,
    language: str,
):
    """Run one edit with a request-scoped LLM configuration."""
    from deeptutor.co_writer.edit_agent import EditAgent

    _, token = activate_llm_selection(llm_selection)
    try:
        # A selected model gets its own agent so concurrent edits cannot race
        # through the shared singleton's mutable api_key/model attributes.
        agent = EditAgent(language=language) if llm_selection else get_edit_agent()
        yield agent
    finally:
        reset_llm_selection(token)


# Generous ceilings — they exist to stop runaway payloads (OOM / surprise
# LLM bills), not to constrain normal documents.
_MAX_DOC_CHARS = 600_000
_MAX_SELECTION_CHARS = 120_000
_MAX_INSTRUCTION_CHARS = 10_000
_MAX_DOCX_UPLOAD_BYTES = 20 * 1024 * 1024
_DOCX_UPLOAD_CHUNK = 1024 * 1024


class EditRequest(BaseModel):
    text: str = Field(max_length=_MAX_DOC_CHARS)
    instruction: str = Field(max_length=_MAX_INSTRUCTION_CHARS)
    action: Literal["rewrite", "shorten", "expand"] = "rewrite"
    source: Literal["rag", "web"] | None = None
    kb_name: str | None = None
    llm_selection: LLMSelectionPayload | None = None


class EditResponse(BaseModel):
    edited_text: str
    operation_id: str


class ReactEditRequest(BaseModel):
    selected_text: str = Field(max_length=_MAX_SELECTION_CHARS)
    instruction: str = Field(default="", max_length=_MAX_INSTRUCTION_CHARS)
    mode: Literal["rewrite", "shorten", "expand", "none"] = "rewrite"
    tools: list[Literal["rag", "web"]] = []
    kb_name: str | None = None
    llm_selection: LLMSelectionPayload | None = None


class ReactEditResponse(BaseModel):
    edited_text: str
    operation_id: str
    tools_used: list[str] = []


class AutoMarkRequest(BaseModel):
    text: str = Field(max_length=_MAX_DOC_CHARS)
    llm_selection: LLMSelectionPayload | None = None


class AutoMarkResponse(BaseModel):
    marked_text: str
    operation_id: str


def _default_mode_instruction(mode: str, language: str) -> str:
    zh = language.startswith("zh")
    defaults = {
        "rewrite": "润色这段 markdown,保持原意、结构和语气自然。",
        "shorten": "压缩这段 markdown,让表达更精炼,同时保留关键信息。",
        "expand": "扩展这段 markdown,补充必要细节,同时保持原有风格。",
        "none": "根据用户要求编辑这段 markdown。",
    }
    if zh:
        return defaults.get(mode, defaults["none"])
    defaults_en = {
        "rewrite": "Rewrite this markdown snippet while preserving its meaning, structure, and tone.",
        "shorten": "Shorten this markdown snippet while preserving the key information.",
        "expand": "Expand this markdown snippet with helpful detail while keeping the original style.",
        "none": "Edit this markdown snippet according to the user's request.",
    }
    return defaults_en.get(mode, defaults_en["none"])


def _build_react_edit_prompt(
    *,
    selected_text: str,
    instruction: str,
    mode: str,
    language: str,
    context: str = "",
) -> str:
    user_instruction = instruction.strip() or _default_mode_instruction(mode, language)
    if language.startswith("zh"):
        context_block = f"参考资料(按需取用,不必全部使用):\n{context}\n\n" if context else ""
        return (
            "你正在编辑一段从 Markdown 编辑器里选中的文本。\n\n"
            f"编辑模式: {mode}\n"
            f"用户要求: {user_instruction}\n\n"
            f"{context_block}"
            "待编辑的选中文本:\n"
            "```markdown\n"
            f"{selected_text}\n"
            "```\n\n"
            "要求:\n"
            "1. 只输出编辑后的那段 Markdown 文本,供编辑器直接替换。\n"
            "2. 不要输出解释、标题、前后缀、代码围栏。\n"
            "3. 保持 Markdown 语法合法。\n"
            "4. 如果给了参考资料,把相关事实自然融入结果,不要提工具或资料来源。\n"
        )
    context_block = (
        f"Reference material (use what is relevant, ignore the rest):\n{context}\n\n"
        if context
        else ""
    )
    return (
        "You are editing a text selection from a Markdown editor.\n\n"
        f"Edit mode: {mode}\n"
        f"User request: {user_instruction}\n\n"
        f"{context_block}"
        "Selected text to edit:\n"
        "```markdown\n"
        f"{selected_text}\n"
        "```\n\n"
        "Requirements:\n"
        "1. Output only the edited Markdown snippet for direct replacement.\n"
        "2. Do not include explanations, headings, prefixes, suffixes, or code fences.\n"
        "3. Keep the Markdown valid.\n"
        "4. If reference material is given, weave the relevant facts in naturally "
        "without mentioning tools or sources.\n"
    )


def _strip_markdown_fence(text: str) -> str:
    cleaned = text.strip()
    if cleaned.startswith("```") and cleaned.endswith("```"):
        lines = cleaned.splitlines()
        if len(lines) >= 3:
            return "\n".join(lines[1:-1]).strip()
    return cleaned


def _clean_react_edit_output(text: str, *, binding: str | None, model: str | None) -> str:
    from deeptutor.services.llm import clean_thinking_tags

    return _strip_markdown_fence(clean_thinking_tags(text, binding, model))


def _normalize_react_edit_tools(tools: list[str] | None) -> list[str]:
    allowed = {"rag", "web"}
    result: list[str] = []
    for tool in tools or []:
        name = str(tool or "").strip()
        if name in allowed and name not in result:
            result.append(name)
    return result


def _prepare_react_edit_request(
    request: ReactEditRequest, language: str
) -> tuple[str, str, list[str]]:
    tools = _normalize_react_edit_tools(request.tools)
    instruction = request.instruction.strip()
    if request.mode == "none" and not instruction:
        detail = (
            "请输入编辑要求,或选择 shorten / expand / rewrite 模式。"
            if language.startswith("zh")
            else "Provide an edit instruction, or choose shorten / expand / rewrite mode."
        )
        raise HTTPException(status_code=400, detail=detail)

    selected_text = request.selected_text.strip("\n")
    if not selected_text.strip():
        detail = (
            "请先选中一段文本。"
            if language.startswith("zh")
            else "Please select a text passage first."
        )
        raise HTTPException(status_code=400, detail=detail)

    return selected_text, instruction, tools


_TRACE_PREVIEW_CHARS = 1200


def _trace_preview(text: str) -> str:
    cleaned = text.strip()
    if len(cleaned) <= _TRACE_PREVIEW_CHARS:
        return cleaned
    return cleaned[:_TRACE_PREVIEW_CHARS].rstrip() + "…"


async def _run_react_edit(
    request: ReactEditRequest,
    *,
    language: str,
    llm_selection: dict[str, str] | None = None,
    stream: StreamBus | None = None,
) -> dict[str, object]:
    from deeptutor.co_writer.edit_agent import append_history, print_stats

    selected_text, instruction, tools = _prepare_react_edit_request(request, language)
    operation_id = datetime.now().strftime("%Y%m%d_%H%M%S") + "_" + uuid.uuid4().hex[:6]

    with _selected_edit_agent(llm_selection, language=language) as agent:
        # Optional reference retrieval before the edit. Each tool degrades to a
        # plain edit on failure — retrieval must never block the user's edit.
        query = instruction or selected_text[:400]
        context_blocks: list[str] = []
        tools_used: list[str] = []
        from deeptutor.services.rag.pipelines.pageindex import is_pageindex_kb

        pageindex_source = "rag" in tools and is_pageindex_kb(request.kb_name)
        for tool in tools:
            kb_name = request.kb_name if tool == "rag" else None
            if tool == "rag" and not kb_name:
                continue
            if tool == "rag" and pageindex_source:
                # The edit loop below receives PageIndex tools directly.
                continue
            if stream is not None:
                await stream.tool_call(
                    tool,
                    {"query": query, **({"kb_name": kb_name} if kb_name else {})},
                    source="co_writer_react_edit",
                    stage="exploring",
                )
            context, _file = await agent.gather_context(
                source=tool,
                query=query,
                kb_name=kb_name,
                operation_id=operation_id,
            )
            if stream is not None:
                await stream.tool_result(
                    tool,
                    _trace_preview(context) if context else "(no result)",
                    source="co_writer_react_edit",
                    stage="exploring",
                )
            if context:
                context_blocks.append(context)
                tools_used.append(tool)

        system_prompt = (
            "You are an expert markdown editor."
            if not language.startswith("zh")
            else "你是一个严格的 Markdown 编辑助手。"
        )
        prompt = _build_react_edit_prompt(
            selected_text=selected_text,
            instruction=instruction,
            mode=request.mode,
            language=language,
            context="\n\n".join(context_blocks),
        )

        response_chunks: list[str] = []
        pageindex_sources: list[dict[str, object]] = []

        async def _consume() -> None:
            if pageindex_source and request.kb_name:
                from deeptutor.services.rag.pipelines.pageindex.reasoning import (
                    read_pageindex_with_agent,
                )

                reading = await read_pageindex_with_agent(
                    kb_name=request.kb_name,
                    system_prompt=system_prompt,
                    user_prompt=prompt,
                    stream=stream,
                    source="co_writer_react_edit",
                    stage="responding",
                )
                if reading.text:
                    response_chunks.append(reading.text)
                    pageindex_sources.extend(reading.sources)
                    tools_used.append("rag")
                    if stream is not None:
                        await stream.content(
                            reading.text,
                            source="co_writer_react_edit",
                            stage="responding",
                        )
                return
            async for chunk in agent.stream_llm(
                user_prompt=prompt,
                system_prompt=system_prompt,
                stage=f"react_edit_{request.mode}",
            ):
                if not chunk:
                    continue
                response_chunks.append(chunk)
                if stream is not None:
                    await stream.content(
                        chunk,
                        source="co_writer_react_edit",
                        stage="responding",
                    )

        if stream is not None:
            async with stream.stage("responding", source="co_writer_react_edit"):
                await _consume()
        else:
            await _consume()

        edited_text = _clean_react_edit_output(
            "".join(response_chunks),
            binding=agent.binding,
            model=agent.get_model(),
        )

        append_history(
            {
                "id": operation_id,
                "timestamp": datetime.now().isoformat(),
                "action": "react_edit",
                "mode": request.mode,
                "tools": tools_used,
                "kb_name": request.kb_name,
                "input": {
                    "selected_text": request.selected_text,
                    "instruction": instruction,
                },
                "output": {"edited_text": edited_text},
                "sources": pageindex_sources,
                "model": agent.get_model(),
            }
        )
        print_stats()

        result = {
            "edited_text": edited_text,
            "operation_id": operation_id,
            "tools_used": tools_used,
        }
        if stream is not None:
            await stream.result(result, source="co_writer_react_edit")
        return result


async def _stream_react_edit(
    request: ReactEditRequest,
    *,
    llm_selection: dict[str, str] | None,
) -> AsyncGenerator[str, None]:
    language = _current_language()
    bus = StreamBus()
    error_holder: dict[str, str] = {}
    result_holder: dict[str, object] | None = None

    async def _run() -> None:
        nonlocal result_holder
        try:
            result_holder = await _run_react_edit(
                request,
                language=language,
                llm_selection=llm_selection,
                stream=bus,
            )
        except HTTPException as exc:
            error_holder["detail"] = str(exc.detail)
        except Exception as exc:
            error_holder["detail"] = str(exc)
        finally:
            await bus.close()

    task = asyncio.create_task(_run())
    try:
        async for event in bus.subscribe():
            yield f"event: stream\ndata: {json.dumps(event.to_dict(), default=str)}\n\n"

        await task
        if error_holder:
            yield f"event: error\ndata: {json.dumps(error_holder, default=str)}\n\n"
        else:
            yield f"event: result\ndata: {json.dumps(result_holder or {}, default=str)}\n\n"
    finally:
        if not task.done():
            task.cancel()


@router.post("/documents/actions/edit", response_model=EditResponse)
async def edit_text(request: EditRequest):
    from deeptutor.co_writer.edit_agent import print_stats

    try:
        # Get agent with refreshed LLM configuration from Settings
        with _selected_edit_agent(
            _validated_llm_selection(request.llm_selection),
            language=_current_language(),
        ) as agent:
            result = await agent.process(
                text=request.text,
                instruction=request.instruction,
                action=request.action,
                source=request.source,
                kb_name=request.kb_name,
            )

        # Print token stats
        print_stats()

        return result

    except HTTPException:
        raise
    except Exception as e:
        traceback.print_exc()
        raise HTTPException(status_code=500, detail=str(e))


@router.post("/documents/actions/edit-react", response_model=ReactEditResponse)
async def edit_text_react(request: ReactEditRequest):
    try:
        return await _run_react_edit(
            request,
            language=_current_language(),
            llm_selection=_validated_llm_selection(request.llm_selection),
        )
    except HTTPException:
        raise
    except Exception as e:
        traceback.print_exc()
        raise HTTPException(status_code=500, detail=str(e))


@router.post("/documents/actions/edit-react/stream")
async def edit_text_react_stream(request: ReactEditRequest):
    try:
        llm_selection = _validated_llm_selection(request.llm_selection)
        _prepare_react_edit_request(request, _current_language())
    except HTTPException:
        raise
    return StreamingResponse(
        _stream_react_edit(request, llm_selection=llm_selection),
        media_type="text/event-stream",
        headers={"Cache-Control": "no-cache", "X-Accel-Buffering": "no"},
    )


@router.post("/documents/actions/automark", response_model=AutoMarkResponse)
async def auto_mark_text(request: AutoMarkRequest):
    """AI auto-mark text"""
    from deeptutor.co_writer.edit_agent import print_stats

    try:
        # Get agent with refreshed LLM configuration from Settings
        with _selected_edit_agent(
            _validated_llm_selection(request.llm_selection),
            language=_current_language(),
        ) as agent:
            result = await agent.auto_mark(text=request.text)

        # Print token stats
        print_stats()

        return result
    except HTTPException:
        raise
    except Exception as e:
        traceback.print_exc()
        raise HTTPException(status_code=500, detail=str(e))


@router.get("/documents/history")
async def get_history():
    """Get all operation history"""
    from deeptutor.co_writer.edit_agent import load_history

    try:
        history = load_history()
        return {"history": history, "total": len(history)}
    except Exception as e:
        raise HTTPException(status_code=500, detail=str(e))


@router.get("/documents/history/{operation_id}")
async def get_operation(operation_id: str):
    """Get single operation details"""
    from deeptutor.co_writer.edit_agent import load_history

    try:
        history = load_history()
        for op in history:
            if op.get("id") == operation_id:
                return op
        raise HTTPException(status_code=404, detail="Operation not found")
    except HTTPException:
        raise
    except Exception as e:
        raise HTTPException(status_code=500, detail=str(e))


@router.get("/documents/tool-calls/{operation_id}")
async def get_tool_call(operation_id: str):
    """Get tool call details"""
    from deeptutor.co_writer.edit_agent import tool_calls_dir

    try:
        # Find matching file
        for filepath in tool_calls_dir().glob(f"{operation_id}_*.json"):
            with open(filepath, encoding="utf-8") as f:
                return json.load(f)
        raise HTTPException(status_code=404, detail="Tool call not found")
    except HTTPException:
        raise
    except Exception as e:
        raise HTTPException(status_code=500, detail=str(e))


# ─────────────────────────────────────────────────────────────────────────────
# Document CRUD (multi-project Co-Writer)
# ─────────────────────────────────────────────────────────────────────────────

# Storage builds paths as `documents/doc_{doc_id}`; an unvalidated id like
# "a/../../x" would escape the documents root (and DELETE runs rmtree).
_DOC_ID_RE = re.compile(r"^[0-9a-f]{8,32}$")


def _validate_doc_id(doc_id: str) -> str:
    if not _DOC_ID_RE.fullmatch(doc_id):
        raise HTTPException(status_code=404, detail="Document not found")
    return doc_id


class CreateDocumentRequest(BaseModel):
    blocks: list[dict] | None = None
    parent_id: str | None = None
    title: str | None = None
    content: str = ""


class UpdateDocumentRequest(BaseModel):
    blocks: list[dict] | None = None
    expected_revision: int | None = Field(default=None, ge=0)
    parent_id: str | None = None
    icon: str = Field(default="", max_length=100)
    cover: str = Field(default="", max_length=2000)
    pinned: bool = False
    title: str | None = None
    content: str | None = None


class DocumentResponse(CoWriterDocument):
    @classmethod
    def from_model(cls, doc: CoWriterDocument) -> "DocumentResponse":
        return cls(**doc.model_dump())


class DocumentSummaryResponse(CoWriterDocumentSummary):
    @classmethod
    def from_summary(cls, summary: CoWriterDocumentSummary) -> "DocumentSummaryResponse":
        return cls(**summary.model_dump())


@router.get("/documents")
async def list_documents() -> dict[str, list[DocumentSummaryResponse]]:
    """List all Co-Writer documents (summary view, sorted by recency)."""
    try:
        storage = get_co_writer_storage()
        summaries = storage.list_documents()
        return {"documents": [DocumentSummaryResponse.from_summary(s) for s in summaries]}
    except Exception as e:
        traceback.print_exc()
        raise HTTPException(status_code=500, detail=str(e))


@router.post("/documents", response_model=DocumentResponse)
async def create_document(request: CreateDocumentRequest) -> DocumentResponse:
    """Create a new Co-Writer document."""
    try:
        storage = get_co_writer_storage()
        document = storage.create_document(**request.model_dump())
        return DocumentResponse.from_model(document)
    except ValueError as exc:
        raise HTTPException(status_code=400, detail=str(exc)) from exc
    except Exception as e:
        traceback.print_exc()
        raise HTTPException(status_code=500, detail=str(e))


class ExportDocxRequest(BaseModel):
    title: str = ""
    content: str = Field(default="", max_length=_MAX_DOC_CHARS)


def _docx_download_filename(title: str) -> str:
    raw = (title or "co-writer").strip() or "co-writer"
    safe = re.sub(r'[\\/:*?"<>|\x00-\x1f\x7f]', "-", raw).strip(" .")[:80]
    safe = safe or "co-writer"
    if not safe.lower().endswith(".docx"):
        safe = f"{safe}.docx"
    return safe


def _content_disposition(filename: str) -> str:
    """Build a header that survives non-ASCII titles (RFC 6266 / RFC 5987).

    Header values are latin-1 encoded on the wire, so a CJK or accented title
    must go in the ``filename*`` parameter with an ASCII ``filename`` fallback.
    """
    ascii_name = filename.encode("ascii", "ignore").decode("ascii").strip(" .")
    if not ascii_name.lower().endswith(".docx"):
        ascii_name = f"{ascii_name}.docx" if ascii_name else "co-writer.docx"
    quoted = urllib.parse.quote(filename, safe="")
    return f"attachment; filename=\"{ascii_name}\"; filename*=UTF-8''{quoted}"


@router.post("/documents/import/docx", response_model=DocumentResponse)
async def import_docx(file: UploadFile = File(...)) -> DocumentResponse:
    filename = (file.filename or "").strip()
    if not filename:
        raise HTTPException(status_code=400, detail="The upload has no filename.")
    ext = Path(filename).suffix.lower()
    if ext == ".doc":
        raise HTTPException(
            status_code=400,
            detail=(
                "Legacy .doc files are not supported yet. "
                "Please save the document as .docx and try again."
            ),
        )
    if ext != ".docx":
        raise HTTPException(status_code=400, detail="Only .docx files can be imported.")

    chunks: list[bytes] = []
    written = 0
    while chunk := await file.read(_DOCX_UPLOAD_CHUNK):
        written += len(chunk)
        if written > _MAX_DOCX_UPLOAD_BYTES:
            raise HTTPException(
                status_code=400,
                detail=(
                    f"{filename} exceeds the {_MAX_DOCX_UPLOAD_BYTES // (1024 * 1024)} MB limit."
                ),
            )
        chunks.append(chunk)
    if written == 0:
        raise HTTPException(status_code=400, detail=f"{filename} is empty.")

    data = b"".join(chunks)
    try:
        markdown = await asyncio.to_thread(docx_to_markdown, data, filename)
    except DocxConversionError as exc:
        raise HTTPException(status_code=400, detail=str(exc)) from exc
    except Exception as exc:
        traceback.print_exc()
        raise HTTPException(status_code=500, detail=str(exc)) from exc

    title = Path(filename).stem.strip()[:120] or None
    try:
        storage = get_co_writer_storage()
        document = storage.create_document(title=title, content=markdown)
        return DocumentResponse.from_model(document)
    except Exception as exc:
        traceback.print_exc()
        raise HTTPException(status_code=500, detail=str(exc)) from exc


@router.post("/documents/export/docx")
async def export_docx(request: ExportDocxRequest) -> Response:
    try:
        data = await asyncio.to_thread(markdown_to_docx, request.content, request.title)
    except DocxConversionError as exc:
        raise HTTPException(status_code=400, detail=str(exc)) from exc
    except Exception as exc:
        traceback.print_exc()
        raise HTTPException(status_code=500, detail=str(exc)) from exc
    filename = _docx_download_filename(request.title)
    return Response(
        content=data,
        media_type="application/vnd.openxmlformats-officedocument.wordprocessingml.document",
        headers={"Content-Disposition": _content_disposition(filename)},
    )


@router.get("/documents/{doc_id}", response_model=DocumentResponse)
async def get_document(doc_id: str) -> DocumentResponse:
    """Get a single Co-Writer document by id."""
    try:
        storage = get_co_writer_storage()
        document = storage.load_document(_validate_doc_id(doc_id))
        if document is None:
            raise HTTPException(status_code=404, detail="Document not found")
        return DocumentResponse.from_model(document)
    except HTTPException:
        raise
    except Exception as e:
        traceback.print_exc()
        raise HTTPException(status_code=500, detail=str(e))


@router.put("/documents/{doc_id}", response_model=DocumentResponse)
async def update_document(doc_id: str, request: UpdateDocumentRequest) -> DocumentResponse:
    """Update a Co-Writer document (title and/or content)."""
    try:
        storage = get_co_writer_storage()
        document = storage.update_document(
            _validate_doc_id(doc_id), **request.model_dump(exclude_unset=True)
        )
        if document is None:
            raise HTTPException(status_code=404, detail="Document not found")
        return DocumentResponse.from_model(document)
    except HTTPException:
        raise
    except ValueError as exc:
        from deeptutor.co_writer.storage import RevisionConflict

        raise HTTPException(
            status_code=409 if isinstance(exc, RevisionConflict) else 400, detail=str(exc)
        ) from exc


@router.delete("/documents/{doc_id}")
async def delete_document(doc_id: str) -> dict[str, bool]:
    """Delete a Co-Writer document."""
    try:
        storage = get_co_writer_storage()
        _validate_doc_id(doc_id)
        if not storage.doc_exists(doc_id):
            raise HTTPException(status_code=404, detail="Document not found")
        success = storage.delete_document(doc_id)
        return {"deleted": success}
    except HTTPException:
        raise
    except Exception as e:
        traceback.print_exc()
        raise HTTPException(status_code=500, detail=str(e))


@router.get("/documents/{doc_id}/suggestions")
async def note_suggestions(doc_id: str):
    from deeptutor.notes.proposals import list_proposals
    from deeptutor.notes.resources import normalize_note_resources, saved_note_resources
    from deeptutor.services.workspace import WorkspaceError

    storage = get_co_writer_storage()
    if not storage.doc_exists(_validate_doc_id(doc_id)):
        raise HTTPException(status_code=404, detail="Page not found")
    suggestions = list_proposals(storage, doc_id)
    for suggestion in suggestions:
        if suggestion["status"] == "pending":
            try:
                suggestion["markdown"], suggestion["blocks"] = normalize_note_resources(
                    suggestion["markdown"],
                    suggestion.get("blocks"),
                    published=await saved_note_resources(
                        suggestion["markdown"], suggestion.get("blocks")
                    ),
                )
            except (WorkspaceError, ValueError):
                # An unavailable file must not hide the rest of the review queue.
                pass
    return {"suggestions": suggestions}


class ReviewSuggestionRequest(BaseModel):
    accept: bool
    blocks: list[dict] | None = None


@router.post("/documents/{doc_id}/suggestions/{suggestion_id}", response_model=DocumentResponse)
async def review_note_suggestion(doc_id: str, suggestion_id: str, request: ReviewSuggestionRequest):
    from deeptutor.co_writer.storage import RevisionConflict
    from deeptutor.notes.proposals import review

    try:
        return review(
            get_co_writer_storage(), _validate_doc_id(doc_id), suggestion_id, **request.model_dump()
        )
    except ValueError as exc:
        raise HTTPException(
            status_code=409 if isinstance(exc, RevisionConflict) else 400, detail=str(exc)
        ) from exc


@router.get("/documents/{doc_id}/backlinks")
async def note_backlinks(doc_id: str):
    _validate_doc_id(doc_id)
    storage = get_co_writer_storage()
    return {
        "pages": [
            s.model_dump()
            for s in storage.list_documents()
            if s.id != doc_id and f"/co-writer/{doc_id}" in storage.load_document(s.id).content
        ]
    }


@router.post("/documents/{doc_id}/assets")
async def upload_note_asset(doc_id: str, file: UploadFile = File(...)):
    import uuid

    storage = get_co_writer_storage()
    if not storage.doc_exists(_validate_doc_id(doc_id)):
        raise HTTPException(status_code=404, detail="Page not found")
    allowed = {
        "image/png": ".png",
        "image/jpeg": ".jpg",
        "image/webp": ".webp",
        "image/gif": ".gif",
        "audio/mpeg": ".mp3",
        "audio/wav": ".wav",
        "video/mp4": ".mp4",
        "application/pdf": ".pdf",
    }
    suffix = allowed.get(file.content_type or "")
    if not suffix:
        raise HTTPException(status_code=400, detail="Unsupported attachment type")
    data = await file.read(25 * 1024 * 1024 + 1)
    if not data or len(data) > 25 * 1024 * 1024:
        raise HTTPException(status_code=400, detail="Attachments must be between 1 byte and 25 MB")
    folder = storage.doc_root(doc_id) / "assets"
    folder.mkdir(exist_ok=True)
    name = uuid.uuid4().hex + suffix
    (folder / name).write_bytes(data)
    from deeptutor.services.workspace.context import current_workspace_id

    return {
        "url": f"/api/documents/{doc_id}/assets/{name}?dt_workspace={urllib.parse.quote(current_workspace_id() or '')}"
    }


@router.get("/documents/{doc_id}/assets/{name}")
async def read_note_asset(doc_id: str, name: str):
    from fastapi.responses import FileResponse

    storage = get_co_writer_storage()
    _validate_doc_id(doc_id)
    if not re.fullmatch(r"[0-9a-f]{32}\.(png|jpg|webp|gif|mp3|wav|mp4|pdf)", name):
        raise HTTPException(status_code=404, detail="Attachment not found")
    path = storage.doc_root(doc_id) / "assets" / name
    if not path.is_file():
        raise HTTPException(status_code=404, detail="Attachment not found")
    return FileResponse(path, headers={"X-Content-Type-Options": "nosniff"})


class ClipRequest(BaseModel):
    title: str = Field(default="", max_length=200)
    markdown: str = Field(max_length=200000)
    source_url: str = Field(default="", max_length=2000)
    source_id: str = Field(default="", max_length=200)
    favorite_type: str = Field(default="", max_length=60)
    summary: str = Field(default="", max_length=200000)
    favorite_metadata: dict = Field(default_factory=dict)


@router.post("/documents/{doc_id}/clips", response_model=DocumentResponse)
async def append_note_clip(doc_id: str, request: ClipRequest):
    import uuid

    from deeptutor.notes.blocks import blocks_to_markdown, safe_link, validate_blocks

    if not safe_link(request.source_url):
        raise HTTPException(status_code=400, detail="Unsupported source URL")
    storage = get_co_writer_storage()
    with storage.locked():
        doc = storage.load_document(_validate_doc_id(doc_id))
        if doc is None:
            raise HTTPException(status_code=404, detail="Page not found")
        if doc.blocks is None and doc.content.strip():
            # Preserve legacy Markdown opaquely until the browser migrates it.
            doc.content += f"\n\n## {request.title}\n\n{request.markdown}" + (
                f"\n\n[Source]({request.source_url})" if request.source_url else ""
            )
        else:
            if doc.blocks is None:
                doc.blocks = []
            doc.blocks.append(
                {
                    "id": uuid.uuid4().hex,
                    "type": "clip",
                    "props": {
                        "title": request.title,
                        "markdown": request.markdown,
                        "sourceUrl": request.source_url,
                        "sourceId": request.source_id,
                        "favoriteType": request.favorite_type,
                        "summary": request.summary,
                        "metadata": json.dumps(request.favorite_metadata, ensure_ascii=False),
                        "expanded": False,
                    },
                    "children": [],
                }
            )
            try:
                validate_blocks(doc.blocks)
            except ValueError as exc:
                raise HTTPException(status_code=400, detail=str(exc)) from exc
            doc.content = blocks_to_markdown(doc.blocks)
        doc.revision += 1
        import time

        doc.updated_at = time.time()
        storage._write(doc)
        return doc


@router.get("/documents/review/due")
async def due_note_cards():
    from deeptutor.notes.review import due_cards

    return {"cards": due_cards(get_co_writer_storage())}


class ReviewCardRequest(BaseModel):
    card_id: str = Field(min_length=1, max_length=200)
    remembered: bool


@router.post("/documents/{doc_id}/review")
async def grade_note_card(doc_id: str, request: ReviewCardRequest):
    from deeptutor.notes.review import grade_card

    try:
        return grade_card(
            get_co_writer_storage(), _validate_doc_id(doc_id), request.card_id, request.remembered
        )
    except ValueError as exc:
        raise HTTPException(status_code=400, detail=str(exc)) from exc


class CreateSuggestionRequest(BaseModel):
    operation: str = "insert"
    block_id: str = ""
    markdown: str = Field(default="", max_length=200000)
    explanation: str = Field(default="", max_length=10000)
    blocks: list[dict] | None = None
    expected_original: dict | None = None
    source_turn_id: str = Field(default="", max_length=120)


@router.post("/documents/{doc_id}/suggestions")
async def create_note_suggestion(doc_id: str, request: CreateSuggestionRequest):
    from deeptutor.co_writer.storage import RevisionConflict
    from deeptutor.notes.proposals import propose

    try:
        values = request.model_dump(exclude_unset=True)
        return propose(
            get_co_writer_storage(),
            _validate_doc_id(doc_id),
            **{"operation": request.operation, **values},
        )
    except RevisionConflict as exc:
        raise HTTPException(status_code=409, detail=str(exc)) from exc
    except ValueError as exc:
        raise HTTPException(status_code=400, detail=str(exc)) from exc


# ── Threads: conversations held at a line of the page ───────────────────────

_SESSION_ID_RE = r"^[A-Za-z0-9_.:-]{1,128}$"


class AnchorThreadRequest(BaseModel):
    session_id: str = Field(pattern=_SESSION_ID_RE)
    block_id: str = Field(min_length=1, max_length=64, pattern=r"^[A-Za-z0-9_-]+$")
    quote: str = Field(default="", max_length=4000)
    origin: Literal["ask", "generate"] = "ask"


@router.get("/documents/{doc_id}/threads")
async def note_threads(doc_id: str):
    """The page's conversations, each with its anchor and its session's state."""
    from deeptutor.notes.threads import list_threads, prune_threads
    from deeptutor.services.session import get_session_store

    storage = get_co_writer_storage()
    if not storage.doc_exists(_validate_doc_id(doc_id)):
        raise HTTPException(status_code=404, detail="Page not found")
    if not (storage.doc_root(doc_id) / "threads.json").exists():
        from deeptutor.notes.threads import adopt_legacy_threads
        from deeptutor.services.session.organization import list_all_sessions_snapshot

        legacy = [
            row["session_id"]
            for row in await list_all_sessions_snapshot(get_session_store())
            if str((row.get("preferences") or {}).get("note_document_id") or "") == doc_id
        ]
        adopt_legacy_threads(storage, doc_id, legacy)
    threads = list_threads(storage, doc_id)
    summaries = {
        row["session_id"]: row
        for row in await get_session_store().get_session_summaries(
            [t["session_id"] for t in threads]
        )
    }
    if threads and len(summaries) < len(threads):
        prune_threads(storage, doc_id, set(summaries))
    rows = []
    for thread in threads:
        summary = summaries.get(thread["session_id"])
        if summary is None:
            continue
        rows.append(
            {
                **thread,
                "title": summary.get("title") or "",
                "status": summary.get("status") or "idle",
                "updated_at": summary.get("updated_at") or thread.get("created_at"),
                "message_count": summary.get("message_count") or 0,
                "last_message": str(summary.get("last_message") or "")[:400],
            }
        )
    return {"threads": rows}


@router.post("/documents/{doc_id}/threads")
async def anchor_note_thread(doc_id: str, request: AnchorThreadRequest):
    from deeptutor.notes.threads import anchor_thread

    try:
        return anchor_thread(
            get_co_writer_storage(), _validate_doc_id(doc_id), **request.model_dump()
        )
    except ValueError as exc:
        raise HTTPException(status_code=404, detail=str(exc)) from exc


@router.delete("/documents/{doc_id}/threads/{session_id}")
async def delete_note_thread(doc_id: str, session_id: str):
    """Delete a page conversation: the session goes to the recycle bin with it."""
    from deeptutor.api.routers.sessions import delete_session
    from deeptutor.notes.threads import find_thread, remove_thread

    storage = get_co_writer_storage()
    _validate_doc_id(doc_id)
    if find_thread(storage, doc_id, session_id) is None:
        raise HTTPException(status_code=404, detail="Conversation not found")
    try:
        await delete_session(session_id)
    except HTTPException as exc:
        if exc.status_code != 404:
            raise
    remove_thread(storage, doc_id, session_id)
    return {"deleted": True}