deeptutor-server 1.7.0__py3-none-any.whl

deeptutor/api/routers/capabilities.py

@@ -0,0 +1,44 @@
+"""What this deployment's capability registry actually resolved at boot.
+
+Chat surfaces address a capability by name — ``deep_research``,
+``visualize``, and so on — but not every name ships in this
+repository. Capabilities also arrive from plugins, and the Whisper practice
+room is one of those: its pages live here while ``whisper_visitor`` /
+``whisper_trainee`` are served by an out-of-tree capability. A page had no way
+to ask whether the backend could honour the name it was about to send, so a
+stock install offered the entry, sent the turn anyway, and the learner got
+``Unknown capability: whisper_visitor. Available: [...]`` (#963).
+
+This endpoint exposes the backend-owned identity, manifest, and validated
+configuration schema for every turn capability. Presentation remains a
+frontend concern.
+"""
+
+from __future__ import annotations
+
+from fastapi import APIRouter
+
+router = APIRouter()
+
+
+@router.get("/registered")
+async def list_registered_capabilities() -> dict[str, list[dict[str, object]]]:
+    """Describe every turn capability the deployment can execute."""
+    from deeptutor.runtime.registry.capability_registry import get_capability_registry
+
+    descriptors: list[dict[str, object]] = []
+    for item in get_capability_registry().get_manifests():
+        manifest = {
+            key: value for key, value in item.items() if key not in {"request_schema", "kind"}
+        }
+        descriptors.append(
+            {
+                "id": str(item["name"]),
+                "kind": str(item.get("kind") or "turn"),
+                "available": True,
+                "manifest": manifest,
+                "config_schema": item.get("request_schema") or {},
+            }
+        )
+    descriptors.sort(key=lambda item: str(item["id"]))
+    return {"capabilities": descriptors}

deeptutor/api/routers/capabilities_settings.py

