Skip to content

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

10.9 KB
Raw Blame
"""Typed turn request value object shared by application and runtime layers."""

from __future__ import annotations

from typing import Any, Literal
import warnings

from pydantic import BaseModel, ConfigDict, Field, StrictStr, field_validator, model_validator

from deeptutor.core.response_languages import validate_reply_language_override

_LEGACY_RUNTIME_CONFIG_KEYS: dict[str, str] = {
    "_persist_user_message": "persist_user_message",
    "_regenerate": "regenerate",
    "_regenerated_from_message_id": "regenerated_from_message_id",
    "_superseded_turn_id": "superseded_turn_id",
    "followup_question_context": "followup_question_context",
    "selection_tutor_context": "selection_tutor_context",
    "subagent_consult_budget": "subagent_consult_budget",
    "consult_partner_id": "consult_partner_id",
    "partner_discussion_group_id": "partner_discussion_group_id",
    "answer_by": "answer_by",
    "auto_route": "auto_route",
}


class LLMSelection(BaseModel):
    model_config = ConfigDict(extra="forbid")

    profile_id: str
    model_id: str


class OutgoingAttachment(BaseModel):
    model_config = ConfigDict(extra="forbid")

    type: str
    url: str | None = None
    base64: str | None = None
    filename: str | None = None
    mime_type: str | None = None
    id: str | None = None


class NotebookReference(BaseModel):
    model_config = ConfigDict(extra="forbid")

    notebook_id: str
    record_ids: list[str] = Field(default_factory=list)


class BookReference(BaseModel):
    model_config = ConfigDict(extra="forbid")

    book_id: str
    page_ids: list[str] = Field(default_factory=list)


class ReadingReference(BaseModel):
    model_config = ConfigDict(extra="forbid")

    material_id: str
    revision: int = Field(ge=1)
    locators: list[int] = Field(default_factory=list)


class ReadingViewport(BaseModel):
    model_config = ConfigDict(extra="forbid")

    locator: int | None = Field(default=None, ge=0)
    selection: str | None = None
    # Playback position of a video material, reported by the reader on each turn.
    time_seconds: float | None = Field(default=None, ge=0)


class TimedMediaViewport(BaseModel):
    model_config = ConfigDict(extra="forbid")

    time_seconds: float = Field(ge=0)


class MasteryCardAnswer(BaseModel):
    """An answer submitted from a mastery question card.

    The card outlives the turn that posed it — posing a question ends that
    turn — so the answer arrives as the next turn's message. This says which
    question the message is answering, letting the runtime commit it to the
    engine before the tutor's first token instead of asking the model to
    recover the pairing from prose.
    """

    model_config = ConfigDict(extra="forbid")

    question_id: str = Field(min_length=1)
    text: str = Field(min_length=1)
    answers: dict[str, StrictStr] | None = Field(default=None, min_length=1, max_length=4)

    @field_validator("answers")
    @classmethod
    def validate_group_answers(cls, value: dict[str, str] | None) -> dict[str, str] | None:
        if value is not None:
            for question_id, answer in value.items():
                if not question_id.strip() or len(question_id) > 200:
                    raise ValueError("group answers require bounded nonempty question IDs")
                if not answer.strip() or len(answer) > 8000:
                    raise ValueError("group answers require bounded nonempty answer text")
        return value


class NoteGeneration(BaseModel):
    """The learning block on the open note page this turn fills in.

    Sent by the note companion when a block's own "Generate" runs. The server
    owns the instructions that follow from it, so the learner's message stays
    exactly what they see in the conversation.
    """

    model_config = ConfigDict(extra="forbid")

    block_id: str = Field(min_length=1, max_length=64, pattern=r"^[A-Za-z0-9_-]+$")
    kind: str = Field(default="", max_length=32)


class MasteryCardSkip(BaseModel):
    """A question the learner dropped instead of answering.

    The same shape of problem as :class:`MasteryCardAnswer`: the card outlives
    the turn that posed it, so "not this one" also arrives as the next turn's
    message. Naming the question is what keeps the runtime from abandoning
    whatever happens to be open by the time the turn starts.
    """

    model_config = ConfigDict(extra="forbid")

    question_id: str = Field(min_length=1)


MemoryReference = Literal["recent", "profile", "scope", "preferences", "summary"]


