@goscribe/server 1.3.4 → 1.6.0

package/dist/lib/ai/inference-backend/mocks.js

@@ -0,0 +1,133 @@
+export function mockStudyGuide() {
+    return `# Mock Study Guide
+
+## Overview
+This is a mock study guide generated for testing purposes.
+
+## Key Concepts
+1. **Concept A**: Mock concept derived from uploaded materials
+2. **Concept B**: Another mock concept with explanations
+3. **Concept C**: A third concept with examples
+
+## Summary
+Mock study guide for local development when \`DONT_TEST_INFERENCE=true\`.`;
+}
+export function mockFlashcards(numQuestions, difficulty) {
+    return Array.from({ length: numQuestions }, (_, i) => ({
+        id: `mock-flashcard-${i + 1}`,
+        question: `Mock question ${i + 1}: What is the main concept covered in this material?`,
+        answer: `Mock answer ${i + 1}: Sample answer based on uploaded content.`,
+        difficulty,
+        category: `Mock Category ${(i % 3) + 1}`,
+    }));
+}
+export function mockWorksheet(numQuestions, difficulty, options) {
+    const mode = options?.mode ?? 'practice';
+    const isQuiz = mode === 'quiz';
+    return {
+        title: isQuiz ? `Mock Quiz - ${difficulty}` : `Mock Worksheet - ${difficulty} Level`,
+        description: 'Mock generated content',
+        difficulty,
+        estimatedTime: `${numQuestions * 2} min`,
+        problems: Array.from({ length: numQuestions }, (_, i) => {
+            if (isQuiz) {
+                return {
+                    question: `Mock MCQ ${i + 1}: What is 2+2?`,
+                    answer: '1',
+                    type: 'MULTIPLE_CHOICE',
+                    options: ['3', '4', '5', '6'],
+                    mark_scheme: {
+                        points: [{ point: 1, requirements: 'Select correct option' }],
+                        totalPoints: 1,
+                    },
+                };
+            }
+            return {
+                question: `Mock question ${i + 1}: Explain a concept.`,
+                answer: 'Mock answer',
+                type: 'TEXT',
+                options: [],
+                mark_scheme: {
+                    points: [{ point: 1, requirements: 'Clear explanation' }],
+                    totalPoints: 1,
+                },
+            };
+        }),
+    };
+}
+export function mockProcessFile(fileType) {
+    const mockPageCount = fileType === 'pdf' ? 15 : 1;
+    return {
+        status: 'success',
+        textContent: `Mock extracted text content from ${fileType} file.`,
+        imageDescriptions: Array.from({ length: mockPageCount }, (_, i) => ({
+            page: i + 1,
+            description: `Page ${i + 1} contains educational content with diagrams and text.`,
+            hasVisualContent: true,
+        })),
+        comprehensiveDescription: `DOCUMENT SUMMARY (${mockPageCount} ${mockPageCount === 1 ? 'page' : 'pages'})\n\nTEXT CONTENT:\nMock extracted text content...`,
+        pageCount: mockPageCount,
+    };
+}
+export function mockPodcastStructure(title, speakers) {
+    const voiceId = speakers[0]?.id || 'mock-voice-1';
+    return {
+        success: true,
+        structure: {
+            episodeTitle: `${title} - AI Generated Episode`,
+            totalEstimatedDuration: '15 minutes',
+            segments: [
+                {
+                    title: 'Welcome & Introduction',
+                    content: "HOST: Welcome to today's episode!\nGUEST: Thanks for having me!\nHOST: Let's dive into the topic.",
+                    speaker: 'dialogue',
+                    voiceId,
+                    keyPoints: ['Introduction', 'What to expect'],
+                    estimatedDuration: '3 minutes',
+                    order: 1,
+                },
+                {
+                    title: 'Main Discussion',
+                    content: 'This is the main content section where we explore the key concepts in detail.',
+                    speaker: 'host',
+                    voiceId,
+                    keyPoints: ['Key concept 1', 'Key concept 2'],
+                    estimatedDuration: '8 minutes',
+                    order: 2,
+                },
+                {
+                    title: 'Conclusion & Takeaways',
+                    content: "HOST: Let's wrap up what we've learned today.\nGUEST: The main takeaway is...\nHOST: Thanks for joining us!",
+                    speaker: 'dialogue',
+                    voiceId,
+                    keyPoints: ['Summary', 'Next steps'],
+                    estimatedDuration: '4 minutes',
+                    order: 3,
+                },
+            ],
+        },
+    };
+}
+export function mockPodcastAudio(user, sessionId, podcastId, segmentIndex, text) {
+    const isDialogue = text.includes('HOST:') || text.includes('GUEST:');
+    return {
+        success: true,
+        segmentIndex,
+        objectKey: `${user}/${sessionId}/podcasts/${podcastId}/segment_${segmentIndex}.mp3`,
+        duration: 45 + Math.floor(Math.random() * 30),
+        type: isDialogue ? 'dialogue' : 'monologue',
+        ...(isDialogue ? { partCount: 4 } : {}),
+    };
+}
+export function mockStudyGuideSegmentation() {
+    return [
+        { hint: 'Overview', content: 'Mock segment 1 content' },
+        { hint: 'Key concepts', content: 'Mock segment 2 content' },
+    ];
+}
+export function mockSegmentSummaryValidation() {
+    return {
+        valid: true,
+        feedback: 'Mock validation feedback for local development.',
+    };
+}

