vellum 0.2.14 → 0.3.2

package/src/memory/job-handlers/summarization.ts

@@ -1,286 +0,0 @@
-import Anthropic from '@anthropic-ai/sdk';
-import { and, desc, eq, gte, isNull, lt } from 'drizzle-orm';
-import { v4 as uuid } from 'uuid';
-import type { AssistantConfig } from '../../config/types.js';
-import { estimateTextTokens } from '../../context/token-estimator.js';
-import { getLogger } from '../../util/logger.js';
-import { getConversationMemoryScopeId } from '../conversation-store.js';
-import { getDb } from '../db.js';
-import { enqueueMemoryJob, type MemoryJob } from '../jobs-store.js';
-import { asString, currentMonthWindow, currentWeekWindow, truncate } from '../job-utils.js';
-import { memoryItems, memorySegments, memorySummaries } from '../schema.js';
-
-const log = getLogger('memory-jobs-worker');
-
-const SUMMARY_LLM_TIMEOUT_MS = 20_000;
-const SUMMARY_MAX_TOKENS = 800;
-
-const CONVERSATION_SUMMARY_SYSTEM_PROMPT = [
-  'You are a memory summarization system. Your job is to produce a compact, information-dense summary of a conversation.',
-  '',
-  'Guidelines:',
-  '- Focus on key facts, decisions, user preferences, and actionable information.',
-  '- Preserve concrete details: names, file paths, tool choices, technical decisions, constraints.',
-  '- Remove filler, pleasantries, and transient discussion that has no lasting value.',
-  '- Use concise bullet points grouped by topic.',
-  '- Target 400-600 tokens. Be dense but readable.',
-  '- If updating an existing summary with new data, merge new information and remove anything that was superseded.',
-].join('\n');
-
-const GLOBAL_SUMMARY_SYSTEM_PROMPT = [
-  'You are a memory summarization system. Your job is to synthesize a higher-level summary from multiple conversation summaries and memory items.',
-  '',
-  'Guidelines:',
-  '- Identify recurring themes, cross-cutting decisions, and persistent user preferences.',
-  '- Highlight the most important facts, active projects, and ongoing concerns.',
-  '- De-duplicate information that appears across multiple conversations.',
-  '- Use concise sections with bullet points.',
-  '- Target 400-600 tokens. Be dense but readable.',
-  '- If updating an existing summary with new data, merge new information and remove anything that was superseded.',
-].join('\n');
-
-export async function buildConversationSummaryJob(job: MemoryJob, config: AssistantConfig): Promise<void> {
-  const conversationId = asString(job.payload.conversationId);
-  if (!conversationId) return;
-  const db = getDb();
-  const rows = db
-    .select()
-    .from(memorySegments)
-    .where(eq(memorySegments.conversationId, conversationId))
-    .orderBy(desc(memorySegments.createdAt))
-    .limit(40)
-    .all();
-  if (rows.length === 0) return;
-
-  const existing = db
-    .select()
-    .from(memorySummaries)
-    .where(and(
-      eq(memorySummaries.scope, 'conversation'),
-      eq(memorySummaries.scopeKey, conversationId),
-    ))
-    .get();
-
-  // Build segment text for LLM input (chronological order)
-  const segmentTexts = rows
-    .slice(0, 30)
-    .reverse()
-    .map((row) => `[${row.role}] ${truncate(row.text, 400)}`)
-    .join('\n\n');
-
-  const summaryText = await summarizeWithLLM(
-    config,
-    CONVERSATION_SUMMARY_SYSTEM_PROMPT,
-    existing?.summary ?? null,
-    segmentTexts,
-    'conversation',
-  );
-
-  // Inherit the conversation's memory scope so private conversation
-  // summaries stay isolated from default-scope retrieval.
-  const scopeId = getConversationMemoryScopeId(conversationId);
-
-  const now = Date.now();
-  const summaryId = existing?.id ?? uuid();
-  const nextVersion = (existing?.version ?? 0) + 1;
-  if (existing) {
-    db.update(memorySummaries)
-      .set({
-        summary: summaryText,
-        tokenEstimate: estimateTextTokens(summaryText),
-        version: nextVersion,
-        scopeId,
-        startAt: rows[rows.length - 1].createdAt,
-        endAt: rows[0].createdAt,
-        updatedAt: now,
-      })
-      .where(eq(memorySummaries.id, existing.id))
-      .run();
-  } else {
-    db.insert(memorySummaries).values({
-      id: summaryId,
-      scope: 'conversation',
-      scopeKey: conversationId,
-      scopeId,
-      summary: summaryText,
-      tokenEstimate: estimateTextTokens(summaryText),
-      version: nextVersion,
-      startAt: rows[rows.length - 1].createdAt,
-      endAt: rows[0].createdAt,
-      createdAt: now,
-      updatedAt: now,
-    }).run();
-  }
-  enqueueMemoryJob('embed_summary', { summaryId });
-}
-
-export async function buildGlobalSummaryJob(scope: 'weekly_global' | 'monthly_global', config: AssistantConfig): Promise<void> {
-  const db = getDb();
-  const now = new Date();
-  const { startMs, endMs, scopeKey } = scope === 'weekly_global'
-    ? currentWeekWindow(now)
-    : currentMonthWindow(now);
-
-  const items = db
-    .select()
-    .from(memoryItems)
-    .where(and(
-      eq(memoryItems.status, 'active'),
-      isNull(memoryItems.invalidAt),
-      eq(memoryItems.scopeId, 'default'),
-      gte(memoryItems.lastSeenAt, startMs),
-      lt(memoryItems.lastSeenAt, endMs),
-    ))
-    .orderBy(desc(memoryItems.lastSeenAt))
-    .limit(80)
-    .all();
-
-  // Gather conversation summaries from this period for higher-level synthesis
-  const convSummaries = db
-    .select()
-    .from(memorySummaries)
-    .where(and(
-      eq(memorySummaries.scope, 'conversation'),
-      eq(memorySummaries.scopeId, 'default'),
-      gte(memorySummaries.endAt, startMs),
-      lt(memorySummaries.startAt, endMs),
-    ))
-    .orderBy(desc(memorySummaries.endAt))
-    .limit(20)
-    .all();
-
-  if (items.length === 0 && convSummaries.length === 0) return;
-
-  // Build input for LLM: conversation summaries + active items
-  const parts: string[] = [];
-  if (convSummaries.length > 0) {
-    parts.push('## Conversation Summaries');
-    for (const cs of convSummaries) {
-      parts.push(`### ${cs.scopeKey}\n${truncate(cs.summary, 600)}`);
-    }
-  }
-  if (items.length > 0) {
-    parts.push('## Active Memory Items');
-    for (const item of items.slice(0, 40)) {
-      parts.push(`- [${item.kind}] ${item.subject}: ${truncate(item.statement, 180)}`);
-    }
-  }
-  const inputText = parts.join('\n\n');
-
-  const existing = db
-    .select()
-    .from(memorySummaries)
-    .where(and(
-      eq(memorySummaries.scope, scope),
-      eq(memorySummaries.scopeKey, scopeKey),
-    ))
-    .get();
-
-  const label = scope === 'weekly_global' ? 'weekly' : 'monthly';
-  const summaryText = await summarizeWithLLM(
-    config,
-    GLOBAL_SUMMARY_SYSTEM_PROMPT,
-    existing?.summary ?? null,
-    inputText,
-    label,
-  );
-
-  const ts = Date.now();
-  const summaryId = existing?.id ?? uuid();
-  const nextVersion = (existing?.version ?? 0) + 1;
-  if (existing) {
-    db.update(memorySummaries)
-      .set({
-        summary: summaryText,
-        tokenEstimate: estimateTextTokens(summaryText),
-        version: nextVersion,
-        startAt: startMs,
-        endAt: endMs,
-        updatedAt: ts,
-      })
-      .where(eq(memorySummaries.id, existing.id))
-      .run();
-  } else {
-    db.insert(memorySummaries).values({
-      id: summaryId,
-      scope,
-      scopeKey,
-      summary: summaryText,
-      tokenEstimate: estimateTextTokens(summaryText),
-      version: nextVersion,
-      startAt: startMs,
-      endAt: endMs,
-      createdAt: ts,
-      updatedAt: ts,
-    }).run();
-  }
-  enqueueMemoryJob('embed_summary', { summaryId });
-}
-
-async function summarizeWithLLM(
-  config: AssistantConfig,
-  systemPrompt: string,
-  existingSummary: string | null,
-  newContent: string,
-  label: string,
-): Promise<string> {
-  const summarizationConfig = config.memory.summarization;
-  if (!summarizationConfig.useLLM) {
-    log.debug({ label }, 'LLM summarization disabled, using fallback');
-    return buildFallbackSummary(existingSummary, newContent, label);
-  }
-
-  const apiKey = config.apiKeys.anthropic ?? process.env.ANTHROPIC_API_KEY;
-  if (!apiKey) {
-    log.debug({ label }, 'No Anthropic API key available for summarization, using fallback');
-    return buildFallbackSummary(existingSummary, newContent, label);
-  }
-
-  const userParts: string[] = [];
-  if (existingSummary) {
-    userParts.push(
-      '### Existing Summary (update with new data, keep what is still relevant, remove superseded info)',
-      existingSummary,
-      '',
-    );
-  }
-  userParts.push('### New Data', newContent);
-
-  try {
-    const client = new Anthropic({ apiKey });
-    const response = await Promise.race([
-      client.messages.create({
-        model: summarizationConfig.model,
-        max_tokens: SUMMARY_MAX_TOKENS,
-        system: systemPrompt,
-        messages: [{ role: 'user' as const, content: userParts.join('\n') }],
-      }),
-      new Promise<never>((_, reject) =>
-        setTimeout(() => reject(new Error('Summarization LLM timeout')), SUMMARY_LLM_TIMEOUT_MS),
-      ),
-    ]);
-
-    const textBlock = response.content.find((b) => b.type === 'text');
-    if (textBlock && textBlock.type === 'text' && textBlock.text.trim().length > 0) {
-      log.debug(
-        { label, inputTokens: response.usage.input_tokens, outputTokens: response.usage.output_tokens },
-        'LLM summarization completed',
-      );
-      return textBlock.text.trim();
-    }
-
-    log.warn({ label }, 'LLM summarization returned empty text, using fallback');
-    return buildFallbackSummary(existingSummary, newContent, label);
-  } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
-    log.warn({ err: message, label }, 'LLM summarization failed, using fallback');
-    return buildFallbackSummary(existingSummary, newContent, label);
-  }
-}
-
-function buildFallbackSummary(_existingSummary: string | null, newContent: string, label: string): string {
-  const lines = newContent.split('\n').filter((l) => l.trim().length > 0);
-  const snippets = lines.slice(0, 20).map((l) => `- ${truncate(l.trim(), 180)}`);
-  const parts: string[] = [`${label} summary`, '', ...snippets];
-  return parts.join('\n');
-}

