Skip to content

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

15.5 KB
Raw Blame
"""
Notebook API Router
Provides notebook creation, querying, updating, deletion, and record management functions
"""

import json
from typing import AsyncGenerator, Literal

from fastapi import APIRouter, HTTPException
from fastapi.responses import PlainTextResponse, StreamingResponse
from pydantic import BaseModel

from deeptutor.agents.notebook import NotebookSummarizeAgent
from deeptutor.services.llm import clean_thinking_tags
from deeptutor.services.notebook import notebook_manager
from deeptutor.services.notebook.service import NotebookCorruptedError

router = APIRouter()


def _unreadable(exc: NotebookCorruptedError) -> HTTPException:
    """Translate a damaged notebook file into a response the UI can explain.

    409 rather than 500: the request was fine, the stored file is not, and
    the client can act on it (restore a backup, delete the notebook).

    Every endpoint re-raises through this before its generic `except
    Exception`, because that generic clause would otherwise flatten a
    diagnosable "your file is damaged" into an anonymous 500. The contract is
    covered by a test that walks the routes, so a new endpoint that forgets
    it fails CI rather than degrading quietly.
    """
    return HTTPException(
        status_code=409,
        detail={
            "code": "notebook_unreadable",
            "notebook_id": exc.notebook_id,
            "message": str(exc),
        },
    )


# === Request/Response Models ===


class CreateNotebookRequest(BaseModel):
    """Create notebook request"""

    name: str
    description: str = ""
    color: str = "#3B82F6"
    icon: str = "book"


class UpdateNotebookRequest(BaseModel):
    """Update notebook request"""

    name: str | None = None
    description: str | None = None
    color: str | None = None
    icon: str | None = None


class AddRecordRequest(BaseModel):
    """Add record request"""

    notebook_ids: list[str]
    record_type: Literal[
        "solve",
        "question",
        "research",
        "chat",
        "co_writer",
        "tutorbot",
        "reading",
        "video_learning",
    ]
    title: str
    summary: str = ""
    user_query: str
    output: str
    metadata: dict = {}
    kb_name: str | None = None


class RemoveRecordRequest(BaseModel):
    """Remove record request"""

    record_id: str


class UpdateRecordRequest(BaseModel):
    """Update an existing notebook record.

    Only the fields the client actually sends are forwarded (see
    ``exclude_unset`` at the call site), which is what keeps ``kb_name``
    from being wiped by a request that merely renames the record.
    """

    title: str | None = None
    summary: str | None = None
    user_query: str | None = None
    output: str | None = None
    metadata: dict | None = None
    kb_name: str | None = None


class MoveRecordRequest(BaseModel):
    """Move or copy a record into another notebook."""

    target_notebook_id: str


# === API Endpoints ===


async def _build_record_summary(request: AddRecordRequest) -> str:
    if request.summary.strip():
        return clean_thinking_tags(request.summary).strip()
    agent = NotebookSummarizeAgent(language=str(request.metadata.get("ui_language", "en")))
    return clean_thinking_tags(
        await agent.summarize(
            title=request.title,
            record_type=request.record_type,
            user_query=request.user_query,
            output=request.output,
            metadata=request.metadata,
        )
    ).strip()


async def _stream_add_record_with_summary(
    request: AddRecordRequest,
) -> AsyncGenerator[str, None]:
    try:
        agent = NotebookSummarizeAgent(language=str(request.metadata.get("ui_language", "en")))
        summary_parts: list[str] = []
        if request.summary.strip():
            summary = clean_thinking_tags(request.summary).strip()
            summary_parts.append(summary)
            if summary:
                yield f"data: {json.dumps({'type': 'summary_chunk', 'content': summary}, ensure_ascii=False)}\n\n"
        else:
            async for chunk in agent.stream_summary(
                title=request.title,
                record_type=request.record_type,
                user_query=request.user_query,
                output=request.output,
                metadata=request.metadata,
            ):
                if not chunk:
                    continue
                summary_parts.append(chunk)

            summary = clean_thinking_tags("".join(summary_parts)).strip()
            if summary:
                yield f"data: {json.dumps({'type': 'summary_chunk', 'content': summary}, ensure_ascii=False)}\n\n"

        summary = clean_thinking_tags("".join(summary_parts)).strip()
        result = notebook_manager.add_record(
            notebook_ids=request.notebook_ids,
            record_type=request.record_type,
            title=request.title,
            summary=summary,
            user_query=request.user_query,
            output=request.output,
            metadata=request.metadata,
            kb_name=request.kb_name,
        )
        payload = {
            "type": "result",
            "success": True,
            "summary": summary,
            "record": result["record"],
            "added_to_notebooks": result["added_to_notebooks"],
        }
        yield f"data: {json.dumps(payload, ensure_ascii=False)}\n\n"
    except Exception as exc:
        payload = {"type": "error", "detail": str(exc)}
        yield f"data: {json.dumps(payload, ensure_ascii=False)}\n\n"


