@prometheus-ai/memory 0.5.0

package/src/core/extraction/client.ts

@@ -0,0 +1,162 @@
+import { getDiagnostics } from "./diagnostics";
+import { EXTRACTION_SYSTEM_PROMPT, EXTRACTION_USER_TEMPLATE } from "./prompts";
+
+export const DEFAULT_EXTRACTION_MODEL = process.env.PROMETHEUS_MEMORY_EXTRACTION_MODEL || "google/gemini-2.5-flash";
+export const OPENROUTER_BASE_URL = (process.env.OPENROUTER_BASE_URL || "https://openrouter.ai/api/v1").replace(
+	/\/+$/,
+	"",
+);
+export const FALLBACK_MODELS = ["google/gemini-flash-latest"] as const;
+const RATE_LIMIT_BACKOFF_BASE_MS = 1_000;
+const RATE_LIMIT_BACKOFF_MAX_MS = 30_000;
+const FALLBACK_MODEL_DELAY_MS = 1_000;
+
+export interface ChatMessage {
+	role: string;
+	content: string;
+}
+
+export interface ExtractedFact {
+	subject?: string;
+	predicate?: string;
+	object?: string;
+	timestamp?: string;
+	source?: number;
+	confidence?: number;
+	[key: string]: unknown;
+}
+
+function sleep(ms: number): Promise<void> {
+	const { promise, resolve } = Promise.withResolvers<void>();
+	setTimeout(resolve, ms);
+	return promise;
+}
+
+function authHeader(apiKey: string): Record<string, string> {
+	const headers: Record<string, string> = { "Content-Type": "application/json" };
+	if (apiKey !== "") {
+		headers.Authorization = `Bearer ${apiKey}`;
+	}
+	return headers;
+}
+
+export class ExtractionClient {
+	model: string;
+	apiKey: string;
+	baseUrl: string;
+	callCount = 0;
+
+	constructor(opts: { model?: string | null; apiKey?: string | null; baseUrl?: string | null } = {}) {
+		this.model = opts.model || DEFAULT_EXTRACTION_MODEL;
+		this.apiKey = opts.apiKey ?? process.env.OPENROUTER_API_KEY ?? "";
+		this.baseUrl = (opts.baseUrl || OPENROUTER_BASE_URL).replace(/\/+$/, "");
+	}
+
+	async chat(messages: readonly ChatMessage[], temperature = 0, maxTokens = 4096): Promise<string> {
+		const diag = getDiagnostics();
+		diag.recordAttempt("cloud");
+		const models = [this.model, ...FALLBACK_MODELS.filter(m => m !== this.model)];
+		let lastError: unknown = null;
+
+		for (const model of models) {
+			for (let attempt = 0; attempt < 3; attempt += 1) {
+				try {
+					const result = await this.callApi(model, messages, temperature, maxTokens);
+					if (result === "") {
+						diag.recordNoOutput("cloud");
+					}
+					return result;
+				} catch (exc) {
+					lastError = exc;
+					const msg = String(exc).toLowerCase();
+					if (msg.includes("429") || msg.includes("rate")) {
+						await sleep(Math.min(RATE_LIMIT_BACKOFF_MAX_MS, RATE_LIMIT_BACKOFF_BASE_MS * 2 ** attempt));
+						continue;
+					}
+					break;
+				}
+			}
+			await sleep(FALLBACK_MODEL_DELAY_MS);
+		}
+
+		diag.recordFailure("cloud", lastError, "all_models_failed");
+		return "";
+	}
+
+	async callApi(
+		model: string,
+		messages: readonly ChatMessage[],
+		temperature: number,
+		maxTokens: number,
+	): Promise<string> {
+		const response = await fetch(`${this.baseUrl}/chat/completions`, {
+			method: "POST",
+			headers: authHeader(this.apiKey),
+			body: JSON.stringify({ model, messages, temperature, max_tokens: maxTokens }),
+			signal: AbortSignal.timeout(60000),
+		});
+		if (!response.ok) {
+			throw new Error(`${response.status} ${response.statusText}`.trim());
+		}
+		const data = (await response.json()) as {
+			choices?: Array<{ message?: { content?: unknown } }>;
+		};
+		this.callCount += 1;
+		const content = data.choices?.[0]?.message?.content;
+		return typeof content === "string" ? content : "";
+	}
+
+	async extractFacts(messages: readonly ChatMessage[]): Promise<ExtractedFact[]> {
+		let conversationText = "";
+		for (let i = 0; i < messages.length; i += 1) {
+			const msg = messages[i];
+			if (msg === undefined) continue;
+			const content = msg.content.trim();
+			if (content !== "") {
+				conversationText += `[${i}] [${msg.role || "unknown"}]: ${content}\n`;
+			}
+		}
+		if (conversationText.trim() === "") {
+			return [];
+		}
+
+		const userPrompt = EXTRACTION_USER_TEMPLATE.replace("{conversation_text}", conversationText);
+		const response = await this.chat(
+			[
+				{ role: "system", content: EXTRACTION_SYSTEM_PROMPT },
+				{ role: "user", content: userPrompt },
+			],
+			0,
+			4096,
+		);
+
+		const diag = getDiagnostics();
+		if (response === "") {
+			diag.recordCall({ succeeded: false, allEmpty: true });
+			return [];
+		}
+
+		try {
+			const jsonStart = response.indexOf("[");
+			const jsonEnd = response.lastIndexOf("]") + 1;
+			if (jsonStart >= 0 && jsonEnd > jsonStart) {
+				const facts = JSON.parse(response.slice(jsonStart, jsonEnd)) as unknown;
+				if (Array.isArray(facts)) {
+					diag.recordSuccess("cloud", facts.length);
+					diag.recordCall({ succeeded: true });
+					return facts as ExtractedFact[];
+				}
+			}
+			diag.recordFailure("cloud", undefined, "no_facts_in_response");
+			diag.recordCall({ succeeded: false, allEmpty: true });
+		} catch (exc) {
+			diag.recordFailure("cloud", exc, "json_parse_failed");
+			diag.recordCall({ succeeded: false });
+		}
+		return [];
+	}
+
+	xtractFacts(messages: readonly ChatMessage[]): Promise<ExtractedFact[]> {
+		return this.extractFacts(messages);
+	}
+}