package/dist/lib/ai/inference-backend/types.d.ts

@@ -0,0 +1,44 @@
+export interface AISession {
+    id: string;
+    workspaceId: string;
+    status: 'initialized' | 'processing' | 'ready' | 'error';
+    files: string[];
+    instructionText?: string;
+    createdAt: Date;
+    updatedAt: Date;
+}
+export interface ProcessFileResult {
+    status: 'success' | 'error';
+    textContent: string | null;
+    imageDescriptions: Array<{
+        page: number;
+        description: string;
+        hasVisualContent: boolean;
+    }>;
+    comprehensiveDescription: string | null;
+    pageCount: number;
+    error?: string;
+}
+export interface PodcastSpeaker {
+    id: string;
+    role: string;
+    name?: string;
+}
+export interface WorksheetGenerationOptions {
+    mode?: 'practice' | 'quiz';
+    mcqRatio?: number;
+    questionTypes?: string[];
+    prompt?: string;
+    ragContext?: string;
+}
+export interface BackendGenerationOptions {
+    ragContext?: string;
+}
+export interface StudyGuideSegment {
+    hint: string;
+    content: string;
+}
+export interface SegmentSummaryValidation {
+    valid: boolean;
+    feedback: string;
+}

package/dist/lib/ai/inference-backend/types.js

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

package/dist/lib/ai/json-parse.d.ts

@@ -0,0 +1,2 @@
+export declare function extractJson(content: string): Record<string, unknown> | null;
+export declare function parseJsonField<T>(value: unknown, field: string): T;

package/dist/lib/ai/json-parse.js

@@ -0,0 +1,34 @@
+export function extractJson(content) {
+    const fencedMatch = content.match(/```json\s*([\s\S]*?)```/i);
+    if (fencedMatch?.[1]) {
+        try {
+            return JSON.parse(fencedMatch[1]);
+        }
+        catch {
+            // fall through
+        }
+    }
+    const objectMatch = content.match(/\{[\s\S]*\}/);
+    if (objectMatch?.[0]) {
+        try {
+            return JSON.parse(objectMatch[0]);
+        }
+        catch {
+            return null;
+        }
+    }
+    return null;
+}
+export function parseJsonField(value, field) {
+    if (typeof value === 'string') {
+        return JSON.parse(value);
+    }
+    if (value && typeof value === 'object' && field in value) {
+        const nested = value[field];
+        if (typeof nested === 'string') {
+            return JSON.parse(nested);
+        }
+        return nested;
+    }
+    throw new Error(`Expected JSON field "${field}" in AI response`);
+}