package/src/memory/job-utils.ts

@@ -1,170 +0,0 @@
-import { getLogger } from '../util/logger.js';
-import { embedWithBackend, getMemoryBackendStatus } from './embedding-backend.js';
-import { getQdrantClient } from './qdrant-client.js';
-import type { AssistantConfig } from '../config/types.js';
-
-const log = getLogger('memory-jobs-worker');
-
-// ── Sentinel error ─────────────────────────────────────────────────
-
-/** Sentinel error: the embedding backend is not configured yet. */
-export class BackendUnavailableError extends Error {
-  constructor(reason: string) {
-    super(reason);
-    this.name = 'BackendUnavailableError';
-  }
-}
-
-// ── Error classification for LLM / API errors ─────────────────────
-
-export type ErrorCategory = 'retryable' | 'fatal';
-
-export const RETRY_BASE_DELAY_MS = 5_000;
-export const RETRY_MAX_DELAY_MS = 5 * 60 * 1000;
-export const RETRY_MAX_ATTEMPTS = 8;
-
-/**
- * Classify an error as retryable or fatal based on its HTTP status or type.
- *
- * Retryable: timeouts, 429 rate limits, 5xx server errors, connection errors.
- * Fatal: 400 bad request, 401 auth, 403 permission, other 4xx client errors.
- */
-export function classifyError(err: unknown): ErrorCategory {
-  // Timeout errors from our own Promise.race wrappers
-  if (err instanceof Error && err.message.includes('timeout')) {
-    return 'retryable';
-  }
-
-  // SDK APIError subclasses (Anthropic and OpenAI share the same shape)
-  if (err != null && typeof err === 'object' && 'status' in err) {
-    const status = (err as { status?: number }).status;
-    if (typeof status === 'number') {
-      if (status === 429) return 'retryable';
-      if (status >= 500) return 'retryable';
-      // 400, 401, 403, 404, 409, 422, other 4xx → fatal
-      return 'fatal';
-    }
-    // No status (connection error) → retryable
-    return 'retryable';
-  }
-
-  // Parse HTTP status codes from error messages (e.g., "request failed (429): ...")
-  // Gemini and Ollama backends embed status codes in plain Error messages
-  if (err instanceof Error) {
-    const statusMatch = err.message.match(/\((\d{3})\)/);
-    if (statusMatch) {
-      const status = parseInt(statusMatch[1], 10);
-      if (status === 429) return 'retryable';
-      if (status >= 500) return 'retryable';
-      // 4xx client errors → fatal
-      if (status >= 400 && status < 500) return 'fatal';
-    }
-  }
-
-  // Connection/network errors without a status code
-  if (err instanceof Error && /ECONNREFUSED|ECONNRESET|ETIMEDOUT|ENETUNREACH|fetch failed/i.test(err.message)) {
-    return 'retryable';
-  }
-
-  // Unknown errors default to fatal to avoid infinite retry loops
-  return 'fatal';
-}
-
-/** Equal jitter backoff: floor of cap/2 plus random in [0, cap/2].
- *  Prevents retry delays from collapsing to 0ms while still avoiding thundering herds. */
-export function retryDelayForAttempt(attempts: number): number {
-  const cap = Math.min(RETRY_BASE_DELAY_MS * Math.pow(2, Math.max(0, attempts - 1)), RETRY_MAX_DELAY_MS);
-  const half = cap / 2;
-  return half + Math.random() * half;
-}
-
-// ── Payload extraction helpers ─────────────────────────────────────
-
-export function asString(value: unknown): string | null {
-  return typeof value === 'string' && value.length > 0 ? value : null;
-}
-
-export function asPositiveMs(value: unknown): number | null {
-  if (typeof value !== 'number') return null;
-  if (!Number.isFinite(value) || value <= 0) return null;
-  return Math.floor(value);
-}
-
-export function truncate(text: string, max: number): string {
-  if (text.length <= max) return text;
-  return `${text.slice(0, max - 3)}...`;
-}
-
-// ── Embedding helper ───────────────────────────────────────────────
-
-export async function embedAndUpsert(
-  config: AssistantConfig,
-  targetType: 'segment' | 'item' | 'summary',
-  targetId: string,
-  text: string,
-  extraPayload?: Record<string, unknown>,
-): Promise<void> {
-  const status = getMemoryBackendStatus(config);
-  if (!status.provider) {
-    throw new BackendUnavailableError(
-      `Embedding backend unavailable (${status.reason ?? 'no provider'})`,
-    );
-  }
-
-  const embedded = await embedWithBackend(config, [text]);
-  const vector = embedded.vectors[0];
-  if (!vector) return;
-
-  let qdrant;
-  try {
-    qdrant = getQdrantClient();
-  } catch {
-    throw new BackendUnavailableError('Qdrant client not initialized');
-  }
-
-  try {
-    const now = Date.now();
-    await qdrant.upsert(targetType, targetId, vector, {
-      text,
-      created_at: (extraPayload?.created_at as number) ?? now,
-      ...(extraPayload as Record<string, unknown> | undefined),
-    });
-  } catch (err) {
-    log.warn({ err, targetType, targetId }, 'Failed to upsert embedding to Qdrant');
-    throw err;
-  }
-}
-
-// ── Time window utilities ──────────────────────────────────────────
-
-export function currentWeekWindow(now: Date): { scopeKey: string; startMs: number; endMs: number } {
-  const day = (now.getUTCDay() + 6) % 7;
-  const start = new Date(Date.UTC(
-    now.getUTCFullYear(),
-    now.getUTCMonth(),
-    now.getUTCDate() - day,
-    0,
-    0,
-    0,
-    0,
-  ));
-  const end = new Date(start);
-  end.setUTCDate(end.getUTCDate() + 7);
-  const scopeKey = `${start.getUTCFullYear()}-W${weekNumber(start).toString().padStart(2, '0')}`;
-  return { scopeKey, startMs: start.getTime(), endMs: end.getTime() };
-}
-
-export function currentMonthWindow(now: Date): { scopeKey: string; startMs: number; endMs: number } {
-  const start = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), 1, 0, 0, 0, 0));
-  const end = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth() + 1, 1, 0, 0, 0, 0));
-  const scopeKey = `${start.getUTCFullYear()}-${String(start.getUTCMonth() + 1).padStart(2, '0')}`;
-  return { scopeKey, startMs: start.getTime(), endMs: end.getTime() };
-}
-
-function weekNumber(date: Date): number {
-  const tmp = new Date(Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate()));
-  const dayNum = tmp.getUTCDay() || 7;
-  tmp.setUTCDate(tmp.getUTCDate() + 4 - dayNum);
-  const yearStart = new Date(Date.UTC(tmp.getUTCFullYear(), 0, 1));
-  return Math.ceil((((tmp.getTime() - yearStart.getTime()) / 86400000) + 1) / 7);
-}