Skip to content

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

14.3 KB
Raw Blame
"""Build the payload for the ``ask_user`` tool.

The tool packages one-to-four structured questions into a payload that
the chat pipeline interprets as a "pause this same turn until the user
answers" signal (``ToolResult.pause_for_user``). The frontend reads the
same payload off ``tool_result.metadata.ask_user`` and renders a card
that lets the user move between questions and submit answers in one
batch.

The schema is intentionally a list-of-questions even for the common
single-question case — every call wraps a list so the frontend has one
code path. Each option is a ``{label, description}`` pair (mirroring
Claude Code's ``AskUserQuestion``): the label is the short clickable
choice, the description explains what picking it means. Plain-string
options are still accepted at the LLM-facing boundary and normalised to
``{label, description: None}``. The legacy ``{question, options}``
argument shape is likewise accepted (``build_ask_user_payload``) and
normalised to a single-element list internally.
"""

from __future__ import annotations

from dataclasses import dataclass
from typing import Any

import json_repair

from deeptutor.utils.text_display import decode_escaped_unicode_for_display

MAX_QUESTIONS = 4
MAX_OPTIONS = 8
MAX_OPTION_CHARS = 120  # option label
MAX_OPTION_DESC_CHARS = 200
MAX_HEADER_CHARS = 16
MAX_QUESTION_CHARS = 800
MAX_INTRO_CHARS = 400
MAX_PLACEHOLDER_CHARS = 120

# Labels the model sometimes adds as its own catch-all option. The card
# already renders a free-form "Other" row whenever ``allow_free_text``
# is on, so a model-supplied duplicate is dropped.
_REDUNDANT_OTHER_LABELS = frozenset({"other", "其他", "其它"})


@dataclass(frozen=True)
class AskUserOption:
    """One clickable choice: short label + optional explanation."""

    label: str
    description: str | None = None

    def to_dict(self) -> dict[str, Any]:
        return {"label": self.label, "description": self.description}


@dataclass(frozen=True)
class AskUserQuestion:
    """A single question rendered as one tab on the ask_user card."""

    id: str
    prompt: str
    options: tuple[AskUserOption, ...] = ()
    header: str | None = None
    multi_select: bool = False
    allow_free_text: bool = True
    placeholder: str | None = None

    def to_dict(self) -> dict[str, Any]:
        return {
            "id": self.id,
            "prompt": self.prompt,
            "header": self.header,
            "multi_select": self.multi_select,
            "options": [o.to_dict() for o in self.options],
            "allow_free_text": self.allow_free_text,
            "placeholder": self.placeholder,
        }


@dataclass(frozen=True)
class AskUserPayload:
    """Structured payload that travels alongside the tool result.

    Mirrored on the frontend by ``AskUserOptions.tsx`` which reads the
    same field names off ``tool_result.metadata.ask_user``.
    """

    questions: tuple[AskUserQuestion, ...]
    intro: str | None = None

    def to_dict(self) -> dict[str, Any]:
        return {
            "intro": self.intro,
            "questions": [q.to_dict() for q in self.questions],
        }

    @property
    def question_ids(self) -> tuple[str, ...]:
        return tuple(q.id for q in self.questions)


def build_ask_user_payload(
    *,
    questions: Any = None,
    intro: Any = None,
    # Legacy single-question shape — auto-normalised into ``questions``.
    question: Any = None,
    options: Any = None,
) -> tuple[AskUserPayload | None, str | None]:
    """Validate + normalise the LLM-provided arguments.

    Accepts either the v2 ``{questions: [...], intro?}`` shape or the
    legacy ``{question, options?}`` shape (which is wrapped into a
    one-element list). Returns ``(payload, None)`` on success, or
    ``(None, error_message)`` if arguments cannot be honoured — errors
    propagate back to the LLM as a tool failure rather than raising.
    """
    raw_questions = _coerce_questions(questions, question, options)
    if isinstance(raw_questions, str):
        return None, raw_questions
    if not raw_questions:
        return None, "`questions` must contain at least one question."
    if len(raw_questions) > MAX_QUESTIONS:
        raw_questions = raw_questions[:MAX_QUESTIONS]

    normalised: list[AskUserQuestion] = []
    used_ids: set[str] = set()
    for idx, raw in enumerate(raw_questions):
        # Same guard the preview uses. A provider that truncates its tool
        # arguments mid-key leaves ``json_repair`` closing the fragment as a
        # *list* (``["labe"]``), and the dispatched call rendered that as a
        # real, pickable ``['labe']`` choice — an answer the model never
        # wrote. Dropping it costs an option the payload never finished.
        q_or_err = _build_question(_drop_half_written_options(raw), idx, used_ids)
        if isinstance(q_or_err, str):
            return None, q_or_err
        normalised.append(q_or_err)
        used_ids.add(q_or_err.id)

    intro_text: str | None = None
    if intro is not None:
        intro_text = _coerce_string(intro).strip() or None
        if intro_text and len(intro_text) > MAX_INTRO_CHARS:
            intro_text = intro_text[:MAX_INTRO_CHARS].rstrip() + "…"

    return AskUserPayload(questions=tuple(normalised), intro=intro_text), None