package/src/core/extraction/diagnostics.ts

@@ -0,0 +1,193 @@
+export const EXTRACTION_TIERS = ["host", "remote", "local", "cloud", "wrapper"] as const;
+export type ExtractionTier = (typeof EXTRACTION_TIERS)[number];
+
+const MAX_ERROR_SAMPLES_PER_TIER = 10;
+const ERROR_MESSAGE_CAP = 200;
+
+export interface ErrorSample {
+	at: string;
+	type: string;
+	msg: string;
+	reason?: string;
+}
+
+export interface TierStatsSnapshot {
+	attempts: number;
+	successes: number;
+	no_output: number;
+	failures: number;
+	error_samples: ErrorSample[];
+}
+
+export interface ExtractionStatsSnapshot {
+	created_at: string;
+	snapshot_at: string;
+	totals: {
+		calls: number;
+		successes: number;
+		failures: number;
+		empty: number;
+		success_rate: number;
+	};
+	by_tier: Record<ExtractionTier, TierStatsSnapshot>;
+}
+
+interface MutableTierStats {
+	attempts: number;
+	successes: number;
+	no_output: number;
+	failures: number;
+	error_samples: ErrorSample[];
+}
+
+export function safeForLog(value: unknown): string {
+	if (value === null || value === undefined) {
+		return "";
+	}
+	const s = value instanceof Error ? `${value.name}: ${value.message}` : String(value);
+	let out = "";
+	for (let i = 0; i < s.length && out.length < ERROR_MESSAGE_CAP; i += 1) {
+		const code = s.charCodeAt(i);
+		out += code >= 32 && code !== 127 && code !== 27 ? s.charAt(i) : " ";
+	}
+	return out;
+}
+
+function emptyTierStats(): Record<ExtractionTier, MutableTierStats> {
+	return {
+		host: { attempts: 0, successes: 0, no_output: 0, failures: 0, error_samples: [] },
+		remote: { attempts: 0, successes: 0, no_output: 0, failures: 0, error_samples: [] },
+		local: { attempts: 0, successes: 0, no_output: 0, failures: 0, error_samples: [] },
+		cloud: { attempts: 0, successes: 0, no_output: 0, failures: 0, error_samples: [] },
+		wrapper: { attempts: 0, successes: 0, no_output: 0, failures: 0, error_samples: [] },
+	};
+}
+
+function isTier(tier: string): tier is ExtractionTier {
+	return (EXTRACTION_TIERS as readonly string[]).includes(tier);
+}
+
+function truncateError(msg: string): string {
+	return msg.length > ERROR_MESSAGE_CAP ? `${msg.slice(0, ERROR_MESSAGE_CAP)}...[truncated]` : msg;
+}
+
+function errorRepr(exc: unknown): string {
+	if (exc instanceof Error) {
+		return `${exc.name}: ${exc.message}`;
+	}
+	return String(exc);
+}
+
+export class ExtractionDiagnostics {
+	private tierStats: Record<ExtractionTier, MutableTierStats> = emptyTierStats();
+	private totalCalls = 0;
+	private totalSuccesses = 0;
+	private totalFailures = 0;
+	private totalEmpty = 0;
+	private createdAt = new Date().toISOString();
+
+	private validateTier(tier: string): asserts tier is ExtractionTier {
+		if (!isTier(tier)) {
+			throw new Error(
+				`unknown extraction tier ${JSON.stringify(tier)}; valid tiers: ${EXTRACTION_TIERS.join(", ")}`,
+			);
+		}
+	}
+
+	recordAttempt(tier: ExtractionTier): void {
+		this.validateTier(tier);
+		this.tierStats[tier].attempts += 1;
+	}
+	recordSuccess(tier: ExtractionTier, _factCount = 0): void {
+		this.validateTier(tier);
+		this.tierStats[tier].successes += 1;
+	}
+	recordNoOutput(tier: ExtractionTier): void {
+		this.validateTier(tier);
+		this.tierStats[tier].no_output += 1;
+	}
+	recordFailure(tier: ExtractionTier, exc?: unknown, reason?: string): void {
+		this.validateTier(tier);
+		const stats = this.tierStats[tier];
+		stats.failures += 1;
+		const sample: ErrorSample = { at: new Date().toISOString(), type: "unspecified", msg: "" };
+		if (exc !== undefined && exc !== null) {
+			sample.type = exc instanceof Error ? exc.name : typeof exc;
+			sample.msg = truncateError(errorRepr(exc));
+		} else if (reason !== undefined) {
+			sample.type = "reason";
+			sample.msg = truncateError(reason);
+		}
+		if (reason !== undefined) {
+			sample.reason = reason;
+		}
+		stats.error_samples.push(sample);
+		if (stats.error_samples.length > MAX_ERROR_SAMPLES_PER_TIER) {
+			stats.error_samples.splice(0, stats.error_samples.length - MAX_ERROR_SAMPLES_PER_TIER);
+		}
+	}
+	recordCall(opts: { succeeded: boolean; allEmpty?: boolean }): void {
+		this.totalCalls += 1;
+		if (opts.succeeded) {
+			this.totalSuccesses += 1;
+		} else if (opts.allEmpty === true) {
+			this.totalEmpty += 1;
+		} else {
+			this.totalFailures += 1;
+		}
+	}
+	successRate(): number {
+		return this.totalCalls === 0 ? 0 : this.totalSuccesses / this.totalCalls;
+	}
+	snapshot(): ExtractionStatsSnapshot {
+		const byTier = {} as Record<ExtractionTier, TierStatsSnapshot>;
+		for (const tier of EXTRACTION_TIERS) {
+			const stats = this.tierStats[tier];
+			byTier[tier] = {
+				attempts: stats.attempts,
+				successes: stats.successes,
+				no_output: stats.no_output,
+				failures: stats.failures,
+				error_samples: stats.error_samples.map(sample => ({ ...sample })),
+			};
+		}
+		return {
+			created_at: this.createdAt,
+			snapshot_at: new Date().toISOString(),
+			totals: {
+				calls: this.totalCalls,
+				successes: this.totalSuccesses,
+				failures: this.totalFailures,
+				empty: this.totalEmpty,
+				success_rate: this.successRate(),
+			},
+			by_tier: byTier,
+		};
+	}
+
+	reset(): void {
+		this.tierStats = emptyTierStats();
+		this.totalCalls = 0;
+		this.totalSuccesses = 0;
+		this.totalFailures = 0;
+		this.totalEmpty = 0;
+		this.createdAt = new Date().toISOString();
+	}
+}
+
+let singleton: ExtractionDiagnostics | null = null;
+
+export function getDiagnostics(): ExtractionDiagnostics {
+	if (singleton === null) {
+		singleton = new ExtractionDiagnostics();
+	}
+	return singleton;
+}
+
+export function getExtractionStats(): ExtractionStatsSnapshot {
+	return getDiagnostics().snapshot();
+}
+
+export function resetExtractionStats(): void {
+	getDiagnostics().reset();
+}