@@ -0,0 +1,38 @@
+"""Capabilities settings endpoint.
+
+Surfaces the per-capability tunables (temperature, max_tokens, stage
+budgets, iteration limits) currently scattered across
+``data/user/settings/agents.yaml`` and ``data/user/settings/main.yaml``.
+
+Mirrors the pattern used by ``/api/memory/settings``:
+
+* ``GET  /settings``  → returns the full schema with defaults merged in.
+* ``PUT  /settings``  → merges payload back into both YAML files and
+                        returns the new state.
+
+Validation lives in
+:mod:`deeptutor.services.config.capabilities_settings` so the API stays
+a thin transport layer.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import APIRouter
+
+router = APIRouter()
+
+
+@router.get("/settings")
+async def get_capabilities_settings_endpoint() -> dict[str, Any]:
+    from deeptutor.services.config.capabilities_settings import capabilities_settings_dict
+
+    return capabilities_settings_dict()
+
+
+@router.put("/settings")
+async def put_capabilities_settings(payload: dict[str, Any]) -> dict[str, Any]:
+    from deeptutor.services.config.capabilities_settings import save_capabilities_settings
+
+    return save_capabilities_settings(payload)

deeptutor/api/routers/dashboard.py

@@ -0,0 +1,292 @@
+"""Dashboard API — what the home screen shows before a conversation starts.
+
+Recent activity comes from the unified SQLite session store; the starter lines
+come from :mod:`deeptutor.services.suggestions`, which reads memory.
+
+Route order matters here: ``/{entry_id}`` at the bottom of this module matches
+any single segment, so every literal path must be declared above it or it will
+never be reached.
+"""
+
+import logging
+from typing import Any
+
+from fastapi import APIRouter, HTTPException
+
+from deeptutor.services.session import get_session_store
+
+logger = logging.getLogger(__name__)
+router = APIRouter()
+
+
+async def _workspace_rows(reader) -> list[dict[str, Any]]:
+    """Read one index in the request's workspace, naming it on every row.
+
+    Switching workspace is switching stores: these indexes never merge another
+    workspace's content. The name stays on the row so follow-up requests and
+    links remain pinned to the store the row came from.
+    """
+    from deeptutor.services.workspace import get_content_workspace_service
+    from deeptutor.services.workspace.context import current_workspace_id
+
+    workspace_id = current_workspace_id()
+    names = {
+        row["workspace_id"]: row["display_name"]
+        for row in get_content_workspace_service().list_workspaces()
+    }
+    return [
+        {
+            **row,
+            "content_workspace_id": workspace_id,
+            "content_workspace_name": names.get(workspace_id, ""),
+        }
+        for row in await reader()
+    ]
+
+
+@router.get("/recent")
+async def get_recent_activities(limit: int = 50, type: str | None = None):
+    store = get_session_store()
+    sessions = await store.list_sessions(limit=limit, offset=0)
+    activities: list[dict[str, Any]] = []
+
+    for session in sessions:
+        capability = str(session.get("capability") or "chat")
+        activity_type = capability.replace("deep_", "")
+        if type is not None and activity_type != type:
+            continue
+        activities.append(
+            {
+                "id": session.get("session_id"),
+                "type": activity_type,
+                "capability": capability,
+                "title": session.get("title", "Untitled"),
+                "timestamp": session.get("updated_at", session.get("created_at", 0)),
+                "summary": (session.get("last_message") or "")[:160],
+                "session_ref": f"sessions/{session.get('session_id')}",
+                "message_count": session.get("message_count", 0),
+                "status": session.get("status", "idle"),
+                "active_turn_id": session.get("active_turn_id"),
+            }
+        )
+
+    return activities[:limit]
+
+
+@router.get("/suggestions")
+async def get_starter_suggestions():
+    """The three starting points for the home composer.
+
+    Returns immediately, even when the set is stale — regeneration happens
+    behind the response. An empty ``suggestions`` list means there is nothing
+    in memory to ground a suggestion in, and the client renders nothing.
+
+    No language parameter: the output language is the learner's own
+    model-output setting, resolved server-side. See
+    :mod:`deeptutor.services.suggestions`.
+    """
+    from deeptutor.services.suggestions import get_suggestions
+
+    return await get_suggestions()
+
+
+@router.post("/suggestions/refresh")
+async def refresh_starter_suggestions():
+    """Generate a new set now. Backs the reroll control.
+
+    Synchronous, unlike the read: a human clicked and is waiting for a
+    different set.
+    """
+    from deeptutor.services.suggestions import refresh_suggestions
+
+    result = await refresh_suggestions()
+    return {**result.to_dict(), "stale": False}
+
+
+@router.get("/learning-index")
+async def get_learning_index():
+    """Read-only entry points into the request's workspace."""
+    from deeptutor.modules.catalog import module_enabled
+    from deeptutor.multi_user.learning_access import learning_surface_allowed
+
+    async def books():
+        from deeptutor.api.routers.book import list_books
+
+        return (await list_books())["books"]
+
+    async def mastery():
+        from deeptutor.api.routers.mastery_path import list_topics
+
+        return (await list_topics())["topics"]
+
+    async def reading():
+        from deeptutor.api.routers.reading import list_workspaces
+
+        return (await list_workspaces(search=""))["workspaces"]
+
+    async def watching():
+        from deeptutor.services.session.organization import list_all_sessions_snapshot
+
+        rows = await list_all_sessions_snapshot(get_session_store())
+        return [
+            row
+            for row in rows
+            if not (row.get("preferences") or {}).get("archived")
+            and (
+                (row.get("preferences") or {}).get("workspace_mode") == "immersive_watching"
+                or (row.get("preferences") or {}).get("capability") == "immersive_watching"
+            )
+        ]
+
+    async def practice():
+        from deeptutor.services.session import get_sqlite_session_store
+
+        return await get_sqlite_session_store().list_notebook_navigation()
+
+    result = {}
+    failed = []
+    for kind, surface, reader in (
+        ("books", "books", books),
+        ("mastery", "chat", mastery),
+        ("reading", "reading", reading),
+        ("watching", "reading", watching),
+        ("practice", "chat", practice),
+    ):
+        # Calling a route function directly bypasses its HTTP dependencies.
+        # Never load a source that the learner could not open individually.
+        result[kind] = []
+        owner = {"watching": "reading", "practice": "notebook"}.get(kind, kind)
+        if not module_enabled(owner) or not learning_surface_allowed(surface):
+            continue
+        try:
+            result[kind] = await _workspace_rows(reader)
+        except Exception:
+            logger.warning("Workspace learning index unavailable: %s", kind, exc_info=True)
+            failed.append(kind)
+    return {"sources": result, "failed": failed}
+
+
+@router.get("/source-library/{kind}")
+async def get_source_library(kind: str):
+    """Source indexes of the request's workspace, for the topic and book pickers."""
+
+    async def read():
+        if kind == "notebooks":
+            from deeptutor.services.notebook import notebook_manager
+
+            return notebook_manager.list_notebooks()
+        if kind == "chats":
+            from deeptutor.services.session.organization import list_all_sessions_snapshot
+
+            return await list_all_sessions_snapshot(get_session_store())
+        if kind == "drafts":
+            from deeptutor.api.routers.co_writer import list_documents
+
+            return [row.model_dump() for row in (await list_documents())["documents"]]
+        raise HTTPException(404, "Unknown source library")
+
+    if kind == "knowledge":
+        # The workspace's own knowledge bases plus the ones assigned to it.
+        from deeptutor.multi_user.knowledge_access import list_visible_knowledge_bases
+        from deeptutor.services.workspace.context import current_workspace_id
+        from deeptutor.services.workspace.knowledge import parse_kb_id
+
+        items = []
+        for row in list_visible_knowledge_bases():
+            # Own bases carry a local id; assigned ones name their home store.
+            parsed = parse_kb_id(str(row.get("id") or ""))
+            origin = parsed[0] if parsed is not None else current_workspace_id()
+            items.append(
+                {
+                    **row,
+                    "content_workspace_id": origin,
+                    "content_workspace_name": row.get("provenance_label", ""),
+                }
+            )
+        return {"items": items, "unavailable_workspaces": []}
+    if kind in {"books", "practice"}:
+        return await get_learning_library(kind)
+    if kind not in {"notebooks", "chats", "drafts"}:
+        raise HTTPException(404, "Unknown source library")
+    return {"items": await _workspace_rows(read), "unavailable_workspaces": []}
+
+
+@router.get("/learning-library/{kind}")
+async def get_learning_library(kind: str):
+    """The request's workspace library of one kind."""
+    can_create = True
+
+    async def read():
+        nonlocal can_create
+        if kind == "books":
+            from deeptutor.api.routers.book import list_books
+
+            result = await list_books()
+            can_create = result["can_create"]
+            return result["books"]
+        if kind == "mastery":
+            from deeptutor.api.routers.mastery_path import list_topics
+
+            return (await list_topics())["topics"]
+        if kind == "reading":
+            from deeptutor.api.routers.reading import list_workspaces
+
+            return (await list_workspaces(search=""))["workspaces"]
+        if kind == "materials":
+            from deeptutor.api.routers.reading import list_library_materials
+
+            return (await list_library_materials(search="", status=None, library_filter="all"))[
+                "materials"
+            ]
+        if kind == "practice":
+            from deeptutor.services.session import get_sqlite_session_store
+
+            store = get_sqlite_session_store()
+            items = []
+            offset = 0
+            while True:
+                result = await store.list_notebook_entries(limit=200, offset=offset)
+                items.extend(result["items"])
+                offset += len(result["items"])
+                if not result["items"] or offset >= result["total"]:
+                    return items
+        from deeptutor.services.session.organization import list_all_sessions_snapshot
+
+        rows = await list_all_sessions_snapshot(get_session_store())
+        return [
+            row
+            for row in rows
+            if not (row.get("preferences") or {}).get("archived")
+            and (
+                (row.get("preferences") or {}).get("workspace_mode") == "immersive_watching"
+                or (row.get("preferences") or {}).get("capability") == "immersive_watching"
+            )
+        ]
+
+    if kind not in {"books", "mastery", "reading", "materials", "practice", "watching"}:
+        raise HTTPException(status_code=404, detail="Unknown learning library")
+    rows = await _workspace_rows(read)
+    return {"items": rows, "unavailable_workspaces": [], "can_create": can_create}
+
+
+@router.get("/{entry_id}")
+async def get_activity_entry(entry_id: str):
+    store = get_session_store()
+    session = await store.get_session_with_messages(entry_id)
+    if session is None:
+        raise HTTPException(status_code=404, detail="Entry not found")
+
+    capability = str(session.get("capability") or "chat")
+    return {
+        "id": session.get("session_id"),
+        "type": capability.replace("deep_", ""),
+        "capability": capability,
+        "title": session.get("title"),
+        "timestamp": session.get("updated_at", session.get("created_at")),
+        "content": {
+            "messages": session.get("messages", []),
+            "active_turns": session.get("active_turns", []),
+            "status": session.get("status", "idle"),
+            "summary": session.get("compressed_summary", ""),
+        },
+    }

