@atomicmemory/core 1.0.0

package/dist/services/embedding.js

@@ -0,0 +1,416 @@
+/**
+ * Embedding provider abstraction.
+ * Supports OpenAI, Ollama, OpenAI-compatible APIs, Voyage AI, and local
+ * WASM (via @huggingface/transformers with ONNX Runtime). Provider/model
+ * selection comes from the RuntimeConfig bound by createCoreRuntime().
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import OpenAI from 'openai';
+import { retryOnRateLimit } from './api-retry.js';
+import { estimateCostUsd, summarizeUsage, writeCostEvent, } from './cost-telemetry.js';
+import { VOYAGE_API_BASE, VoyageEmbedding } from './voyage-embedding.js';
+let embeddingConfig = null;
+/**
+ * Bind the embedding module's config. Called once by the composition
+ * root (`createCoreRuntime`). Calling again rebinds and invalidates the
+ * stateful provider cache — primarily for tests that need to swap
+ * providers within a process.
+ */
+export function initEmbedding(config) {
+    embeddingConfig = config;
+    provider = null;
+    providerKey = '';
+    embeddingCache.clear();
+}
+function requireConfig() {
+    if (!embeddingConfig) {
+        throw new Error('embedding.ts: initEmbedding(config) must be called at composition-root time before embedText/embedTexts. See runtime-container.ts.');
+    }
+    return embeddingConfig;
+}
+function writeEmbeddingUsageEvent(config, model, usage, started) {
+    writeCostEvent({
+        stage: 'embedding',
+        provider: config.embeddingProvider,
+        model,
+        requestKind: 'embedding',
+        durationMs: performance.now() - started,
+        cacheHit: false,
+        inputTokens: usage.inputTokens ?? null,
+        outputTokens: usage.outputTokens ?? null,
+        totalTokens: usage.totalTokens ?? null,
+        estimatedCostUsd: estimateCostUsd(config.embeddingProvider, model, usage),
+    }, config);
+}
+/** OpenAI and any OpenAI-compatible embedding API. */
+class OpenAICompatibleEmbedding {
+    client;
+    model;
+    dimensions;
+    constructor(apiKey, model, baseURL, dimensions) {
+        this.client = new OpenAI({ apiKey, baseURL });
+        this.model = model;
+        this.dimensions = dimensions;
+    }
+    async embed(text, _task) {
+        const response = await this.requestAndTrack(text);
+        return response.data[0].embedding;
+    }
+    async embedBatch(texts, _task) {
+        if (texts.length === 0)
+            return [];
+        const response = await this.requestAndTrack(texts);
+        return response.data
+            .sort((a, b) => a.index - b.index)
+            .map((d) => d.embedding);
+    }
+    embeddingRequest(input) {
+        const request = {
+            model: this.model,
+            input,
+        };
+        if (this.dimensions !== undefined)
+            request.dimensions = this.dimensions;
+        return request;
+    }
+    usageFromResponse(response) {
+        const totalTokens = response.usage?.total_tokens ?? null;
+        const promptTokens = response.usage?.prompt_tokens ?? null;
+        const inputTokens = promptTokens === null ? totalTokens : promptTokens;
+        return summarizeUsage(inputTokens, null, totalTokens);
+    }
+    async requestAndTrack(input) {
+        const config = requireConfig();
+        const request = () => this.client.embeddings.create(this.embeddingRequest(input));
+        const started = performance.now();
+        const response = await retryOnRateLimit(request);
+        writeEmbeddingUsageEvent(config, this.model, this.usageFromResponse(response), started);
+        return response;
+    }
+}
+/** Ollama embedding via native HTTP API. */
+class OllamaEmbedding {
+    baseUrl;
+    model;
+    constructor(model, baseUrl = 'http://localhost:11434') {
+        this.baseUrl = baseUrl;
+        this.model = model;
+    }
+    async embed(text, _task) {
+        const data = await this.ollamaFetch(text, 'Ollama embed failed');
+        return data.embeddings[0];
+    }
+    async embedBatch(texts, _task) {
+        if (texts.length === 0)
+            return [];
+        const data = await this.ollamaFetch(texts, 'Ollama embed batch failed');
+        return data.embeddings;
+    }
+    async ollamaFetch(input, errorLabel) {
+        const config = requireConfig();
+        const started = performance.now();
+        const response = await fetch(`${this.baseUrl}/api/embed`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ model: this.model, input }),
+            signal: AbortSignal.timeout(300_000),
+        });
+        if (!response.ok) {
+            throw new Error(`${errorLabel} (${response.status}): ${await response.text()}`);
+        }
+        const data = await response.json();
+        const usage = summarizeUsage(data.prompt_eval_count ?? null, data.eval_count ?? null, null);
+        writeEmbeddingUsageEvent(config, this.model, usage, started);
+        return data;
+    }
+}
+/**
+ * Local WASM embedding via @huggingface/transformers (ONNX Runtime).
+ * Eliminates network latency — target sub-15ms per embed at fp32.
+ * Pipeline is lazily initialized on first use (downloads model on first run).
+ */
+/**
+ * Local ONNX embedding with serialized inference.
+ * ONNX Runtime's C++ mutex corrupts under concurrent async calls, causing
+ * `mutex lock failed: Invalid argument` crashes in long-running processes.
+ * All inference is serialized through a promise queue to prevent this.
+ */
+class TransformersEmbedding {
+    model;
+    pipelinePromise = null;
+    inferenceQueue = Promise.resolve();
+    constructor(model) {
+        this.model = model;
+    }
+    getPipeline() {
+        if (!this.pipelinePromise) {
+            this.pipelinePromise = initTransformersPipeline(this.model);
+        }
+        return this.pipelinePromise;
+    }
+    serialized(fn) {
+        return new Promise((resolve, reject) => {
+            this.inferenceQueue = this.inferenceQueue.then(async () => {
+                try {
+                    const extractor = await this.getPipeline();
+                    resolve(await fn(extractor));
+                }
+                catch (err) {
+                    reject(err);
+                }
+            });
+        });
+    }
+    async embed(text, _task) {
+        return this.serialized(async (extractor) => {
+            const output = await extractor(text, { pooling: 'mean', normalize: true });
+            return Array.from(output.data);
+        });
+    }
+    async embedBatch(texts, _task) {
+        if (texts.length === 0)
+            return [];
+        return this.serialized(async (extractor) => {
+            const output = await extractor(texts, { pooling: 'mean', normalize: true });
+            const dims = output.dims;
+            const embeddingSize = dims[dims.length - 1];
+            const data = output.data;
+            const results = [];
+            for (let i = 0; i < texts.length; i++) {
+                results.push(Array.from(data.slice(i * embeddingSize, (i + 1) * embeddingSize)));
+            }
+            return results;
+        });
+    }
+}
+async function initTransformersPipeline(model) {
+    const { pipeline } = await import('@huggingface/transformers');
+    console.log(`[embedding] Loading local WASM model: ${model}`);
+    const start = performance.now();
+    const extractor = await pipeline('feature-extraction', model, { dtype: 'fp32' });
+    console.log(`[embedding] Model loaded in ${(performance.now() - start).toFixed(0)}ms`);
+    return extractor;
+}
+/** Create embedding provider from config. */
+function createEmbeddingProvider() {
+    const config = requireConfig();
+    switch (config.embeddingProvider) {
+        case 'openai':
+            return new OpenAICompatibleEmbedding(config.openaiApiKey, config.embeddingModel, undefined, config.embeddingDimensions);
+        case 'ollama':
+            return new OllamaEmbedding(config.embeddingModel, config.ollamaBaseUrl);
+        case 'openai-compatible':
+            return new OpenAICompatibleEmbedding(config.embeddingApiKey ?? config.openaiApiKey, config.embeddingModel, config.embeddingApiUrl, config.embeddingDimensions);
+        case 'transformers':
+            return new TransformersEmbedding(config.embeddingModel);
+        case 'voyage':
+            if (!config.voyageApiKey) {
+                throw new Error('VOYAGE_API_KEY is required when EMBEDDING_PROVIDER=voyage');
+            }
+            return new VoyageEmbedding(config, config.voyageApiKey, config.voyageDocumentModel, config.voyageQueryModel, config.embeddingDimensions);
+        default:
+            throw new Error(`Unknown embedding provider: ${config.embeddingProvider}`);
+    }
+}
+let provider = null;
+let providerKey = '';
+function setEmbeddingDimensions(dimensions) {
+    const config = requireConfig();
+    config.embeddingDimensions = dimensions;
+    provider = null;
+    providerKey = '';
+    embeddingCache.clear();
+}
+function effectiveModel(task) {
+    const config = requireConfig();
+    if (config.embeddingProvider === 'voyage') {
+        return task === 'query' ? config.voyageQueryModel : config.voyageDocumentModel;
+    }
+    return config.embeddingModel;
+}
+function endpointMarker() {
+    const config = requireConfig();
+    switch (config.embeddingProvider) {
+        case 'openai':
+            return 'openai:api.openai.com';
+        case 'openai-compatible':
+            return `compat:${config.embeddingApiUrl ?? ''}`;
+        case 'ollama':
+            return `ollama:${config.ollamaBaseUrl}`;
+        case 'transformers':
+            return 'transformers:local';
+        case 'voyage':
+            return `voyage:${VOYAGE_API_BASE}`;
+    }
+}
+function getProviderKey() {
+    const config = requireConfig();
+    return [
+        config.embeddingProvider,
+        config.embeddingDimensions,
+        endpointMarker(),
+        config.embeddingModel,
+        config.voyageDocumentModel,
+        config.voyageQueryModel,
+    ].join('|');
+}
+function getProvider() {
+    const nextKey = getProviderKey();
+    if (!provider || nextKey !== providerKey) {
+        provider = createEmbeddingProvider();
+        providerKey = nextKey;
+        embeddingCache.clear();
+    }
+    return provider;
+}
+/**
+ * Returns the instruction prefix required by certain embedding models.
+ * snowflake-arctic-embed2 and mxbai-embed-large are sensitive to these.
+ */
+function getInstructionPrefix(model, task) {
+    if (task === 'document')
+        return '';
+    if (model.includes('mxbai-embed-large')) {
+        // 0.838 similarity with this prefix vs 0.831 without.
+        return 'Represent this sentence for searching relevant passages: ';
+    }
+    if (model.includes('nomic-embed-text')) {
+        return 'search_query: ';
+    }
+    // snowflake-arctic-embed2 (Ollama v0.5.x) diagnostic showed significant
+    // regression with prefixes (0.80 -> 0.71). We use no prefix for this model.
+    return '';
+}
+/**
+ * LRU embedding cache — avoids redundant API calls for identical text within
+ * and across requests. The key includes provider, endpoint, model, dimensions,
+ * and task so query/document embeddings of the same text never collide.
+ */
+const EMBEDDING_CACHE_MAX = 512;
+const embeddingCache = new Map();
+function embeddingCacheKey(text, task) {
+    const config = requireConfig();
+    const parts = [
+        config.embeddingProvider,
+        effectiveModel(task),
+        String(config.embeddingDimensions),
+        endpointMarker(),
+        task,
+        text,
+    ].join('\0');
+    return createHash('sha256').update(parts).digest('hex').slice(0, 16);
+}
+function getCachedEmbedding(key) {
+    const cached = embeddingCache.get(key);
+    if (cached) {
+        // Move to end (most recently used)
+        embeddingCache.delete(key);
+        embeddingCache.set(key, cached);
+    }
+    return cached;
+}
+function setCachedEmbedding(key, embedding) {
+    if (embeddingCache.size >= EMBEDDING_CACHE_MAX) {
+        // Evict oldest (first entry)
+        const oldest = embeddingCache.keys().next().value;
+        if (oldest !== undefined)
+            embeddingCache.delete(oldest);
+    }
+    embeddingCache.set(key, embedding);
+}
+/**
+ * Disk-based embedding cache — persists embeddings across process restarts.
+ * Eliminates API transport variance and saves API calls during eval runs.
+ * Enabled via EMBEDDING_CACHE_ENABLED=true; reuses EXTRACTION_CACHE_DIR.
+ */
+function readDiskEmbedding(key) {
+    const config = requireConfig();
+    if (!config.embeddingCacheEnabled)
+        return null;
+    const filePath = join(config.extractionCacheDir, `emb-${key}.json`);
+    if (!existsSync(filePath))
+        return null;
+    return JSON.parse(readFileSync(filePath, 'utf-8'));
+}
+function writeDiskEmbedding(key, embedding) {
+    const config = requireConfig();
+    if (!config.embeddingCacheEnabled)
+        return;
+    mkdirSync(config.extractionCacheDir, { recursive: true });
+    const filePath = join(config.extractionCacheDir, `emb-${key}.json`);
+    const tmpPath = `${filePath}.tmp`;
+    writeFileSync(tmpPath, JSON.stringify(embedding), 'utf-8');
+    renameSync(tmpPath, filePath);
+}
+/** Embed a single text — primary API used throughout the codebase. */
+export async function embedText(text, task = 'document') {
+    const prefix = getInstructionPrefix(effectiveModel(task), task);
+    const finalInput = prefix + text;
+    const key = embeddingCacheKey(finalInput, task);
+    const cached = getCachedEmbedding(key);
+    if (cached)
+        return cached;
+    // Check disk cache before hitting the API
+    const diskCached = readDiskEmbedding(key);
+    if (diskCached) {
+        setCachedEmbedding(key, diskCached);
+        return diskCached;
+    }
+    const embedding = await getProvider().embed(finalInput, task);
+    setCachedEmbedding(key, embedding);
+    writeDiskEmbedding(key, embedding);
+    return embedding;
+}
+/** Embed multiple texts in one call, with per-text cache integration. */
+export async function embedTexts(texts, task = 'document') {
+    if (texts.length === 0)
+        return [];
+    const prefix = getInstructionPrefix(effectiveModel(task), task);
+    const inputs = texts.map((t) => prefix + t);
+    const keys = inputs.map((input) => embeddingCacheKey(input, task));
+    const results = keys.map((key) => getCachedEmbedding(key) ?? null);
+    const uncachedIndices = results.reduce((acc, r, i) => {
+        if (r === null)
+            acc.push(i);
+        return acc;
+    }, []);
+    if (uncachedIndices.length > 0) {
+        const uncachedInputs = uncachedIndices.map((i) => inputs[i]);
+        const freshEmbeddings = await getProvider().embedBatch(uncachedInputs, task);
+        for (let j = 0; j < uncachedIndices.length; j++) {
+            const idx = uncachedIndices[j];
+            results[idx] = freshEmbeddings[j];
+            setCachedEmbedding(keys[idx], freshEmbeddings[j]);
+        }
+    }
+    return results;
+}
+/** Get current cache size (for testing/monitoring). */
+export function getEmbeddingCacheSize() {
+    return embeddingCache.size;
+}
+/** Clear the embedding cache (for testing). */
+export function clearEmbeddingCache() {
+    embeddingCache.clear();
+}
+/**
+ * Detect the actual embedding width returned by the active provider.
+ * Some OpenAI-compatible backends ignore the requested dimensions parameter,
+ * so the database schema must align to the real vector width, not just config.
+ */
+export async function resolveEmbeddingDimensions() {
+    const config = requireConfig();
+    const p = getProvider();
+    console.log(`[embedding] resolveEmbeddingDimensions: using provider ${p.constructor.name} for model ${effectiveModel('document')}`);
+    const embedding = await p.embed('dimension probe', 'document');
+    const actualDimensions = embedding.length;
+    console.log(`[embedding] resolveEmbeddingDimensions: actual length returned is ${actualDimensions}`);
+    if (actualDimensions !== config.embeddingDimensions) {
+        console.warn(`[embedding] Configured EMBEDDING_DIMENSIONS=${config.embeddingDimensions}, provider returned ${actualDimensions}; using provider dimensions.`);
+        setEmbeddingDimensions(actualDimensions);
+    }
+    return actualDimensions;
+}
+export { cosineSimilarity } from '../vector-math.js';

