@soleri/core 2.0.1 → 2.1.0

package/src/curator/types.ts

@@ -0,0 +1,114 @@
+// ─── Curator Types ──────────────────────────────────────────────────
+
+export type EntryStatus = 'active' | 'stale' | 'archived';
+export type EntrySource = 'manual' | 'capture' | 'seed' | 'unknown';
+
+// ─── Tag Normalization ──────────────────────────────────────────────
+
+export interface TagNormalizationResult {
+  original: string;
+  normalized: string;
+  wasAliased: boolean;
+}
+
+export interface CanonicalTag {
+  tag: string;
+  description: string | null;
+  usageCount: number;
+  aliasCount: number;
+}
+
+// ─── Duplicate Detection ────────────────────────────────────────────
+
+export interface DuplicateCandidate {
+  entryId: string;
+  title: string;
+  similarity: number;
+  suggestMerge: boolean;
+}
+
+export interface DuplicateDetectionResult {
+  entryId: string;
+  matches: DuplicateCandidate[];
+  scannedCount: number;
+}
+
+// ─── Contradictions ─────────────────────────────────────────────────
+
+export type ContradictionStatus = 'open' | 'resolved' | 'dismissed';
+
+export interface Contradiction {
+  id: number;
+  patternId: string;
+  antipatternId: string;
+  similarity: number;
+  status: ContradictionStatus;
+  createdAt: number;
+  resolvedAt: number | null;
+}
+
+// ─── Grooming ───────────────────────────────────────────────────────
+
+export interface GroomResult {
+  entryId: string;
+  tagsNormalized: TagNormalizationResult[];
+  stale: boolean;
+  lastGroomedAt: number;
+}
+
+export interface GroomAllResult {
+  totalEntries: number;
+  groomedCount: number;
+  tagsNormalized: number;
+  staleCount: number;
+  durationMs: number;
+}
+
+// ─── Consolidation ──────────────────────────────────────────────────
+
+export interface ConsolidationOptions {
+  dryRun?: boolean;
+  staleDaysThreshold?: number;
+  duplicateThreshold?: number;
+  contradictionThreshold?: number;
+}
+
+export interface ConsolidationResult {
+  dryRun: boolean;
+  duplicates: DuplicateDetectionResult[];
+  staleEntries: string[];
+  contradictions: Contradiction[];
+  mutations: number;
+  durationMs: number;
+}
+
+// ─── Changelog & Health ─────────────────────────────────────────────
+
+export interface ChangelogEntry {
+  id: number;
+  action: string;
+  entryId: string;
+  beforeValue: string | null;
+  afterValue: string | null;
+  reason: string;
+  createdAt: number;
+}
+
+export interface HealthMetrics {
+  coverage: number;
+  freshness: number;
+  quality: number;
+  tagHealth: number;
+}
+
+export interface HealthAuditResult {
+  score: number;
+  metrics: HealthMetrics;
+  recommendations: string[];
+}
+
+export interface CuratorStatus {
+  initialized: boolean;
+  tables: Record<string, number>;
+  lastGroomedAt: number | null;
+}

package/src/index.ts

@@ -6,8 +6,40 @@ export { loadIntelligenceData } from './intelligence/loader.js';
 export { Vault } from './vault/vault.js';
 export type { SearchResult, VaultStats, ProjectInfo, Memory, MemoryStats } from './vault/vault.js';
 
+// ─── Text Utilities ─────────────────────────────────────────────────
+export {
+  tokenize,
+  calculateTf,
+  calculateTfIdf,
+  cosineSimilarity,
+  jaccardSimilarity,
+} from './text/similarity.js';
+export type { SparseVector } from './text/similarity.js';
+
+// ─── Curator ────────────────────────────────────────────────────────
+export { Curator } from './curator/curator.js';
+export type {
+  EntryStatus,
+  EntrySource,
+  TagNormalizationResult,
+  CanonicalTag,
+  DuplicateCandidate,
+  DuplicateDetectionResult,
+  Contradiction,
+  ContradictionStatus,
+  GroomResult,
+  GroomAllResult,
+  ConsolidationOptions,
+  ConsolidationResult,
+  ChangelogEntry,
+  HealthMetrics,
+  HealthAuditResult,
+  CuratorStatus,
+} from './curator/types.js';
+
 // ─── Brain ───────────────────────────────────────────────────────────
 export { Brain } from './brain/brain.js';