package/dist/lib/ai/llm-client.d.ts

@@ -0,0 +1,7 @@
+import type { ChatCompletion } from 'openai/resources/chat/completions';
+import type { ChatMessage, CompleteOptions } from './types.js';
+export declare function complete(messages: ChatMessage[], options?: CompleteOptions): Promise<ChatCompletion>;
+export declare function completeText(messages: ChatMessage[], options?: CompleteOptions): Promise<string>;
+export declare function streamComplete(messages: ChatMessage[], onDelta: (delta: string) => void | Promise<void>, options?: CompleteOptions): Promise<string>;
+/** @deprecated Use `complete()` from the ai module instead. */
+export default complete;

package/dist/lib/ai/llm-client.js

@@ -0,0 +1,36 @@
+import OpenAI from 'openai';
+import { aiConfig } from './config.js';
+const client = new OpenAI({
+    apiKey: aiConfig.llm.apiKey,
+    baseURL: aiConfig.llm.baseUrl,
+});
+export async function complete(messages, options = {}) {
+    return client.chat.completions.create({
+        model: options.model ?? aiConfig.llm.model,
+        messages,
+        ...(options.temperature !== undefined ? { temperature: options.temperature } : {}),
+    });
+}
+export async function completeText(messages, options = {}) {
+    const response = await complete(messages, options);
+    return response.choices?.[0]?.message?.content ?? '';
+}
+export async function streamComplete(messages, onDelta, options = {}) {
+    const stream = await client.chat.completions.create({
+        model: options.model ?? aiConfig.llm.model,
+        messages,
+        stream: true,
+        ...(options.temperature !== undefined ? { temperature: options.temperature } : {}),
+    });
+    let content = '';
+    for await (const chunk of stream) {
+        const delta = chunk.choices?.[0]?.delta?.content ?? '';
+        if (!delta)
+            continue;
+        content += delta;
+        await onDelta(delta);
+    }
+    return content;
+}
+/** @deprecated Use `complete()` from the ai module instead. */
+export default complete;

package/dist/lib/ai/mock.d.ts

@@ -0,0 +1,2 @@
+export declare function isAiMockMode(): boolean;
+export declare function mockDelay(): Promise<void>;

package/dist/lib/ai/mock.js

@@ -0,0 +1,10 @@
+import { aiConfig } from './config.js';
+export function isAiMockMode() {
+    return aiConfig.inferenceBackend.mockEnabled;
+}
+export async function mockDelay() {
+    const delay = aiConfig.inferenceBackend.mockDelayMs;
+    if (delay > 0) {
+        await new Promise((resolve) => setTimeout(resolve, delay));
+    }
+}

package/dist/lib/ai/types.d.ts

@@ -0,0 +1,9 @@
+export type ChatRole = 'system' | 'user' | 'assistant';
+export interface ChatMessage {
+    role: ChatRole;
+    content: string;
+}
+export interface CompleteOptions {
+    model?: string;
+    temperature?: number;
+}

package/dist/lib/ai/types.js

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

package/dist/lib/chunking.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Approximate text chunker for RAG indexing.
+ *
+ * Splits a long document into overlapping windows aimed at a target token
+ * count. We don't have a tokenizer dependency, so we approximate using
+ * `chars / 4` (a rule of thumb that matches GPT-style BPE within ~10-20%).
+ * Chunk boundaries snap to paragraph / sentence breaks when possible so we
+ * don't slice mid-thought.
+ */
+export interface ChunkOptions {
+    targetTokens?: number;
+    overlapTokens?: number;
+}
+export interface Chunk {
+    index: number;
+    content: string;
+    approxTokens: number;
+}
+export declare function chunkText(text: string, opts?: ChunkOptions): Chunk[];

package/dist/lib/chunking.js

