agentikit 0.0.7 → 0.0.8

package/src/config.ts

@@ -0,0 +1,124 @@
+import fs from "node:fs"
+import path from "node:path"
+import { resolveStashDir } from "./common"
+
+// ── Types ───────────────────────────────────────────────────────────────────
+
+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
+}
+
+// ── Defaults ────────────────────────────────────────────────────────────────
+
+export const DEFAULT_CONFIG: AgentikitConfig = {
+  semanticSearch: true,
+  additionalStashDirs: [],
+}
+
+// ── Paths ───────────────────────────────────────────────────────────────────
+
+export function getConfigPath(stashDir: string): string {
+  return path.join(stashDir, "config.json")
+}
+
+// ── Load / Save / Update ────────────────────────────────────────────────────
+
+export function loadConfig(stashDir?: string): AgentikitConfig {
+  const dir = stashDir ?? resolveStashDir()
+  const configPath = getConfigPath(dir)
+
+  let raw: Record<string, unknown>
+  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: AgentikitConfig, stashDir?: string): void {
+  const dir = stashDir ?? resolveStashDir()
+  const configPath = getConfigPath(dir)
+  fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n", "utf8")
+}
+
+export function updateConfig(
+  partial: Partial<AgentikitConfig>,
+  stashDir?: string,
+): AgentikitConfig {
+  const dir = stashDir ?? resolveStashDir()
+  const current = loadConfig(dir)
+  const merged: AgentikitConfig = { ...current, ...partial }
+  saveConfig(merged, dir)
+  return merged
+}
+
+// ── Helpers ─────────────────────────────────────────────────────────────────
+
+function pickKnownKeys(raw: Record<string, unknown>): AgentikitConfig {
+  const config: AgentikitConfig = { ...DEFAULT_CONFIG }
+
+  if (typeof raw.semanticSearch === "boolean") {
+    config.semanticSearch = raw.semanticSearch
+  }
+
+  if (Array.isArray(raw.additionalStashDirs)) {
+    config.additionalStashDirs = raw.additionalStashDirs.filter(
+      (d): d is string => 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: unknown,
+): EmbeddingConnectionConfig | LlmConnectionConfig | undefined {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return undefined
+  const obj = value as Record<string, unknown>
+  if (typeof obj.endpoint !== "string" || !obj.endpoint) return undefined
+  if (typeof obj.model !== "string" || !obj.model) return undefined
+  const result: { endpoint: string; model: string; apiKey?: string } = {
+    endpoint: obj.endpoint,
+    model: obj.model,
+  }
+  if (typeof obj.apiKey === "string" && obj.apiKey) {
+    result.apiKey = obj.apiKey
+  }
+  return result
+}

package/src/embedder.ts

@@ -0,0 +1,117 @@
+import type { EmbeddingConnectionConfig } from "./config"
+
+// ── Types ───────────────────────────────────────────────────────────────────
+
+export type EmbeddingVector = number[]
+
+// ── Singleton local embedder ────────────────────────────────────────────────
+
+let localEmbedder: any
+
+async function getLocalEmbedder(): Promise<any> {
+  if (!localEmbedder) {
+    let pipeline: any
+    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: string): Promise<EmbeddingVector> {
+  const model = await getLocalEmbedder()
+  const result = await model(text, { pooling: "mean", normalize: true })
+  return Array.from(result.data) as number[]
+}
+
+// ── OpenAI-compatible remote embedder ───────────────────────────────────────
+
+async function embedRemote(
+  text: string,
+  config: EmbeddingConnectionConfig,
+): Promise<EmbeddingVector> {
+  const headers: Record<string, string> = { "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()) as {
+    data: Array<{ embedding: number[] }>
+  }
+
+  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: string,
+  embeddingConfig?: EmbeddingConnectionConfig,
+): Promise<EmbeddingVector> {
+  if (embeddingConfig) {
+    return embedRemote(text, embeddingConfig)
+  }
+  return embedLocal(text)
+}
+
+// ── Similarity ──────────────────────────────────────────────────────────────
+
+export function cosineSimilarity(a: EmbeddingVector, b: EmbeddingVector): number {
+  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?: EmbeddingConnectionConfig,
+): Promise<boolean> {
+  if (embeddingConfig) {
+    try {
+      await embedRemote("test", embeddingConfig)
+      return true
+    } catch {
+      return false
+    }
+  }
+  try {
+    await getLocalEmbedder()
+    return true
+  } catch {
+    return false
+  }
+}

package/src/frontmatter.ts

@@ -0,0 +1,95 @@
+/**
+ * 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: string): {
+  data: Record<string, unknown>
+  content: string
+  frontmatter: string | null
+  bodyStartLine: number
+} {
+  const parsedBlock = parseFrontmatterBlock(raw)
+  if (!parsedBlock) {
+    return { data: {}, content: raw, frontmatter: null, bodyStartLine: 1 }
+  }
+
+  const data: Record<string, unknown> = {}
+  let currentKey: string | null = null
+  let nested: Record<string, unknown> | null = 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: string,
+): { frontmatter: string; content: string; bodyStartLine: number } | null {
+  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: string): number {
+  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: string): unknown {
+  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: unknown): string | undefined {
+  return typeof value === "string" && value.trim() ? value : undefined
+}