class TurnRequest(BaseModel):
    """Validated turn input; ``config`` contains capability options only.

    The model keeps the historical keyword construction style. Runtime-only
    keys nested in ``config`` are translated for one major version so older
    clients continue to work while receiving a deprecation warning.
    """

    model_config = ConfigDict(extra="forbid")

    content: str
    # Browser-minted causal identity for a newly submitted user row. A retry
    # can then distinguish its own persisted row from identical text sent in
    # another tab without relying on clocks or stale transcript baselines.
    client_submission_id: str | None = Field(default=None, min_length=1, max_length=100)
    capability: str | None = "chat"
    session_id: str | None = None
    tools: list[str] | None = None
    knowledge_bases: list[str] = Field(default_factory=list)
    language: str | None = None
    # Only an explicit session selector sets this. Omitted means keep the
    # conversation's override; null returns it to the account default.
    reply_language_override: str | None = None
    config: dict[str, Any] = Field(default_factory=dict)

    notebook_references: list[NotebookReference] = Field(default_factory=list)
    history_references: list[str] = Field(default_factory=list)
    partner_group_references: list[dict[str, Any]] = Field(default_factory=list)
    question_notebook_references: list[int] = Field(default_factory=list)
    book_references: list[BookReference] = Field(default_factory=list)
    reading_references: list[ReadingReference] = Field(default_factory=list)
    memory_references: list[MemoryReference] = Field(default_factory=list)
    attachments: list[OutgoingAttachment] = Field(default_factory=list)
    # Per-conversation narrowing of the workspace's skill and MCP selections.
    # Empty means inherit — everything the workspace allows — so a client that
    # never picks behaves exactly as it did before the pickers existed. A
    # non-empty list is intersected with the workspace allowlist, never added to
    # it: a conversation can narrow its own reach but never widen it.
    skills: list[str] = Field(default_factory=list)
    mcp: list[str] = Field(default_factory=list)

    persona: str | None = None
    llm_selection: LLMSelection | None = None
    workspace_mode: str | None = None
    # Content workspace ownership; omitted means inherit, null/empty means the general workspace.
    workspace_id: str | None = None
    mastery_path_id: str | None = None
    #: What this mastery conversation is for — "outline" | "study" | "review".
    #: Durable session state (see
    #: :mod:`deeptutor.capabilities.mastery.mode`); an absent value is
    #: read as the ordinary study session every mastery conversation was
    #: before kinds existed.
    mastery_session_mode: str | None = None
    mastery_path_lease_managed: bool = False
    mastery_answer: MasteryCardAnswer | None = None
    mastery_skip: MasteryCardSkip | None = None
    note_document_id: str | None = Field(default=None, pattern=r"^[0-9a-f]{8,32}$")
    note_generation: NoteGeneration | None = None
    reading_material_id: str | None = None
    reading_material_revision: int | None = Field(default=None, ge=1)
    reading_workspace_id: str | None = None
    reading_viewport: ReadingViewport | None = None
    timed_media_id: str | None = None
    timed_media_viewport: TimedMediaViewport | None = None
    parent_message_id: int | None = None

    # Runtime options are explicit and never passed to a capability schema.
    persist_user_message: bool = True
    regenerate: bool = False
    # A saved failed-turn Resend repeats the old request without changing the
    # conversation's current settings for future turns.
    preserve_session_preferences: bool = False
    # This turn runs in `capability` without making it the conversation's mode
    # (a reading "Quiz me" asks the quiz engine once; the next message is chat).
    capability_once: bool = False
    # SQLite message rowids are integers; PocketBase message record ids are
    # opaque strings. Preserve either form in the SESSION event for clients.
    regenerated_from_message_id: int | str | None = None
    superseded_turn_id: str | None = None
    followup_question_context: dict[str, Any] | None = None
    selection_tutor_context: dict[str, Any] | None = None
    subagent_consult_budget: int | None = Field(default=None, ge=0)
    consult_partner_id: str | None = None
    partner_discussion_group_id: str | None = None
    # Who answers this turn when it is not DeepTutor: ``partner:<id>`` or
    # ``subagent:<connection>``. The turn is handed over whole — see
    # ``deeptutor.capabilities.handoff``.
    answer_by: str | None = Field(default=None, pattern=r"^(partner|subagent):\S.*$")
    auto_route: bool | None = None

    @field_validator("reply_language_override")
    @classmethod
    def _validate_reply_language_override(cls, value: str | None) -> str | None:
        return validate_reply_language_override(value)

    @model_validator(mode="before")
    @classmethod
    def _translate_legacy_runtime_config(cls, value: Any) -> Any:
        if not isinstance(value, dict):
            return value
        result = dict(value)
        config = result.get("config")
        if config is None or not isinstance(config, dict):
            return result
        public_config = dict(config)
        translated: list[str] = []
        for legacy_key, field_name in _LEGACY_RUNTIME_CONFIG_KEYS.items():
            if legacy_key not in public_config:
                continue
            legacy_value = public_config.pop(legacy_key)
            if field_name not in result:
                result[field_name] = legacy_value
            translated.append(legacy_key)
        result["config"] = public_config
        if translated:
            warnings.warn(
                "Runtime turn options in config are deprecated; use explicit TurnRequest "
                f"fields instead ({', '.join(sorted(translated))})",
                DeprecationWarning,
                stacklevel=3,
            )
        return result

    def to_payload(self) -> dict[str, Any]:
        """Return an execution payload while preserving omitted-field semantics."""

        return self.model_dump(mode="python", exclude_unset=True)


__all__ = [
    "BookReference",
    "LLMSelection",
    "MasteryCardAnswer",
    "MasteryCardSkip",
    "MemoryReference",
    "NotebookReference",
    "OutgoingAttachment",
    "ReadingReference",
    "ReadingViewport",
    "TimedMediaViewport",
    "TurnRequest",
]