deeptutor-server 1.7.0__py3-none-any.whl

deeptutor/api/routers/file_preview.py

@@ -0,0 +1,205 @@
+"""Authenticated, same-origin Office document preview as a paginated PDF."""
+
+from __future__ import annotations
+
+import asyncio
+from contextlib import nullcontext
+from pathlib import Path
+import re
+from urllib.parse import parse_qs, unquote, urlsplit
+
+from fastapi import APIRouter, File, HTTPException, Request, UploadFile
+from fastapi.responses import Response
+
+from deeptutor.api.utils.http_headers import content_disposition
+from deeptutor.multi_user.paths import get_current_path_service
+from deeptutor.services.office_preview import (
+    MAX_OFFICE_BYTES,
+    OFFICE_SUFFIXES,
+    OfficePreviewConversionFailed,
+    OfficePreviewInvalid,
+    OfficePreviewTimeout,
+    OfficePreviewUnavailable,
+    render_office_pdf,
+)
+from deeptutor.services.workspace.context import workspace_context
+from deeptutor.services.workspace.models import WorkspaceError
+
+router = APIRouter()
+
+
+def _source_path(source: str, request: Request) -> tuple[Path, str, Path]:
+    """Resolve only local URLs using their existing authorization boundaries."""
+    if len(source) > 8192:
+        raise HTTPException(status_code=400, detail="Invalid preview source")
+    parsed = urlsplit(source)
+    if parsed.scheme or parsed.netloc or parsed.fragment or not parsed.path.startswith("/"):
+        raise HTTPException(status_code=400, detail="Preview source must be a local file URL")
+    query = parse_qs(parsed.query, keep_blank_values=True)
+    if any(
+        name not in {"dt_workspace", "workspace", "resource_library"} or len(values) != 1
+        for name, values in query.items()
+    ):
+        raise HTTPException(status_code=400, detail="Invalid preview source query")
+    pinned_scope = query.get("dt_workspace", [None])[0]
+    legacy_scope = query.get("workspace", [None])[0]
+    if pinned_scope is not None and legacy_scope is not None and pinned_scope != legacy_scope:
+        raise HTTPException(status_code=400, detail="Conflicting workspace scopes")
+    inner_scope = pinned_scope if pinned_scope is not None else legacy_scope
+    outer_scopes = request.query_params.getlist("dt_workspace")
+    if len(outer_scopes) > 1:
+        raise HTTPException(status_code=400, detail="Conflicting workspace scopes")
+    outer_scope = outer_scopes[0] if outer_scopes else request.headers.get("x-deeptutor-workspace")
+    if inner_scope is not None and outer_scope is not None and inner_scope != outer_scope:
+        raise HTTPException(status_code=400, detail="Conflicting workspace scopes")
+    library = query.get("resource_library", ["false"])[0]
+    if library not in {"true", "false"}:
+        raise HTTPException(status_code=400, detail="Invalid preview source query")
+    if library == "true" and not parsed.path.startswith("/api/knowledge-bases/"):
+        raise HTTPException(status_code=400, detail="Invalid preview source query")
+
+    # The authentication dependency selects the outer request scope. Historic
+    # file URLs may carry only an inner scope, so restore that scope here after
+    # auth; workspace_context validates that it belongs to the caller.
+    if library == "true":
+        # The canonical knowledge-base route selects the account library,
+        # independent of the currently selected content workspace.
+        context = workspace_context("")
+    elif inner_scope is not None and outer_scope is None:
+        context = workspace_context(inner_scope)
+    else:
+        context = nullcontext()
+    canonical_path = unquote(parsed.path)
+    _assert_surface("reading" if canonical_path.startswith("/api/knowledge-bases/") else "chat")
+    try:
+        with context:
+            target, filename = _resolve_authorized_file(canonical_path, query)
+            return target, filename, _cache_dir()
+    except WorkspaceError as exc:
+        raise HTTPException(status_code=404, detail="Preview source not found") from exc
+
+
+def _resolve_authorized_file(path: str, query: dict[str, list[str]]) -> tuple[Path, str]:
+    if match := re.fullmatch(r"/files/attachments/([^/]+)/([^/]+)/([^/]+)", path):
+        from deeptutor.services.storage import LocalDiskAttachmentStore, get_attachment_store
+
+        store = get_attachment_store()
+        if not isinstance(store, LocalDiskAttachmentStore):
+            raise HTTPException(status_code=501, detail="Attachment backend not servable")
+        target = store.resolve_path(
+            session_id=match.group(1), attachment_id=match.group(2), filename=match.group(3)
+        )
+        if target is None:
+            raise HTTPException(status_code=404, detail="Preview source not found")
+        return target, match.group(3)
+
+    if path.startswith("/files/outputs/"):
+        from deeptutor.api.routers.outputs import (
+            _request_path_service,
+            _resolve_output,
+            _resolve_partner_output,
+        )
+
+        relative = path.removeprefix("/files/outputs/")
+        try:
+            target = _resolve_output(_request_path_service(), relative)
+        except HTTPException:
+            target = _resolve_partner_output(relative)
+            if target is None:
+                raise HTTPException(status_code=404, detail="Preview source not found")
+        return target, target.name
+
+    if match := re.fullmatch(r"/files/workspace-items/([^/]+)/([^/]+)", path):
+        from deeptutor.api.routers.workspace import _resolve_partner_item
+        from deeptutor.services.workspace import get_content_workspace_service
+
+        try:
+            target, item = get_content_workspace_service().resolve_published_item(*match.groups())
+        except WorkspaceError:
+            resolved = _resolve_partner_item(*match.groups())
+            if resolved is None:
+                raise HTTPException(status_code=404, detail="Preview source not found")
+            target, item = resolved
+        return target, item.filename
+
+    if match := re.fullmatch(r"/api/knowledge-bases/([^/]+)/files/(.+)", path):
+        from deeptutor.api.routers.knowledge import _resolve_kb_raw_file_or_404
+        from deeptutor.services.workspace.knowledge import library_request
+
+        library = query.get("resource_library", ["false"])[0]
+        token = library_request.set(library == "true")
+        try:
+            target = _resolve_kb_raw_file_or_404(match.group(1), match.group(2))
+        finally:
+            library_request.reset(token)
+        return target, target.name
+
+    raise HTTPException(status_code=400, detail="Unsupported preview source URL")
+
+
+def _cache_dir() -> Path:
+    return get_current_path_service().get_user_root() / "cache" / "office_previews"
+
+
+def _read_bounded(path: Path) -> bytes:
+    try:
+        with path.open("rb") as source:
+            return source.read(MAX_OFFICE_BYTES + 1)
+    except OSError as exc:
+        raise HTTPException(status_code=404, detail="Preview source not found") from exc
+
+
+def _assert_surface(surface: str) -> None:
+    from deeptutor.multi_user.learning_access import assert_learning_surface
+
+    try:
+        assert_learning_surface(surface)
+    except PermissionError as exc:
+        raise HTTPException(status_code=403, detail=str(exc)) from exc
+
+
+async def _pdf_response(data: bytes, filename: str, cache_dir: Path) -> Response:
+    if Path(filename).suffix.lower() not in OFFICE_SUFFIXES:
+        raise HTTPException(status_code=415, detail="Unsupported Office file type")
+    try:
+        pdf = await render_office_pdf(data, filename, cache_dir)
+    except OfficePreviewInvalid as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+    except OfficePreviewUnavailable as exc:
+        raise HTTPException(status_code=503, detail=str(exc)) from exc
+    except OfficePreviewTimeout as exc:
+        raise HTTPException(status_code=504, detail=str(exc)) from exc
+    except OfficePreviewConversionFailed as exc:
+        raise HTTPException(status_code=502, detail=str(exc)) from exc
+    pdf_name = "".join(char if char.isprintable() else "_" for char in Path(filename).stem) + ".pdf"
+    return Response(
+        content=pdf,
+        media_type="application/pdf",
+        headers={
+            "Content-Disposition": content_disposition(pdf_name),
+            "Cache-Control": "private, no-store",
+            "X-Content-Type-Options": "nosniff",
+        },
+    )
+
+
+@router.get("/pdf")
+async def preview_office_source(source: str, request: Request) -> Response:
+    """Render a file URL that this same authenticated user could open."""
+    path, filename, cache_dir = _source_path(source, request)
+    data = await asyncio.to_thread(_read_bounded, path)
+    return await _pdf_response(data, filename, cache_dir)
+
+
+@router.post("/pdf")
+async def preview_office_upload(file: UploadFile = File(...)) -> Response:
+    """Render a bounded pending Blob/data attachment that has no file URL."""
+    _assert_surface("chat")
+    filename = file.filename or ""
+    if Path(filename).suffix.lower() not in OFFICE_SUFFIXES:
+        raise HTTPException(status_code=415, detail="Unsupported Office file type")
+    try:
+        data = await file.read(MAX_OFFICE_BYTES + 1)
+    finally:
+        await file.close()
+    return await _pdf_response(data, filename, _cache_dir())

