@soleri/core 2.12.0 → 8.0.0

package/src/brain/knowledge-synthesizer.ts

@@ -0,0 +1,218 @@
+/**
+ * Knowledge Synthesizer — turn vault knowledge into structured content.
+ *
+ * Searches vault for relevant entries, builds context, calls LLM to synthesize
+ * into one of 4 formats: brief, outline, talking-points, post-draft.
+ *
+ * Graceful degradation: if no LLM, returns raw entries without synthesis.
+ */
+
+import type { Brain } from './brain.js';
+import type { LLMClient } from '../llm/llm-client.js';
+import type { RankedResult } from './types.js';
+
+// ─── Types ───────────────────────────────────────────────────────────
+
+export type SynthesisFormat = 'brief' | 'outline' | 'talking-points' | 'post-draft';
+export type Audience = 'technical' | 'executive' | 'general';
+
+export interface SynthesisOptions {
+  format: SynthesisFormat;
+  maxEntries?: number;
+  audience?: Audience;
+}
+
+export interface SynthesisResult {
+  query: string;
+  format: SynthesisFormat;
+  content: string;
+  sources: Array<{ id: string; title: string; score: number }>;
+  coverage: number;
+  gaps: string[];
+  entriesConsulted: number;
+}
+
+// ─── Prompts ─────────────────────────────────────────────────────────
+
+const FORMAT_PROMPTS: Record<SynthesisFormat, string> = {
+  brief:
+    'Produce a concise executive brief (5-10 bullet points). Start with a one-line summary. ' +
+    'Group findings by theme. End with open questions or knowledge gaps.',
+  outline:
+    'Produce a structured article/document outline with numbered sections. ' +
+    'Each section should reference which vault entries support it. ' +
+    'Mark sections where knowledge is thin as [GAP].',
+  'talking-points':
+    'Produce bullet-point talking points for a presentation or discussion. ' +
+    'Each point should be self-contained and quotable. ' +
+    'Include a "Questions to anticipate" section at the end.',
+  'post-draft':
+    'Draft a short-form post (200-300 words) suitable for LinkedIn or a blog. ' +
+    'Conversational tone, one key insight, actionable takeaway. ' +
+    'End with a question to prompt engagement.',
+};
+
+const AUDIENCE_CONTEXT: Record<Audience, string> = {
+  technical: 'The audience is software engineers and architects. Use precise technical language.',
+  executive:
+    'The audience is non-technical leadership. Focus on impact, decisions, and outcomes. Avoid jargon.',
+  general: 'The audience is mixed. Be clear and accessible while maintaining accuracy.',
+};
+
+// ─── Class ───────────────────────────────────────────────────────────
+
+export class KnowledgeSynthesizer {
+  private brain: Brain;
+  private llm: LLMClient | null;
+
+  constructor(brain: Brain, llm: LLMClient | null) {
+    this.brain = brain;
+    this.llm = llm;
+  }
+
+  async synthesize(query: string, opts: SynthesisOptions): Promise<SynthesisResult> {
+    const maxEntries = opts.maxEntries ?? 10;
+    const audience = opts.audience ?? 'general';
+
+    // 1. Search vault for relevant entries
+    const results = await this.brain.intelligentSearch(query, { limit: maxEntries });
+
+    const sources = results.map((r) => ({
+      id: r.entry.id,
+      title: r.entry.title,
+      score: r.score,
+    }));
+
+    // Coverage: how many entries scored above 0.3 vs how many we asked for
+    const strongMatches = results.filter((r) => r.score > 0.3).length;
+    const coverage =
+      maxEntries > 0 ? Math.min(Math.round((strongMatches / maxEntries) * 100), 100) : 0;
+
+    // 2. If no LLM, return raw entries without synthesis
+    if (!this.llm || results.length === 0) {
+      return {
+        query,
+        format: opts.format,
+        content:
+          results.length === 0
+            ? `No vault entries found for "${query}".`
+            : formatRawEntries(results),
+        sources,
+        coverage,
+        gaps: results.length === 0 ? [`No knowledge found for: ${query}`] : [],
+        entriesConsulted: results.length,
+      };
+    }
+
+    // 3. Build context from entries
+    const context = buildContext(results);
+
+    // 4. LLM synthesis call
+    const systemPrompt = buildSystemPrompt(opts.format, audience);
+    const userPrompt = buildUserPrompt(query, context, opts.format);
+
+    let llmOutput: string;
+    try {
+      const result = await this.llm.complete({
+        provider: 'openai',
+        model: 'gpt-4o-mini',
+        systemPrompt,
+        userPrompt,
+        temperature: 0.3,
+        maxTokens: 1500,
+        caller: 'knowledge-synthesizer',
+        task: 'synthesize',
+      });
+      llmOutput = result.text;
+    } catch {
+      // LLM failed — return raw entries
+      return {
+        query,
+        format: opts.format,
+        content: formatRawEntries(results),
+        sources,
+        coverage,
+        gaps: [],
+        entriesConsulted: results.length,
+      };
+    }
+
+    // 5. Extract gaps from LLM output
+    const gaps = extractGaps(llmOutput);
+
+    return {
+      query,
+      format: opts.format,
+      content: llmOutput,
+      sources,
+      coverage,
+      gaps,
+      entriesConsulted: results.length,
+    };
+  }
+}
+
+// ─── Helpers ─────────────────────────────────────────────────────────
+
+function buildContext(results: RankedResult[]): string {
+  return results
+    .map((r, i) => {
+      const entry = r.entry;
+      let text = `[${i + 1}] ${entry.title} (${entry.type}, ${entry.severity})\n`;
+      text += `   ${entry.description}`;
+      if (entry.why) text += `\n   Why: ${entry.why}`;
+      if (entry.context) text += `\n   Context: ${entry.context}`;
+      if (entry.tags.length > 0) text += `\n   Tags: ${entry.tags.join(', ')}`;
+      return text;
+    })
+    .join('\n\n');
+}
+
+function buildSystemPrompt(format: SynthesisFormat, audience: Audience): string {
+  return (
+    'You are a knowledge synthesizer. You take structured vault entries (patterns, anti-patterns, rules) ' +
+    'and produce clear, actionable content.\n\n' +
+    FORMAT_PROMPTS[format] +
+    '\n\n' +
+    AUDIENCE_CONTEXT[audience] +
+    '\n\n' +
+    'Rules:\n' +
+    '- Only use information from the provided vault entries. Do not invent facts.\n' +
+    '- Reference entries by their [number] when making claims.\n' +
+    "- If the entries don't cover an important subtopic, note it as a GAP.\n" +
+    '- Be concise. Every sentence should earn its place.'
+  );
+}
+
+function buildUserPrompt(query: string, context: string, format: SynthesisFormat): string {
+  return (
+    `Topic: ${query}\n\n` +
+    `Format: ${format}\n\n` +
+    `Vault entries:\n${context}\n\n` +
+    'Synthesize the above entries into the requested format. ' +
+    'Include a "Knowledge Gaps" section at the end listing topics not covered by the entries.'
+  );
+}
+
+function formatRawEntries(results: RankedResult[]): string {
+  if (results.length === 0) return 'No entries found.';
+  return results
+    .map(
+      (r) =>
+        `- **${r.entry.title}** (${r.entry.type}, score: ${r.score.toFixed(2)}): ${r.entry.description}`,
+    )
+    .join('\n');
+}
+
+function extractGaps(llmOutput: string): string[] {
+  // Look for a "Knowledge Gaps" or "Gaps" or "[GAP]" section
+  const gapSection = llmOutput.match(
+    /(?:knowledge\s+gaps?|gaps?|open\s+questions?)[\s:]*\n([\s\S]*?)(?:\n##|\n\*\*|$)/i,
+  );
+  if (!gapSection) return [];
+
+  return gapSection[1]
+    .split('\n')
+    .map((line) => line.replace(/^[-*•\d.)\s]+/, '').trim())
+    .filter((line) => line.length > 5);
+}