@@ -0,0 +1,47 @@
+const CHARS_PER_TOKEN = 4;
+export function chunkText(text, opts = {}) {
+    const targetTokens = opts.targetTokens ?? 500;
+    const overlapTokens = opts.overlapTokens ?? 60;
+    const targetChars = targetTokens * CHARS_PER_TOKEN;
+    const overlapChars = overlapTokens * CHARS_PER_TOKEN;
+    const cleaned = text.replace(/\r\n/g, '\n').replace(/[ \t]+/g, ' ').trim();
+    if (!cleaned)
+        return [];
+    const chunks = [];
+    let cursor = 0;
+    let index = 0;
+    while (cursor < cleaned.length) {
+        const hardEnd = Math.min(cleaned.length, cursor + targetChars);
+        let end = hardEnd;
+        if (hardEnd < cleaned.length) {
+            // Prefer a paragraph break, then a sentence break, then a space.
+            const window = cleaned.slice(cursor, hardEnd);
+            const lastPara = window.lastIndexOf('\n\n');
+            const lastSentence = Math.max(window.lastIndexOf('. '), window.lastIndexOf('! '), window.lastIndexOf('? '), window.lastIndexOf('.\n'));
+            const lastSpace = window.lastIndexOf(' ');
+            const minBreak = Math.floor(targetChars * 0.5);
+            if (lastPara >= minBreak) {
+                end = cursor + lastPara + 2;
+            }
+            else if (lastSentence >= minBreak) {
+                end = cursor + lastSentence + 2;
+            }
+            else if (lastSpace >= minBreak) {
+                end = cursor + lastSpace + 1;
+            }
+        }
+        const piece = cleaned.slice(cursor, end).trim();
+        if (piece) {
+            chunks.push({
+                index,
+                content: piece,
+                approxTokens: Math.max(1, Math.round(piece.length / CHARS_PER_TOKEN)),
+            });
+            index += 1;
+        }
+        if (end >= cleaned.length)
+            break;
+        cursor = Math.max(end - overlapChars, cursor + 1);
+    }
+    return chunks;
+}

package/dist/lib/curated-kb-seed.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Curated AP & IB knowledge bases seeded on server startup.
+ * Each entry uses a stable slug in `meta` so the client can pick icons/colors.
+ */
+export interface CuratedKbSeed {
+    slug: string;
+    name: string;
+    description: string;
+    category: 'AP' | 'IB';
+    subject: string;
+}
+export declare const CURATED_KB_SEEDS: CuratedKbSeed[];

package/dist/lib/curated-kb-seed.js