deeptutor/api/routers/imports.py

@@ -0,0 +1,146 @@
+"""
+Import chat histories from ChatGPT exports and external coding CLIs (Claude
+Code, Codex) into the user's learning space as normal, re-openable sessions.
+
+Reading the user's local ``~/.claude`` / ``~/.codex`` or ChatGPT export happens
+in the browser — those files live on the user's machine, not the server. The
+browser normalizes each conversation to the small JSON shape below and POSTs
+it here; this router only validates and persists. Imported sessions
+share the session tables with native chats (so the chat loop can re-open and
+continue them) but carry an ``imported_`` id prefix that keeps them in their
+own Space category. Re-importing the same folder is idempotent (dedup by id).
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from fastapi import APIRouter, HTTPException, Query
+from pydantic import BaseModel, Field, field_validator
+
+from deeptutor.services.session import (
+    get_sqlite_session_store,
+    make_imported_session_id,
+)
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter()
+
+# Browser adapters only emit these; reject anything else so a malformed payload
+# can never seed an unsupported provider category.
+_ALLOWED_SOURCES = {"chatgpt", "claude_code", "codex"}
+
+# Defensive ceilings — a single import request should never grow unbounded.
+_MAX_SESSIONS_PER_REQUEST = 1000
+_MAX_MESSAGES_PER_SESSION = 10000
+
+
+class ImportedMessage(BaseModel):
+    role: str = Field(..., pattern="^(user|assistant)$")
+    content: str = ""
+    created_at: float | None = None
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class ImportedSession(BaseModel):
+    external_id: str = Field(..., min_length=1, max_length=256)
+    title: str = ""
+    source_cwd: str = ""
+    created_at: float
+    updated_at: float
+    messages: list[ImportedMessage] = Field(default_factory=list)
+
+
+class ChatHistoryImportRequest(BaseModel):
+    source: str = Field(..., min_length=1)
+    # All sessions in one request belong to one agent (a named, scoped slice of
+    # a source folder). Empty when the client hasn't adopted the agent model yet
+    # — the backend stays backwards-compatible by simply omitting attribution.
+    agent_id: str = Field(default="", max_length=256)
+    agent_name: str = Field(default="", max_length=256)
+    sessions: list[ImportedSession] = Field(default_factory=list)
+
+    @field_validator("source")
+    @classmethod
+    def _normalize_source(cls, value: str) -> str:
+        normalized = (value or "").strip().lower()
+        if normalized not in _ALLOWED_SOURCES:
+            raise ValueError(f"Unsupported import source: {value!r}")
+        return normalized
+
+
+@router.post("/chat-history")
+async def import_chat_history(payload: ChatHistoryImportRequest) -> dict[str, Any]:
+    if not payload.sessions:
+        raise HTTPException(status_code=400, detail="No sessions to import")
+    if len(payload.sessions) > _MAX_SESSIONS_PER_REQUEST:
+        raise HTTPException(
+            status_code=413,
+            detail=f"Too many sessions in one request (max {_MAX_SESSIONS_PER_REQUEST})",
+        )
+
+    store = get_sqlite_session_store()
+    imported = 0
+    skipped = 0
+    results: list[dict[str, Any]] = []
+
+    for incoming in payload.sessions:
+        # Drop content-less rows (e.g. tool-only turns the adapter could not
+        # reduce to text) so the transcript stays a clean human conversation.
+        messages = [m for m in incoming.messages if (m.content or "").strip()]
+        if not messages:
+            skipped += 1
+            results.append(
+                {"external_id": incoming.external_id, "imported": False, "reason": "empty"}
+            )
+            continue
+        if len(messages) > _MAX_MESSAGES_PER_SESSION:
+            messages = messages[:_MAX_MESSAGES_PER_SESSION]
+
+        session_id = make_imported_session_id(payload.source, incoming.external_id)
+        import_meta: dict[str, Any] = {
+            "source": payload.source,
+            "source_cwd": incoming.source_cwd,
+            "external_id": incoming.external_id,
+        }
+        if payload.agent_id:
+            import_meta["agent_id"] = payload.agent_id
+        if payload.agent_name:
+            import_meta["agent_name"] = payload.agent_name
+        preferences = {"import": import_meta}
+        try:
+            result = await store.import_session(
+                session_id,
+                incoming.title,
+                incoming.created_at,
+                incoming.updated_at,
+                preferences,
+                [m.model_dump() for m in messages],
+            )
+        except Exception:
+            logger.exception("failed to import session %s", incoming.external_id)
+            skipped += 1
+            results.append(
+                {"external_id": incoming.external_id, "imported": False, "reason": "error"}
+            )
+            continue
+
+        if result.get("imported"):
+            imported += 1
+        else:
+            skipped += 1
+        results.append({"external_id": incoming.external_id, **result})
+
+    return {"imported": imported, "skipped": skipped, "sessions": results}
+
+
+@router.get("/chat-history")
+async def list_imported_chat_history(
+    limit: int = Query(default=50, ge=1, le=200),
+    offset: int = Query(default=0, ge=0),
+) -> dict[str, Any]:
+    store = get_sqlite_session_store()
+    sessions = await store.list_imported_sessions(limit=limit, offset=offset)
+    return {"sessions": sessions}

deeptutor/api/routers/learning_journal.py

@@ -0,0 +1,18 @@
+"""Read-only view of the workspace's conversational learning journal."""
+
+from fastapi import APIRouter, HTTPException
+
+from deeptutor.services.learning_journal import get_learning_journal_store
+
+router = APIRouter()
+
+
+@router.get("")
+def overview():
+    try:
+        return get_learning_journal_store().overview()
+    except (OSError, ValueError) as exc:
+        raise HTTPException(
+            status_code=409,
+            detail="Learning journal could not be read. Its original file has been preserved.",
+        ) from exc

