@goscribe/server 1.3.4 → 1.6.0

package/src/lib/ai/inference-backend/client.ts

@@ -0,0 +1,479 @@
+import { TRPCError } from '@trpc/server';
+import { getInferenceBackendUploadUrl, aiConfig, tryGetInferenceBackendUploadUrl } from '../config.js';
+import { isAiMockMode, mockDelay } from '../mock.js';
+import { parseJsonField } from '../json-parse.js';
+import { withRetry } from '../../retry.js';
+import { logger } from '../../logger.js';
+import type { MarkScheme, UserMarkScheme } from '../../../types/index.js';
+import {
+  mockFlashcards,
+  mockPodcastAudio,
+  mockPodcastStructure,
+  mockProcessFile,
+  mockSegmentSummaryValidation,
+  mockStudyGuide,
+  mockStudyGuideSegmentation,
+  mockWorksheet,
+} from './mocks.js';
+import type {
+  AISession,
+  PodcastSpeaker,
+  ProcessFileResult,
+  StudyGuideSegment,
+  WorksheetGenerationOptions,
+  BackendGenerationOptions,
+} from './types.js';
+
+interface PostCommandOptions {
+  label: string;
+  timeoutMs?: number;
+  retries?: number;
+}
+
+export class InferenceBackendClient {
+  private sessions = new Map<string, AISession>();
+
+  private get uploadUrl(): string {
+    return getInferenceBackendUploadUrl();
+  }
+
+  private async postCommand<T>(
+    formData: FormData,
+    options: PostCommandOptions,
+  ): Promise<T> {
+    const { label, timeoutMs = 300_000, retries = 3 } = options;
+
+    return withRetry(
+      async () => {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+          const response = await fetch(this.uploadUrl, {
+            method: 'POST',
+            body: formData,
+            signal: controller.signal,
+          });
+          clearTimeout(timeoutId);
+
+          if (!response.ok) {
+            const errorText = await response.text().catch(() => '');
+            throw new Error(
+              `AI backend error (${response.status}): ${errorText || response.statusText}`,
+            );
+          }
+
+          return (await response.json()) as T;
+        } catch (error) {
+          clearTimeout(timeoutId);
+          throw error;
+        }
+      },
+      { maxRetries: retries, timeoutMs, label },
+    );
+  }
+
+  private buildForm(command: string, fields: Record<string, string> = {}): FormData {
+    const formData = new FormData();
+    formData.append('command', command);
+    for (const [key, value] of Object.entries(fields)) {
+      formData.append(key, value);
+    }
+    return formData;
+  }
+
+  private withRag(
+    fields: Record<string, string>,
+    opts?: BackendGenerationOptions,
+  ): Record<string, string> {
+    if (opts?.ragContext?.trim()) {
+      return { ...fields, rag_context: opts.ragContext.trim() };
+    }
+    return fields;
+  }
+
+  async initSession(workspaceId: string, user: string): Promise<AISession> {
+    await mockDelay();
+    const sessionId = workspaceId;
+
+    if (isAiMockMode()) {
+      logger.info(`[ai] mock initSession workspace=${workspaceId}`);
+      const session: AISession = {
+        id: sessionId,
+        workspaceId,
+        status: 'initialized',
+        files: [],
+        createdAt: new Date(),
+        updatedAt: new Date(),
+      };
+      this.sessions.set(sessionId, session);
+      return session;
+    }
+
+    const result = await this.postCommand<{ message?: string }>(
+      this.buildForm('init_session', { session: sessionId, user }),
+      { label: 'initSession' },
+    );
+
+    if (!result.message) {
+      throw new TRPCError({
+        code: 'INTERNAL_SERVER_ERROR',
+        message: 'AI backend returned no session message',
+      });
+    }
+
+    const session: AISession = {
+      id: sessionId,
+      workspaceId,
+      status: 'initialized',
+      files: [],
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    };
+    this.sessions.set(sessionId, session);
+    return session;
+  }
+
+  async processFile(
+    sessionId: string,
+    _user: string,
+    fileUrl: string,
+    fileType: 'image' | 'pdf',
+    maxPages?: number,
+  ): Promise<ProcessFileResult> {
+    await mockDelay();
+
+    if (isAiMockMode()) {
+      logger.info(`[ai] mock processFile session=${sessionId} type=${fileType}`);
+      return mockProcessFile(fileType);
+    }
+
+    const fields: Record<string, string> = { fileUrl, fileType };
+    if (maxPages) fields.maxPages = maxPages.toString();
+
+    try {
+      const result = await this.postCommand<ProcessFileResult>(
+        this.buildForm('process_file', fields),
+        { label: 'processFile' },
+      );
+
+      if (result.status === 'error') {
+        throw new Error(result.error || 'File processing failed');
+      }
+      return result;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : 'Unknown error';
+      logger.error(`[ai] processFile failed: ${message}`);
+      return {
+        status: 'error',
+        textContent: null,
+        imageDescriptions: [],
+        comprehensiveDescription: null,
+        pageCount: 0,
+        error: message,
+      };
+    }
+  }
+
+  async generateStudyGuide(
+    sessionId: string,
+    user: string,
+    opts?: BackendGenerationOptions,
+  ): Promise<string> {
+    await mockDelay();
+    if (isAiMockMode()) {
+      logger.info(`[ai] mock generateStudyGuide session=${sessionId}`);
+      return mockStudyGuide();
+    }
+
+    const result = await this.postCommand<{ markdown?: string }>(
+      this.buildForm(
+        'generate_study_guide',
+        this.withRag({ session: sessionId, user }, opts),
+      ),
+      { label: 'generateStudyGuide' },
+    );
+
+    if (!result.markdown) {
+      throw new Error('AI backend returned empty study guide');
+    }
+    return result.markdown;
+  }
+
+  async generateFlashcardQuestions(
+    sessionId: string,
+    user: string,
+    numQuestions: number,
+    difficulty: 'easy' | 'medium' | 'hard',
+    prompt?: string,
+    opts?: BackendGenerationOptions,
+  ): Promise<string> {
+    await mockDelay();
+    if (isAiMockMode()) {
+      logger.info(`[ai] mock generateFlashcardQuestions session=${sessionId}`);
+      return JSON.stringify(
+        mockFlashcards(numQuestions, difficulty),
+      );
+    }
+
+    const fields: Record<string, string> = {
+      session: sessionId,
+      user,
+      num_questions: numQuestions.toString(),
+      difficulty,
+    };
+    if (prompt) fields.prompt = prompt;
+
+    const result = await this.postCommand<{ flashcards: string }>(
+      this.buildForm(
+        'generate_flashcard_questions',
+        this.withRag(fields, opts),
+      ),
+      { label: 'generateFlashcardQuestions' },
+    );
+
+    const parsed = JSON.parse(result.flashcards) as
+      | { flashcards?: unknown[] }
+      | unknown[];
+    if (Array.isArray(parsed)) return JSON.stringify(parsed);
+    return JSON.stringify(parsed.flashcards ?? []);
+  }
+
+  async generateWorksheetQuestions(
+    sessionId: string,
+    user: string,
+    numQuestions: number,
+    difficulty: 'EASY' | 'MEDIUM' | 'HARD',
+    options?: WorksheetGenerationOptions,
+  ): Promise<string> {
+    await mockDelay();
+    if (isAiMockMode()) {
+      logger.info(`[ai] mock generateWorksheetQuestions session=${sessionId}`);
+      return JSON.stringify(mockWorksheet(numQuestions, difficulty, options));
+    }
+
+    const fields: Record<string, string> = {
+      session: sessionId,
+      user,
+      num_questions: numQuestions.toString(),
+      difficulty,
+      mode: options?.mode ?? 'practice',
+    };
+    if (options?.mcqRatio !== undefined) {
+      fields.mcq_ratio = String(options.mcqRatio);
+    }
+    if (options?.questionTypes?.length) {
+      fields.question_types = JSON.stringify(options.questionTypes);
+    }
+    if (options?.prompt) {
+      fields.worksheet_prompt = options.prompt;
+    }
+
+    const result = await this.postCommand<{ worksheet: string }>(
+      this.buildForm(
+        'generate_worksheet_questions',
+        this.withRag(fields, { ragContext: options?.ragContext }),
+      ),
+      { label: 'generateWorksheetQuestions' },
+    );
+    return result.worksheet;
+  }
+
+  async checkWorksheetQuestions(
+    sessionId: string,
+    user: string,
+    question: string,
+    answer: string,
+    markScheme: MarkScheme,
+  ): Promise<UserMarkScheme> {
+    const result = await this.postCommand<{ marking: string }>(
+      this.buildForm('mark_worksheet_questions', {
+        session: sessionId,
+        user,
+        question,
+        answer,
+        mark_scheme: JSON.stringify(markScheme),
+      }),
+      { label: 'checkWorksheetQuestions', retries: 2 },
+    );
+
+    return parseJsonField<UserMarkScheme>(result.marking, 'marking');
+  }
+
+  async generatePodcastStructure(
+    sessionId: string,
+    user: string,
+    title: string,
+    description: string,
+    prompt: string,
+    speakers: PodcastSpeaker[],
+  ): Promise<any> {
+    await mockDelay();
+    if (isAiMockMode()) {
+      logger.info(`[ai] mock generatePodcastStructure session=${sessionId}`);
+      return mockPodcastStructure(title, speakers);
+    }
+
+    try {
+      return await this.postCommand<any>(
+        this.buildForm('generate_podcast_structure', {
+          user,
+          session: sessionId,
+          title,
+          description,
+          prompt,
+          speakers: JSON.stringify(speakers),
+        }),
+        { label: 'generatePodcastStructure' },
+      );
+    } catch (error) {
+      throw new TRPCError({
+        code: 'INTERNAL_SERVER_ERROR',
+        message: `Failed to generate podcast structure: ${error instanceof Error ? error.message : 'Unknown error'}`,
+      });
+    }
+  }
+
+  async generatePodcastAudioFromText(
+    sessionId: string,
+    user: string,
+    podcastId: string,
+    segmentIndex: number,
+    text: string,
+    speakers: PodcastSpeaker[],
+    voiceId?: string,
+  ): Promise<any> {
+    await mockDelay();
+    if (isAiMockMode()) {
+      logger.info(`[ai] mock generatePodcastAudio session=${sessionId}`);
+      return mockPodcastAudio(user, sessionId, podcastId, segmentIndex, text);
+    }
+
+    const fields: Record<string, string> = {
+      user,
+      session: sessionId,
+      podcast_id: podcastId,
+      segment_index: segmentIndex.toString(),
+      text,
+      speakers: JSON.stringify(speakers),
+    };
+    if (voiceId) fields.voice_id = voiceId;
+
+    try {
+      return await this.postCommand<any>(
+        this.buildForm('generate_podcast_audio_from_text', fields),
+        { label: 'generatePodcastAudioFromText' },
+      );
+    } catch (error) {
+      throw new TRPCError({
+        code: 'INTERNAL_SERVER_ERROR',
+        message: `Failed to generate podcast audio: ${error instanceof Error ? error.message : 'Unknown error'}`,
+      });
+    }
+  }
+
+  async generatePodcastImage(
+    sessionId: string,
+    user: string,
+    summary: string,
+  ): Promise<string> {
+    const result = await this.postCommand<{ image_key: string }>(
+      this.buildForm('generate_podcast_image', {
+        session: sessionId,
+        user,
+        summary,
+      }),
+      { label: 'generatePodcastImage' },
+    );
+    return result.image_key;
+  }
+
+  async segmentStudyGuide(
+    sessionId: string,
+    user: string,
+    studyGuide: string,
+  ): Promise<StudyGuideSegment[]> {
+    if (isAiMockMode()) {
+      return mockStudyGuideSegmentation();
+    }
+
+    const result = await this.postCommand<{ segmentation: StudyGuideSegment[] }>(
+      this.buildForm('generate_study_guide_segmentation', {
+        session: sessionId,
+        user,
+        study_guide: studyGuide,
+      }),
+      { label: 'segmentStudyGuide' },
+    );
+    return result.segmentation;
+  }
+
+  async validateSegmentSummary(
+    sessionId: string,
+    user: string,
+    segmentContent: string,
+    studentResponse: string,
+    studyGuide: string,
+  ): Promise<{ valid: boolean; feedback: string }> {
+    if (isAiMockMode()) {
+      return mockSegmentSummaryValidation();
+    }
+
+    const result = await this.postCommand<{ feedback: { valid: boolean; feedback: string } }>(
+      this.buildForm('validate_segment_summary', {
+        session: sessionId,
+        user,
+        segment_content: segmentContent,
+        student_response: studentResponse,
+        study_guide: studyGuide,
+      }),
+      { label: 'validateSegmentSummary' },
+    );
+    return result.feedback;
+  }
+
+  getSession(sessionId: string): AISession | undefined {
+    return this.sessions.get(sessionId);
+  }
+
+  getSessionsByUserAndWorkspace(_userId: string, workspaceId: string): AISession[] {
+    return Array.from(this.sessions.values()).filter(
+      (session) => session.workspaceId === workspaceId,
+    );
+  }
+
+  deleteSession(sessionId: string): boolean {
+    return this.sessions.delete(sessionId);
+  }
+
+  async checkHealth(): Promise<boolean> {
+    await mockDelay();
+    if (isAiMockMode()) {
+      logger.info('[ai] mock health check');
+      return true;
+    }
+
+    const uploadUrl = tryGetInferenceBackendUploadUrl();
+    if (!uploadUrl) return false;
+
+    try {
+      const response = await fetch(uploadUrl, {
+        method: 'POST',
+        body: new FormData(),
+      });
+      return response.ok;
+    } catch (error) {
+      logger.error('[ai] health check failed', error);
+      return false;
+    }
+  }
+}
+
+export const inferenceBackend = new InferenceBackendClient();
+
+if (aiConfig.inferenceBackend.url) {
+  logger.info(`[ai] inference backend: ${aiConfig.inferenceBackend.url}`);
+}
+
+if (isAiMockMode()) {
+  logger.info('[ai] mock mode enabled (DONT_TEST_INFERENCE=true)');
+}