# NOTE: every literal path below must stay above the `/{notebook_id}` routes.
# FastAPI matches in declaration order, so a literal declared later is shadowed
# by the parameterised route and becomes unreachable.
@router.get("/notebooks/health")
async def health_check():
    """Health check"""
    return {"status": "healthy", "service": "notebook"}


@router.get("/notebooks")
async def list_notebooks():
    """
    Get all notebook list

    Returns:
        Notebook list (includes summary information)
    """
    try:
        notebooks = notebook_manager.list_notebooks()
        return {"notebooks": notebooks, "total": len(notebooks)}
    except NotebookCorruptedError as exc:
        raise _unreadable(exc)
    except Exception as e:
        raise HTTPException(status_code=500, detail=str(e))


@router.get("/notebooks/statistics")
async def get_statistics():
    """
    Get notebook statistics

    Returns:
        Statistics information
    """
    try:
        stats = notebook_manager.get_statistics()
        return stats
    except NotebookCorruptedError as exc:
        raise _unreadable(exc)
    except Exception as e:
        raise HTTPException(status_code=500, detail=str(e))


@router.post("/notebooks")
async def create_notebook(request: CreateNotebookRequest):
    """
    Create new notebook

    Args:
        request: Create request

    Returns:
        Created notebook information
    """
    try:
        notebook = notebook_manager.create_notebook(
            name=request.name,
            description=request.description,
            color=request.color,
            icon=request.icon,
        )
        return {"success": True, "notebook": notebook}
    except NotebookCorruptedError as exc:
        raise _unreadable(exc)
    except Exception as e:
        raise HTTPException(status_code=500, detail=str(e))


@router.get("/notebooks/{notebook_id}")
async def get_notebook(notebook_id: str):
    """
    Get notebook details

    Args:
        notebook_id: Notebook ID

    Returns:
        Notebook details (includes all records)
    """
    try:
        notebook = notebook_manager.get_notebook(notebook_id)
        if not notebook:
            raise HTTPException(status_code=404, detail="Notebook not found")
        return notebook
    except HTTPException:
        raise
    except NotebookCorruptedError as exc:
        raise _unreadable(exc)
    except Exception as e:
        raise HTTPException(status_code=500, detail=str(e))


@router.put("/notebooks/{notebook_id}")
async def update_notebook(notebook_id: str, request: UpdateNotebookRequest):
    """
    Update notebook information

    Args:
        notebook_id: Notebook ID
        request: Update request

    Returns:
        Updated notebook information
    """
    try:
        notebook = notebook_manager.update_notebook(
            notebook_id=notebook_id,
            name=request.name,
            description=request.description,
            color=request.color,
            icon=request.icon,
        )
        if not notebook:
            raise HTTPException(status_code=404, detail="Notebook not found")
        return {"success": True, "notebook": notebook}
    except HTTPException:
        raise
    except NotebookCorruptedError as exc:
        raise _unreadable(exc)
    except Exception as e:
        raise HTTPException(status_code=500, detail=str(e))


@router.delete("/notebooks/{notebook_id}")
async def delete_notebook(notebook_id: str):
    """
    Delete notebook

    Args:
        notebook_id: Notebook ID

    Returns:
        Deletion result
    """
    try:
        success = notebook_manager.delete_notebook(notebook_id)
        if not success:
            raise HTTPException(status_code=404, detail="Notebook not found")
        return {"success": True, "message": "Notebook deleted successfully"}
    except HTTPException:
        raise
    except NotebookCorruptedError as exc:
        raise _unreadable(exc)
    except Exception as e:
        raise HTTPException(status_code=500, detail=str(e))


@router.post("/notebooks/actions/add-record")
async def add_record(request: AddRecordRequest):
    """
    Add record to notebook

    Args:
        request: Add record request

    Returns:
        Addition result
    """
    try:
        summary = await _build_record_summary(request)
        result = notebook_manager.add_record(
            notebook_ids=request.notebook_ids,
            record_type=request.record_type,
            title=request.title,
            summary=summary,
            user_query=request.user_query,
            output=request.output,
            metadata=request.metadata,
            kb_name=request.kb_name,
        )
        return {
            "success": True,
            "summary": summary,
            "record": result["record"],
            "added_to_notebooks": result["added_to_notebooks"],
        }
    except NotebookCorruptedError as exc:
        raise _unreadable(exc)
    except Exception as e:
        raise HTTPException(status_code=500, detail=str(e))