deeptutor/api/routers/mcp_settings.py

@@ -0,0 +1,133 @@
+"""
+MCP Settings API Router
+=======================
+
+Manage the deployment-global MCP server registry: read/update the config,
+inspect live connection status, and probe a server before saving.
+
+Mounted at ``/api/settings/mcp``. Admin-gated: the registry is
+deployment-global state, and a stdio server's ``command`` runs on the host
+as the app user — letting non-admins edit it would be privilege escalation.
+Per-user MCP access is granted through the multi-user grant whitelist
+(``mcp_tools``), not by sharing this registry.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import APIRouter, Depends, HTTPException
+from pydantic import BaseModel, Field, ValidationError
+
+from deeptutor.api.routers.auth import require_admin
+from deeptutor.services.i18n import t
+from deeptutor.services.mcp import (
+    MCPConfig,
+    MCPServerConfig,
+    get_mcp_manager,
+    load_mcp_config,
+    save_mcp_config,
+    validate_mcp_url,
+)
+from deeptutor.services.mcp.manager import probe_server
+
+router = APIRouter(dependencies=[Depends(require_admin)])
+
+
+class MCPSettingsPayload(BaseModel):
+    servers: dict[str, MCPServerConfig] = Field(default_factory=dict)
+
+
+def _validate_servers(config: MCPConfig) -> None:
+    for name, cfg in config.servers.items():
+        transport = cfg.resolved_type()
+        if transport is None:
+            raise HTTPException(
+                status_code=400,
+                detail=t("mcp.configure_command_or_url", name=name),
+            )
+        if transport in {"sse", "streamableHttp"}:
+            ok, error = validate_mcp_url(cfg.url)
+            if not ok:
+                raise HTTPException(
+                    status_code=400, detail=t("mcp.server_error", name=name, error=error)
+                )
+
+
+@router.get("")
+async def get_mcp_settings() -> dict[str, Any]:
+    config = load_mcp_config()
+    manager = get_mcp_manager()
+    await manager.ensure_started()
+    return {
+        "servers": {name: cfg.model_dump(mode="json") for name, cfg in config.servers.items()},
+        "status": manager.status(),
+    }
+
+
+@router.put("")
+async def update_mcp_settings(payload: MCPSettingsPayload) -> dict[str, Any]:
+    try:
+        config = MCPConfig(servers=payload.servers)
+    except (ValidationError, ValueError) as exc:
+        raise HTTPException(status_code=400, detail=str(exc))
+    _validate_servers(config)
+    save_mcp_config(config)
+    manager = get_mcp_manager()
+    await manager.reload()
+    return {"status": manager.status()}
+
+
+@router.put("/servers/{name}")
+async def upsert_mcp_server(name: str, cfg: MCPServerConfig) -> dict[str, Any]:
+    """Upsert one server, leaving every other entry byte-identical.
+
+    The whole-map ``PUT`` above cannot express "change this one": a client has to
+    send back everything it read, so it silently drops any field it does not
+    model (a hand-written ``disabled_tools`` blocklist) and overwrites whatever
+    a second administrator saved in between.
+    """
+    config = load_mcp_config()
+    servers = dict(config.servers)
+    servers[name] = cfg
+    try:
+        updated = MCPConfig(servers=servers)
+    except (ValidationError, ValueError) as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+    _validate_servers(MCPConfig(servers={name: cfg}))
+    save_mcp_config(updated)
+    manager = get_mcp_manager()
+    await manager.reload()
+    return {
+        "servers": {key: value.model_dump(mode="json") for key, value in updated.servers.items()},
+        "status": manager.status(),
+    }
+
+
+@router.delete("/servers/{name}")
+async def delete_mcp_server(name: str) -> dict[str, Any]:
+    config = load_mcp_config()
+    servers = {key: value for key, value in config.servers.items() if key != name}
+    updated = MCPConfig(servers=servers)
+    save_mcp_config(updated)
+    manager = get_mcp_manager()
+    await manager.reload()
+    return {
+        "servers": {key: value.model_dump(mode="json") for key, value in updated.servers.items()},
+        "status": manager.status(),
+    }
+
+
+@router.post("/test")
+async def test_mcp_server(cfg: MCPServerConfig) -> dict[str, Any]:
+    transport = cfg.resolved_type()
+    if transport is None:
+        raise HTTPException(
+            status_code=400,
+            detail=t("mcp.configure_before_testing"),
+        )
+    if transport in {"sse", "streamableHttp"}:
+        ok, error = validate_mcp_url(cfg.url)
+        if not ok:
+            raise HTTPException(status_code=400, detail=error)
+    return await probe_server(cfg)

deeptutor/api/routers/modules.py

@@ -0,0 +1,12 @@
+"""Read-only deployment inventory; code mutations run in the offline CLI."""
+
+from fastapi import APIRouter
+
+from deeptutor.modules.catalog import module_statuses
+
+router = APIRouter()
+
+
+@router.get("")
+def list_modules():
+    return {"modules": module_statuses()}