@spark-agents/engram 0.1.0

package/dist/config.d.ts

@@ -0,0 +1,19 @@
+import { type EngramConfig, type MediaModality } from "./types.js";
+export interface ResolvedConfig {
+    geminiApiKey?: string;
+    dimensions: 768 | 1536 | 3072;
+    chunkTokens: number;
+    chunkOverlap: number;
+    reranking: boolean;
+    timeDecay: {
+        enabled: boolean;
+        halfLifeDays: number;
+    };
+    maxSessionShare: number;
+    multimodal: {
+        enabled: boolean;
+        modalities: MediaModality[];
+        maxFileBytes: number;
+    };
+}
+export declare function resolveConfig(raw?: EngramConfig | Record<string, unknown>): ResolvedConfig;

package/dist/config.js

@@ -0,0 +1,38 @@
+import { DEFAULT_CONFIG } from "./types.js";
+const DEFAULT_MAX_MEDIA_FILE_BYTES = 10 * 1024 * 1024;
+const DEFAULT_MEDIA_MODALITIES = ["image", "audio"];
+function normalizeMediaModalities(modalities) {
+    if (!Array.isArray(modalities) || modalities.length === 0) {
+        return [...DEFAULT_MEDIA_MODALITIES];
+    }
+    const unique = new Set();
+    for (const modality of modalities) {
+        if (modality === "image" || modality === "audio") {
+            unique.add(modality);
+        }
+    }
+    if (unique.size === 0) {
+        return [...DEFAULT_MEDIA_MODALITIES];
+    }
+    return Array.from(unique);
+}
+export function resolveConfig(raw) {
+    const cfg = (raw ?? {});
+    return {
+        geminiApiKey: cfg.geminiApiKey,
+        dimensions: cfg.dimensions ?? DEFAULT_CONFIG.dimensions,
+        chunkTokens: cfg.chunkTokens ?? DEFAULT_CONFIG.chunkTokens,
+        chunkOverlap: cfg.chunkOverlap ?? DEFAULT_CONFIG.chunkOverlap,
+        reranking: cfg.reranking ?? true,
+        timeDecay: {
+            enabled: cfg.timeDecay?.enabled ?? DEFAULT_CONFIG.timeDecay.enabled,
+            halfLifeDays: cfg.timeDecay?.halfLifeDays ?? DEFAULT_CONFIG.timeDecay.halfLifeDays,
+        },
+        maxSessionShare: cfg.maxSessionShare ?? DEFAULT_CONFIG.maxSessionShare,
+        multimodal: {
+            enabled: cfg.multimodal?.enabled ?? true,
+            modalities: normalizeMediaModalities(cfg.multimodal?.modalities),
+            maxFileBytes: Math.max(1, Math.trunc(cfg.multimodal?.maxFileBytes ?? DEFAULT_MAX_MEDIA_FILE_BYTES)),
+        },
+    };
+}

package/dist/embedding.d.ts

@@ -0,0 +1,8 @@
+import type { EmbeddingClient } from "./types.js";
+export declare function l2Normalize(vec: Float32Array): Float32Array;
+export declare function createEmbeddingClient(params: {
+    apiKey: string;
+    dimensions?: number;
+    model?: string;
+    baseUrl?: string;
+}): Promise<EmbeddingClient>;

package/dist/embedding.js

