DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.
Python ai-agentsai-tutorclawbotcli-tooldeepresearchinteractive-learninglearningmulti-agent-systemsrag
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}