@goscribe/server 1.6.0 → 1.7.0

package/dist/src/services/content/worksheet-content.service.js

@@ -0,0 +1,84 @@
+import { BaseService } from '../base.service.js';
+function parseObjectValue(value) {
+    if (!value)
+        return {};
+    if (typeof value === 'object') {
+        return value;
+    }
+    if (typeof value === 'string') {
+        try {
+            const parsed = JSON.parse(value);
+            return typeof parsed === 'object' && parsed ? parsed : {};
+        }
+        catch {
+            return {};
+        }
+    }
+    return {};
+}
+export function mergeWorksheetQuestionProgress(questions, progressRows) {
+    const progressByQuestionId = new Map(progressRows.map((row) => [row.worksheetQuestionId, row]));
+    return questions.map((question) => {
+        const progress = progressByQuestionId.get(question.id);
+        const existingMeta = parseObjectValue(question.meta);
+        if (!progress) {
+            return {
+                ...question,
+                meta: existingMeta,
+            };
+        }
+        const progressMeta = parseObjectValue(progress.meta);
+        return {
+            ...question,
+            meta: {
+                ...existingMeta,
+                completed: progress.modified,
+                userAnswer: progress.userAnswer,
+                completedAt: progress.completedAt,
+                userMarkScheme: progressMeta.userMarkScheme,
+            },
+        };
+    });
+}
+export function parseWorksheetGenerationContent(content) {
+    const parsedRoot = parseObjectValue(content);
+    let payload = parsedRoot;
+    if (typeof parsedRoot.last_response === 'string') {
+        const nested = parseObjectValue(parsedRoot.last_response);
+        if (Object.keys(nested).length > 0) {
+            payload = nested;
+        }
+    }
+    const rawProblems = payload.problems ?? payload.questions ?? payload;
+    const problems = Array.isArray(rawProblems)
+        ? rawProblems.map((problem) => (typeof problem === 'object' && problem ? problem : {}))
+        : [];
+    return {
+        problems,
+        title: typeof payload.title === 'string' ? payload.title : undefined,
+        description: typeof payload.description === 'string' ? payload.description : undefined,
+        estimatedTime: typeof payload.estimatedTime === 'string' ? payload.estimatedTime : undefined,
+    };
+}
+export function parseQuestionMeta(meta) {
+    return parseObjectValue(meta);
+}
+/**
+ * Class wrapper around the pure worksheet-content helpers so consumers can
+ * depend on a service the same way they depend on other domain services.
+ * The standalone function exports remain part of the public surface.
+ */
+export class WorksheetContentService extends BaseService {
+    constructor(db) {
+        super(db);
+    }
+    mergeProgress(questions, progress) {
+        return mergeWorksheetQuestionProgress(questions, progress);
+    }
+    parseGenerationContent(content) {
+        return parseWorksheetGenerationContent(content);
+    }
+    parseQuestionMeta(meta) {
+        return parseQuestionMeta(meta);
+    }
+}

package/dist/src/services/content/worksheet-content.service.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/services/content/worksheet-content.service.test.js

