DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.
Python ai-agentsai-tutorclawbotcli-tooldeepresearchinteractive-learninglearningmulti-agent-systemsrag
/**
* Shared types for Quiz Generation (deep_question capability).
*/
import { decodeEscapedUnicodeForDisplay } from "./markdown-display";
import {
type NormalizedQuizQuestionType,
normalizeQuizQuestionType,
} from "./quiz-question-type";
export type DeepQuestionMode = "custom" | "mimic";
export interface DeepQuestionFormConfig {
mode: DeepQuestionMode;
topic: string;
num_questions: number;
difficulty: string;
/**
* Multi-select allowed-types whitelist. Empty list = "auto" (planner
* picks any type per question). When ≥1 type is selected, the planner
* is restricted to those types.
*/
question_types: NormalizedQuizQuestionType[];
/**
* Per-type quantity targets (sums to num_questions when non-empty).
* Only populated when ≥2 types are selected and the user has tweaked
* the ratio bar; empty means "distribute evenly across allowed types".
*/
per_type_counts: Partial<Record<NormalizedQuizQuestionType, number>>;
paper_path: string;
max_questions: number;
}
export const DEFAULT_QUIZ_CONFIG: DeepQuestionFormConfig = {
mode: "custom",
topic: "",
num_questions: 3,
difficulty: "auto",
question_types: [],
per_type_counts: {},
paper_path: "",
max_questions: 10,
};
export interface QuizQuestion {
question_id: string;
question: string;
question_type: NormalizedQuizQuestionType;
options?: Record<string, string>;
correct_answer: string;
explanation: string;
difficulty?: string;
concentration?: string;
knowledge_context?: string;
}
export interface QuizFollowupContext {
parent_quiz_session_id?: string;
question_id: string;
question: string;
question_type: QuizQuestion["question_type"];
options?: Record<string, string>;
correct_answer: string;
explanation: string;
difficulty?: string;
concentration?: string;
knowledge_context?: string;
user_answer?: string;
is_correct?: boolean;
/**
* Filenames of the images the learner attached as their answer. Image
* bytes ride on the first follow-up message as regular attachments so
* vision-capable models see them; the filenames here let the follow-up
* system prompt mention them explicitly so the LLM knows the attached
* images are the learner's answer, not unrelated context.
*/
user_answer_image_filenames?: string[];
/** Latest AI judgment text for this question, when one has been run. */
ai_judgment?: string;
}
/** Decode dense ``\\uXXXX`` runs on learner-facing quiz strings (#973 family). */
function decodeQuizText(value: string | undefined | null): string {
return decodeEscapedUnicodeForDisplay(String(value ?? ""));
}
function decodeQuizOptions(
options: Record<string, string> | undefined,
): Record<string, string> | undefined {
if (!options || typeof options !== "object") return undefined;
const out: Record<string, string> = {};
for (const [key, value] of Object.entries(options)) {
out[key] = decodeQuizText(value);
}
return out;
}
function buildQuizQuestionFromQa(qa: Record<string, unknown>): QuizQuestion {
return {
question_id: String(qa.question_id ?? ""),
question: decodeQuizText(qa.question as string | undefined | null),
question_type: normalizeQuizQuestionType(qa.question_type),
options: decodeQuizOptions(qa.options as Record<string, string> | undefined),
correct_answer: decodeQuizText(qa.correct_answer as string | undefined | null),
explanation: decodeQuizText(qa.explanation as string | undefined | null),
difficulty: qa.difficulty ? String(qa.difficulty) : undefined,
concentration: qa.concentration ? String(qa.concentration) : undefined,
knowledge_context:
qa.metadata &&
typeof qa.metadata === "object" &&
"knowledge_context" in qa.metadata &&
qa.metadata.knowledge_context
? decodeQuizText(String(qa.metadata.knowledge_context))
: undefined,
};
}
/**
* Extract QuizQuestion[] from per-question ``content`` events emitted live
* by the new ``QuestionPipeline`` while the quizzing phase is running.
*
* The backend tags each event with ``metadata.call_kind ===
* "quiz_question_emitted"`` and the structured ``qa_pair`` payload. We
* collect them, dedupe by ``question_id``, and order by
* ``question_index`` so QuizViewer can render each question the moment
* it lands — without waiting for the final ``result`` event.
*
* Returns ``null`` until at least one valid quiz event has arrived, so
* the caller can fall back to the legacy ``extractQuizQuestions`` shape
* for older (mimic) result envelopes.
*/
export function extractStreamingQuizQuestions(
events: Array<{
type?: string;
metadata?: Record<string, unknown> | undefined;
}>,
): QuizQuestion[] | null {
if (!Array.isArray(events) || events.length === 0) return null;
const byId = new Map<string, { idx: number; qa: QuizQuestion }>();
for (const event of events) {
if (event.type !== "content") continue;
const meta = (event.metadata ?? {}) as Record<string, unknown>;
if (meta.call_kind !== "quiz_question_emitted") continue;
const qa = meta.qa_pair as Record<string, unknown> | undefined;
if (!qa || typeof qa !== "object" || !qa.question) continue;
const idx = Number(meta.question_index);
const question = buildQuizQuestionFromQa(qa);
const key = question.question_id || String(idx);
byId.set(key, {
idx: Number.isFinite(idx) ? idx : byId.size,
qa: question,
});
}
if (byId.size === 0) return null;
return Array.from(byId.values())
.sort((a, b) => a.idx - b.idx)
.map((entry) => entry.qa);
}
/**
* Resolve the turn identity of a quiz message from its event stream.
*
* Quiz answer state is scoped per turn: the notebook unique key is
* ``(session_id, turn_id, question_id)`` and positional question ids
* (``q_1``..``q_N``) repeat across quizzes in one session. During
* generation the final ``result`` event hasn't landed yet, so the turn id
* must come from the streamed events themselves — every unified-WS event
* carries ``turn_id``. The ``result`` event stays authoritative when
* present so the settled/persisted path is unchanged (issues #487 / #677).
*
* Returns ``null`` only for legacy persisted turns whose events predate
* ``turn_id``; QuizViewer renders those cards local-only (no notebook
* reads or writes), so they can never inherit another turn's answers.
*/
export function extractQuizTurnId(
events: Array<{ type?: string; turn_id?: string }> | undefined,
): string | null {
if (!Array.isArray(events)) return null;
const result = events.find(
(event) => event.type === "result" && event.turn_id,
);
if (result?.turn_id) return result.turn_id;
return events.find((event) => event.turn_id)?.turn_id ?? null;
}
/**
* Extract QuizQuestion[] from the raw `result` event metadata returned by
* the deep_question capability.
*/
export function extractQuizQuestions(
resultMetadata: Record<string, unknown> | undefined,
): QuizQuestion[] | null {
if (!resultMetadata) return null;
const summary = resultMetadata.summary as Record<string, unknown> | undefined;
if (!summary) return null;
const results = summary.results as Array<Record<string, unknown>> | undefined;
if (!Array.isArray(results) || results.length === 0) return null;
const parsed: Array<QuizQuestion | null> = results.map((item) => {
const qa = (item.qa_pair ?? item) as Record<string, unknown>;
if (!qa.question) return null;
return buildQuizQuestionFromQa(qa);
});
return parsed.filter(
(question): question is QuizQuestion => question !== null,
);
}
export interface QuizFollowupExtras {
/** Filenames of the learner's image answers (bytes ride on first msg). */
userAnswerImageFilenames?: string[] | null;
/** Last AI-judgment text for this question, if the learner ran it. */
aiJudgment?: string | null;
}
export function buildQuizFollowupConfig(
question: QuizQuestion,
userAnswer: string,
isCorrect: boolean | null,
parentQuizSessionId?: string | null,
extras?: QuizFollowupExtras,
): Record<string, unknown> {
const filenames = (extras?.userAnswerImageFilenames ?? [])
.map((name) => (typeof name === "string" ? name.trim() : ""))
.filter((name) => name.length > 0);
const context: QuizFollowupContext = {
question_id: question.question_id,
question: question.question,
question_type: question.question_type,
options: question.options,
correct_answer: question.correct_answer,
explanation: question.explanation,
difficulty: question.difficulty,
concentration: question.concentration,
knowledge_context: question.knowledge_context,
user_answer: userAnswer || undefined,
is_correct: typeof isCorrect === "boolean" ? isCorrect : undefined,
parent_quiz_session_id: parentQuizSessionId || undefined,
user_answer_image_filenames: filenames.length > 0 ? filenames : undefined,
ai_judgment: extras?.aiJudgment?.trim() || undefined,
};
return {
followup_question_context: context,
};
}
function titleCase(value: string): string {
if (!value) return "";
return value.charAt(0).toUpperCase() + value.slice(1);
}
export const QUIZ_TYPE_LABEL_KEYS: Record<NormalizedQuizQuestionType, string> =
{
choice: "Multiple Choice",
concept: "Concept Question",
fill_in_blank: "Fill in the Blank",
short_answer: "Short Answer",
written: "Essay",
coding: "Coding",
};
/**
* One-line summary of the quiz form, shown next to the collapsed `Settings`
* chevron in the composer. Pass `translate` (`t` from `react-i18next`) so the
* summary follows the active UI language.
*/
export function summarizeQuizConfig(
cfg: DeepQuestionFormConfig,
translate?: (key: string) => string,
): string {
const tr = translate ?? ((s: string) => s);
if (cfg.mode === "mimic") {
const target = cfg.paper_path.trim() || tr("no paper");
return [
tr("Mimic Paper"),
target,
`${tr("Max")} ${cfg.max_questions}`,
].join(" · ");
}
const typeSummary =
cfg.question_types.length === 0
? tr("Auto")
: cfg.question_types.length === 1
? tr(QUIZ_TYPE_LABEL_KEYS[cfg.question_types[0]])
: `${cfg.question_types.length} ${tr("types")}`;
return [
tr("Custom"),
`${cfg.num_questions} ${tr("questions")}`,
tr(titleCase(cfg.difficulty || "auto")),
typeSummary,
].join(" · ");
}
/**
* Build the `config` payload to send over WebSocket for a quiz generation
* request.
*/
export function buildQuizWSConfig(
cfg: DeepQuestionFormConfig,
): Record<string, unknown> {
if (cfg.mode === "mimic") {
return {
mode: "mimic",
paper_path: cfg.paper_path.trim(),
max_questions: cfg.max_questions,
};
}
// Only forward per-type counts when >=2 types are selected AND the user
// actually populated counts that sum to num_questions. Otherwise let
// the backend distribute freely across the allowed set.
const countsValid =
cfg.question_types.length >= 2 &&
Object.keys(cfg.per_type_counts).length > 0 &&
Object.values(cfg.per_type_counts).reduce((sum, v) => sum + (v || 0), 0) ===
cfg.num_questions;
return {
mode: "custom",
num_questions: cfg.num_questions,
difficulty: cfg.difficulty === "auto" ? "" : cfg.difficulty,
question_types: cfg.question_types,
per_type_counts: countsValid ? cfg.per_type_counts : {},
};
}