package/src/core/extraction/prompts.ts

@@ -0,0 +1,31 @@
+export const EXTRACTION_SYSTEM_PROMPT = `You extract structured facts from conversation messages. For each message or group of related messages, identify:
+
+1. ENTITIES: People, projects, tools, versions, dates, numbers mentioned
+2. RELATIONSHIPS: How entities relate to each other (uses, created, set, changed, prefers)
+3. TEMPORAL ANCHORS: When something happened, deadlines, durations
+4. CONTRADICTIONS: When a fact was later changed or updated
+
+Return ONLY a JSON array of fact objects. Each fact must have:
+- subject: the entity the fact is about (string)
+- predicate: the relationship or action (string)
+- object: the value or related entity (string)
+- timestamp: ISO timestamp when this was stated (string, from message context)
+- source: which message index this came from (integer, 0-based)
+- confidence: 0.0-1.0 how certain you are (float)
+
+RULES:
+- One fact per relationship. "I use React 18.2 and Node.js 18" = 2 facts.
+- Use lowercase for predicates: "uses", "set", "changed", "created", "prefers"
+- Include versions and numbers as objects when available
+- If a message states something changed, extract BOTH old and new facts
+- If unclear, use confidence < 0.8
+
+Format: [{"subject": "...", "predicate": "...", "object": "...", "timestamp": "...", "source": 0, "confidence": 0.95}]
+`;
+
+export const EXTRACTION_USER_TEMPLATE = `Extract all structured facts from the following conversation messages. Return ONLY the JSON array, no other text.
+
+CONVERSATION:
+{conversation_text}
+
+FACTS:`;