@@ -0,0 +1,69 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mergeWorksheetQuestionProgress, parseQuestionMeta, parseWorksheetGenerationContent, } from './worksheet-content.service.js';
+test('parseQuestionMeta: handles null and object inputs', () => {
+    assert.deepEqual(parseQuestionMeta(null), {});
+    assert.deepEqual(parseQuestionMeta({ markScheme: { points: [] } }), {
+        markScheme: { points: [] },
+    });
+});
+test('parseQuestionMeta: parses JSON strings', () => {
+    assert.deepEqual(parseQuestionMeta('{"options":["A","B"]}'), { options: ['A', 'B'] });
+});
+test('parseQuestionMeta: returns empty object on invalid JSON', () => {
+    assert.deepEqual(parseQuestionMeta('not json'), {});
+});
+test('mergeWorksheetQuestionProgress: merges per-user progress into question meta', () => {
+    const questions = [
+        { id: 'q1', meta: { options: ['A', 'B'] } },
+        { id: 'q2', meta: null },
+    ];
+    const progress = [
+        {
+            worksheetQuestionId: 'q1',
+            modified: true,
+            userAnswer: 'A',
+            completedAt: new Date('2024-01-01'),
+            meta: { userMarkScheme: { points: [] } },
+        },
+    ];
+    const merged = mergeWorksheetQuestionProgress(questions, progress);
+    assert.equal(merged[0].meta.options?.[0], 'A');
+    assert.equal(merged[0].meta.completed, true);
+    assert.equal(merged[0].meta.userAnswer, 'A');
+    assert.ok(merged[0].meta.userMarkScheme);
+    assert.equal(merged[1].meta.completed, undefined);
+});
+test('parseWorksheetGenerationContent: unwraps last_response strings', () => {
+    const content = JSON.stringify({
+        last_response: JSON.stringify({
+            title: 'Test Title',
+            description: 'A description',
+            estimatedTime: '15m',
+            problems: [{ question: 'What?' }],
+        }),
+    });
+    const parsed = parseWorksheetGenerationContent(content);
+    assert.equal(parsed.title, 'Test Title');
+    assert.equal(parsed.description, 'A description');
+    assert.equal(parsed.estimatedTime, '15m');
+    assert.equal(parsed.problems.length, 1);
+});
+test('parseWorksheetGenerationContent: accepts top-level problems', () => {
+    const content = JSON.stringify({
+        title: 'Plain',
+        problems: [{ question: 'Q1' }, { question: 'Q2' }],
+    });
+    const parsed = parseWorksheetGenerationContent(content);
+    assert.equal(parsed.title, 'Plain');
+    assert.equal(parsed.problems.length, 2);
+});
+test('parseWorksheetGenerationContent: falls back to questions array', () => {
+    const content = JSON.stringify({ questions: [{ question: 'Q' }] });
+    assert.equal(parseWorksheetGenerationContent(content).problems.length, 1);
+});
+test('parseWorksheetGenerationContent: returns empty problems on invalid content', () => {
+    const parsed = parseWorksheetGenerationContent('not json');
+    assert.deepEqual(parsed.problems, []);
+    assert.equal(parsed.title, undefined);
+});

package/dist/src/services/content/worksheet-generation.service.d.ts