@@ -0,0 +1,186 @@
+const GEMINI_DEFAULT_BASE_URL = "https://generativelanguage.googleapis.com";
+const GEMINI_DEFAULT_MODEL = "gemini-embedding-2-preview";
+const DEFAULT_DIMENSIONS = 768;
+const MAX_BATCH_SIZE = 100;
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function normalizeModelName(model) {
+    return model.startsWith("models/") ? model.slice("models/".length) : model;
+}
+function modelResourceName(model) {
+    return model.startsWith("models/") ? model : `models/${model}`;
+}
+function getNumberArray(value, context) {
+    if (!Array.isArray(value)) {
+        throw new Error(`${context} must be an array`);
+    }
+    const out = new Array(value.length);
+    for (let i = 0; i < value.length; i++) {
+        const item = value[i];
+        if (typeof item !== "number") {
+            throw new Error(`${context} contains a non-number value at index ${i}`);
+        }
+        out[i] = item;
+    }
+    return out;
+}
+function toGeminiVector(values, dimensions) {
+    const vec = Float32Array.from(values);
+    if (dimensions < 3072) {
+        return l2Normalize(vec);
+    }
+    return vec;
+}
+function buildGeminiEndpoint(params) {
+    const root = params.baseUrl.replace(/\/+$/, "");
+    return `${root}/v1beta/models/${params.model}:${params.method}?key=${encodeURIComponent(params.apiKey)}`;
+}
+function sleep(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+async function postJsonWithRetry(params) {
+    for (let attempt = 0; attempt < 2; attempt++) {
+        const response = await fetch(params.url, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                ...(params.headers ?? {}),
+            },
+            body: JSON.stringify(params.body),
+        });
+        if (response.status === 429 && attempt === 0) {
+            await sleep(1000);
+            continue;
+        }
+        if (!response.ok) {
+            const responseBody = await response.text();
+            throw new Error(`${params.providerName} embedding request failed (${response.status}): ${responseBody || "<empty response body>"}`);
+        }
+        return (await response.json());
+    }
+    throw new Error(`${params.providerName} embedding request failed after retry`);
+}
+function parseGeminiEmbeddingResponse(response, dimensions) {
+    if (!isRecord(response)) {
+        throw new Error("Gemini embedding response must be an object");
+    }
+    const embedding = response.embedding;
+    if (!isRecord(embedding)) {
+        throw new Error("Gemini embedding response missing embedding object");
+    }
+    return toGeminiVector(getNumberArray(embedding.values, "embedding.values"), dimensions);
+}
+export function l2Normalize(vec) {
+    let norm = 0;
+    for (let i = 0; i < vec.length; i++)
+        norm += vec[i] * vec[i];
+    norm = Math.sqrt(norm);
+    if (norm === 0)
+        return vec;
+    const out = new Float32Array(vec.length);
+    for (let i = 0; i < vec.length; i++)
+        out[i] = vec[i] / norm;
+    return out;
+}
+export async function createEmbeddingClient(params) {
+    const model = normalizeModelName(params.model ?? GEMINI_DEFAULT_MODEL);
+    const dimensions = params.dimensions ?? DEFAULT_DIMENSIONS;
+    const baseUrl = params.baseUrl ?? GEMINI_DEFAULT_BASE_URL;
+    const embedText = async (text, taskType) => {
+        const endpoint = buildGeminiEndpoint({
+            baseUrl,
+            model,
+            method: "embedContent",
+            apiKey: params.apiKey,
+        });
+        const body = {
+            content: {
+                parts: [{ text }],
+            },
+            taskType,
+            outputDimensionality: dimensions,
+        };
+        const response = await postJsonWithRetry({
+            url: endpoint,
+            body,
+            providerName: "Gemini",
+        });
+        return parseGeminiEmbeddingResponse(response, dimensions);
+    };
+    const embedMedia = async (data, mimeType) => {
+        const endpoint = buildGeminiEndpoint({
+            baseUrl,
+            model,
+            method: "embedContent",
+            apiKey: params.apiKey,
+        });
+        const body = {
+            content: {
+                parts: [{ inlineData: { data: data.toString("base64"), mimeType } }],
+            },
+            taskType: "RETRIEVAL_DOCUMENT",
+            outputDimensionality: dimensions,
+        };
+        const response = await postJsonWithRetry({
+            url: endpoint,
+            body,
+            providerName: "Gemini",
+        });
+        return parseGeminiEmbeddingResponse(response, dimensions);
+    };
+    const embedBatch = async (texts, taskType) => {
+        if (texts.length === 0) {
+            return [];
+        }
+        const endpoint = buildGeminiEndpoint({
+            baseUrl,
+            model,
+            method: "batchEmbedContents",
+            apiKey: params.apiKey,
+        });
+        const vectors = [];
+        for (let i = 0; i < texts.length; i += MAX_BATCH_SIZE) {
+            const chunk = texts.slice(i, i + MAX_BATCH_SIZE);
+            const body = {
+                requests: chunk.map((text) => ({
+                    model: modelResourceName(model),
+                    content: {
+                        parts: [{ text }],
+                    },
+                    taskType,
+                    outputDimensionality: dimensions,
+                })),
+            };
+            const response = await postJsonWithRetry({
+                url: endpoint,
+                body,
+                providerName: "Gemini",
+            });
+            if (!isRecord(response) || !Array.isArray(response.embeddings)) {
+                throw new Error("Gemini batch embedding response missing embeddings array");
+            }
+            if (response.embeddings.length !== chunk.length) {
+                throw new Error(`Gemini batch embedding response count mismatch: expected ${chunk.length}, got ${response.embeddings.length}`);
+            }
+            for (let j = 0; j < response.embeddings.length; j++) {
+                const embedding = response.embeddings[j];
+                if (!isRecord(embedding)) {
+                    throw new Error(`Gemini batch embedding at index ${j} is not an object`);
+                }
+                vectors.push(toGeminiVector(getNumberArray(embedding.values, `embeddings[${j}].values`), dimensions));
+            }
+        }
+        return vectors;
+    };
+    return {
+        embedText,
+        embedBatch,
+        embedMedia,
+        supportsMultimodal: true,
+        dimensions,
+        model,
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+import { type ResolvedConfig } from "./config.js";
+type OpenClawApi = any;
+interface CliAgentConfig {
+    id: string;
+    workspace: string;
+    agentDir: string;
+}
+export declare function resolveAgentsFromConfig(clawConfig: any, agentFilter?: string): CliAgentConfig[];
+export declare function registerEngramCli(program: any, api: OpenClawApi, config: ResolvedConfig, clawConfig: any): void;
+declare const engramPlugin: {
+    id: string;
+    name: string;
+    description: string;
+    kind: "memory";
+    register(api: OpenClawApi): void;
+};
+export default engramPlugin;