package/src/lib/ai/inference-backend/mocks.ts

@@ -0,0 +1,171 @@
+import type {
+  ProcessFileResult,
+  PodcastSpeaker,
+  StudyGuideSegment,
+  WorksheetGenerationOptions,
+} from './types.js';
+
+export function mockStudyGuide(): string {
+  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: number,
+  difficulty: 'easy' | 'medium' | 'hard',
+): unknown[] {
+  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: number,
+  difficulty: 'EASY' | 'MEDIUM' | 'HARD',
+  options?: WorksheetGenerationOptions,
+): object {
+  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: 'image' | 'pdf',
+): ProcessFileResult {
+  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: string,
+  speakers: PodcastSpeaker[],
+): object {
+  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: string,
+  sessionId: string,
+  podcastId: string,
+  segmentIndex: number,
+  text: string,
+): object {
+  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(): StudyGuideSegment[] {
+  return [
+    { hint: 'Overview', content: 'Mock segment 1 content' },
+    { hint: 'Key concepts', content: 'Mock segment 2 content' },
+  ];
+}
+
+export function mockSegmentSummaryValidation(): {
+  valid: boolean;
+  feedback: string;
+} {
+  return {
+    valid: true,
+    feedback: 'Mock validation feedback for local development.',
+  };
+}

package/src/lib/ai/inference-backend/types.ts

@@ -0,0 +1,50 @@
+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;
+}