package/src/brain/learning-radar.ts

@@ -0,0 +1,340 @@
+/**
+ * Learning Radar — automatic pattern detection from agent sessions.
+ *
+ * Analyzes signals (corrections, search misses, explicit captures, workarounds)
+ * and queues knowledge candidates by confidence level:
+ *   >= 0.8  → auto-capture silently
+ *   0.4-0.8 → queue for end-of-session review
+ *   < 0.4   → log to metrics only
+ *
+ * Zero-friction: never interrupts the user. All analysis is pull-based.
+ */
+
+import type { Vault } from '../vault/vault.js';
+import type { PersistenceProvider } from '../persistence/types.js';
+import type { Brain } from './brain.js';
+
+// ─── Types ───────────────────────────────────────────────────────────
+
+export type SignalType =
+  | 'correction'
+  | 'search_miss'
+  | 'explicit_capture'
+  | 'pattern_success'
+  | 'workaround'
+  | 'repeated_question';
+
+export type CandidateStatus = 'pending' | 'captured' | 'dismissed' | 'logged';
+
+export interface RadarSignal {
+  type: SignalType;
+  title: string;
+  description: string;
+  /** Override suggested entry type. Default inferred from signal type. */
+  suggestedType?: 'pattern' | 'anti-pattern';
+  /** Override confidence. Default computed from signal type. */
+  confidence?: number;
+  /** Original query that triggered this signal (for search_miss, repeated_question). */
+  sourceQuery?: string;
+  /** Additional context (e.g., what the user said, what was corrected). */
+  context?: string;
+}
+
+export interface RadarCandidate {
+  id: number;
+  signalType: SignalType;
+  title: string;
+  description: string;
+  suggestedType: string;
+  confidence: number;
+  status: CandidateStatus;
+  sourceQuery: string | null;
+  context: string | null;
+  createdAt: string;
+}
+
+export interface RadarStats {
+  totalAnalyzed: number;
+  autoCaptured: number;
+  queued: number;
+  dismissed: number;
+  logged: number;
+  knowledgeGaps: number;
+}
+
+export interface FlushResult {
+  captured: number;
+  capturedIds: number[];
+  failed: number;
+}
+
+// ─── Constants ───────────────────────────────────────────────────────
+
+const HIGH_CONFIDENCE = 0.8;
+const MEDIUM_CONFIDENCE = 0.4;
+
+const DEFAULT_CONFIDENCE: Record<SignalType, number> = {
+  explicit_capture: 0.95,
+  correction: 0.75,
+  workaround: 0.65,
+  search_miss: 0.5,
+  pattern_success: 0.4,
+  repeated_question: 0.6,
+};
+
+const DEFAULT_TYPE: Record<SignalType, 'pattern' | 'anti-pattern'> = {
+  explicit_capture: 'pattern',
+  correction: 'anti-pattern',
+  workaround: 'pattern',
+  search_miss: 'pattern',
+  pattern_success: 'pattern',
+  repeated_question: 'pattern',
+};
+
+// ─── Class ───────────────────────────────────────────────────────────
+
+export class LearningRadar {
+  private provider: PersistenceProvider;
+  private vault: Vault;
+  private brain: Brain;
+
+  constructor(vault: Vault, brain: Brain) {
+    this.vault = vault;
+    this.brain = brain;
+    this.provider = vault.getProvider();
+    this.initializeTable();
+  }
+
+  private initializeTable(): void {
+    this.provider.execSql(`
+      CREATE TABLE IF NOT EXISTS radar_candidates (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        signal_type TEXT NOT NULL,
+        title TEXT NOT NULL,
+        description TEXT NOT NULL,
+        suggested_type TEXT NOT NULL DEFAULT 'pattern',
+        confidence REAL NOT NULL,
+        status TEXT NOT NULL DEFAULT 'pending',
+        source_query TEXT,
+        context TEXT,
+        created_at TEXT NOT NULL DEFAULT (datetime('now'))
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_radar_status ON radar_candidates(status);
+    `);
+  }
+
+  /**
+   * Analyze a signal and classify it by confidence.
+   * High confidence → auto-capture. Medium → queue. Low → log only.
+   */
+  analyze(signal: RadarSignal): RadarCandidate | null {
+    const confidence = signal.confidence ?? DEFAULT_CONFIDENCE[signal.type] ?? 0.5;
+    const suggestedType = signal.suggestedType ?? DEFAULT_TYPE[signal.type] ?? 'pattern';
+
+    let status: CandidateStatus;
+    if (confidence >= HIGH_CONFIDENCE) {
+      status = 'captured';
+    } else if (confidence >= MEDIUM_CONFIDENCE) {
+      status = 'pending';
+    } else {
+      status = 'logged';
+    }
+
+    const result = this.provider.run(
+      `INSERT INTO radar_candidates (signal_type, title, description, suggested_type, confidence, status, source_query, context)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
+      [
+        signal.type,
+        signal.title,
+        signal.description,
+        suggestedType,
+        confidence,
+        status,
+        signal.sourceQuery ?? null,
+        signal.context ?? null,
+      ],
+    );
+
+    const id = Number(result.lastInsertRowid);
+
+    // Auto-capture high confidence signals immediately
+    if (status === 'captured') {
+      this.captureCandidate(id, signal.title, signal.description, suggestedType, signal.type);
+    }
+
+    return this.getCandidate(id);
+  }
+
+  /**
+   * Get all pending candidates (medium confidence, queued for review).
+   */
+  getCandidates(limit: number = 20): RadarCandidate[] {
+    const rows = this.provider.all<CandidateRow>(
+      'SELECT * FROM radar_candidates WHERE status = ? ORDER BY confidence DESC LIMIT ?',
+      ['pending', limit],
+    );
+    return rows.map(rowToCandidate);
+  }
+
+  /**
+   * Get a single candidate by ID.
+   */
+  getCandidate(id: number): RadarCandidate | null {
+    const row = this.provider.get<CandidateRow>('SELECT * FROM radar_candidates WHERE id = ?', [
+      id,
+    ]);
+    return row ? rowToCandidate(row) : null;
+  }
+
+  /**
+   * Approve a pending candidate — capture it to vault.
+   */
+  approve(candidateId: number): { captured: boolean; entryId?: string } {
+    const candidate = this.getCandidate(candidateId);
+    if (!candidate || candidate.status !== 'pending') {
+      return { captured: false };
+    }
+
+    const entryId = this.captureCandidate(
+      candidateId,
+      candidate.title,
+      candidate.description,
+      candidate.suggestedType,
+      candidate.signalType,
+    );
+
+    return { captured: true, entryId };
+  }
+
+  /**
+   * Dismiss a pending candidate — mark it as not worth capturing.
+   */
+  dismiss(candidateId: number): { dismissed: boolean } {
+    const result = this.provider.run(
+      "UPDATE radar_candidates SET status = 'dismissed' WHERE id = ? AND status = 'pending'",
+      [candidateId],
+    );
+    return { dismissed: result.changes > 0 };
+  }
+
+  /**
+   * Flush: auto-capture all pending candidates above a confidence threshold.
+   */
+  flush(minConfidence: number = HIGH_CONFIDENCE): FlushResult {
+    const rows = this.provider.all<CandidateRow>(
+      'SELECT * FROM radar_candidates WHERE status = ? AND confidence >= ? ORDER BY confidence DESC',
+      ['pending', minConfidence],
+    );
+
+    let captured = 0;
+    let failed = 0;
+    const capturedIds: number[] = [];
+
+    for (const row of rows) {
+      try {
+        this.captureCandidate(
+          row.id,
+          row.title,
+          row.description,
+          row.suggested_type,
+          row.signal_type,
+        );
+        captured++;
+        capturedIds.push(row.id);
+      } catch {
+        failed++;
+      }
+    }
+
+    return { captured, capturedIds, failed };
+  }
+
+  /**
+   * Get radar statistics.
+   */
+  getStats(): RadarStats {
+    const total = this.provider.get<{ count: number }>(
+      'SELECT COUNT(*) as count FROM radar_candidates',
+    )!.count;
+
+    const statusRows = this.provider.all<{ status: string; count: number }>(
+      'SELECT status, COUNT(*) as count FROM radar_candidates GROUP BY status',
+    );
+    const byStatus: Record<string, number> = {};
+    for (const row of statusRows) byStatus[row.status] = row.count;
+
+    const gaps = this.provider.get<{ count: number }>(
+      "SELECT COUNT(*) as count FROM radar_candidates WHERE signal_type = 'search_miss' OR signal_type = 'repeated_question'",
+    )!.count;
+
+    return {
+      totalAnalyzed: total,
+      autoCaptured: byStatus['captured'] ?? 0,
+      queued: byStatus['pending'] ?? 0,
+      dismissed: byStatus['dismissed'] ?? 0,
+      logged: byStatus['logged'] ?? 0,
+      knowledgeGaps: gaps,
+    };
+  }
+
+  // ─── Internal ──────────────────────────────────────────────────────
+
+  private captureCandidate(
+    candidateId: number,
+    title: string,
+    description: string,
+    suggestedType: string,
+    signalType: string,
+  ): string {
+    const id = `radar-${signalType}-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`;
+    const entryType = suggestedType === 'anti-pattern' ? 'anti-pattern' : 'pattern';
+
+    this.brain.enrichAndCapture({
+      id,
+      type: entryType,
+      domain: 'general',
+      title,
+      description,
+      severity: 'suggestion' as const,
+      tags: ['radar-detected', signalType],
+      origin: 'agent' as const,
+    });
+
+    this.provider.run("UPDATE radar_candidates SET status = 'captured' WHERE id = ?", [
+      candidateId,
+    ]);
+
+    return id;
+  }
+}
+
+// ─── Row Types ───────────────────────────────────────────────────────
+
+interface CandidateRow {
+  id: number;
+  signal_type: string;
+  title: string;
+  description: string;
+  suggested_type: string;
+  confidence: number;
+  status: string;
+  source_query: string | null;
+  context: string | null;
+  created_at: string;
+}
+
+function rowToCandidate(row: CandidateRow): RadarCandidate {
+  return {
+    id: row.id,
+    signalType: row.signal_type as SignalType,
+    title: row.title,
+    description: row.description,
+    suggestedType: row.suggested_type,
+    confidence: row.confidence,
+    status: row.status as CandidateStatus,
+    sourceQuery: row.source_query,
+    context: row.context,
+    createdAt: row.created_at,
+  };
+}

package/src/brain/types.ts

@@ -33,6 +33,22 @@ export interface SearchOptions {
   severity?: string;
   limit?: number;
   tags?: string[];
+  /** 'full' returns RankedResult[] with complete entries (default). 'scan' returns ScanResult[] — lightweight titles + scores for two-pass retrieval. */
+  mode?: 'full' | 'scan';
+}
+
+/** Lightweight search result for scan mode — titles + scores without full entry body. */
+export interface ScanResult {
+  id: string;
+  title: string;
+  score: number;
+  type: string;
+  domain: string;
+  severity: string;
+  tags: string[];
+  snippet: string;
+  /** Estimated tokens if this entry were loaded in full. */
+  tokenEstimate: number;
 }
 
 export interface CaptureResult {

package/src/capabilities/chain-mapping.ts

@@ -0,0 +1,93 @@
+/**
+ * Chain-to-capability mapping — v1 to v2 bridge.
+ *
+ * Maps Soleri's existing 26 v1 chain names (from data/flows/*.flow.yaml)
+ * to capability IDs in domain.action format.
+ *
+ * Used during migration: flows with chains: [] are auto-translated to
+ * capability references. Remove this file when all flows use needs: []
+ * exclusively.
+ *
+ * @see docs/architecture/capability-packs.md — "Chain-to-capability mapping"
+ */
+
+/**
+ * Exhaustive map of every chain name used across Soleri's 8 flow YAML files.
+ *
+ * Sources:
+ *   build.flow.yaml    — vault-search, memory-search, component-search,
+ *                         recommend-design-system, architecture-search,
+ *                         brain-recommend, component-workflow,
+ *                         validate-component, validate-tokens
+ *   deliver.flow.yaml  — validate-component, validate-tokens,
+ *                         design-rules-check, test-coverage-check,
+ *                         performance-audit, delivery-checklist
+ *   design.flow.yaml   — vault-search, memory-search, cognee-design-search,
+ *                         recommend-design-system, recommend-style,
+ *                         recommend-palette, recommend-typography,
+ *                         get-stack-guidelines, brain-recommend
+ *   enhance.flow.yaml  — vault-search, memory-search, architecture-search,
+ *                         brain-recommend, validate-component, validate-tokens
+ *   explore.flow.yaml  — vault-search, memory-search, brain-strengths,
+ *                         brain-recommend, playbook-search
+ *   fix.flow.yaml      — vault-search-antipatterns, memory-search,
+ *                         error-pattern-search, brain-recommend,
+ *                         validate-component, validate-tokens
+ *   plan.flow.yaml     — vault-search, memory-search, brain-recommend,
+ *                         architecture-search, plan-create
+ *   review.flow.yaml   — validate-component, validate-tokens,
+ *                         design-rules-check, vault-search, contrast-check,
+ *                         accessibility-audit, review-report
+ */
+const CHAIN_TO_CAPABILITY: Record<string, string> = {
+  // Vault & Knowledge
+  'vault-search': 'vault.search',
+  'vault-search-antipatterns': 'vault.search',
+  'memory-search': 'memory.search',
+  'playbook-search': 'vault.playbook',
+
+  // Brain
+  'brain-recommend': 'brain.recommend',
+  'brain-strengths': 'brain.strengths',
+
+  // Components
+  'component-search': 'component.search',
+  'component-workflow': 'component.workflow',
+  'validate-component': 'component.validate',
+
+  // Design
+  'contrast-check': 'color.validate',
+  'validate-tokens': 'token.check',
+  'design-rules-check': 'design.rules',
+  'recommend-design-system': 'design.recommend',
+  'recommend-palette': 'design.palette',
+  'recommend-style': 'design.style',
+  'recommend-typography': 'design.typography',
+  'get-stack-guidelines': 'stack.guidelines',
+
+  // Architecture
+  'architecture-search': 'architecture.search',
+  'cognee-design-search': 'cognee.search',
+
+  // Planning
+  'plan-create': 'plan.create',
+
+  // Review & Quality
+  'review-report': 'review.report',
+  'accessibility-audit': 'a11y.audit',
+  'performance-audit': 'perf.audit',
+  'test-coverage-check': 'test.coverage',
+  'error-pattern-search': 'debug.patterns',
+  'delivery-checklist': 'deliver.checklist',
+};
+
+/**
+ * Translate a v1 chain name to a v2 capability ID.
+ *
+ * @param chain - The chain name from a flow YAML `chains:` field
+ * @returns The corresponding capability ID in domain.action format, or
+ *          undefined if no mapping exists
+ */
+export function chainToCapability(chain: string): string | undefined {
+  return CHAIN_TO_CAPABILITY[chain];
+}

package/src/capabilities/index.ts

@@ -0,0 +1,21 @@
+/**
+ * Capability system — barrel export.
+ *
+ * @see docs/architecture/capability-packs.md
+ */
+
+export { CapabilityRegistry } from './registry.js';
+export type { FlowForValidation } from './registry.js';
+export { chainToCapability } from './chain-mapping.js';
+export type {
+  CapabilityDefinition,
+  CapabilityHandler,
+  CapabilityContext,
+  CapabilityResult,
+  KnowledgeContext,
+  BrainRecommendation,
+  RegisteredCapability,
+  ResolvedCapability,
+  PackSuggestion,
+  FlowValidation,
+} from './types.js';