@router.post("/notebooks/actions/add-record-with-summary")
async def add_record_with_summary(request: AddRecordRequest):
    """Add record to notebook and stream generated summary."""
    return StreamingResponse(
        _stream_add_record_with_summary(request),
        media_type="text/event-stream",
        headers={"Cache-Control": "no-cache", "X-Accel-Buffering": "no"},
    )


@router.delete("/notebooks/{notebook_id}/records/{record_id}")
async def remove_record(notebook_id: str, record_id: str):
    """
    Remove record from notebook

    Args:
        notebook_id: Notebook ID
        record_id: Record ID

    Returns:
        Deletion result
    """
    try:
        success = notebook_manager.remove_record(notebook_id, record_id)
        if not success:
            raise HTTPException(status_code=404, detail="Record not found")
        return {"success": True, "message": "Record removed successfully"}
    except HTTPException:
        raise
    except NotebookCorruptedError as exc:
        raise _unreadable(exc)
    except Exception as e:
        raise HTTPException(status_code=500, detail=str(e))


@router.get("/notebooks/records/{record_id}/location")
async def locate_record(record_id: str, notebook_id: str = ""):
    """Resolve a source citation after a collection move, within the active workspace."""
    location = notebook_manager.locate_record(record_id, notebook_id)
    if location is None:
        raise HTTPException(status_code=404, detail="Favorite not found")
    return {"notebook_id": location, "record_id": record_id}


@router.put("/notebooks/{notebook_id}/records/{record_id}")
async def update_record(notebook_id: str, record_id: str, request: UpdateRecordRequest):
    """Update an existing notebook record in place."""
    try:
        # Forward only what the client actually sent. Passing every field
        # unconditionally would hand `kb_name=None` to the service on every
        # request and clear the record's knowledge-base link as a side effect
        # of renaming it; the service's sentinel default only works if an
        # omitted field never reaches it.
        changes = request.model_dump(exclude_unset=True)
        if "output" in changes or "user_query" in changes:
            raise HTTPException(
                status_code=400,
                detail="Favorites preserve their original content. Add this record to a note to edit it.",
            )
        if not changes:
            raise HTTPException(status_code=400, detail="No fields to update")
        updated = notebook_manager.update_record(
            notebook_id=notebook_id,
            record_id=record_id,
            **changes,
        )
        if not updated:
            raise HTTPException(status_code=404, detail="Record not found")
        return {"success": True, "record": updated}
    except HTTPException:
        raise
    except NotebookCorruptedError as exc:
        raise _unreadable(exc)
    except Exception as e:
        raise HTTPException(status_code=500, detail=str(e))


@router.post("/notebooks/{notebook_id}/records/{record_id}/actions/copy")
async def copy_record(notebook_id: str, record_id: str, request: MoveRecordRequest):
    """Duplicate a record into another notebook under a fresh id."""
    try:
        copied = notebook_manager.copy_record(notebook_id, record_id, request.target_notebook_id)
        if not copied:
            raise HTTPException(status_code=404, detail="Record or target notebook not found")
        return {"success": True, "record": copied}
    except HTTPException:
        raise
    except NotebookCorruptedError as exc:
        raise _unreadable(exc)
    except Exception as e:
        raise HTTPException(status_code=500, detail=str(e))


@router.post("/notebooks/{notebook_id}/records/{record_id}/actions/move")
async def move_record(notebook_id: str, record_id: str, request: MoveRecordRequest):
    """Move a record from this notebook into another one."""
    try:
        moved = notebook_manager.move_record(notebook_id, record_id, request.target_notebook_id)
        if not moved:
            raise HTTPException(status_code=404, detail="Record or target notebook not found")
        return {"success": True, "record": moved}
    except HTTPException:
        raise
    except NotebookCorruptedError as exc:
        raise _unreadable(exc)
    except ValueError as exc:
        raise HTTPException(status_code=409, detail=str(exc))
    except Exception as e:
        raise HTTPException(status_code=500, detail=str(e))


@router.get("/notebooks/{notebook_id}/export", response_class=PlainTextResponse)
async def export_notebook(notebook_id: str):
    """Render the whole notebook as a single Markdown document."""
    try:
        markdown = notebook_manager.export_markdown(notebook_id)
        if markdown is None:
            raise HTTPException(status_code=404, detail="Notebook not found")
        return PlainTextResponse(
            markdown,
            media_type="text/markdown; charset=utf-8",
            headers={"Content-Disposition": f'attachment; filename="{notebook_id}.md"'},
        )
    except HTTPException:
        raise
    except NotebookCorruptedError as exc:
        raise _unreadable(exc)
    except Exception as e:
        raise HTTPException(status_code=500, detail=str(e))