keyring-agent-core 0.1.0

package/dist/llm/GeminiProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GeminiProvider.d.ts","sourceRoot":"","sources":["../../src/llm/GeminiProvider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,WAAW,EACX,WAAW,EACX,WAAW,EACX,iBAAiB,EACjB,WAAW,EAEX,cAAc,EACf,MAAM,UAAU,CAAC;AAqClB;;;GAGG;AACH,qBAAa,cAAe,YAAW,WAAW;IAChD,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,OAAO,CAAS;gBAEZ,MAAM,EAAE,iBAAiB;IAO/B,IAAI,CAAC,QAAQ,EAAE,WAAW,EAAE,EAAE,KAAK,CAAC,EAAE,cAAc,EAAE,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;IAsG1G,OAAO,CAAC,UAAU;IAwHlB,OAAO,CAAC,sBAAsB;CAgC/B"}

package/dist/llm/GeminiProvider.js

@@ -0,0 +1,248 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GeminiProvider = void 0;
+const PARAM_TYPE_MAP = {
+    string: 'STRING',
+    number: 'NUMBER',
+    boolean: 'BOOLEAN',
+    object: 'OBJECT',
+    array: 'ARRAY',
+};
+const DEFAULT_BASE_URL = 'https://nft-demo.keyring.app/api/gemini-stable';
+/**
+ * LLM provider that calls the Gemini-compatible proxy via fetch.
+ * No API key required — the proxy handles authentication.
+ */
+class GeminiProvider {
+    model;
+    maxTokens;
+    temperature;
+    baseUrl;
+    constructor(config) {
+        this.model = config.model ?? 'gemini-2.5-flash-lite';
+        this.maxTokens = config.maxTokens ?? 4096;
+        this.temperature = config.temperature ?? 1;
+        this.baseUrl = config.baseUrl ?? DEFAULT_BASE_URL;
+    }
+    async chat(messages, tools, options) {
+        const { systemInstruction, contents } = this.toContents(messages);
+        const { maxRetries = 5, retryDelayMs = 1000 } = options ?? {};
+        // Gemini rejects empty `contents`. If the caller only sent system
+        // message(s), synthesize a minimal user turn so the request is valid.
+        const safeContents = contents.length > 0 ? contents : [{ role: 'user', parts: [{ text: '(continue)' }] }];
+        // Debug: log the exact turn sequence so ordering violations are visible.
+        if (options?.['_debug']) {
+            console.log('[GeminiProvider] turn sequence:');
+            for (const c of safeContents) {
+                const partSummary = c.parts
+                    .map((p) => p.functionCall
+                    ? `fc:${p.functionCall.name}`
+                    : p.functionResponse
+                        ? `fr:${p.functionResponse.name}`
+                        : `text:${(p.text ?? '').slice(0, 40)}`)
+                    .join(', ');
+                console.log(`  ${c.role}: [${partSummary}]`);
+            }
+        }
+        const body = {
+            contents: safeContents,
+            generationConfig: {
+                maxOutputTokens: this.maxTokens,
+                temperature: this.temperature,
+            },
+        };
+        if (systemInstruction) {
+            body.systemInstruction = systemInstruction;
+        }
+        if (tools?.length) {
+            body.tools = [{ functionDeclarations: this.toFunctionDeclarations(tools) }];
+        }
+        else if (options?.googleSearch) {
+            body.tools = [{ googleSearch: {} }];
+        }
+        const url = `${this.baseUrl}/v1beta/models/${this.model}:generateContent`;
+        let lastError = 'Unknown error';
+        for (let attempt = 1; attempt <= maxRetries; attempt++) {
+            try {
+                const res = await fetch(url, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify(body),
+                });
+                if (!res.ok) {
+                    const errText = await res.text().catch(() => res.statusText);
+                    throw new Error(`Gemini proxy error ${res.status}: ${errText}`);
+                }
+                const data = (await res.json());
+                const candidate = data.candidates?.[0];
+                if (!candidate) {
+                    return { text: '', toolCalls: [] };
+                }
+                let text = '';
+                const toolCalls = [];
+                for (const part of candidate.content.parts) {
+                    if (part.text) {
+                        text += part.text;
+                    }
+                    if (part.functionCall) {
+                        toolCalls.push({
+                            toolName: part.functionCall.name,
+                            args: part.functionCall.args ?? {},
+                            callId: part.functionCall.id ?? `call_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`,
+                        });
+                    }
+                }
+                const usage = data.usageMetadata
+                    ? {
+                        promptTokens: data.usageMetadata.promptTokenCount ?? 0,
+                        completionTokens: data.usageMetadata.candidatesTokenCount ?? 0,
+                        totalTokens: data.usageMetadata.totalTokenCount ?? 0,
+                    }
+                    : undefined;
+                return { text, toolCalls, usage };
+            }
+            catch (error) {
+                lastError = error instanceof Error ? error.message : String(error);
+                if (attempt < maxRetries)
+                    await new Promise((r) => setTimeout(r, retryDelayMs));
+            }
+        }
+        throw new Error(lastError);
+    }
+    // ---- helpers ----
+    toContents(messages) {
+        const systemParts = [];
+        const raw = [];
+        for (const msg of messages) {
+            if (msg.role === 'system') {
+                systemParts.push(msg.content);
+                continue;
+            }
+            if (msg.role === 'tool') {
+                raw.push({
+                    role: 'function',
+                    parts: [
+                        {
+                            functionResponse: {
+                                name: msg.toolName ?? 'unknown',
+                                response: { result: msg.content },
+                                ...(msg.toolCallId ? { id: msg.toolCallId } : {}),
+                            },
+                        },
+                    ],
+                });
+                continue;
+            }
+            if (msg.role === 'assistant' && msg.toolCalls?.length) {
+                // functionCall parts MUST be in their own model turn — never merged
+                // with text parts, because Gemini requires functionCall to be the
+                // only content in that turn.
+                raw.push({
+                    role: 'model',
+                    parts: msg.toolCalls.map((tc) => ({
+                        functionCall: {
+                            name: tc.toolName,
+                            args: tc.args,
+                            ...(tc.callId ? { id: tc.callId } : {}),
+                        },
+                    })),
+                });
+                continue;
+            }
+            raw.push({
+                role: msg.role === 'assistant' ? 'model' : 'user',
+                parts: [{ text: msg.content }],
+            });
+        }
+        // Merge consecutive messages with the same role (Gemini rejects them),
+        // BUT never merge a functionCall model turn with a plain text model turn —
+        // Gemini requires functionCall to be the sole content in its turn.
+        const merged = [];
+        for (const item of raw) {
+            const last = merged[merged.length - 1];
+            const itemHasFunctionCall = item.parts.some((p) => p.functionCall);
+            const lastHasFunctionCall = last?.parts.some((p) => p.functionCall);
+            if (last && last.role === item.role && !itemHasFunctionCall && !lastHasFunctionCall) {
+                last.parts.push(...item.parts);
+            }
+            else {
+                merged.push({ ...item, parts: [...item.parts] });
+            }
+        }
+        // Enforce Gemini turn-order rules by dropping invalid messages:
+        //   1. A 'function' turn must be immediately preceded by a 'model' turn
+        //      that contains functionCall parts.
+        //   2. A 'model' turn with functionCall must not be the last turn
+        //      (the LLM needs to respond after, not hang).
+        // We fix violations by dropping the offending message rather than
+        // crashing — the LLM will work with less context instead of erroring.
+        const contents = [];
+        for (let i = 0; i < merged.length; i++) {
+            const item = merged[i];
+            const prev = contents[contents.length - 1];
+            if (item.role === 'function') {
+                const prevHasFunctionCall = prev?.parts.some((p) => p.functionCall);
+                if (!prevHasFunctionCall) {
+                    // Orphan function response — drop it to avoid 400
+                    continue;
+                }
+            }
+            if (item.role === 'model') {
+                const hasFunctionCall = item.parts.some((p) => p.functionCall);
+                if (hasFunctionCall) {
+                    // Look ahead: if no function response follows, drop this turn
+                    // because an unanswered functionCall at the end of history is invalid.
+                    const nextIsFunctionResponse = merged[i + 1]?.role === 'function';
+                    if (!nextIsFunctionResponse) {
+                        continue;
+                    }
+                }
+            }
+            contents.push(item);
+        }
+        // Gemini requires the last turn to be 'user' or 'function'.
+        // If the last content is a 'model' text turn, it's safe to keep (the API
+        // will respond to it). But a trailing 'model(functionCall)' was already
+        // dropped above. No further action needed.
+        // Gemini requires contents[0] to be 'user'. If the history slice starts
+        // with model/function turns (e.g. when a history window starts mid tool
+        // exchange), drop leading turns until we reach the first 'user' turn.
+        while (contents.length > 0 && contents[0].role !== 'user') {
+            contents.shift();
+        }
+        const systemInstruction = systemParts.length ? { role: 'user', parts: [{ text: systemParts.join('\n') }] } : null;
+        return { systemInstruction, contents };
+    }
+    toFunctionDeclarations(tools) {
+        return tools.map((tool) => {
+            const properties = {};
+            const required = [];
+            for (const param of tool.parameters) {
+                const prop = {
+                    type: PARAM_TYPE_MAP[param.type] ?? 'STRING',
+                    description: param.description,
+                };
+                if (param.type === 'array') {
+                    prop.items = {
+                        type: PARAM_TYPE_MAP[param.items?.type ?? 'string'] ?? 'STRING',
+                    };
+                }
+                properties[param.name] = prop;
+                if (param.required) {
+                    required.push(param.name);
+                }
+            }
+            return {
+                name: tool.name,
+                description: tool.description,
+                parameters: {
+                    type: 'OBJECT',
+                    properties,
+                    required,
+                },
+            };
+        });
+    }
+}
+exports.GeminiProvider = GeminiProvider;
+//# sourceMappingURL=GeminiProvider.js.map

