Skip to content

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

9.8 KB
Raw Blame
"""Stable application-layer facade for DeepTutor entry points."""

from __future__ import annotations

from dataclasses import asdict, dataclass
from functools import wraps
import inspect
import json
from typing import Any, AsyncIterator

from .container import get_application_container
from .contracts import TurnRequest


def _in_app_workspace(method):
    from deeptutor.services.workspace.activity import data_activity
    from deeptutor.services.workspace.models import WorkspaceError

    def validate(scope):
        if scope.archived and method.__name__ in {
            "rename_session",
            "delete_session",
            "create_notebook",
            "add_record",
            "update_record",
            "remove_record",
        }:
            raise WorkspaceError("Restore this workspace before changing its data.")

    if inspect.iscoroutinefunction(method):

        @wraps(method)
        async def call(self, *args, **kwargs):
            with self._workspace_context() as scope, data_activity():
                validate(scope)
                return await method(self, *args, **kwargs)
    else:

        @wraps(method)
        def call(self, *args, **kwargs):
            with self._workspace_context() as scope, data_activity():
                validate(scope)
                return method(self, *args, **kwargs)

    return call


@dataclass(slots=True)
class CapabilityAvailability:
    """Availability result for optional capabilities."""

    name: str
    available: bool
    install_hint: str = ""


