Skip to content

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

2.9 KB
Raw Blame
"""Small data models for DeepTutor's optional multi-user layer."""

from __future__ import annotations

from dataclasses import dataclass, field
from pathlib import Path
from typing import Any, Literal

Role = Literal["admin", "teacher", "student", "user"]
AccountPreset = Literal["standard", "learner", "custom"]
ScopeKind = Literal["admin", "user"]

#: The single source of truth for valid role values. Every role-bearing
#: store/validator must accept exactly this set; authorization itself stays
#: least-privilege — only "admin" elevates.
VALID_ROLES: frozenset[str] = frozenset({"admin", "teacher", "student", "user"})


def normalize_role(value: str, default: str = "user") -> str:
    """Return ``value`` when it is a legal role, else ``default``.

    Least-privilege degrade: an unknown or corrupted role never keeps or
    gains privileges — it falls back to the given default (usually "user").
    """
    return value if value in VALID_ROLES else default


@dataclass(frozen=True, slots=True)
class UserRecord:
    id: str
    username: str
    role: Role = "user"
    created_at: str = ""
    disabled: bool = False
    # Avatar marker: "" (deterministic fallback), "icon:<name>:<color>" for a
    # picked icon, or "img:<version>" when the user uploaded an image (the
    # version is bumped on every upload so clients can cache-bust).
    avatar: str = ""

    # Account presets describe how a normal ``user`` is configured. They are
    # deliberately not a third identity role: admins remain admins and every
    # preset remains an ordinary account.
    preset: AccountPreset = "standard"

    def public_dict(self) -> dict[str, Any]:
        return {
            "id": self.id,
            "username": self.username,
            "role": self.role,
            "created_at": self.created_at,
            "disabled": self.disabled,
            "avatar": self.avatar,
            "preset": self.preset,
        }


@dataclass(frozen=True, slots=True)
class UserScope:
    kind: ScopeKind
    user_id: str
    root: Path

    @property
    def cache_key(self) -> str:
        return f"{self.kind}:{self.user_id}:{self.root.resolve()}"


@dataclass(frozen=True, slots=True)
class CurrentUser:
    id: str
    username: str
    role: Role
    scope: UserScope

    @property
    def is_admin(self) -> bool:
        return self.role == "admin"

    def public_dict(self) -> dict[str, Any]:
        return {
            "id": self.id,
            "username": self.username,
            "role": self.role,
            "is_admin": self.is_admin,
        }


@dataclass(frozen=True, slots=True)
class KnowledgeResource:
    id: str
    name: str
    base_dir: Path
    source: Literal["admin", "user"]
    assigned: bool = False
    read_only: bool = False
    metadata: dict[str, Any] = field(default_factory=dict)

    @property
    def physical_name(self) -> str:
        return self.name


LOCAL_ADMIN_ID = "local-admin"
LOCAL_ADMIN_USERNAME = "local"