package/dist/llm/GeminiProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GeminiProvider.js","sourceRoot":"","sources":["../../src/llm/GeminiProvider.ts"],"names":[],"mappings":"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"}

package/dist/llm/index.d.ts

@@ -0,0 +1,2 @@
+export { GeminiProvider } from './GeminiProvider';
+//# sourceMappingURL=index.d.ts.map

package/dist/llm/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/llm/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/llm/index.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GeminiProvider = void 0;
+var GeminiProvider_1 = require("./GeminiProvider");
+Object.defineProperty(exports, "GeminiProvider", { enumerable: true, get: function () { return GeminiProvider_1.GeminiProvider; } });
+//# sourceMappingURL=index.js.map

package/dist/llm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/llm/index.ts"],"names":[],"mappings":";;;AAAA,mDAAkD;AAAzC,gHAAA,cAAc,OAAA"}

package/dist/memory/ChatHistory.d.ts

@@ -0,0 +1,83 @@
+import type { ChatMessage } from '../types';
+/**
+ * Manages conversation history for a single session.
+ *
+ * Two parallel stores:
+ *  - `messages`     — working window for the LLM (gets compacted when too long)
+ *  - `fullMessages` — append-only log of every message (never truncated, for UI export)
+ *
+ * Summary is kept separately so it never conflicts with component system prompts.
+ */
+export declare class ChatHistory {
+    private messages;
+    private fullMessages;
+    private summary;
+    private maxMessages;
+    constructor(maxMessages?: number);
+    /** Add a message to the history. */
+    add(message: ChatMessage): void;
+    /** Add multiple messages. */
+    addMany(messages: ChatMessage[]): void;
+    /**
+     * Add a message to the UI log only — does NOT enter the working window.
+     * Use for KB-answered turns: the user still sees them in the chat UI, but
+     * they never pollute the LLM context that subagents and the router analyze.
+     */
+    addUIOnly(message: ChatMessage): void;
+    /**
+     * Remove the last message from the working window without touching fullMessages.
+     * Used to roll back an addUserMessage() when the turn is handled by KB and
+     * should not enter the LLM working context.
+     */
+    rollbackLastWorkingMessage(): void;
+    /** Get the working message window (may be compacted). */
+    getAll(): ChatMessage[];
+    /** Get the complete untruncated message history (for UI export). */
+    getAllFull(): ChatMessage[];
+    /** Get the last N messages. */
+    getRecent(n: number): ChatMessage[];
+    /**
+     * Get conversation messages for LLM consumption.
+     * Prepends summary (if any) as a system message, then the working window.
+     */
+    getConversation(): ChatMessage[];
+    /** Total message count (working window). */
+    get length(): number;
+    /**
+     * Whether the history should be summarized.
+     *
+     * Counts logical turns (user messages) rather than raw message count.
+     * Tool call/response pairs and _intermediate bridge messages inflate the
+     * raw count significantly per turn, so checking messages.length would
+     * trigger compaction far too early.
+     */
+    needsSummary(): boolean;
+    /** Current summary text (if any). */
+    getSummary(): string | null;
+    /**
+     * Compact the working window: keep only the last N messages and store the
+     * summary. fullMessages is never touched.
+     */
+    compact(summary: string, keepLast?: number): void;
+    /**
+     * Compact using an explicit tail slice — the caller has already decided
+     * which messages to keep (e.g. to avoid splitting a tool-call group).
+     * fullMessages is never touched.
+     */
+    compactWith(summary: string, keepTail: ChatMessage[]): void;
+    /** Clear all history and summary (both working window and full log). */
+    clear(): void;
+    /** Serialise to JSON-safe object (for persistence). */
+    serialise(): {
+        messages: ChatMessage[];
+        summary: string | null;
+        fullMessages: ChatMessage[];
+    };
+    /** Restore from a serialised object. */
+    restore(data: {
+        messages: ChatMessage[];
+        summary?: string | null;
+        fullMessages?: ChatMessage[];
+    } | ChatMessage[]): void;
+}
+//# sourceMappingURL=ChatHistory.d.ts.map