@@ -0,0 +1,91 @@
+import { z } from 'zod';
+/** Persisted on Artifact.worksheetConfig and inside generatingMetadata while generating */
+export declare const worksheetModeSchema: z.ZodEnum<{
+    practice: "practice";
+    quiz: "quiz";
+}>;
+export type WorksheetMode = z.infer<typeof worksheetModeSchema>;
+export declare const worksheetDifficultyInputSchema: z.ZodEnum<{
+    easy: "easy";
+    medium: "medium";
+    hard: "hard";
+}>;
+export type WorksheetDifficultyInput = z.infer<typeof worksheetDifficultyInputSchema>;
+export declare const questionTypeSchema: z.ZodEnum<{
+    MULTIPLE_CHOICE: "MULTIPLE_CHOICE";
+    TEXT: "TEXT";
+    NUMERIC: "NUMERIC";
+    TRUE_FALSE: "TRUE_FALSE";
+    MATCHING: "MATCHING";
+    FILL_IN_THE_BLANK: "FILL_IN_THE_BLANK";
+}>;
+export type WorksheetQuestionTypeConfig = z.infer<typeof questionTypeSchema>;
+/** Shape stored in WorksheetPreset.config and used for generation */
+export declare const worksheetPresetConfigSchema: z.ZodObject<{
+    mode: z.ZodDefault<z.ZodEnum<{
+        practice: "practice";
+        quiz: "quiz";
+    }>>;
+    numQuestions: z.ZodDefault<z.ZodNumber>;
+    difficulty: z.ZodDefault<z.ZodEnum<{
+        easy: "easy";
+        medium: "medium";
+        hard: "hard";
+    }>>;
+    questionTypes: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        MULTIPLE_CHOICE: "MULTIPLE_CHOICE";
+        TEXT: "TEXT";
+        NUMERIC: "NUMERIC";
+        TRUE_FALSE: "TRUE_FALSE";
+        MATCHING: "MATCHING";
+        FILL_IN_THE_BLANK: "FILL_IN_THE_BLANK";
+    }>>>;
+    mcqRatio: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type WorksheetPresetConfig = z.infer<typeof worksheetPresetConfigSchema>;
+export declare const worksheetPresetConfigPartialSchema: z.ZodObject<{
+    mode: z.ZodOptional<z.ZodDefault<z.ZodEnum<{
+        practice: "practice";
+        quiz: "quiz";
+    }>>>;
+    numQuestions: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
+    difficulty: z.ZodOptional<z.ZodDefault<z.ZodEnum<{
+        easy: "easy";
+        medium: "medium";
+        hard: "hard";
+    }>>>;
+    questionTypes: z.ZodOptional<z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        MULTIPLE_CHOICE: "MULTIPLE_CHOICE";
+        TEXT: "TEXT";
+        NUMERIC: "NUMERIC";
+        TRUE_FALSE: "TRUE_FALSE";
+        MATCHING: "MATCHING";
+        FILL_IN_THE_BLANK: "FILL_IN_THE_BLANK";
+    }>>>>;
+    mcqRatio: z.ZodOptional<z.ZodOptional<z.ZodNumber>>;
+}, z.core.$strip>;
+/** Resolved config used by generateFromPrompt background job */
+export type ResolvedWorksheetGeneration = WorksheetPresetConfig & {
+    prompt: string;
+    title?: string;
+    estimatedTime?: string;
+    presetId?: string | null;
+};
+export declare function parsePresetConfig(raw: unknown): WorksheetPresetConfig;
+export declare function mergeWorksheetGenerationConfig(presetConfig: Partial<WorksheetPresetConfig> | null | undefined, configOverride: Partial<WorksheetPresetConfig> | null | undefined, legacy: {
+    numQuestions?: number;
+    difficulty?: WorksheetDifficultyInput;
+    mode?: WorksheetMode;
+}): WorksheetPresetConfig;
+/** Normalize one LLM problem row before DB insert */
+export declare function normalizeWorksheetProblemForDb(problem: Record<string, unknown>, index0: number, difficultyUpper: 'EASY' | 'MEDIUM' | 'HARD', forceMcq: boolean): {
+    prompt: string;
+    answer: string | null;
+    type: string;
+    difficulty: 'EASY' | 'MEDIUM' | 'HARD';
+    order: number;
+    meta: {
+        options?: string[];
+        markScheme?: unknown;
+    };
+};

package/dist/src/services/content/worksheet-generation.service.js