+export { BrainIntelligence } from './brain/intelligence.js';
 export type {
   ScoringWeights,
   ScoreBreakdown,
@@ -16,7 +48,20 @@ export type {
   CaptureResult,
   BrainStats,
   QueryContext,
-} from './brain/brain.js';
+  PatternStrength,
+  StrengthsQuery,
+  BrainSession,
+  SessionLifecycleInput,
+  KnowledgeProposal,
+  ExtractionResult,
+  GlobalPattern,
+  DomainProfile,
+  BuildIntelligenceResult,
+  BrainIntelligenceStats,
+  SessionContext,
+  BrainExportData,
+  BrainImportResult,
+} from './brain/types.js';
 
 // ─── Cognee ─────────────────────────────────────────────────────────
 export { CogneeClient } from './cognee/client.js';
@@ -73,3 +118,12 @@ export type {
   FacadeResponse,
   FacadeInput,
 } from './facades/types.js';
+
+// ─── LLM Client ─────────────────────────────────────────────────────
+export { LLMClient } from './llm/llm-client.js';
+
+// ─── Runtime Factory ────────────────────────────────────────────────
+export { createAgentRuntime } from './runtime/runtime.js';
+export { createCoreOps } from './runtime/core-ops.js';
+export { createDomainFacade, createDomainFacades } from './runtime/domain-ops.js';
+export type { AgentRuntimeConfig, AgentRuntime } from './runtime/types.js';

package/src/llm/llm-client.ts