package/dist/memory/ChatHistory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ChatHistory.d.ts","sourceRoot":"","sources":["../../src/memory/ChatHistory.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAE5C;;;;;;;;GAQG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAqB;IACrC,OAAO,CAAC,YAAY,CAAqB;IACzC,OAAO,CAAC,OAAO,CAAuB;IACtC,OAAO,CAAC,WAAW,CAAS;gBAEhB,WAAW,SAAK;IAI5B,oCAAoC;IACpC,GAAG,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI;IAK/B,6BAA6B;IAC7B,OAAO,CAAC,QAAQ,EAAE,WAAW,EAAE,GAAG,IAAI;IAKtC;;;;OAIG;IACH,SAAS,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI;IAIrC;;;;OAIG;IACH,0BAA0B,IAAI,IAAI;IAIlC,yDAAyD;IACzD,MAAM,IAAI,WAAW,EAAE;IAIvB,oEAAoE;IACpE,UAAU,IAAI,WAAW,EAAE;IAI3B,+BAA+B;IAC/B,SAAS,CAAC,CAAC,EAAE,MAAM,GAAG,WAAW,EAAE;IAInC;;;OAGG;IACH,eAAe,IAAI,WAAW,EAAE;IAahC,4CAA4C;IAC5C,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED;;;;;;;OAOG;IACH,YAAY,IAAI,OAAO;IAKvB,qCAAqC;IACrC,UAAU,IAAI,MAAM,GAAG,IAAI;IAI3B;;;OAGG;IACH,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,SAAK,GAAG,IAAI;IAK7C;;;;OAIG;IACH,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,WAAW,EAAE,GAAG,IAAI;IAK3D,wEAAwE;IACxE,KAAK,IAAI,IAAI;IAMb,uDAAuD;IACvD,SAAS,IAAI;QAAE,QAAQ,EAAE,WAAW,EAAE,CAAC;QAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,YAAY,EAAE,WAAW,EAAE,CAAA;KAAE;IAQ7F,wCAAwC;IACxC,OAAO,CACL,IAAI,EAAE;QAAE,QAAQ,EAAE,WAAW,EAAE,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,YAAY,CAAC,EAAE,WAAW,EAAE,CAAA;KAAE,GAAG,WAAW,EAAE,GACvG,IAAI;CAaR"}