@@ -0,0 +1,95 @@
+import { z } from 'zod';
+/** Persisted on Artifact.worksheetConfig and inside generatingMetadata while generating */
+export const worksheetModeSchema = z.enum(['practice', 'quiz']);
+export const worksheetDifficultyInputSchema = z.enum(['easy', 'medium', 'hard']);
+export const questionTypeSchema = z.enum([
+    'MULTIPLE_CHOICE',
+    'TEXT',
+    'NUMERIC',
+    'TRUE_FALSE',
+    'MATCHING',
+    'FILL_IN_THE_BLANK',
+]);
+/** Shape stored in WorksheetPreset.config and used for generation */
+export const worksheetPresetConfigSchema = z.object({
+    mode: worksheetModeSchema.default('practice'),
+    numQuestions: z.number().int().min(1).max(20).default(8),
+    difficulty: worksheetDifficultyInputSchema.default('medium'),
+    /** When omitted, quiz mode implies MCQ-only on the inference side */
+    questionTypes: z.array(questionTypeSchema).optional(),
+    /** 0–1 fraction of problems that should be MCQ (practice mode); ignored when quiz forces all MCQ */
+    mcqRatio: z.number().min(0).max(1).optional(),
+});
+export const worksheetPresetConfigPartialSchema = worksheetPresetConfigSchema.partial();
+const defaultConfig = worksheetPresetConfigSchema.parse({});
+export function parsePresetConfig(raw) {
+    return worksheetPresetConfigSchema.parse(raw);
+}
+export function mergeWorksheetGenerationConfig(presetConfig, configOverride, legacy) {
+    // Precedence: legacy flat fields > configOverride > preset > defaults
+    // We place legacy AFTER configOverride because configOverride's Zod partial schema injects defaults (like medium) 
+    // that shouldn't overwrite explicit explicit user choices passing via legacy parameters.
+    const merged = {
+        ...defaultConfig,
+        ...presetConfig,
+        ...configOverride,
+        ...(legacy.numQuestions !== undefined ? { numQuestions: legacy.numQuestions } : {}),
+        ...(legacy.difficulty !== undefined ? { difficulty: legacy.difficulty } : {}),
+        ...(legacy.mode !== undefined ? { mode: legacy.mode } : {}),
+    };
+    return worksheetPresetConfigSchema.parse(merged);
+}
+/** Normalize one LLM problem row before DB insert */
+export function normalizeWorksheetProblemForDb(problem, index0, difficultyUpper, forceMcq) {
+    const prompt = (typeof problem.question === 'string' && problem.question) ||
+        (typeof problem.prompt === 'string' && problem.prompt) ||
+        `Question ${index0 + 1}`;
+    let type = String(problem.type || 'TEXT').toUpperCase().replace(/[\s-]/g, '_');
+    if (forceMcq)
+        type = 'MULTIPLE_CHOICE';
+    let options = [];
+    if (Array.isArray(problem.options)) {
+        options = problem.options.filter((o) => typeof o === 'string' && o.trim().length > 0);
+    }
+    let answer = (typeof problem.answer === 'string' && problem.answer) ||
+        (typeof problem.solution === 'string' && problem.solution) ||
+        '';
+    if (type === 'MULTIPLE_CHOICE') {
+        if (options.length < 2) {
+            options = ['Option A', 'Option B', 'Option C', 'Option D'];
+        }
+        const correctIndex = resolveMcqCorrectIndex(answer, options);
+        answer = String(correctIndex);
+    }
+    return {
+        prompt,
+        answer: answer || null,
+        type,
+        difficulty: difficultyUpper,
+        order: index0,
+        meta: {
+            ...(options.length > 0 ? { options } : {}),
+            ...(problem.mark_scheme !== undefined ? { markScheme: problem.mark_scheme } : {}),
+            // Non-MCQ questions are AI-marked via markScheme; provide a safe fallback
+            ...(type === 'TEXT' && problem.mark_scheme === undefined
+                ? {
+                    markScheme: {
+                        points: [{ point: 1, requirements: 'Typed answer matches expected content.' }],
+                        totalPoints: 1,
+                    },
+                }
+                : {}),
+        },
+    };
+}
+function resolveMcqCorrectIndex(answer, options) {
+    const trimmed = answer.trim();
+    const asNum = parseInt(trimmed, 10);
+    if (!Number.isNaN(asNum) && asNum >= 0 && asNum < options.length) {
+        return asNum;
+    }
+    const byText = options.findIndex((o) => o.trim() === trimmed);
+    if (byText >= 0)
+        return byText;
+    return 0;
+}

package/dist/src/services/content/worksheet-generation.service.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/services/content/worksheet-generation.service.test.js

@@ -0,0 +1,20 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mergeWorksheetGenerationConfig, normalizeWorksheetProblemForDb } from './worksheet-generation.service.js';
+test('mergeWorksheetGenerationConfig: override beats preset and legacy', () => {
+    const r = mergeWorksheetGenerationConfig({ mode: 'practice', numQuestions: 5, difficulty: 'easy' }, { mode: 'quiz', numQuestions: 10, difficulty: 'medium' }, { numQuestions: 3, difficulty: 'hard' });
+    assert.equal(r.mode, 'quiz');
+    assert.equal(r.numQuestions, 3);
+    assert.equal(r.difficulty, 'hard');
+});
+test('normalizeWorksheetProblemForDb coerces MCQ answer to option index', () => {
+    const row = normalizeWorksheetProblemForDb({
+        question: 'Capital of France?',
+        answer: 'Paris',
+        type: 'MULTIPLE_CHOICE',
+        options: ['London', 'Paris', 'Berlin'],
+    }, 0, 'MEDIUM', true);
+    assert.equal(row.type, 'MULTIPLE_CHOICE');
+    assert.equal(row.answer, '1');
+    assert.ok(row.meta.options && row.meta.options.length >= 2);
+});