package/dist/services/entity-attribute-extractor.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Entity-Attribute Index (EAI) extractor — Sprint 4.
+ *
+ * For each ingest with stored memories, runs an LLM pass that extracts
+ * (entity_name, attribute_key, attribute_value, value_type) quadruples
+ * from the conversation text. The triples populate the entity_attributes
+ * table for later lookup by specific-fact retrieval.
+ *
+ * Example extractions:
+ *   - "I added two columns: category and notes" →
+ *       (transactions_table, columns, "[category, notes]", list)
+ *       (transactions_table, columns_count, "2", number)
+ *   - "completed 25 problems with 90% accuracy" →
+ *       (problems, count, "25", number)
+ *       (problems, accuracy, "90%", string)
+ *
+ * Fire-and-forget from ingest. Fail-closed on parse errors (throws). The
+ * caller wraps in try/catch so failures never block the ingest path.
+ */
+import type { LLMProvider } from './llm.js';
+import type { MemoryServiceDeps } from './memory-service-types.js';
+import type { EntityAttributeInput } from '../db/repository-entity-attributes.js';
+export declare class EntityAttributeExtractorError extends Error {
+    readonly cause?: unknown | undefined;
+    constructor(message: string, cause?: unknown | undefined);
+}
+/** Extract triples from raw conversation text via the LLM. */
+export declare function extractEntityAttributes(conversationText: string, llmClient?: LLMProvider): Promise<Array<Omit<EntityAttributeInput, 'userId' | 'sourceMemoryId' | 'observedAt'>>>;
+/**
+ * Post-write fire-and-forget extractor. Pulls the conversation text + the
+ * stored memory IDs from the caller, runs the LLM pass, bulk-inserts.
+ * Errors are caught and logged; never throws to the caller.
+ */
+export declare function maybeExtractEntityAttributesForIngest(deps: MemoryServiceDeps, userId: string, conversationText: string, sessionTimestamp: Date | undefined, storedMemoryIds: string[]): Promise<number>;

