agentikit 0.0.3 → 0.0.8

package/dist/src/config.d.ts

@@ -0,0 +1,31 @@
+export interface EmbeddingConnectionConfig {
+    /** OpenAI-compatible embeddings endpoint (e.g. "http://localhost:11434/v1/embeddings") */
+    endpoint: string;
+    /** Model name to use for embeddings (e.g. "nomic-embed-text") */
+    model: string;
+    /** Optional API key for authenticated endpoints */
+    apiKey?: string;
+}
+export interface LlmConnectionConfig {
+    /** OpenAI-compatible chat completions endpoint (e.g. "http://localhost:11434/v1/chat/completions") */
+    endpoint: string;
+    /** Model name to use (e.g. "llama3.2") */
+    model: string;
+    /** Optional API key for authenticated endpoints */
+    apiKey?: string;
+}
+export interface AgentikitConfig {
+    /** Whether semantic search is enabled. Default: true */
+    semanticSearch: boolean;
+    /** Additional stash directories to search alongside the primary one */
+    additionalStashDirs: string[];
+    /** OpenAI-compatible embedding endpoint config. If not set, uses local @xenova/transformers */
+    embedding?: EmbeddingConnectionConfig;
+    /** OpenAI-compatible LLM endpoint config for metadata generation. If not set, uses heuristic generation */
+    llm?: LlmConnectionConfig;
+}
+export declare const DEFAULT_CONFIG: AgentikitConfig;
+export declare function getConfigPath(stashDir: string): string;
+export declare function loadConfig(stashDir?: string): AgentikitConfig;
+export declare function saveConfig(config: AgentikitConfig, stashDir?: string): void;
+export declare function updateConfig(partial: Partial<AgentikitConfig>, stashDir?: string): AgentikitConfig;

package/dist/src/config.js

@@ -0,0 +1,74 @@
+import fs from "node:fs";
+import path from "node:path";
+import { resolveStashDir } from "./common";
+// ── Defaults ────────────────────────────────────────────────────────────────
+export const DEFAULT_CONFIG = {
+    semanticSearch: true,
+    additionalStashDirs: [],
+};
+// ── Paths ───────────────────────────────────────────────────────────────────
+export function getConfigPath(stashDir) {
+    return path.join(stashDir, "config.json");
+}
+// ── Load / Save / Update ────────────────────────────────────────────────────
+export function loadConfig(stashDir) {
+    const dir = stashDir ?? resolveStashDir();
+    const configPath = getConfigPath(dir);
+    let raw;
+    try {
+        raw = JSON.parse(fs.readFileSync(configPath, "utf8"));
+        if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+            return { ...DEFAULT_CONFIG };
+        }
+    }
+    catch {
+        return { ...DEFAULT_CONFIG };
+    }
+    return pickKnownKeys(raw);
+}
+export function saveConfig(config, stashDir) {
+    const dir = stashDir ?? resolveStashDir();
+    const configPath = getConfigPath(dir);
+    fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n", "utf8");
+}
+export function updateConfig(partial, stashDir) {
+    const dir = stashDir ?? resolveStashDir();
+    const current = loadConfig(dir);
+    const merged = { ...current, ...partial };
+    saveConfig(merged, dir);
+    return merged;
+}
+// ── Helpers ─────────────────────────────────────────────────────────────────
+function pickKnownKeys(raw) {
+    const config = { ...DEFAULT_CONFIG };
+    if (typeof raw.semanticSearch === "boolean") {
+        config.semanticSearch = raw.semanticSearch;
+    }
+    if (Array.isArray(raw.additionalStashDirs)) {
+        config.additionalStashDirs = raw.additionalStashDirs.filter((d) => typeof d === "string");
+    }
+    const embedding = parseConnectionConfig(raw.embedding);
+    if (embedding)
+        config.embedding = embedding;
+    const llm = parseConnectionConfig(raw.llm);
+    if (llm)
+        config.llm = llm;
+    return config;
+}
+function parseConnectionConfig(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return undefined;
+    const obj = value;
+    if (typeof obj.endpoint !== "string" || !obj.endpoint)
+        return undefined;
+    if (typeof obj.model !== "string" || !obj.model)
+        return undefined;
+    const result = {
+        endpoint: obj.endpoint,
+        model: obj.model,
+    };
+    if (typeof obj.apiKey === "string" && obj.apiKey) {
+        result.apiKey = obj.apiKey;
+    }
+    return result;
+}

