@goscribe/server 1.3.4 → 1.5.0

package/src/lib/ai/json-parse.ts

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

package/src/lib/ai/llm-client.ts

@@ -0,0 +1,31 @@
+import OpenAI from 'openai';
+import type { ChatCompletion } from 'openai/resources/chat/completions';
+import { aiConfig } from './config.js';
+import type { ChatMessage, CompleteOptions } from './types.js';
+
+const client = new OpenAI({
+  apiKey: aiConfig.llm.apiKey,
+  baseURL: aiConfig.llm.baseUrl,
+});
+
+export async function complete(
+  messages: ChatMessage[],
+  options: CompleteOptions = {},
+): Promise<ChatCompletion> {
+  return client.chat.completions.create({
+    model: options.model ?? aiConfig.llm.model,
+    messages,
+    ...(options.temperature !== undefined ? { temperature: options.temperature } : {}),
+  });
+}
+
+export async function completeText(
+  messages: ChatMessage[],
+  options: CompleteOptions = {},
+): Promise<string> {
+  const response = await complete(messages, options);
+  return response.choices?.[0]?.message?.content ?? '';
+}
+
+/** @deprecated Use `complete()` from the ai module instead. */
+export default complete;

package/src/lib/ai/mock.ts

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

package/src/lib/ai/types.ts

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

package/src/lib/chunking.ts