package/dist/services/entity-attribute-extractor.js

@@ -0,0 +1,117 @@
+import { llm as defaultLlm } from './llm.js';
+import { extractFirstJsonObject } from './extraction.js';
+const EXTRACT_MAX_TOKENS = 1024;
+const MAX_TRIPLES_PER_CALL = 24;
+const MAX_INPUT_CHARS = 6000;
+const ALLOWED_VALUE_TYPES = new Set(['number', 'string', 'list', 'boolean', 'date']);
+const SYSTEM_PROMPT = [
+    'You extract (entity, attribute, value, value_type) quadruples from a user conversation.',
+    '',
+    'Rules:',
+    '- Each quadruple captures one specific fact the user stated or that the assistant confirmed about the user.',
+    '- entity_name: the noun phrase the fact is about (e.g. "transactions_table", "weather_app", "triangle_problems").',
+    '- attribute_key: a short snake_case key naming what is being measured/described (e.g. "columns_count", "accuracy", "features_list", "api_quota").',
+    '- attribute_value: the exact value as a string (e.g. "25", "90%", "category, notes", "1200/day", "true").',
+    '- value_type: one of: number, string, list, boolean, date.',
+    '- Extract specific facts: counts, names, dates, percentages, lists. Skip vague generalities.',
+    '- Do NOT speculate or infer beyond what the conversation directly states.',
+    '- Output a JSON object: {"triples": [{"entity_name": "...", "attribute_key": "...", "attribute_value": "...", "value_type": "..."}, ...]}.',
+    '- Output up to ' + String(MAX_TRIPLES_PER_CALL) + ' triples.',
+    '- No markdown fences. No prose around the JSON.',
+].join('\n');
+export class EntityAttributeExtractorError extends Error {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+        this.name = 'EntityAttributeExtractorError';
+    }
+}
+/** Extract triples from raw conversation text via the LLM. */
+export async function extractEntityAttributes(conversationText, llmClient = defaultLlm) {
+    const text = conversationText.slice(0, MAX_INPUT_CHARS);
+    if (text.trim().length === 0) {
+        throw new EntityAttributeExtractorError('empty input text');
+    }
+    const messages = [
+        { role: 'system', content: SYSTEM_PROMPT },
+        { role: 'user', content: 'CONVERSATION:\n' + text + '\n\nReturn JSON {"triples": [...]}.' },
+    ];
+    let raw;
+    try {
+        raw = await llmClient.chat(messages, {
+            temperature: 0,
+            jsonMode: true,
+            maxTokens: EXTRACT_MAX_TOKENS,
+        });
+    }
+    catch (err) {
+        throw new EntityAttributeExtractorError(`extractor LLM call failed: ${err.message}`, err);
+    }
+    if (!raw)
+        throw new EntityAttributeExtractorError('extractor returned empty content');
+    const cleaned = extractFirstJsonObject(raw);
+    let parsed;
+    try {
+        parsed = JSON.parse(cleaned);
+    }
+    catch (err) {
+        throw new EntityAttributeExtractorError(`extractor returned non-JSON: ${cleaned.slice(0, 200)}`, err);
+    }
+    if (!Array.isArray(parsed.triples)) {
+        throw new EntityAttributeExtractorError('extractor JSON missing "triples" array');
+    }
+    return parsed.triples.flatMap((t) => validateTriple(t));
+}
+function asTrimmedString(value) {
+    return typeof value === 'string' ? value.trim() : '';
+}
+function asValueType(value) {
+    if (typeof value !== 'string')
+        return null;
+    return ALLOWED_VALUE_TYPES.has(value) ? value : null;
+}
+function validateTriple(t) {
+    const entityName = asTrimmedString(t.entity_name);
+    const attributeKey = asTrimmedString(t.attribute_key);
+    const attributeValue = asTrimmedString(t.attribute_value);
+    const valueType = asValueType(t.value_type);
+    if (!entityName || !attributeKey || !attributeValue || !valueType)
+        return [];
+    return [{ entityName, attributeKey, attributeValue, valueType }];
+}
+/**
+ * Post-write fire-and-forget extractor. Pulls the conversation text + the
+ * stored memory IDs from the caller, runs the LLM pass, bulk-inserts.
+ * Errors are caught and logged; never throws to the caller.
+ */
+export async function maybeExtractEntityAttributesForIngest(deps, userId, conversationText, sessionTimestamp, storedMemoryIds) {
+    if (!deps.config.entityAttributesEnabled)
+        return 0;
+    const repo = deps.stores.entityAttributes;
+    if (!repo)
+        return 0;
+    if (storedMemoryIds.length === 0)
+        return 0;
+    try {
+        const triples = await extractEntityAttributes(conversationText);
+        if (triples.length === 0)
+            return 0;
+        const observedAt = sessionTimestamp ?? new Date();
+        const sourceMemoryId = storedMemoryIds[0]; // attribute provenance to the first new memory
+        const rows = triples.map((t) => ({
+            userId,
+            entityName: t.entityName,
+            attributeKey: t.attributeKey,
+            attributeValue: t.attributeValue,
+            valueType: t.valueType,
+            sourceMemoryId,
+            observedAt,
+        }));
+        return await repo.bulkInsert(rows);
+    }
+    catch (err) {
+        console.warn(`[eai] extraction failed for user=${userId}: ${err.message}`);
+        return 0;
+    }
+}