def _coerce_questions(questions: Any, question: Any, options: Any) -> list[Any] | str:
    if questions is not None:
        if not isinstance(questions, (list, tuple)):
            return "`questions` must be an array."
        return list(questions)
    if question is not None:
        # Legacy single-question shape.
        return [{"prompt": question, "options": options}]
    return []


def build_ask_user_preview(raw_arguments: str) -> dict[str, Any] | None:
    """Draw what an ``ask_user`` call looks like so far, mid-stream.

    The model writes this tool's arguments as one JSON object, and a card
    with three explained options is several seconds of generation. Nothing
    used to leave the backend until that object was closed, so the reader
    watched a silent gap and then had a whole card land at once. This turns
    the partial argument text into the same payload shape the finished call
    produces, so the card can be drawn as it is written.

    Deliberately best-effort: ``json_repair`` closes the truncated string /
    object / array the model is still in the middle of, questions that do
    not have a prompt yet are skipped rather than rejected, and any input it
    cannot make sense of returns ``None`` (the round simply keeps waiting).
    The result is a *preview* — the dispatched call is still parsed from the
    complete arguments by the ordinary path, so nothing here can change what
    the tool actually runs.
    """
    text = (raw_arguments or "").strip()
    if not text:
        return None
    try:
        data = json_repair.loads(text)
    except Exception:
        return None
    if not isinstance(data, dict):
        return None

    raw_questions = data.get("questions")
    if raw_questions is None and data.get("question") is not None:
        raw_questions = [{"prompt": data.get("question"), "options": data.get("options")}]
    questions: list[dict[str, Any]] = []
    used_ids: set[str] = set()
    if isinstance(raw_questions, (list, tuple)):
        for idx, raw in enumerate(list(raw_questions)[:MAX_QUESTIONS]):
            built = _build_question(_drop_half_written_options(raw), idx, used_ids)
            if isinstance(built, str):
                # Not enough of this question has arrived to draw it yet.
                continue
            used_ids.add(built.id)
            questions.append(built.to_dict())

    intro_text: str | None = None
    intro = data.get("intro")
    if intro is not None:
        intro_text = _coerce_string(intro).strip() or None
        if intro_text and len(intro_text) > MAX_INTRO_CHARS:
            intro_text = intro_text[:MAX_INTRO_CHARS].rstrip() + "…"

    # An intro on its own is worth showing: it is the first thing the model
    # writes, so it puts the card on screen while the options are still
    # being typed into it.
    if not intro_text and not questions:
        return None
    return {"intro": intro_text, "questions": questions}


def _drop_half_written_options(raw: Any) -> Any:
    """Strip the options ``json_repair`` invented from an unfinished key.

    An object whose key is still being typed (``{"labe``) is closed as a
    *list* — ``["labe"]`` — which the ordinary option normaliser would
    stringify into a visible ``['labe']`` choice for one frame. Real options
    are objects (``{label, description}``) or, from older payloads, plain
    strings; anything else at this position is an artefact of repairing a
    truncated stream and is dropped until the model finishes writing it.
    """
    if not isinstance(raw, dict):
        return raw
    options = raw.get("options")
    if not isinstance(options, (list, tuple)):
        return raw
    kept = [opt for opt in options if isinstance(opt, (dict, str))]
    if len(kept) == len(options):
        return raw
    return {**raw, "options": kept}


def _option_match_key(label: str) -> str:
    """Compare labels like ``mastery_quiz`` compares option bodies."""
    return "".join(label.split()).casefold()