@@ -0,0 +1,81 @@
+/**
+ * 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;
+}
+
+const CHARS_PER_TOKEN = 4;
+
+export function chunkText(
+  text: string,
+  opts: ChunkOptions = {},
+): Chunk[] {
+  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: Chunk[] = [];
+  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/src/lib/curated-kb-seed.ts

@@ -0,0 +1,164 @@
+/**
+ * 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 const CURATED_KB_SEEDS: CuratedKbSeed[] = [
+  // ── 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',
+  },
+];

package/src/lib/email.ts

@@ -1,24 +1,46 @@
-import nodemailer from 'nodemailer';
+import { Resend } from 'resend';
 import { logger } from './logger.js';
 import { env } from './env.js';
 
-// Commented out Resend flow as requested
-// import { Resend } from 'resend';
-// const resend = env.RESEND_API_KEY ? new Resend(env.RESEND_API_KEY) : null;
-
-const transporter = nodemailer.createTransport({
-  host: env.SMTP_HOST,
-  port: env.SMTP_PORT,
-  secure: env.SMTP_SECURE,
-  auth: {
-    user: env.SMTP_USER,
-    pass: env.SMTP_PASSWORD,
-  },
-});
-
+const resend = env.RESEND_API_KEY ? new Resend(env.RESEND_API_KEY) : null;
 const FROM_EMAIL = env.EMAIL_FROM;
 const APP_URL = env.FRONTEND_URL;
 
+async function sendEmail(options: {
+  to: string;
+  subject: string;
+  html: string;
+  successLog: string;
+  missingConfigLog: string;
+  devLogDetail: string;
+}): Promise<boolean> {
+  try {
+    if (!resend) {
+      logger.warn(`${options.missingConfigLog} Logging instead:`);
+      logger.info(options.devLogDetail);
+      return true;
+    }
+
+    const { data, error } = await resend.emails.send({
+      from: FROM_EMAIL,
+      to: options.to,
+      subject: options.subject,
+      html: options.html,
+    });
+
+    if (error) {
+      logger.error('Email send error:', error);
+      return false;
+    }
+
+    logger.info(options.successLog + (data?.id ? ` (id: ${data.id})` : ''));
+    return true;
+  } catch (err) {
+    logger.error('Email send error:', err);
+    return false;
+  }
+}
+
 export async function sendVerificationEmail(
   email: string,
   token: string,
@@ -41,26 +63,14 @@ export async function sendVerificationEmail(
     </div>
   `;
 
-  try {
-    if (!env.SMTP_HOST) {
-      logger.warn('Email service not configured (SMTP_HOST missing). Logging email content instead:');
-      logger.info(`Verification Email to ${email}: ${verifyUrl}`);
-      return true;
-    }
-
-    await transporter.sendMail({
-      from: FROM_EMAIL,
-      to: email,
-      subject: 'Verify your email - Scribe',
-      html,
-    });
-
-    logger.info(`Verification email sent to ${email}`);
-    return true;
-  } catch (err) {
-    logger.error('Email send error:', err);
-    return false;
-  }
+  return sendEmail({
+    to: email,
+    subject: 'Verify your email - Scribe',
+    html,
+    successLog: `Verification email sent to ${email}`,
+    missingConfigLog: 'Email service not configured (RESEND_API_KEY missing).',
+    devLogDetail: `Verification Email to ${email}: ${verifyUrl}`,
+  });
 }
 
 export async function sendInvitationEmail(invitation: {
@@ -88,26 +98,14 @@ export async function sendInvitationEmail(invitation: {
     </div>
   `;
 
-  try {
-    if (!env.SMTP_HOST) {
-      logger.warn('Email service not configured (SMTP_HOST missing). Logging invitation link instead:');
-      logger.info(`Invitation Link for ${invitation.email}: ${inviteUrl}`);
-      return true;
-    }
-
-    await transporter.sendMail({
-      from: FROM_EMAIL,
-      to: invitation.email,
-      subject: `Invitation to join ${invitation.workspaceTitle} on Scribe`,
-      html,
-    });
-
-    logger.info(`Invitation email sent to ${invitation.email}`);
-    return true;
-  } catch (err) {
-    logger.error('Email send error:', err);
-    return false;
-  }
+  return sendEmail({
+    to: invitation.email,
+    subject: `Invitation to join ${invitation.workspaceTitle} on Scribe`,
+    html,
+    successLog: `Invitation email sent to ${invitation.email}`,
+    missingConfigLog: 'Email service not configured (RESEND_API_KEY missing).',
+    devLogDetail: `Invitation Link for ${invitation.email}: ${inviteUrl}`,
+  });
 }
 
 export async function sendAccountDeletionScheduledEmail(email: string, token: string): Promise<boolean> {
@@ -129,26 +127,14 @@ export async function sendAccountDeletionScheduledEmail(email: string, token: st
     </div>
   `;
 
-  try {
-    if (!env.SMTP_HOST) {
-      logger.warn('Email service not configured (SMTP_HOST missing). Logging email content instead:');
-      logger.info(`Account Deletion Scheduled Email to ${email}: ${restoreUrl}`);
-      return true;
-    }
-
-    await transporter.sendMail({
-      from: FROM_EMAIL,
-      to: email,
-      subject: 'Account Deletion Scheduled - Scribe',
-      html,
-    });
-
-    logger.info(`Account deletion scheduled email sent to ${email}`);
-    return true;
-  } catch (err) {
-    logger.error('Email send error:', err);
-    return false;
-  }
+  return sendEmail({
+    to: email,
+    subject: 'Account Deletion Scheduled - Scribe',
+    html,
+    successLog: `Account deletion scheduled email sent to ${email}`,
+    missingConfigLog: 'Email service not configured (RESEND_API_KEY missing).',
+    devLogDetail: `Account Deletion Scheduled Email to ${email}: ${restoreUrl}`,
+  });
 }
 
 export async function sendPasswordResetEmail(
@@ -172,26 +158,14 @@ export async function sendPasswordResetEmail(
     </div>
   `;
 
-  try {
-    if (!env.SMTP_HOST) {
-      logger.warn('Email service not configured (SMTP_HOST missing). Logging reset link instead:');
-      logger.info(`Password reset for ${email}: ${resetUrl}`);
-      return true;
-    }
-
-    await transporter.sendMail({
-      from: FROM_EMAIL,
-      to: email,
-      subject: 'Reset your password - Scribe',
-      html,
-    });
-
-    logger.info(`Password reset email sent to ${email}`);
-    return true;
-  } catch (err) {
-    logger.error('Email send error:', err);
-    return false;
-  }
+  return sendEmail({
+    to: email,
+    subject: 'Reset your password - Scribe',
+    html,
+    successLog: `Password reset email sent to ${email}`,
+    missingConfigLog: 'Email service not configured (RESEND_API_KEY missing).',
+    devLogDetail: `Password reset for ${email}: ${resetUrl}`,
+  });
 }
 
 export async function sendAccountRestoredEmail(email: string): Promise<boolean> {
@@ -207,24 +181,12 @@ export async function sendAccountRestoredEmail(email: string): Promise<boolean>
     </div>
   `;
 
-  try {
-    if (!env.SMTP_HOST) {
-      logger.warn('Email service not configured (SMTP_HOST missing). Logging email content instead:');
-      logger.info(`Account Restored Email to ${email}`);
-      return true;
-    }
-
-    await transporter.sendMail({
-      from: FROM_EMAIL,
-      to: email,
-      subject: 'Account Restored - Scribe',
-      html,
-    });
-
-    logger.info(`Account restored email sent to ${email}`);
-    return true;
-  } catch (err) {
-    logger.error('Email send error:', err);
-    return false;
-  }
+  return sendEmail({
+    to: email,
+    subject: 'Account Restored - Scribe',
+    html,
+    successLog: `Account restored email sent to ${email}`,
+    missingConfigLog: 'Email service not configured (RESEND_API_KEY missing).',
+    devLogDetail: `Account Restored Email to ${email}: ${loginUrl}`,
+  });
 }

package/src/lib/embeddings.ts

@@ -0,0 +1,9 @@
+export {
+  DEFAULT_EMBEDDING_DIM,
+  DEFAULT_EMBEDDING_MODEL,
+  embedQuery,
+  embedTexts,
+  toVectorLiteral,
+} from './ai/embedding-client.js';
+
+export type { EmbedOptions } from './ai/embedding-client.js';

package/src/lib/ensure-curated-kb-catalog.ts

@@ -0,0 +1,60 @@
+import type { PrismaClient } from '@prisma/client';
+import { CURATED_KB_SEEDS } from '../lib/curated-kb-seed.js';
+import { logger } from '../lib/logger.js';
+
+/**
+ * Ensures the curated AP/IB catalog exists. Idempotent — safe to call on every
+ * server boot. Matches existing KBs by slug stored in `meta.slug`.
+ */
+export async function ensureCuratedKbCatalog(db: PrismaClient) {
+  let created = 0;
+
+  for (const seed of CURATED_KB_SEEDS) {
+    const existing =
+      (await db.knowledgeBase.findFirst({
+        where: {
+          meta: { path: ['slug'], equals: seed.slug },
+        },
+      })) ??
+      (await db.knowledgeBase.findFirst({
+        where: {
+          name: { equals: seed.name, mode: 'insensitive' },
+        },
+      }));
+
+    if (existing) {
+      await db.knowledgeBase.update({
+        where: { id: existing.id },
+        data: {
+          name: seed.name,
+          description: seed.description,
+          isCurated: true,
+          meta: {
+            slug: seed.slug,
+            category: seed.category,
+            subject: seed.subject,
+          },
+        },
+      });
+      continue;
+    }
+
+    await db.knowledgeBase.create({
+      data: {
+        name: seed.name,
+        description: seed.description,
+        isCurated: true,
+        meta: {
+          slug: seed.slug,
+          category: seed.category,
+          subject: seed.subject,
+        },
+      },
+    });
+    created += 1;
+  }
+
+  if (created > 0) {
+    logger.info(`Seeded ${created} curated knowledge base(s)`, 'KB');
+  }
+}

