This commit is contained in:
Oleg Maslov
2026-09-02 10:14:22 +02:00
parent 0c3e2ead3b
commit b20b138fe4
771 changed files with 161561 additions and 9027 deletions

View File

@@ -0,0 +1,281 @@
/**
* BEAM 1M — multi-route dated retrieval (E4 retrieval-architecture lever).
*
* Eywa's BEAM lead is dominated by COVERAGE / CHRONOLOGICAL-ORDER / CROSS-SESSION
* retrieval, which a single top-30 similarity route cannot serve. This module
* builds a deterministic 3-route retrieval over the DATED raw-turn store and
* fuses it with RRF:
*
* Route V (vector) : substrate.search.search(q, {limit:kVec}) — existing.
* Route T (timeline) : broad similarity fetch (kWide), dated via dateMap;
* parseDateWindow(q) hard-filters to an explicit period
* when present; ranked by DATE-STRATIFIED COVERAGE
* (≤capPerDate turns/date, chronological) so breadth —
* not similarity density — drives event_ordering / summ.
* Route E (entity) : deterministic query-entity extraction → per-entity
* keywordSearch (FTS, phrase-quoted, conv-scoped) → ALL
* cross-session mentions of each entity (multi_session).
*
* FUSE: RRF (k=60) over the three ranked frame-id lists → top-N. Then EVERY
* survivor is dated via the dateMap and rendered oldest→newest as
* "[YYYY-MM-DD] role: content" (undated turns appended last, unbracketed).
* Raw turns are kept verbatim (we still win instruction/preference on detail).
*
* WHY dateMap and not `created_at`: BEAM ingest writes every turn with
* created_at = ingest time (all frames share one date), so the substrate's
* built-in since/until temporal filter cannot separate turns by conversation
* date. The dateMap (chat.json time_anchor) is the only real per-turn date.
*
* Pure retrieval + string assembly; the only I/O is substrate.search (local
* ollama embeddings + SQLite). No LLM calls here.
*/
import type { SearchResult } from '@waggle/core';
import { parseDateWindow } from '@waggle/core';
import type { Substrate } from './substrate.js';
const RRF_K = 60;
// ── Entity extraction (deterministic, query-side) ────────────────────────────
/** Question words / generic tokens that are never useful retrieval entities. */
const STOP = new Set([
'what', 'when', 'which', 'where', 'who', 'whom', 'whose', 'why', 'how', 'did',
'do', 'does', 'have', 'has', 'had', 'was', 'were', 'is', 'are', 'am', 'the',
'a', 'an', 'my', 'your', 'our', 'their', 'his', 'her', 'its', 'i', 'you', 'we',
'they', 'it', 'this', 'that', 'these', 'those', 'and', 'or', 'but', 'for', 'to',
'of', 'in', 'on', 'at', 'by', 'with', 'from', 'about', 'into', 'over', 'after',
'before', 'between', 'during', 'since', 'until', 'ago', 'many', 'much', 'any',
'some', 'all', 'each', 'every', 'been', 'be', 'being', 'will', 'would', 'can',
'could', 'should', 'may', 'might', 'must', 'me', 'us', 'them', 'if', 'then',
'there', 'here', 'now', 'ever', 'never', 'still', 'yet', 'also', 'just', 'so',
'than', 'as', 'up', 'out', 'down', 'off', 'no', 'not', 'yes',
// BEAM probing-question instruction / filler / quantifier words — these recur
// verbatim ("Mention ONLY and ONLY ten items", "in order", "list every ...")
// and are never useful retrieval entities.
'mention', 'only', 'list', 'name', 'named', 'items', 'item', 'order', 'ordered',
'progress', 'progressed', 'discussion', 'discussions', 'discussed', 'discuss',
'say', 'said', 'tell', 'give', 'provide', 'describe', 'summarize', 'summary',
'overview', 'account', 'sequence', 'chronological', 'versions', 'version',
'thing', 'things', 'stuff', 'first', 'second', 'third', 'fourth', 'fifth', 'last',
'one', 'two', 'three', 'four', 'five', 'six', 'seven', 'eight', 'nine', 'ten',
'eleven', 'twelve', 'both', 'entire', 'whole', 'total', 'number', 'count',
'happened', 'occur', 'occurred', 'time', 'times', 'date', 'dates', 'day', 'days',
'week', 'weeks', 'month', 'months', 'year', 'years',
'considering', 'using', 'given', 'based', 'regarding', 'concerning',
]);
/**
* Extract distinctive entities from a question: quoted spans, version/tech
* tokens (contain a digit or dot, e.g. "React 18.2", "v6.1.0", "port 4000"),
* lowercase alnum tokens with a digit, and runs of Capitalized words
* (proper-noun phrases). Deduplicated case-insensitively, capped.
*/
export function extractQueryEntities(question: string, cap = 6): string[] {
const out: string[] = [];
const seen = new Set<string>();
const push = (raw: string): void => {
const t = raw.trim().replace(/[.,;:?!]+$/, '').trim();
if (t.length < 3) return;
const key = t.toLowerCase();
if (seen.has(key)) return;
// Skip pure stopwords / question words.
if (STOP.has(key)) return;
seen.add(key);
out.push(t);
};
// 1) Quoted spans (highest precision).
for (const m of question.matchAll(/["'“”‘’]([^"'“”‘’]{2,60})["'“”‘’]/g)) push(m[1]);
// 2) Version / tech tokens: a token containing a digit (React18, 18.2, v6.1.0,
// 4000, PostgreSQL14) OR a dotted identifier. Keep an adjacent Capitalized
// word as a two-word unit ("React 18.2", "PostgreSQL 14", "port 4000").
const words = question.split(/\s+/);
for (let i = 0; i < words.length; i++) {
const w = words[i].replace(/[(),;:?!]+$/g, '').replace(/^[(),;:?!]+/g, '');
if (/\d/.test(w) && /[A-Za-z0-9.]/.test(w) && !/^\d{4}$/.test(w) === true) {
const prev = i > 0 ? words[i - 1].replace(/[(),;:?!]+$/g, '') : '';
if (prev && (/^[A-Z]/.test(prev) || /^(port|version|v|node|python|react|postgres|postgresql)$/i.test(prev)) && !STOP.has(prev.toLowerCase())) {
push(`${prev} ${w}`);
}
push(w);
}
}
// 3) Runs of Capitalized words (proper-noun phrases), ignoring the leading
// sentence-initial capital by only taking runs of length>=1 that aren't a
// lone stopword. Multi-word runs are kept whole AND their head token.
const capRun = /([A-Z][A-Za-z0-9+.#-]*(?:\s+[A-Z][A-Za-z0-9+.#-]*)*)/g;
for (const m of question.matchAll(capRun)) {
const phrase = m[1].trim();
const toks = phrase.split(/\s+/);
// Drop a leading sentence-initial single-cap common word (e.g. "What").
if (toks.length === 1) {
if (!STOP.has(toks[0].toLowerCase()) && toks[0].length >= 4) push(toks[0]);
continue;
}
// Multi-word proper-noun phrase.
const filtered = toks.filter((t, idx) => !(idx === 0 && STOP.has(t.toLowerCase())));
if (filtered.length >= 2) push(filtered.join(' '));
else if (filtered.length === 1 && filtered[0].length >= 4) push(filtered[0]);
}
// 4) lowercase alnum tokens that carry a digit (e.g. "franc6", "gpt4") — rare
// but distinctive; plain lowercase words are left to Route V/T.
for (const w of words) {
const t = w.replace(/[(),;:?!.]+$/g, '');
if (/^[a-z][a-z0-9.-]*\d[a-z0-9.-]*$/i.test(t)) push(t);
}
return out.slice(0, cap);
}
// ── RRF fusion ───────────────────────────────────────────────────────────────
/** RRF-fuse ranked id lists → id → score. Higher = better. */
export function rrfFuse(lists: number[][], k = RRF_K): Map<number, number> {
const scores = new Map<number, number>();
for (const list of lists) {
list.forEach((id, rank) => {
scores.set(id, (scores.get(id) ?? 0) + 1 / (k + rank));
});
}
return scores;
}
// ── Timeline route (date-stratified coverage) ────────────────────────────────
interface DatedFrame { id: number; content: string; date: string }
/** Rank a candidate set for COVERAGE: keep ≤capPerDate per date, ordered
* chronologically (oldest→newest). Returns frame ids in coverage order. */
function coverageRank(dated: DatedFrame[], capPerDate: number, limit: number): number[] {
const sorted = [...dated].sort((a, b) => (a.date === b.date ? a.id - b.id : a.date < b.date ? -1 : 1));
const perDate = new Map<string, number>();
const kept: number[] = [];
for (const e of sorted) {
const n = perDate.get(e.date) ?? 0;
if (n >= capPerDate) continue;
perDate.set(e.date, n + 1);
kept.push(e.id);
if (kept.length >= limit) break;
}
return kept;
}
// ── Public: build the fused, dated, chronological context ────────────────────
export interface MultiRouteOptions {
kVec: number; // Route V similarity limit (baseline parity, 30)
kWide: number; // Route T broad similarity fetch (150)
perEntity: number; // Route E per-entity FTS limit (20)
capPerDate: number;// Route T coverage stratification cap (2)
topN: number; // fused frames kept for the answer context (45)
}
export const DEFAULT_MULTIROUTE: MultiRouteOptions = {
kVec: 30, kWide: 150, perEntity: 20, capPerDate: 2, topN: 45,
};
export interface MultiRouteResult {
/** Dated display strings, oldest→newest, ready for buildAnswerGenerationPromptV2. */
displayStrings: string[];
/** Diagnostics. */
entities: string[];
dateWindow: { since: string; until: string; label: string } | null;
nVec: number;
nTimeline: number;
nEntity: number;
nFused: number;
nDated: number;
}
/**
* Run all three routes over one conversation's raw-turn mind and return the
* fused, dated, chronologically-ordered answer context. `dateMap` maps exact
* frame content ("role: text") → ISO date (from chat.json time_anchor).
*/
export async function buildMultiRouteContext(
sub: Substrate,
gopId: string,
question: string,
dateMap: Map<string, string> | null,
opts: MultiRouteOptions = DEFAULT_MULTIROUTE,
): Promise<MultiRouteResult> {
const frameById = new Map<number, { id: number; content: string }>();
const record = (r: SearchResult): void => { frameById.set(r.frame.id, { id: r.frame.id, content: r.frame.content }); };
const dateOf = (content: string): string => dateMap?.get(content) ?? '';
// Route V — vector (baseline parity).
const vec = await sub.search.search(question, { limit: opts.kVec, gopId });
vec.forEach(record);
const Lv = vec.map(r => r.frame.id);
// Route T — timeline: broad fetch, date-window filter, coverage rank.
const wide = await sub.search.search(question, { limit: opts.kWide, gopId });
wide.forEach(record);
const window = parseDateWindow(question);
let widedated: DatedFrame[] = wide.map(r => ({ id: r.frame.id, content: r.frame.content, date: dateOf(r.frame.content) }));
if (window) {
const inWin = widedated.filter(e => e.date && e.date >= window.since && e.date <= window.until);
// Only apply the window if it actually retains evidence; else keep the broad
// set (a mis-parse must never empty the context).
if (inWin.length > 0) widedated = inWin;
}
const Lt = coverageRank(widedated, opts.capPerDate, opts.kWide);
// Route E — entity: per-entity FTS across the whole conversation.
const entities = extractQueryEntities(question);
const entityHits = new Map<number, number>(); // id → #entities that matched it
for (const ent of entities) {
// Phrase-quote multi-word entities so keywordSearch does a phrase match
// (it passes a query containing a quote through to FTS unchanged).
const q = /\s/.test(ent) ? `"${ent.replace(/"/g, '')}"` : ent;
let ids: number[] = [];
try { ids = await sub.search.keywordSearch(q, opts.perEntity, gopId); } catch { ids = []; }
for (const id of ids) entityHits.set(id, (entityHits.get(id) ?? 0) + 1);
// Materialise contents for ids not yet seen by V/T.
const missing = ids.filter(id => !frameById.has(id));
if (missing.length) {
const rawdb = sub.db.getDatabase();
const ph = missing.map(() => '?').join(',');
const rows = rawdb.prepare(`SELECT id, content FROM memory_frames WHERE id IN (${ph})`).all(...missing) as Array<{ id: number; content: string }>;
for (const row of rows) frameById.set(row.id, row);
}
}
// Le ranked by (most entities matched, then id) — frames mentioning more of
// the question's entities rank higher.
const Le = [...entityHits.entries()].sort((a, b) => (b[1] - a[1]) || (a[0] - b[0])).map(e => e[0]);
// FUSE — RRF over the three ranked lists → top-N.
const fused = rrfFuse([Lv, Lt, Le]);
const fusedIds = [...fused.entries()]
.sort((a, b) => b[1] - a[1])
.map(e => e[0])
.slice(0, opts.topN);
// DATE + chronological render: dated turns oldest→newest, undated appended last.
const entries = fusedIds
.map(id => frameById.get(id))
.filter((f): f is { id: number; content: string } => !!f)
.map(f => ({ id: f.id, content: f.content, date: dateOf(f.content) }));
entries.sort((a, b) => {
if (a.date && b.date) return a.date === b.date ? a.id - b.id : a.date < b.date ? -1 : 1;
if (a.date) return -1; // dated before undated
if (b.date) return 1;
return a.id - b.id;
});
const displayStrings = entries.map(e => (e.date ? `[${e.date}] ${e.content}` : e.content));
return {
displayStrings,
entities,
dateWindow: window,
nVec: Lv.length,
nTimeline: Lt.length,
nEntity: Le.length,
nFused: fusedIds.length,
nDated: entries.filter(e => e.date).length,
};
}

View File

@@ -31,6 +31,11 @@ export interface BeamLlmResult {
latencyMs: number;
/** null = OK; otherwise a short failure classification. */
failureMode: string | null;
/** Prompt-caching economics (Anthropic via OpenRouter): tokens served from
* cache (cheap) and tokens written to cache (surcharged). Absent when the
* provider/route reports no cache usage. */
cacheReadTokens?: number;
cacheCreationTokens?: number;
}
export interface BeamLlm {
@@ -138,7 +143,7 @@ ANSWER:`;
* negation/"never happened" rule is added. All other rules are verbatim v1.
* Pair with date-stamped `memories` ("[YYYY-MM-DD] role: ...") so the
* contradiction rule can surface each statement with its date. */
export function buildAnswerGenerationPromptV2(question: string, memories: string[], outline?: string): string {
export function buildAnswerGenerationPromptV2(question: string, memories: string[], outline?: string, beliefsBlock?: string): string {
const memoriesText =
memories.length === 0
? '(No memories available)'
@@ -146,6 +151,12 @@ export function buildAnswerGenerationPromptV2(question: string, memories: string
// `outline` is a generic pre-labeled preamble: the CALLER builds the labeled
// block(s) (timeline, standing directives, ...) and this just inserts them.
const outlineBlock = outline ? `\n${outline}\n` : '';
// `beliefsBlock` is an ADDITIVE consolidated "current values" section built by
// the belief cell (real supersede/consolidation code). Placed BEFORE the raw
// turns so the model prefers the latest known value on a conflict, while the
// raw dated turns remain for detail. When absent the prompt is BYTE-IDENTICAL
// to the original v2 (both `beliefsSection` and `outlineBlock` collapse to '').
const beliefsSection = beliefsBlock ? `\n${beliefsBlock}\n` : '';
return `You are an AI assistant with access to stored memories from prior conversations with a user.
Use these memories to answer the following question as accurately and completely as possible.
@@ -162,7 +173,7 @@ IMPORTANT RULES:
10. Do NOT invent or assume information that isn't in the memories.
QUESTION: ${question}
${outlineBlock}
${beliefsSection}${outlineBlock}
RETRIEVED MEMORIES:
${memoriesText}
@@ -283,6 +294,54 @@ ${memoriesText}
ANSWER:`;
}
/** Answer-REPAIR prompt (E5 self-correction lever). Test-time, gold-blind second
* pass: it sees ONLY the question, the SAME retrieved dated context the drafter
* saw, and the draft answer — NO rubric, NO gold, NO nuggets. It rewrites the
* draft into a more complete, better-grounded answer:
* - fill coverage gaps (enumerate every relevant item/date/clause the context
* supports that the draft omitted) — BEAM grades on nugget coverage;
* - correct chronology / temporal anchors (event date, not mention date);
* - strip any claim the context does not support (no new facts);
* - PRESERVE correct abstentions — if the context genuinely lacks the answer,
* keep the exact sentinel and do not invent to look complete.
* Mirrors the V2 signature (optional outline + beliefsBlock) so the repair pass
* is grounded in the identical context the drafter received. */
export function buildRepairPrompt(
question: string,
memories: string[],
draftAnswer: string,
outline?: string,
beliefsBlock?: string,
): string {
const memoriesText =
memories.length === 0
? '(No memories available)'
: memories.map((m, i) => `${i + 1}. ${m}`).join('\n');
const outlineBlock = outline ? `\n${outline}\n` : '';
const beliefsSection = beliefsBlock ? `\n${beliefsBlock}\n` : '';
return `You are a meticulous reviewer improving a draft answer to a question. You are given the question, the stored memories (dated, from prior conversations with the user) that were available, and a DRAFT ANSWER written from those memories. Your job is to return a single IMPROVED ANSWER that is more complete and better grounded — nothing else.
REPAIR RULES:
1. Ground everything ONLY in the provided memories (and any consolidated values/timeline shown). Do NOT add any fact, name, date, number, or claim that is not supported by the provided context. You have no outside knowledge of this user.
2. Improve COVERAGE: re-scan ALL memories and add every relevant item the draft missed. If the question asks for a summary, overview, account of a process/journey, or a list/ordering of events, be EXHAUSTIVE — enumerate every relevant topic, project, event, tool, version, number, date, cause, outcome, and sub-step the memories support. Do not drop minor items.
3. Fix accuracy: correct any wrong or unsupported statement in the draft. For dates and durations, anchor on the date the event actually happened or is scheduled FOR (not the date it was merely mentioned); present events in chronological order.
4. Handle contradictions honestly: if the memories contain conflicting statements relevant to the question, present each conflicting statement (with its date when shown) rather than silently picking one.
5. Remove hallucinations: delete anything in the draft that the memories do not support.
6. PRESERVE CORRECT ABSTENTION: if the memories genuinely do not contain the information asked, do NOT invent an answer to look more complete — return exactly: "I don't have enough information to answer this question." Conversely, if the memories DO support an answer but the draft wrongly abstained, replace the abstention with the supported answer.
7. Keep everything in the draft that is already correct and supported; this is a revision, not a rewrite from scratch.
8. Output ONLY the improved answer text — no preamble, no explanation of your changes, no mention of "the draft".
QUESTION: ${question}
${beliefsSection}${outlineBlock}
RETRIEVED MEMORIES:
${memoriesText}
DRAFT ANSWER:
${draftAnswer}
IMPROVED ANSWER:`;
}
/** Fact-extraction prompt for event_ordering (mem0 `get_beam_fact_extraction_prompt`). */
export function buildFactExtractionPrompt(response: string): string {
return `Extract all distinct events or facts mentioned in the following response,
@@ -551,12 +610,30 @@ export async function judgeQuestion(
}
const nuggetScores: NuggetScore[] = [];
let judgeFailures = 0;
for (const nugget of input.rubric) {
const ns = await judgeSingleNugget(llm, input.question, nugget, input.answer);
llmResults.push(ns.result);
// A transport failure (http_429/timeout/etc.) or an empty completion means
// the JUDGE broke — not that the answer scored 0. Recording 0 here would
// silently corrupt the metric, so flag it and let the caller retry / hard-fail.
if (ns.result.failureMode || ns.result.text.trim() === '') judgeFailures++;
nuggetScores.push({ nugget, score: ns.score, reason: ns.reason });
}
if (judgeFailures > 0) {
return {
judgement: {
score: 0,
judgment: 'ERROR',
nuggetScores,
judgeCalls: nuggetScores.length,
error: `judge transport failure on ${judgeFailures}/${nuggetScores.length} nuggets`,
},
llmResults,
};
}
const avg = nuggetScores.reduce((s, n) => s + n.score, 0) / nuggetScores.length;
const judgement: QuestionJudgement = {
score: round4(avg),

View File

@@ -77,9 +77,14 @@ export const OPENAI_PRICING: Record<string, ModelPricing> = {
};
/** gpt-5 / o-series reasoning models reject `max_tokens` + non-default
* temperature, and spend completion budget on hidden reasoning tokens. */
* temperature, and spend completion budget on hidden reasoning tokens. The
* provider-prefixed form ("openai/gpt-5" via OpenRouter) must match too, or the
* client wrongly uses the max_tokens path and gpt-5 truncates its JSON mid-
* reasoning. gpt-5-chat is NOT a reasoning model, so exclude it explicitly. */
function isReasoningModel(model: string): boolean {
return /^(gpt-5|o\d)/.test(model.toLowerCase());
const m = model.toLowerCase();
if (/(^|\/)gpt-5-chat/.test(m)) return false;
return /(^|\/)(gpt-5|o\d)/.test(m);
}
// ── Client ──────────────────────────────────────────────────────────────────
@@ -94,6 +99,11 @@ export interface BeamOpenAiClientOptions {
pricing?: ModelPricing;
timeoutMs?: number;
maxRetries?: number;
/** Optional reasoning_effort for gpt-5/o-series (e.g. 'minimal' | 'low' |
* 'medium' | 'high'). Only sent for reasoning models; omitted by default so
* existing callers are byte-identical. Extraction uses 'low' to cut hidden
* reasoning tokens (latency + cost) on a mechanical task. */
reasoningEffort?: string;
}
export class BeamOpenAiClient implements BeamLlm {
@@ -103,6 +113,7 @@ export class BeamOpenAiClient implements BeamLlm {
private readonly pricing: ModelPricing;
private readonly timeoutMs: number;
private readonly maxRetries: number;
private readonly reasoningEffort: string | null;
constructor(opts: BeamOpenAiClientOptions) {
this.model = opts.model;
@@ -111,9 +122,21 @@ export class BeamOpenAiClient implements BeamLlm {
this.pricing = opts.pricing ?? OPENAI_PRICING[opts.model] ?? { inputPerMillion: 0, outputPerMillion: 0 };
this.timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
this.maxRetries = opts.maxRetries ?? DEFAULT_MAX_RETRIES;
this.reasoningEffort = opts.reasoningEffort ?? null;
}
async chat(opts: { system: string; user: string; jsonMode?: boolean; maxTokens?: number }): Promise<BeamLlmResult> {
async chat(opts: {
system: string;
user: string;
jsonMode?: boolean;
maxTokens?: number;
/** Large, stable text prefix to mark for prompt caching (Anthropic via
* OpenRouter). Placed FIRST in the system message with
* cache_control:{type:'ephemeral'} so repeated calls sharing this prefix
* (e.g. one conversation's ledger across its 20 questions) read it from
* cache. Ignored (sent as a plain system block) by non-caching providers. */
cacheableSystem?: string;
}): Promise<BeamLlmResult> {
const started = Date.now();
let lastFailure = 'unknown';
const reasoning = isReasoningModel(this.model);
@@ -130,15 +153,30 @@ export class BeamOpenAiClient implements BeamLlm {
const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), this.timeoutMs);
try {
// System message: when a cacheable prefix is supplied, send the system
// content as an array of parts with cache_control on the (large, stable)
// prefix so Anthropic (via OpenRouter) serves it from cache on repeat
// calls. Otherwise a plain string (byte-identical to prior behaviour).
let systemContent: unknown;
if (opts.cacheableSystem) {
const parts: Array<Record<string, unknown>> = [
{ type: 'text', text: opts.cacheableSystem, cache_control: { type: 'ephemeral' } },
];
if (opts.system) parts.push({ type: 'text', text: opts.system });
systemContent = parts;
} else {
systemContent = opts.system;
}
const body: Record<string, unknown> = {
model: this.model,
messages: [
{ role: 'system', content: opts.system },
{ role: 'system', content: systemContent },
{ role: 'user', content: opts.user },
],
};
if (reasoning) {
body.max_completion_tokens = reasoningBudget;
if (this.reasoningEffort) body.reasoning_effort = this.reasoningEffort;
} else {
body.temperature = 0;
body.max_tokens = opts.maxTokens ?? 800;
@@ -165,7 +203,13 @@ export class BeamOpenAiClient implements BeamLlm {
const json = (await res.json()) as {
choices?: Array<{ message?: { content?: string } }>;
usage?: { prompt_tokens?: number; completion_tokens?: number };
usage?: {
prompt_tokens?: number;
completion_tokens?: number;
prompt_tokens_details?: { cached_tokens?: number };
cache_creation_input_tokens?: number;
cache_read_input_tokens?: number;
};
};
const text = json.choices?.[0]?.message?.content ?? '';
// Retry-on-empty for reasoning models: HTTP-200 but no answer text means
@@ -183,10 +227,28 @@ export class BeamOpenAiClient implements BeamLlm {
}
const inputTokens = json.usage?.prompt_tokens ?? approxTokens(opts.system + opts.user);
const outputTokens = json.usage?.completion_tokens ?? approxTokens(text);
// Prompt-caching accounting (Anthropic via OpenRouter). Providers report
// either Anthropic-native fields (cache_creation/cache_read_input_tokens)
// or the OpenAI-style prompt_tokens_details.cached_tokens (reads only).
const cacheCreationTokens = json.usage?.cache_creation_input_tokens ?? 0;
const cacheReadTokens =
json.usage?.cache_read_input_tokens ?? json.usage?.prompt_tokens_details?.cached_tokens ?? 0;
// `prompt_tokens` from Anthropic EXCLUDES cached-read tokens but INCLUDES
// cache-creation tokens; from OpenAI it INCLUDES cached tokens. Compute
// uncached input as prompt_tokens minus any cache portions already in it.
const inRate = this.pricing.inputPerMillion / 1_000_000;
const outRate = this.pricing.outputPerMillion / 1_000_000;
// Cache writes are surcharged 1.25x, reads discounted to 0.1x (Anthropic).
const uncachedInput = Math.max(0, inputTokens - cacheCreationTokens - (json.usage?.prompt_tokens_details?.cached_tokens ?? 0));
const costUsd =
(inputTokens / 1_000_000) * this.pricing.inputPerMillion +
(outputTokens / 1_000_000) * this.pricing.outputPerMillion;
return { text, inputTokens, outputTokens, costUsd, latencyMs: Date.now() - started, failureMode: null };
uncachedInput * inRate +
cacheCreationTokens * inRate * 1.25 +
cacheReadTokens * inRate * 0.1 +
outputTokens * outRate;
return {
text, inputTokens, outputTokens, costUsd, latencyMs: Date.now() - started, failureMode: null,
cacheReadTokens, cacheCreationTokens,
};
} catch (err) {
const name = (err as Error).name;
lastFailure = name === 'AbortError' ? 'timeout' : `fetch_error_${name}`;
@@ -209,6 +271,9 @@ export function createBeamOpenAiClient(opts: {
envPath?: string;
baseUrl?: string;
pricing?: ModelPricing;
timeoutMs?: number;
maxRetries?: number;
reasoningEffort?: string;
}): BeamOpenAiClient {
loadDotEnv(opts.envPath);
const apiKey = process.env.OPENAI_API_KEY;
@@ -218,7 +283,10 @@ export function createBeamOpenAiClient(opts: {
'Set it in waggle-os/.env or export it before running.',
);
}
return new BeamOpenAiClient({ model: opts.model, apiKey, baseUrl: opts.baseUrl, pricing: opts.pricing });
return new BeamOpenAiClient({
model: opts.model, apiKey, baseUrl: opts.baseUrl, pricing: opts.pricing,
timeoutMs: opts.timeoutMs, maxRetries: opts.maxRetries, reasoningEffort: opts.reasoningEffort,
});
}
function approxTokens(s: string): number {