package/dist/memory/ChatHistory.js

@@ -0,0 +1,143 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ChatHistory = void 0;
+/**
+ * Manages conversation history for a single session.
+ *
+ * Two parallel stores:
+ *  - `messages`     — working window for the LLM (gets compacted when too long)
+ *  - `fullMessages` — append-only log of every message (never truncated, for UI export)
+ *
+ * Summary is kept separately so it never conflicts with component system prompts.
+ */
+class ChatHistory {
+    messages = [];
+    fullMessages = [];
+    summary = null;
+    maxMessages;
+    constructor(maxMessages = 50) {
+        this.maxMessages = maxMessages;
+    }
+    /** Add a message to the history. */
+    add(message) {
+        this.messages.push(message);
+        this.fullMessages.push(message);
+    }
+    /** Add multiple messages. */
+    addMany(messages) {
+        this.messages.push(...messages);
+        this.fullMessages.push(...messages);
+    }
+    /**
+     * Add a message to the UI log only — does NOT enter the working window.
+     * Use for KB-answered turns: the user still sees them in the chat UI, but
+     * they never pollute the LLM context that subagents and the router analyze.
+     */
+    addUIOnly(message) {
+        this.fullMessages.push(message);
+    }
+    /**
+     * Remove the last message from the working window without touching fullMessages.
+     * Used to roll back an addUserMessage() when the turn is handled by KB and
+     * should not enter the LLM working context.
+     */
+    rollbackLastWorkingMessage() {
+        this.messages.pop();
+    }
+    /** Get the working message window (may be compacted). */
+    getAll() {
+        return [...this.messages];
+    }
+    /** Get the complete untruncated message history (for UI export). */
+    getAllFull() {
+        return [...this.fullMessages];
+    }
+    /** Get the last N messages. */
+    getRecent(n) {
+        return this.messages.slice(-n);
+    }
+    /**
+     * Get conversation messages for LLM consumption.
+     * Prepends summary (if any) as a system message, then the working window.
+     */
+    getConversation() {
+        const out = [];
+        if (this.summary) {
+            out.push({
+                role: 'system',
+                content: `[Previous conversation summary]: ${this.summary}`,
+                timestamp: 0,
+            });
+        }
+        out.push(...this.messages);
+        return out;
+    }
+    /** Total message count (working window). */
+    get length() {
+        return this.messages.length;
+    }
+    /**
+     * Whether the history should be summarized.
+     *
+     * Counts logical turns (user messages) rather than raw message count.
+     * Tool call/response pairs and _intermediate bridge messages inflate the
+     * raw count significantly per turn, so checking messages.length would
+     * trigger compaction far too early.
+     */
+    needsSummary() {
+        const userTurns = this.messages.filter((m) => m.role === 'user').length;
+        return userTurns > this.maxMessages;
+    }
+    /** Current summary text (if any). */
+    getSummary() {
+        return this.summary;
+    }
+    /**
+     * Compact the working window: keep only the last N messages and store the
+     * summary. fullMessages is never touched.
+     */
+    compact(summary, keepLast = 10) {
+        this.summary = summary;
+        this.messages = this.messages.slice(-keepLast);
+    }
+    /**
+     * Compact using an explicit tail slice — the caller has already decided
+     * which messages to keep (e.g. to avoid splitting a tool-call group).
+     * fullMessages is never touched.
+     */
+    compactWith(summary, keepTail) {
+        this.summary = summary;
+        this.messages = [...keepTail];
+    }
+    /** Clear all history and summary (both working window and full log). */
+    clear() {
+        this.messages = [];
+        this.fullMessages = [];
+        this.summary = null;
+    }
+    /** Serialise to JSON-safe object (for persistence). */
+    serialise() {
+        return {
+            messages: [...this.messages],
+            summary: this.summary,
+            fullMessages: [...this.fullMessages],
+        };
+    }
+    /** Restore from a serialised object. */
+    restore(data) {
+        if (Array.isArray(data)) {
+            // Backward compatible: plain array
+            this.messages = [...data];
+            this.fullMessages = [...data];
+            this.summary = null;
+        }
+        else {
+            this.messages = [...data.messages];
+            this.summary = data.summary ?? null;
+            // Backward compatible: if fullMessages not present, seed from messages
+            this.fullMessages = data.fullMessages ? [...data.fullMessages] : [...data.messages];
+        }
+    }
+}
+exports.ChatHistory = ChatHistory;
+//# sourceMappingURL=ChatHistory.js.map