def _build_question(raw: Any, idx: int, used_ids: set[str]) -> AskUserQuestion | str:
    if not isinstance(raw, dict):
        return f"Question #{idx + 1} must be an object."

    # ``prompt`` is the canonical field; accept ``question`` as alias
    # for forgiveness toward older LLM prompts.
    prompt_raw = raw.get("prompt")
    if prompt_raw is None:
        prompt_raw = raw.get("question")
    prompt = _coerce_string(prompt_raw).strip()
    if not prompt:
        return f"Question #{idx + 1}: `prompt` must be a non-empty string."
    if len(prompt) > MAX_QUESTION_CHARS:
        prompt = prompt[:MAX_QUESTION_CHARS].rstrip() + "…"

    allow_free_text = raw.get("allow_free_text")
    allow_free_text = True if allow_free_text is None else bool(allow_free_text)

    options_raw = raw.get("options")
    options: tuple[AskUserOption, ...] = ()
    if options_raw is not None:
        if not isinstance(options_raw, (list, tuple)):
            return f"Question #{idx + 1}: `options` must be an array."
        cleaned: list[AskUserOption] = []
        seen_labels: set[str] = set()
        seen_bodies: set[str] = set()
        for opt in options_raw:
            normalised = _build_option(opt)
            if normalised is None:
                continue
            # The card auto-renders an "Other" free-text row; drop a
            # model-supplied duplicate so the user never sees two.
            match_key = _option_match_key(normalised.label)
            if allow_free_text and match_key in _REDUNDANT_OTHER_LABELS:
                continue
            # Two labels that differ only by whitespace or case render as the
            # same choice, so keep the first rather than shipping an
            # unanswerable card (#1409).
            if match_key in seen_labels:
                continue
            # Two options whose visible text matches once whitespace and case
            # are folded leave the learner nothing to pick between — the same
            # duplicate-body rule the mastery quiz contract enforces at
            # registration (#1409). An option with no body *is* its label, so
            # label-only cards are governed by label uniqueness alone.
            body = (normalised.description or "").strip()
            if body:
                body_key = " ".join(body.split()).casefold()
                if body_key in seen_bodies:
                    continue
                seen_bodies.add(body_key)
            seen_labels.add(match_key)
            cleaned.append(normalised)
            if len(cleaned) >= MAX_OPTIONS:
                break
        options = tuple(cleaned)

    # ``multi_select`` is canonical; accept camelCase ``multiSelect``
    # since models trained on Claude Code's tool emit that spelling.
    multi_select_raw = raw.get("multi_select")
    if multi_select_raw is None:
        multi_select_raw = raw.get("multiSelect")
    multi_select = bool(multi_select_raw)

    header_raw = raw.get("header")
    header: str | None = None
    if header_raw is not None:
        header = _coerce_string(header_raw).strip() or None
        if header and len(header) > MAX_HEADER_CHARS:
            header = header[:MAX_HEADER_CHARS].rstrip()

    placeholder_raw = raw.get("placeholder")
    placeholder: str | None = None
    if placeholder_raw is not None:
        placeholder = _coerce_string(placeholder_raw).strip() or None
        if placeholder and len(placeholder) > MAX_PLACEHOLDER_CHARS:
            placeholder = placeholder[:MAX_PLACEHOLDER_CHARS].rstrip() + "…"

    qid = _coerce_string(raw.get("id")).strip()
    if not qid:
        qid = f"q{idx + 1}"
    # Disambiguate duplicate ids deterministically rather than rejecting.
    if qid in used_ids:
        suffix = 2
        while f"{qid}_{suffix}" in used_ids:
            suffix += 1
        qid = f"{qid}_{suffix}"

    return AskUserQuestion(
        id=qid,
        prompt=prompt,
        options=options,
        header=header,
        multi_select=multi_select,
        allow_free_text=allow_free_text,
        placeholder=placeholder,
    )


def _build_option(raw: Any) -> AskUserOption | None:
    """Normalise one option: ``{label, description?}`` dict or plain string."""
    if isinstance(raw, dict):
        label = _coerce_string(raw.get("label")).strip()
        description = _coerce_string(raw.get("description")).strip() or None
    else:
        label = _coerce_string(raw).strip()
        description = None
    if not label:
        return None
    if len(label) > MAX_OPTION_CHARS:
        label = label[:MAX_OPTION_CHARS].rstrip() + "…"
    if description and len(description) > MAX_OPTION_DESC_CHARS:
        description = description[:MAX_OPTION_DESC_CHARS].rstrip() + "…"
    return AskUserOption(label=label, description=description)


def _coerce_string(value: Any) -> str:
    if value is None:
        return ""
    if isinstance(value, str):
        raw = value
    else:
        raw = str(value)
    return decode_escaped_unicode_for_display(raw)


__all__ = [
    "AskUserOption",
    "AskUserPayload",
    "AskUserQuestion",
    "MAX_HEADER_CHARS",
    "MAX_INTRO_CHARS",
    "MAX_OPTION_CHARS",
    "MAX_OPTION_DESC_CHARS",
    "MAX_OPTIONS",
    "MAX_PLACEHOLDER_CHARS",
    "MAX_QUESTION_CHARS",
    "MAX_QUESTIONS",
    "build_ask_user_payload",
    "build_ask_user_preview",
]