@soleri/core 2.0.1 → 2.1.0

package/src/runtime/domain-ops.ts

@@ -0,0 +1,144 @@
+/**
+ * Domain facade factory — creates the standard 5-op domain facade pattern.
+ *
+ * Every domain gets: get_patterns, search, get_entry, capture, remove.
+ * This replaces per-domain generated facade files.
+ */
+
+import { z } from 'zod';
+import type { FacadeConfig, OpDefinition } from '../facades/types.js';
+import type { AgentRuntime } from './types.js';
+
+function capitalize(s: string): string {
+  return s.charAt(0).toUpperCase() + s.slice(1);
+}
+
+/**
+ * Create a single domain facade with 5 standard ops.
+ *
+ * @param runtime - The agent runtime (vault + brain)
+ * @param agentId - Agent identifier (used for facade naming)
+ * @param domain - Domain name (e.g. 'security', 'api-design')
+ */
+export function createDomainFacade(
+  runtime: AgentRuntime,
+  agentId: string,
+  domain: string,
+): FacadeConfig {
+  const { vault, brain } = runtime;
+  const facadeName = `${agentId}_${domain.replace(/-/g, '_')}`;
+
+  const ops: OpDefinition[] = [
+    {
+      name: 'get_patterns',
+      description: `Get ${domain} patterns filtered by tags or severity.`,
+      auth: 'read',
+      schema: z.object({
+        tags: z.array(z.string()).optional(),
+        severity: z.enum(['critical', 'warning', 'suggestion']).optional(),
+        type: z.enum(['pattern', 'anti-pattern', 'rule']).optional(),
+        limit: z.number().optional(),
+      }),
+      handler: async (params) => {
+        return vault.list({
+          domain,
+          severity: params.severity as string | undefined,
+          type: params.type as string | undefined,
+          tags: params.tags as string[] | undefined,
+          limit: (params.limit as number) ?? 20,
+        });
+      },
+    },
+    {
+      name: 'search',
+      description: `Search ${domain} knowledge with natural language query. Results ranked by TF-IDF + severity + recency.`,
+      auth: 'read',
+      schema: z.object({
+        query: z.string(),
+        tags: z.array(z.string()).optional(),
+        limit: z.number().optional(),
+      }),
+      handler: async (params) => {
+        return brain.intelligentSearch(params.query as string, {
+          domain,
+          tags: params.tags as string[] | undefined,
+          limit: (params.limit as number) ?? 10,
+        });
+      },
+    },
+    {
+      name: 'get_entry',
+      description: `Get a specific ${domain} knowledge entry by ID.`,
+      auth: 'read',
+      schema: z.object({ id: z.string() }),
+      handler: async (params) => {
+        const entry = vault.get(params.id as string);
+        if (!entry) return { error: 'Entry not found: ' + params.id };
+        return entry;
+      },
+    },
+    {
+      name: 'capture',
+      description: `Capture a new ${domain} pattern, anti-pattern, or rule. Auto-tags and checks for duplicates.`,
+      auth: 'write',
+      schema: z.object({
+        id: z.string(),
+        type: z.enum(['pattern', 'anti-pattern', 'rule']),
+        title: z.string(),
+        severity: z.enum(['critical', 'warning', 'suggestion']),
+        description: z.string(),
+        context: z.string().optional(),
+        example: z.string().optional(),
+        counterExample: z.string().optional(),
+        why: z.string().optional(),
+        tags: z.array(z.string()).optional().default([]),
+      }),
+      handler: async (params) => {
+        return brain.enrichAndCapture({
+          id: params.id as string,
+          type: params.type as 'pattern' | 'anti-pattern' | 'rule',
+          domain,
+          title: params.title as string,
+          severity: params.severity as 'critical' | 'warning' | 'suggestion',
+          description: params.description as string,
+          context: params.context as string | undefined,
+          example: params.example as string | undefined,
+          counterExample: params.counterExample as string | undefined,
+          why: params.why as string | undefined,
+          tags: params.tags as string[],
+        });
+      },
+    },
+    {
+      name: 'remove',
+      description: `Remove a ${domain} knowledge entry by ID.`,
+      auth: 'admin',
+      schema: z.object({ id: z.string() }),
+      handler: async (params) => {
+        const removed = vault.remove(params.id as string);
+        return { removed, id: params.id };
+      },
+    },
+  ];
+
+  return {
+    name: facadeName,
+    description: `${capitalize(domain.replace(/-/g, ' '))} patterns, rules, and guidance.`,
+    ops,
+  };
+}
+
+/**
+ * Create domain facades for all domains.
+ *
+ * @param runtime - The agent runtime
+ * @param agentId - Agent identifier
+ * @param domains - Array of domain names
+ */
+export function createDomainFacades(
+  runtime: AgentRuntime,
+  agentId: string,
+  domains: string[],
+): FacadeConfig[] {
+  return domains.map((d) => createDomainFacade(runtime, agentId, d));
+}