class DeepTutorApp:
    """Facade around runtime, session, notebook, and capability contracts."""

    def __init__(self, *, workspace_id: str | None = None) -> None:
        self.workspace_id = workspace_id
        self._turn_workspaces: dict[str, str] = {}
        self.container = get_application_container()
        self.turns = self.container.turns
        self.capabilities = self.container.capability_registry

    def _workspace_context(self):
        from deeptutor.services.workspace.context import current_workspace_id, workspace_context

        return workspace_context(
            self.workspace_id if self.workspace_id is not None else current_workspace_id()
        )

    @property
    def notebooks(self):
        from deeptutor.modules.catalog import require_module

        require_module("notebook")
        from deeptutor.services.notebook import get_notebook_manager

        with self._workspace_context():
            return get_notebook_manager()

    def resolve_capability(self, value: str | None) -> str:
        requested = str(value or "chat").strip() or "chat"
        manifests = self.capabilities.get_manifests()
        for manifest in manifests:
            if manifest["name"] == requested:
                return requested
            aliases = {str(alias).strip() for alias in manifest.get("cli_aliases", [])}
            if requested in aliases:
                return str(manifest["name"])
        available = ", ".join(sorted(manifest["name"] for manifest in manifests))
        raise ValueError(f"Unknown capability `{requested}`. Available: {available}")

    def get_capability_contracts(self) -> list[dict[str, Any]]:
        contracts = []
        for manifest in self.capabilities.get_manifests():
            contracts.append(
                {
                    **manifest,
                    "availability": asdict(self.get_capability_availability(manifest["name"])),
                }
            )
        return contracts

    def get_capability_contract(self, value: str) -> dict[str, Any]:
        resolved = self.resolve_capability(value)
        for manifest in self.capabilities.get_manifests():
            if manifest["name"] == resolved:
                return {
                    **manifest,
                    "availability": asdict(self.get_capability_availability(resolved)),
                }
        raise ValueError(f"Capability not found: {resolved}")

    def get_capability_availability(self, capability: str) -> CapabilityAvailability:
        resolved = self.resolve_capability(capability)
        from deeptutor.modules.catalog import contribution_owner, module_statuses

        owner = contribution_owner("capabilities", resolved)
        status = next(row for row in module_statuses() if row["id"] == owner)
        return CapabilityAvailability(
            name=resolved,
            available=status["ready"],
            install_hint="; ".join(status["issues"]) if not status["ready"] else "",
        )

    async def start_turn(
        self, request: TurnRequest | dict[str, Any]
    ) -> tuple[dict[str, Any], dict[str, Any]]:
        if isinstance(request, dict):
            request = TurnRequest(**request)
        await self.container.start()
        resolved_capability = self.resolve_capability(request.capability)
        from deeptutor.services.workspace.context import current_workspace_id, workspace_context

        workspace_id = (
            request.workspace_id
            if "workspace_id" in request.model_fields_set
            else self.workspace_id
        )
        if workspace_id is None:
            workspace_id = current_workspace_id()
        with workspace_context(workspace_id):
            result = await self.turns.start_turn(
                {
                    **request.to_payload(),
                    "capability": resolved_capability,
                    "workspace_id": workspace_id,
                }
            )
        self._turn_workspaces[result[1]["id"]] = workspace_id
        return result

    async def stream_turn(self, turn_id: str, after_seq: int = 0) -> AsyncIterator[dict[str, Any]]:
        await self.container.start()
        from deeptutor.services.workspace.context import current_workspace_id, workspace_context

        with workspace_context(
            self._turn_workspaces.get(
                turn_id,
                self.workspace_id if self.workspace_id is not None else current_workspace_id(),
            )
        ):
            async for item in self.turns.subscribe_turn(turn_id, after_seq=after_seq):
                yield item

    async def cancel_turn(self, turn_id: str) -> bool:
        await self.container.start()
        from deeptutor.services.workspace.context import current_workspace_id, workspace_context

        with workspace_context(
            self._turn_workspaces.get(
                turn_id,
                self.workspace_id if self.workspace_id is not None else current_workspace_id(),
            )
        ):
            return await self.turns.cancel_turn(turn_id)

    async def submit_user_reply(
        self,
        turn_id: str,
        text: str | None = None,
        *,
        answers: list[dict[str, Any]] | None = None,
    ) -> bool:
        """Deliver the user's reply to a turn paused on ``ask_user``."""
        await self.container.start()
        from deeptutor.services.workspace.context import workspace_context

        with (
            workspace_context(self._turn_workspaces[turn_id])
            if turn_id in self._turn_workspaces
            else self._workspace_context()
        ):
            return await self.turns.submit_user_reply(turn_id, text=text, answers=answers)

    @_in_app_workspace
    async def regenerate_last_turn(
        self,
        session_id: str,
        overrides: dict[str, Any] | None = None,
    ) -> tuple[dict[str, Any], dict[str, Any]]:
        await self.container.start()
        return await self.turns.regenerate_last_turn(session_id, overrides=overrides)

    @_in_app_workspace
    async def list_sessions(self, limit: int = 50, offset: int = 0) -> list[dict[str, Any]]:
        await self.container.start()
        return await self.turns.list_sessions(limit=limit, offset=offset)

    @_in_app_workspace
    async def get_session(self, session_id: str) -> dict[str, Any] | None:
        await self.container.start()
        return await self.turns.get_session(session_id)

    @_in_app_workspace
    async def rename_session(self, session_id: str, title: str) -> bool:
        await self.container.start()
        return await self.turns.rename_session(session_id, title)

    @_in_app_workspace
    async def delete_session(self, session_id: str) -> bool:
        await self.container.start()
        return await self.turns.delete_session(session_id)

    @_in_app_workspace
    async def get_active_turn(self, session_id: str) -> dict[str, Any] | None:
        await self.container.start()
        return await self.turns.check_active_turn(session_id)

    @_in_app_workspace
    def list_notebooks(self) -> list[dict[str, Any]]:
        return self.notebooks.list_notebooks()

    @_in_app_workspace
    def create_notebook(
        self,
        name: str,
        description: str = "",
        *,
        color: str = "#3B82F6",
        icon: str = "book",
    ) -> dict[str, Any]:
        return self.notebooks.create_notebook(
            name=name,
            description=description,
            color=color,
            icon=icon,
        )

    @_in_app_workspace
    def get_notebook(self, notebook_id: str) -> dict[str, Any] | None:
        return self.notebooks.get_notebook(notebook_id)

    @_in_app_workspace
    def add_record(self, **kwargs: Any) -> dict[str, Any]:
        return self.notebooks.add_record(**kwargs)

    @_in_app_workspace
    def update_record(
        self, notebook_id: str, record_id: str, **kwargs: Any
    ) -> dict[str, Any] | None:
        return self.notebooks.update_record(notebook_id, record_id, **kwargs)

    @_in_app_workspace
    def remove_record(self, notebook_id: str, record_id: str) -> bool:
        return self.notebooks.remove_record(notebook_id, record_id)

    @_in_app_workspace
    def get_records_by_references(
        self, notebook_references: list[dict[str, Any]]
    ) -> list[dict[str, Any]]:
        return self.notebooks.get_records_by_references(notebook_references)


def dumps_json(value: Any) -> str:
    return json.dumps(value, ensure_ascii=False, indent=2, default=str)