@@ -0,0 +1,155 @@
+/**
+ * Curated AP & IB knowledge bases seeded on server startup.
+ * Each entry uses a stable slug in `meta` so the client can pick icons/colors.
+ */
+export const CURATED_KB_SEEDS = [
+    // ── AP ──────────────────────────────────────────────────────────
+    {
+        slug: 'ap-biology',
+        name: 'AP Biology',
+        description: 'Cell biology, genetics, evolution, and ecology aligned with the AP Biology curriculum.',
+        category: 'AP',
+        subject: 'biology',
+    },
+    {
+        slug: 'ap-chemistry',
+        name: 'AP Chemistry',
+        description: 'Atomic structure, bonding, thermodynamics, and kinetics for AP Chemistry.',
+        category: 'AP',
+        subject: 'chemistry',
+    },
+    {
+        slug: 'ap-physics-1',
+        name: 'AP Physics 1',
+        description: 'Algebra-based mechanics, waves, and electricity for AP Physics 1.',
+        category: 'AP',
+        subject: 'physics',
+    },
+    {
+        slug: 'ap-calculus-ab',
+        name: 'AP Calculus AB',
+        description: 'Limits, derivatives, integrals, and the Fundamental Theorem of Calculus.',
+        category: 'AP',
+        subject: 'calculus',
+    },
+    {
+        slug: 'ap-calculus-bc',
+        name: 'AP Calculus BC',
+        description: 'Series, parametric equations, polar coordinates, and advanced integration.',
+        category: 'AP',
+        subject: 'calculus',
+    },
+    {
+        slug: 'ap-us-history',
+        name: 'AP US History',
+        description: 'Colonial America through the modern era with primary source analysis.',
+        category: 'AP',
+        subject: 'history',
+    },
+    {
+        slug: 'ap-world-history',
+        name: 'AP World History',
+        description: 'Global civilizations, trade networks, and historical thinking skills.',
+        category: 'AP',
+        subject: 'history',
+    },
+    {
+        slug: 'ap-english-lang',
+        name: 'AP English Language',
+        description: 'Rhetorical analysis, argumentation, and synthesis writing strategies.',
+        category: 'AP',
+        subject: 'english',
+    },
+    {
+        slug: 'ap-english-lit',
+        name: 'AP English Literature',
+        description: 'Literary analysis, poetry, prose fiction, and critical essay writing.',
+        category: 'AP',
+        subject: 'literature',
+    },
+    {
+        slug: 'ap-psychology',
+        name: 'AP Psychology',
+        description: 'Biological bases of behavior, cognition, development, and social psychology.',
+        category: 'AP',
+        subject: 'psychology',
+    },
+    {
+        slug: 'ap-environmental-science',
+        name: 'AP Environmental Science',
+        description: 'Ecosystems, biodiversity, pollution, and sustainability concepts.',
+        category: 'AP',
+        subject: 'environmental',
+    },
+    {
+        slug: 'ap-macroeconomics',
+        name: 'AP Macroeconomics',
+        description: 'GDP, inflation, fiscal and monetary policy, and international trade.',
+        category: 'AP',
+        subject: 'economics',
+    },
+    // ── IB ──────────────────────────────────────────────────────────
+    {
+        slug: 'ib-biology-hl',
+        name: 'IB Biology HL',
+        description: 'Higher Level biology: molecular biology, genetics, ecology, and human physiology.',
+        category: 'IB',
+        subject: 'biology',
+    },
+    {
+        slug: 'ib-chemistry-hl',
+        name: 'IB Chemistry HL',
+        description: 'Higher Level chemistry: organic, inorganic, physical, and analytical topics.',
+        category: 'IB',
+        subject: 'chemistry',
+    },
+    {
+        slug: 'ib-physics-hl',
+        name: 'IB Physics HL',
+        description: 'Higher Level physics: mechanics, fields, waves, and nuclear physics.',
+        category: 'IB',
+        subject: 'physics',
+    },
+    {
+        slug: 'ib-math-aa-hl',
+        name: 'IB Math AA HL',
+        description: 'Analysis & Approaches HL: calculus, proof, vectors, and complex numbers.',
+        category: 'IB',
+        subject: 'math',
+    },
+    {
+        slug: 'ib-math-ai-hl',
+        name: 'IB Math AI HL',
+        description: 'Applications & Interpretation HL: statistics, modelling, and technology use.',
+        category: 'IB',
+        subject: 'math',
+    },
+    {
+        slug: 'ib-history-hl',
+        name: 'IB History HL',
+        description: 'Higher Level history: 20th century world history and historical investigation.',
+        category: 'IB',
+        subject: 'history',
+    },
+    {
+        slug: 'ib-english-a-hl',
+        name: 'IB English A HL',
+        description: 'Language & Literature HL: textual analysis, comparative study, and IO prep.',
+        category: 'IB',
+        subject: 'literature',
+    },
+    {
+        slug: 'ib-economics-hl',
+        name: 'IB Economics HL',
+        description: 'Microeconomics, macroeconomics, international economics, and development.',
+        category: 'IB',
+        subject: 'economics',
+    },
+    {
+        slug: 'ib-psychology-hl',
+        name: 'IB Psychology HL',
+        description: 'Biological, cognitive, sociocultural, and abnormal psychology at HL depth.',
+        category: 'IB',
+        subject: 'psychology',
+    },
+];