package/src/runtime/runtime.ts

@@ -0,0 +1,76 @@
+/**
+ * Agent runtime factory — one call to initialize all modules.
+ *
+ * ```ts
+ * const runtime = createAgentRuntime({ agentId: 'my-agent' });
+ * // runtime.vault, runtime.brain, runtime.planner, etc. all ready
+ * ```
+ */
+
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { Vault } from '../vault/vault.js';
+import { Brain } from '../brain/brain.js';
+import { BrainIntelligence } from '../brain/intelligence.js';
+import { Planner } from '../planning/planner.js';
+import { Curator } from '../curator/curator.js';
+import { KeyPool, loadKeyPoolConfig } from '../llm/key-pool.js';
+import { loadIntelligenceData } from '../intelligence/loader.js';
+import { LLMClient } from '../llm/llm-client.js';
+import type { AgentRuntimeConfig, AgentRuntime } from './types.js';
+
+/**
+ * Create a fully initialized agent runtime.
+ *
+ * All modules (vault, brain, planner, curator, key pools, LLM client)
+ * are initialized and wired together. New modules added to core in
+ * future versions will be included automatically — existing agents
+ * just `npm update @soleri/core`.
+ */
+export function createAgentRuntime(config: AgentRuntimeConfig): AgentRuntime {
+  const { agentId } = config;
+  const agentHome = join(homedir(), `.${agentId}`);
+  const vaultPath = config.vaultPath ?? join(agentHome, 'vault.db');
+  const plansPath = config.plansPath ?? join(agentHome, 'plans.json');
+
+  // Vault — persistent SQLite knowledge store
+  const vault = new Vault(vaultPath);
+
+  // Seed intelligence data if dataDir provided
+  if (config.dataDir) {
+    const entries = loadIntelligenceData(config.dataDir);
+    if (entries.length > 0) {
+      vault.seed(entries);
+    }
+  }
+
+  // Planner — multi-step task tracking
+  const planner = new Planner(plansPath);
+
+  // Brain — intelligence layer (TF-IDF scoring, auto-tagging, dedup)
+  const brain = new Brain(vault);
+
+  // Brain Intelligence — pattern strengths, session knowledge, intelligence pipeline
+  const brainIntelligence = new BrainIntelligence(vault, brain);
+
+  // Curator — vault self-maintenance (dedup, contradictions, grooming, health)
+  const curator = new Curator(vault);
+
+  // LLM key pools and client
+  const keyPoolFiles = loadKeyPoolConfig(agentId);
+  const openaiKeyPool = new KeyPool(keyPoolFiles.openai);
+  const anthropicKeyPool = new KeyPool(keyPoolFiles.anthropic);
+  const llmClient = new LLMClient(openaiKeyPool, anthropicKeyPool, agentId);
+
+  return {
+    config,
+    vault,
+    brain,
+    brainIntelligence,
+    planner,
+    curator,
+    keyPool: { openai: openaiKeyPool, anthropic: anthropicKeyPool },
+    llmClient,
+    close: () => vault.close(),
+  };
+}

package/src/runtime/types.ts

@@ -0,0 +1,39 @@
+import type { Vault } from '../vault/vault.js';
+import type { Brain } from '../brain/brain.js';
+import type { BrainIntelligence } from '../brain/intelligence.js';
+import type { Planner } from '../planning/planner.js';
+import type { Curator } from '../curator/curator.js';
+import type { KeyPool } from '../llm/key-pool.js';
+import type { LLMClient } from '../llm/llm-client.js';
+
+/**
+ * Configuration for creating an agent runtime.
+ * Only `agentId` is required — everything else has sensible defaults.
+ */
+export interface AgentRuntimeConfig {
+  /** Agent identifier (kebab-case), e.g. 'my-agent'. Used for paths: ~/.{agentId}/ */
+  agentId: string;
+  /** Path to vault database. Default: ~/.{agentId}/vault.db */
+  vaultPath?: string;
+  /** Path to plans JSON store. Default: ~/.{agentId}/plans.json */
+  plansPath?: string;
+  /** Intelligence data directory to seed vault from. Optional. */
+  dataDir?: string;
+}
+
+/**
+ * Fully initialized agent runtime — all modules ready.
+ * Created by `createAgentRuntime(config)`.
+ */
+export interface AgentRuntime {
+  config: AgentRuntimeConfig;
+  vault: Vault;
+  brain: Brain;
+  brainIntelligence: BrainIntelligence;
+  planner: Planner;
+  curator: Curator;
+  keyPool: { openai: KeyPool; anthropic: KeyPool };
+  llmClient: LLMClient;
+  /** Close the vault database connection. Call on shutdown. */
+  close(): void;
+}