deeptutor/api/routers/file_library.py

@@ -0,0 +1,169 @@
+"""HTTP endpoints for the Persistent File Library (issue #1437).
+
+URL shape::
+
+    GET   /files/library/              — list files (newest first)
+    POST  /files/library/              — upload a file (multipart)
+    GET   /files/library/search        — search by filename (query param: q)
+    GET   /files/library/{file_id}     — get one entry
+    GET   /files/library/{file_id}/download  — download the file
+    DELETE /files/library/{file_id}     — soft-delete a file
+    POST  /files/library/{file_id}/restore    — restore a soft-deleted file
+
+The library is scoped to the authenticated user (via ``require_auth``) so
+each user sees only their own files.
+"""
+
+from __future__ import annotations
+
+import logging
+import mimetypes
+
+from fastapi import (
+    APIRouter,
+    Depends,
+    File,
+    Form,
+    HTTPException,
+    Query,
+)
+from fastapi.responses import FileResponse
+
+from deeptutor.api.routers.auth import require_auth
+from deeptutor.services.auth import TokenPayload
+from deeptutor.services.storage import file_library as _fl
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter()
+
+
+def _get_store():
+    """Resolve the store at call time so tests can monkey-patch ``_fl``."""
+    return _fl.get_file_library_store()
+
+
+def _mime_type(filename: str) -> str:
+    mt, _ = mimetypes.guess_type(filename)
+    return mt or "application/octet-stream"
+
+
+# ── endpoints ──────────────────────────────────────────────────────────────
+
+
+@router.get("/", operation_id="library_list")
+async def list_library_files(
+    limit: int = Query(default=50, ge=1, le=200),
+    offset: int = Query(default=0, ge=0),
+    _auth: TokenPayload = Depends(require_auth),
+) -> list[dict]:
+    """List active library entries, newest first."""
+    return await _get_store().list_files(limit=limit, offset=offset)
+
+
+@router.post("/", operation_id="library_add")
+async def add_library_file(
+    filename: str = File(..., description="Original filename"),
+    mime_type: str = Form(""),
+    file: bytes = File(..., description="Raw file bytes"),
+    _auth: TokenPayload = Depends(require_auth),
+) -> dict:
+    """Add a file to the library.
+
+    The request must be ``multipart/form-data`` with a ``file`` field containing
+    the raw bytes.  If a file with the same SHA-256 content hash already exists
+    in the library, returns the existing entry (deduplication).
+    """
+    entry = await _get_store().add_file(
+        data=file,
+        filename=filename,
+        mime_type=mime_type,
+    )
+    return entry
+
+
+@router.get("/search", operation_id="library_search")
+async def search_library_files(
+    q: str = Query(..., min_length=1, max_length=200),
+    _auth: TokenPayload = Depends(require_auth),
+) -> list[dict]:
+    """Search library entries by filename (case-insensitive substring)."""
+    return await _get_store().search_files(query=q)
+
+
+@router.get("/{file_id}", operation_id="library_get")
+async def get_library_file(
+    file_id: str,
+    _auth: TokenPayload = Depends(require_auth),
+) -> dict:
+    """Get a single library entry by id (includes soft-deleted)."""
+    entry = await _get_store().get_file(file_id)
+    if entry is None:
+        raise HTTPException(status_code=404, detail="File not found")
+    return entry
+
+
+@router.get("/{file_id}/download", operation_id="library_download")
+async def download_library_file(
+    file_id: str,
+    _auth: TokenPayload = Depends(require_auth),
+) -> FileResponse:
+    """Download a library file by id."""
+    store = _get_store()
+    entry = await store.get_file(file_id)
+    if entry is None or entry.get("is_deleted"):
+        raise HTTPException(status_code=404, detail="File not found")
+
+    path = store.resolve_path(file_id)
+    if path is None or not path.is_file():
+        raise HTTPException(status_code=404, detail="File not found on disk")
+
+    media_type = _mime_type(entry["filename"])
+    return FileResponse(
+        path,
+        media_type=media_type,
+        filename=entry["filename"],
+        headers={
+            "Cache-Control": "private, max-age=31536000, immutable",
+            "X-Content-Type-Options": "nosniff",
+        },
+    )
+
+
+@router.head("/{file_id}/download", operation_id="library_download_head")
+async def download_library_file_head(
+    file_id: str,
+    _auth: TokenPayload = Depends(require_auth),
+) -> None:
+    """Check whether a library file exists (HEAD only)."""
+    store = _get_store()
+    entry = await store.get_file(file_id)
+    if entry is None or entry.get("is_deleted"):
+        raise HTTPException(status_code=404, detail="File not found")
+    path = store.resolve_path(file_id)
+    if path is None or not path.is_file():
+        raise HTTPException(status_code=404, detail="File not found on disk")
+
+
+@router.delete("/{file_id}", operation_id="library_delete")
+async def delete_library_file(
+    file_id: str,
+    _auth: TokenPayload = Depends(require_auth),
+) -> dict:
+    """Soft-delete a library file (sets is_deleted=1)."""
+    deleted = await _get_store().delete_file(file_id)
+    if not deleted:
+        raise HTTPException(status_code=404, detail="File not found")
+    return {"id": file_id, "deleted": True}
+
+
+@router.post("/{file_id}/restore", operation_id="library_restore")
+async def restore_library_file(
+    file_id: str,
+    _auth: TokenPayload = Depends(require_auth),
+) -> dict:
+    """Restore a soft-deleted library file."""
+    restored = await _get_store().restore_file(file_id)
+    if not restored:
+        raise HTTPException(status_code=404, detail="File not found")
+    return {"id": file_id, "restored": True}