package/dist/memory/ChatHistory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ChatHistory.js","sourceRoot":"","sources":["../../src/memory/ChatHistory.ts"],"names":[],"mappings":"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"}

package/dist/memory/KnowledgeBase.d.ts

@@ -0,0 +1,38 @@
+import type { KBSearchResult, KnowledgeBaseEntry, KnowledgeBaseProvider, LLMProvider } from '../types';
+export type { KBSearchResult };
+/**
+ * Knowledge base with LLM-powered semantic matching.
+ * Supports cross-language queries and synonym understanding.
+ *
+ * Suitable for small KBs (≲ 50 entries) — every search sends the full FAQ
+ * list to the LLM. For larger KBs use `UpstashKnowledgeBase` (vector search).
+ */
+export declare class KnowledgeBase implements KnowledgeBaseProvider {
+    private entries;
+    private llm;
+    constructor(entries?: KnowledgeBaseEntry[]);
+    /** Attach an LLM provider for semantic matching. */
+    setLLM(llm: LLMProvider): void;
+    /** Replace all entries. */
+    setEntries(entries: KnowledgeBaseEntry[]): void;
+    /** Add entries without replacing existing ones. */
+    addEntries(entries: KnowledgeBaseEntry[]): void;
+    /** Snapshot of current entries (defensive copy). */
+    getEntries(): KnowledgeBaseEntry[];
+    /** Get total entry count. */
+    get size(): number;
+    /**
+     * Search for entries relevant to the user query using LLM semantic matching.
+     * Falls back to basic token matching if LLM is not available.
+     */
+    search(query: string, maxResults?: number): Promise<KBSearchResult[]>;
+    /** LLM-based semantic search — handles any language + synonyms. */
+    private llmSearch;
+    /** Basic token-overlap search (fallback). */
+    private tokenSearch;
+    /** Tokenize text into a set of normalized words. */
+    private tokenize;
+    /** Jaccard similarity: |A ∩ B| / |A ∪ B| */
+    private jaccardSimilarity;
+}
+//# sourceMappingURL=KnowledgeBase.d.ts.map