@@ -0,0 +1,310 @@
+/**
+ * LLM Client — Unified OpenAI/Anthropic caller with key pool rotation,
+ * circuit breaker, retry, and model routing.
+ *
+ * Anthropic SDK is loaded via dynamic import on first use, keeping it
+ * an optional peer dependency.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { homedir } from 'node:os';
+import { LLMError } from './types.js';
+import { CircuitBreaker, retry, parseRateLimitHeaders } from './utils.js';
+import type { LLMCallOptions, LLMCallResult, RouteEntry, RoutingConfig } from './types.js';
+import type { KeyPool } from './key-pool.js';
+
+// =============================================================================
+// CONSTANTS
+// =============================================================================
+
+const OPENAI_API_URL = 'https://api.openai.com/v1/chat/completions';
+
+// =============================================================================
+// MODEL ROUTER
+// =============================================================================
+
+function loadRoutingConfig(agentId: string): RoutingConfig {
+  const defaultConfig: RoutingConfig = {
+    routes: [],
+    defaultOpenAIModel: 'gpt-4o-mini',
+    defaultAnthropicModel: 'claude-sonnet-4-20250514',
+  };
+
+  const configPath = path.join(homedir(), `.${agentId}`, 'model-routing.json');
+
+  try {
+    if (fs.existsSync(configPath)) {
+      const data = JSON.parse(fs.readFileSync(configPath, 'utf-8')) as Partial<RoutingConfig>;
+      if (data.routes && Array.isArray(data.routes)) {
+        defaultConfig.routes = data.routes;
+      }
+      if (data.defaultOpenAIModel) {
+        defaultConfig.defaultOpenAIModel = data.defaultOpenAIModel;
+      }
+      if (data.defaultAnthropicModel) {
+        defaultConfig.defaultAnthropicModel = data.defaultAnthropicModel;
+      }
+    }
+  } catch {
+    // Config not available — use defaults
+  }
+
+  return defaultConfig;
+}
+
+function inferProvider(model: string): 'openai' | 'anthropic' {
+  if (model.startsWith('claude-') || model.startsWith('anthropic/')) {
+    return 'anthropic';
+  }
+  return 'openai';
+}
+
+class ModelRouter {
+  private config: RoutingConfig;
+
+  constructor(config?: RoutingConfig) {
+    this.config = config ?? {
+      routes: [],
+      defaultOpenAIModel: 'gpt-4o-mini',
+      defaultAnthropicModel: 'claude-sonnet-4-20250514',
+    };
+  }
+
+  resolve(
+    caller: string,
+    task?: string,
+    originalModel?: string,
+  ): { model: string; provider: 'openai' | 'anthropic' } {
+    if (task) {
+      const exactMatch = this.config.routes.find((r) => r.caller === caller && r.task === task);
+      if (exactMatch) {
+        return { model: exactMatch.model, provider: exactMatch.provider };
+      }
+    }
+
+    const callerMatch = this.config.routes.find((r) => r.caller === caller && !r.task);
+    if (callerMatch) {
+      return { model: callerMatch.model, provider: callerMatch.provider };
+    }
+
+    if (originalModel) {
+      const provider = inferProvider(originalModel);
+      return { model: originalModel, provider };
+    }
+
+    return { model: this.config.defaultOpenAIModel, provider: 'openai' };
+  }
+
+  getRoutes(): RouteEntry[] {
+    return [...this.config.routes];
+  }
+}
+
+// =============================================================================
+// LLM CLIENT
+// =============================================================================
+
+// Anthropic SDK type — we only need the messages.create method shape
+interface AnthropicClient {
+  messages: {
+    create(
+      params: {
+        model: string;
+        max_tokens: number;
+        system: string;
+        messages: Array<{ role: string; content: string }>;
+      },
+      options?: { timeout: number },
+    ): Promise<{
+      content: Array<{ type: string; text?: string }>;
+      usage?: { input_tokens?: number; output_tokens?: number };
+    }>;
+  };
+}
+
+export class LLMClient {
+  private openaiKeyPool: KeyPool;
+  private anthropicKeyPool: KeyPool;
+  private anthropicClient: AnthropicClient | null = null;
+  private anthropicBreaker: CircuitBreaker;
+  private anthropicKeyFingerprint: string = '';
+  private router: ModelRouter;
+
+  constructor(openaiKeyPool: KeyPool, anthropicKeyPool: KeyPool, agentId?: string) {
+    this.openaiKeyPool = openaiKeyPool;
+    this.anthropicKeyPool = anthropicKeyPool;
+    this.anthropicBreaker = new CircuitBreaker({
+      name: 'llm-anthropic',
+      failureThreshold: 5,
+      resetTimeoutMs: 60_000,
+    });
+    this.router = new ModelRouter(agentId ? loadRoutingConfig(agentId) : undefined);
+  }
+
+  async complete(options: LLMCallOptions): Promise<LLMCallResult> {
+    const routed = this.router.resolve(options.caller, options.task, options.model);
+    const resolvedOptions = { ...options, model: routed.model, provider: routed.provider };
+
+    return resolvedOptions.provider === 'anthropic'
+      ? this.callAnthropic(resolvedOptions)
+      : this.callOpenAI(resolvedOptions);
+  }
+
+  isAvailable(): { openai: boolean; anthropic: boolean } {
+    return {
+      openai: this.openaiKeyPool.hasKeys,
+      anthropic: this.anthropicKeyPool.hasKeys,
+    };
+  }
+
+  getRoutes(): RouteEntry[] {
+    return this.router.getRoutes();
+  }
+
+  // ===========================================================================
+  // OPENAI
+  // ===========================================================================
+
+  private async callOpenAI(options: LLMCallOptions): Promise<LLMCallResult> {
+    const keyPool = this.openaiKeyPool.hasKeys ? this.openaiKeyPool : null;
+
+    if (!keyPool) {
+      throw new LLMError('OpenAI API key not configured', { retryable: false });
+    }
+
+    const start = Date.now();
+
+    const doRequest = async (): Promise<LLMCallResult> => {
+      const apiKey = keyPool.getActiveKey().expose();
+      const keyIndex = keyPool.activeKeyIndex;
+
+      const response = await fetch(OPENAI_API_URL, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          Authorization: `Bearer ${apiKey}`,
+        },
+        body: JSON.stringify({
+          model: options.model,
+          messages: [
+            { role: 'system', content: options.systemPrompt },
+            { role: 'user', content: options.userPrompt },
+          ],
+          temperature: options.temperature ?? 0.3,
+          max_completion_tokens: options.maxTokens ?? 500,
+        }),
+      });
+
+      if (response.headers) {
+        const rateLimits = parseRateLimitHeaders(response.headers);
+        if (rateLimits.remaining !== null) {
+          keyPool.updateQuota(keyIndex, rateLimits.remaining);
+          keyPool.rotatePreemptive();
+        }
+      }
+
+      if (!response.ok) {
+        if (response.status === 429 && keyPool.poolSize > 1) {
+          keyPool.rotateOnError();
+        }
+
+        const errorBody = await response.text();
+        throw new LLMError(`OpenAI API error: ${response.status} - ${errorBody}`, {
+          retryable: response.status === 429 || response.status >= 500,
+          statusCode: response.status,
+        });
+      }
+
+      const data = (await response.json()) as {
+        choices: Array<{ message: { content: string } }>;
+        usage?: { prompt_tokens?: number; completion_tokens?: number };
+      };
+
+      return {
+        text: data.choices[0]?.message?.content || '',
+        model: options.model,
+        provider: 'openai' as const,
+        inputTokens: data.usage?.prompt_tokens,
+        outputTokens: data.usage?.completion_tokens,
+        durationMs: Date.now() - start,
+      };
+    };
+
+    return retry(doRequest, { maxAttempts: 3 });
+  }
+
+  // ===========================================================================
+  // ANTHROPIC
+  // ===========================================================================
+
+  private async callAnthropic(options: LLMCallOptions): Promise<LLMCallResult> {
+    const client = await this.getAnthropicClient();
+    if (!client) {
+      throw new LLMError('Anthropic API key not configured', { retryable: false });
+    }
+
+    const start = Date.now();
+
+    return this.anthropicBreaker.call(() =>
+      retry(
+        async () => {
+          const response = await client.messages.create(
+            {
+              model: options.model,
+              max_tokens: options.maxTokens ?? 1024,
+              system: options.systemPrompt,
+              messages: [{ role: 'user', content: options.userPrompt }],
+            },
+            { timeout: 60_000 },
+          );
+
+          const text = response.content
+            .filter(
+              (block): block is { type: 'text'; text: string } =>
+                block.type === 'text' && typeof block.text === 'string',
+            )
+            .map((block) => block.text)
+            .join('\n');
+
+          return {
+            text,
+            model: options.model,
+            provider: 'anthropic' as const,
+            inputTokens: response.usage?.input_tokens,
+            outputTokens: response.usage?.output_tokens,
+            durationMs: Date.now() - start,
+          };
+        },
+        { maxAttempts: 2 },
+      ),
+    );
+  }
+
+  private async getAnthropicClient(): Promise<AnthropicClient | null> {
+    if (!this.anthropicKeyPool.hasKeys) return null;
+
+    const currentKey = this.anthropicKeyPool.getActiveKey().expose();
+    const currentFingerprint = currentKey.slice(-8);
+
+    if (currentFingerprint !== this.anthropicKeyFingerprint) {
+      this.anthropicClient = null;
+      this.anthropicKeyFingerprint = currentFingerprint;
+    }
+
+    if (this.anthropicClient) return this.anthropicClient;
+
+    try {
+      // Dynamic import — @anthropic-ai/sdk is an optional peer dep.
+      // eslint-disable-next-line @typescript-eslint/no-require-imports
+      const mod = await (Function('return import("@anthropic-ai/sdk")')() as Promise<{
+        default: new (opts: { apiKey: string }) => AnthropicClient;
+      }>);
+      this.anthropicClient = new mod.default({ apiKey: currentKey });
+      return this.anthropicClient;
+    } catch {
+      // SDK not installed — Anthropic provider unavailable
+      return null;
+    }
+  }
+}