package/src/text/similarity.ts

@@ -0,0 +1,168 @@
+// ─── Shared Text Processing & Similarity Utilities ──────────────────
+// Pure functions used by Brain (ranked search) and Curator (dedup, contradictions).
+
+export type SparseVector = Map<string, number>;
+
+// ─── Stopwords ─────────────────────────────────────────────────────
+
+export const STOPWORDS = new Set([
+  'a',
+  'an',
+  'the',
+  'and',
+  'or',
+  'but',
+  'in',
+  'on',
+  'at',
+  'to',
+  'for',
+  'of',
+  'with',
+  'by',
+  'from',
+  'as',
+  'is',
+  'was',
+  'are',
+  'were',
+  'been',
+  'be',
+  'have',
+  'has',
+  'had',
+  'do',
+  'does',
+  'did',
+  'will',
+  'would',
+  'could',
+  'should',
+  'may',
+  'might',
+  'shall',
+  'can',
+  'need',
+  'must',
+  'it',
+  'its',
+  'this',
+  'that',
+  'these',
+  'those',
+  'i',
+  'you',
+  'he',
+  'she',
+  'we',
+  'they',
+  'me',
+  'him',
+  'her',
+  'us',
+  'them',
+  'my',
+  'your',
+  'his',
+  'our',
+  'their',
+  'what',
+  'which',
+  'who',
+  'whom',
+  'when',
+  'where',
+  'why',
+  'how',
+  'all',
+  'each',
+  'every',
+  'both',
+  'few',
+  'more',
+  'most',
+  'other',
+  'some',
+  'such',
+  'no',
+  'not',
+  'only',
+  'same',
+  'so',
+  'than',
+  'too',
+  'very',
+  'just',
+  'because',
+  'if',
+  'then',
+  'else',
+  'about',
+  'up',
+  'out',
+  'into',
+]);
+
+// ─── Text Processing ───────────────────────────────────────────────
+
+export function tokenize(text: string): string[] {
+  return text
+    .toLowerCase()
+    .replace(/[^a-z0-9\s-]/g, ' ')
+    .split(/\s+/)
+    .filter((t) => t.length > 2 && !STOPWORDS.has(t));
+}
+
+export function calculateTf(tokens: string[]): SparseVector {
+  const tf: SparseVector = new Map();
+  for (const token of tokens) {
+    tf.set(token, (tf.get(token) ?? 0) + 1);
+  }
+  const len = tokens.length || 1;
+  for (const [term, count] of tf) {
+    tf.set(term, count / len);
+  }
+  return tf;
+}
+
+export function calculateTfIdf(tokens: string[], vocabulary: Map<string, number>): SparseVector {
+  const tf = calculateTf(tokens);
+  const tfidf: SparseVector = new Map();
+  for (const [term, tfValue] of tf) {
+    const idf = vocabulary.get(term) ?? 0;
+    if (idf > 0) {
+      tfidf.set(term, tfValue * idf);
+    }
+  }
+  return tfidf;
+}
+
+export function cosineSimilarity(a: SparseVector, b: SparseVector): number {
+  let dot = 0;
+  let normA = 0;
+  let normB = 0;
+  for (const [term, valA] of a) {
+    normA += valA * valA;
+    const valB = b.get(term);
+    if (valB !== undefined) {
+      dot += valA * valB;
+    }
+  }
+  for (const [, valB] of b) {
+    normB += valB * valB;
+  }
+  const denom = Math.sqrt(normA) * Math.sqrt(normB);
+  return denom === 0 ? 0 : dot / denom;
+}
+
+export function jaccardSimilarity(a: string[], b: string[]): number {
+  if (a.length === 0 && b.length === 0) return 0;
+  const setA = new Set(a);
+  const setB = new Set(b);
+  let intersection = 0;
+  for (const item of setA) {
+    if (setB.has(item)) intersection++;
+  }
+  const union = new Set([...a, ...b]).size;
+  return union === 0 ? 0 : intersection / union;
+}