package/dist/memory/KnowledgeBase.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"KnowledgeBase.d.ts","sourceRoot":"","sources":["../../src/memory/KnowledgeBase.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,WAAW,EAAe,MAAM,UAAU,CAAC;AAGpH,YAAY,EAAE,cAAc,EAAE,CAAC;AAmB/B;;;;;;GAMG;AACH,qBAAa,aAAc,YAAW,qBAAqB;IACzD,OAAO,CAAC,OAAO,CAA4B;IAC3C,OAAO,CAAC,GAAG,CAA4B;gBAE3B,OAAO,CAAC,EAAE,kBAAkB,EAAE;IAI1C,oDAAoD;IACpD,MAAM,CAAC,GAAG,EAAE,WAAW,GAAG,IAAI;IAI9B,2BAA2B;IAC3B,UAAU,CAAC,OAAO,EAAE,kBAAkB,EAAE,GAAG,IAAI;IAI/C,mDAAmD;IACnD,UAAU,CAAC,OAAO,EAAE,kBAAkB,EAAE,GAAG,IAAI;IAI/C,oDAAoD;IACpD,UAAU,IAAI,kBAAkB,EAAE;IAIlC,6BAA6B;IAC7B,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;;OAGG;IACG,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,SAAI,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IAWtE,mEAAmE;YACrD,SAAS;IAqCvB,6CAA6C;IAC7C,OAAO,CAAC,WAAW;IAmBnB,oDAAoD;IACpD,OAAO,CAAC,QAAQ;IAShB,4CAA4C;IAC5C,OAAO,CAAC,iBAAiB;CAW1B"}