package/dist/services/entity-card-synthesis.d.ts

@@ -0,0 +1,54 @@
+/** One observation fed into entity grouping + card synthesis. */
+export interface ObservationForCard {
+    id: string;
+    text: string;
+    type: string;
+    observedAt: Date;
+}
+export interface EntityCardSynth {
+    entityName: string;
+    cardText: string;
+    sourceObservationIds: string[];
+}
+/** Schema for the tool-use call that returns the updated card text. */
+declare const ENTITY_CARD_TOOL_SCHEMA: {
+    readonly name: "record_entity_card";
+    readonly description: "Persist the updated entity card text.";
+    readonly input_schema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly card_text: {
+                readonly type: "string";
+            };
+        };
+        readonly required: readonly ["card_text"];
+    };
+};
+interface EntityCardToolOutput {
+    card_text: string;
+}
+/**
+ * Group observations by entity_name. The entity is extracted from
+ * entity_state observations whose text begins with "<EntityName>:" or
+ * a leading capitalized noun before the first colon/verb.
+ *
+ * Heuristic (simplified — see compromises in report): the first capitalized
+ * token sequence at the start of the observation text. The literal token
+ * "User" / "user" maps to the canonical entity "user".
+ */
+export declare function groupObservationsByEntity(observations: readonly ObservationForCard[]): Map<string, ObservationForCard[]>;
+export interface SynthesizeCardsDeps {
+    llmCallTool: (system: string, user: string, schema: typeof ENTITY_CARD_TOOL_SCHEMA) => Promise<EntityCardToolOutput>;
+    /** Minimum observations an entity needs before its card is synthesized. */
+    minObservations: number;
+    /** Max entities to synthesize per call (cost ceiling). */
+    maxEntities: number;
+}
+/**
+ * Synthesize ENTITY_CARDs for every entity with >= minObservations
+ * observations in the current Reflect run. Prior cards are looked up
+ * by entity_name; absent entities use the empty prior. Returns one
+ * EntityCardSynth per synthesized entity.
+ */
+export declare function synthesizeCards(observations: readonly ObservationForCard[], priorCards: ReadonlyMap<string, string>, deps: SynthesizeCardsDeps): Promise<EntityCardSynth[]>;
+export {};