package/dist/src/embedder.d.ts

@@ -0,0 +1,10 @@
+import type { EmbeddingConnectionConfig } from "./config";
+export type EmbeddingVector = number[];
+/**
+ * Generate an embedding for the given text.
+ * If embeddingConfig is provided, uses the configured OpenAI-compatible endpoint.
+ * Otherwise falls back to local @xenova/transformers.
+ */
+export declare function embed(text: string, embeddingConfig?: EmbeddingConnectionConfig): Promise<EmbeddingVector>;
+export declare function cosineSimilarity(a: EmbeddingVector, b: EmbeddingVector): number;
+export declare function isEmbeddingAvailable(embeddingConfig?: EmbeddingConnectionConfig): Promise<boolean>;

package/dist/src/embedder.js

@@ -0,0 +1,87 @@
+// ── Singleton local embedder ────────────────────────────────────────────────
+let localEmbedder;
+async function getLocalEmbedder() {
+    if (!localEmbedder) {
+        let pipeline;
+        try {
+            const mod = await import("@xenova/transformers");
+            pipeline = mod.pipeline;
+        }
+        catch {
+            throw new Error("Semantic search requires @xenova/transformers. Install it with: npm install @xenova/transformers");
+        }
+        localEmbedder = await pipeline("feature-extraction", "Xenova/all-MiniLM-L6-v2");
+    }
+    return localEmbedder;
+}
+async function embedLocal(text) {
+    const model = await getLocalEmbedder();
+    const result = await model(text, { pooling: "mean", normalize: true });
+    return Array.from(result.data);
+}
+// ── OpenAI-compatible remote embedder ───────────────────────────────────────
+async function embedRemote(text, config) {
+    const headers = { "Content-Type": "application/json" };
+    if (config.apiKey) {
+        headers["Authorization"] = `Bearer ${config.apiKey}`;
+    }
+    const response = await fetch(config.endpoint, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({
+            input: text,
+            model: config.model,
+        }),
+    });
+    if (!response.ok) {
+        const body = await response.text().catch(() => "");
+        throw new Error(`Embedding request failed (${response.status}): ${body}`);
+    }
+    const json = (await response.json());
+    if (!json.data?.[0]?.embedding) {
+        throw new Error("Unexpected embedding response format: missing data[0].embedding");
+    }
+    return json.data[0].embedding;
+}
+// ── Public API ──────────────────────────────────────────────────────────────
+/**
+ * Generate an embedding for the given text.
+ * If embeddingConfig is provided, uses the configured OpenAI-compatible endpoint.
+ * Otherwise falls back to local @xenova/transformers.
+ */
+export async function embed(text, embeddingConfig) {
+    if (embeddingConfig) {
+        return embedRemote(text, embeddingConfig);
+    }
+    return embedLocal(text);
+}
+// ── Similarity ──────────────────────────────────────────────────────────────
+export function cosineSimilarity(a, b) {
+    const len = Math.min(a.length, b.length);
+    if (len === 0)
+        return 0;
+    let dot = 0;
+    for (let i = 0; i < len; i++) {
+        dot += a[i] * b[i];
+    }
+    return dot;
+}
+// ── Availability check ──────────────────────────────────────────────────────
+export async function isEmbeddingAvailable(embeddingConfig) {
+    if (embeddingConfig) {
+        try {
+            await embedRemote("test", embeddingConfig);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    try {
+        await getLocalEmbedder();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/src/frontmatter.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Shared frontmatter parsing utilities.
+ *
+ * Provides a single, canonical YAML-subset frontmatter parser used by both
+ * the stash open logic and the metadata generator.
+ */
+/**
+ * Parse YAML-subset frontmatter from a Markdown (or similar) string.
+ *
+ * Returns the parsed key-value data and the remaining body content.
+ */
+export declare function parseFrontmatter(raw: string): {
+    data: Record<string, unknown>;
+    content: string;
+    frontmatter: string | null;
+    bodyStartLine: number;
+};
+export declare function parseFrontmatterBlock(raw: string): {
+    frontmatter: string;
+    content: string;
+    bodyStartLine: number;
+} | null;
+/**
+ * Parse a simple YAML scalar value (string, boolean, or number).
+ */
+export declare function parseYamlScalar(value: string): unknown;
+/**
+ * Coerce an unknown value to a trimmed string, or return undefined if empty/non-string.
+ */
+export declare function toStringOrUndefined(value: unknown): string | undefined;

package/dist/src/frontmatter.js

@@ -0,0 +1,86 @@
+/**
+ * Shared frontmatter parsing utilities.
+ *
+ * Provides a single, canonical YAML-subset frontmatter parser used by both
+ * the stash open logic and the metadata generator.
+ */
+/**
+ * Parse YAML-subset frontmatter from a Markdown (or similar) string.
+ *
+ * Returns the parsed key-value data and the remaining body content.
+ */
+export function parseFrontmatter(raw) {
+    const parsedBlock = parseFrontmatterBlock(raw);
+    if (!parsedBlock) {
+        return { data: {}, content: raw, frontmatter: null, bodyStartLine: 1 };
+    }
+    const data = {};
+    let currentKey = null;
+    let nested = null;
+    for (const line of parsedBlock.frontmatter.split(/\r?\n/)) {
+        const indented = line.match(/^  (\w[\w-]*):\s*(.+)$/);
+        if (indented && currentKey && nested) {
+            nested[indented[1]] = parseYamlScalar(indented[2].trim());
+            continue;
+        }
+        const top = line.match(/^(\w[\w-]*):\s*(.*)$/);
+        if (!top) {
+            continue;
+        }
+        currentKey = top[1];
+        const value = top[2].trim();
+        if (value === "") {
+            nested = {};
+            data[currentKey] = nested;
+        }
+        else {
+            nested = null;
+            data[currentKey] = parseYamlScalar(value);
+        }
+    }
+    return {
+        data,
+        content: parsedBlock.content,
+        frontmatter: parsedBlock.frontmatter,
+        bodyStartLine: parsedBlock.bodyStartLine,
+    };
+}
+export function parseFrontmatterBlock(raw) {
+    const match = raw.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
+    if (!match)
+        return null;
+    return {
+        frontmatter: match[1],
+        content: match[2],
+        bodyStartLine: countLines(raw.slice(0, match[0].length - match[2].length)) + 1,
+    };
+}
+function countLines(text) {
+    if (text.length === 0)
+        return 0;
+    return text.split(/\r?\n/).length - 1;
+}
+/**
+ * Parse a simple YAML scalar value (string, boolean, or number).
+ */
+export function parseYamlScalar(value) {
+    if (value === "")
+        return "";
+    if (value === "true")
+        return true;
+    if (value === "false")
+        return false;
+    const asNumber = Number(value);
+    if (!Number.isNaN(asNumber))
+        return asNumber;
+    if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+        return value.slice(1, -1);
+    }
+    return value;
+}
+/**
+ * Coerce an unknown value to a trimmed string, or return undefined if empty/non-string.
+ */
+export function toStringOrUndefined(value) {
+    return typeof value === "string" && value.trim() ? value : undefined;
+}

package/dist/src/indexer.d.ts

@@ -1,26 +1,44 @@
 import { type StashEntry } from "./metadata";
+import { type SerializedTfIdf } from "./similarity";
+import type { EmbeddingVector } from "./embedder";
 export interface IndexedEntry {
     entry: StashEntry;
     path: string;
     dirPath: string;
+    embedding?: EmbeddingVector;
 }
 export interface SearchIndex {
     version: number;
     builtAt: string;
     stashDir: string;
+    /** All stash directories that were indexed (primary + additional) */
+    stashDirs?: string[];
     entries: IndexedEntry[];
     /** Serialized TF-IDF state (term frequencies, idf values) */
-    tfidf?: unknown;
+    tfidf?: SerializedTfIdf;
+    /** Whether embeddings are included in entries */
+    hasEmbeddings?: boolean;
 }
 export interface IndexResponse {
     stashDir: string;
     totalEntries: number;
     generatedMetadata: number;
     indexPath: string;
+    mode: "full" | "incremental";
+    directoriesScanned: number;
+    directoriesSkipped: number;
+    /** Timing counters in milliseconds */
+    timing?: {
+        totalMs: number;
+        walkMs: number;
+        embedMs: number;
+        tfidfMs: number;
+    };
 }
 export declare function getIndexPath(): string;
 export declare function loadSearchIndex(): SearchIndex | null;
 export declare function agentikitIndex(options?: {
     stashDir?: string;
-}): IndexResponse;
+    full?: boolean;
+}): Promise<IndexResponse>;
 export declare function buildSearchText(entry: StashEntry): string;