package/src/lib/env.ts

@@ -36,12 +36,8 @@ const envSchema = z.object({
   // CORS
   FRONTEND_URL: z.string().url().default('http://localhost:3000'),
 
-  // Email
-  SMTP_HOST: z.string(),
-  SMTP_PORT: z.string().regex(/^\d+$/).default('587').transform(Number),
-  SMTP_USER: z.string().optional(),
-  SMTP_PASSWORD: z.string().optional(),
-  SMTP_SECURE: z.enum(['true', 'false']).default('false').transform((v) => v === 'true'),
+  // Email (Resend)
+  RESEND_API_KEY: z.string().optional(),
   EMAIL_FROM: z.string().default('Scribe <hello@scribe.study>'),
   // Stripe
   STRIPE_SECRET_KEY: z.string().startsWith('sk_').optional(),
@@ -57,7 +53,6 @@ const envSchema = z.object({
  * Parsed and validated environment variables
  */
 export const env = envSchema.parse(process.env);
-// console.log('DEBUG: SMTP_HOST loaded:', env.SMTP_HOST ? 'Yes' : 'No');
 
 /**
  * Check if running in production

package/src/lib/inference.ts

@@ -1,21 +1 @@
-import OpenAI from 'openai';
-
-const openai = new OpenAI({
-    apiKey: process.env.INFERENCE_API_KEY,
-    baseURL: process.env.INFERENCE_BASE_URL,
-});
-
-async function inference(messages: { role: 'system' | 'user' | 'assistant', content: string }[]) {
-    try {
-        const response = await openai.chat.completions.create({
-            model: "command-a-03-2025",
-            messages: messages,
-        });
-        return response;
-    } catch (error) {
-        // Inference error logged at call site
-        throw error;
-    }
-}
-
-export default inference;
+export { complete as default, complete, completeText } from './ai/llm-client.js';