cognitive-core 0.0.2 → 0.1.0

package/src/memory/playbook.ts

@@ -0,0 +1,493 @@
+/**
+ * Playbook Library - Unified store for adaptive guidance
+ * Replaces StrategyBank + SkillStore with a single, evolvable abstraction
+ */
+
+import type {
+  Playbook,
+  PlaybookOrigin,
+  FailureRecord,
+  Refinement,
+} from '../types/index.js';
+import { createPlaybook, bumpPlaybookVersion } from '../types/index.js';
+import { JsonStore } from '../utils/storage.js';
+import { textSimilarity } from '../utils/similarity.js';
+
+/**
+ * Match result for playbook retrieval
+ */
+export interface PlaybookMatch {
+  playbook: Playbook;
+  score: number;
+  matchType: 'situation' | 'trigger' | 'domain';
+}
+
+/**
+ * Options for finding matching playbooks
+ */
+export interface FindMatchingOptions {
+  k?: number;
+  domains?: string[];
+  minConfidence?: number;
+  excludeAntiPatterns?: boolean;
+  minScore?: number;
+}
+
+/**
+ * Playbook Library - Store and retrieve adaptive guidance
+ */
+export class PlaybookLibrary {
+  private store: JsonStore<Playbook>;
+  private initialized = false;
+
+  constructor(baseDir: string) {
+    this.store = new JsonStore<Playbook>(baseDir, 'playbooks', {
+      autoSaveInterval: 60000,
+      pretty: true,
+    });
+  }
+
+  async init(): Promise<void> {
+    if (this.initialized) return;
+    await this.store.init();
+    this.initialized = true;
+  }
+
+  // === RETRIEVAL ===
+
+  /**
+   * Find playbooks matching a context
+   * Uses weighted scoring across situations, triggers, and anti-patterns
+   */
+  async findMatching(
+    context: string,
+    options?: FindMatchingOptions
+  ): Promise<PlaybookMatch[]> {
+    await this.init();
+
+    const k = options?.k ?? 5;
+    let playbooks = this.store.values();
+
+    // Filter by domains if specified
+    if (options?.domains && options.domains.length > 0) {
+      playbooks = playbooks.filter((p) =>
+        p.applicability.domains.some((d) => options.domains!.includes(d))
+      );
+    }
+
+    // Filter by minimum confidence
+    if (options?.minConfidence !== undefined) {
+      playbooks = playbooks.filter((p) => p.confidence >= options.minConfidence!);
+    }
+
+    // Score playbooks
+    const scored: PlaybookMatch[] = [];
+
+    for (const playbook of playbooks) {
+      // Check anti-patterns first (if enabled)
+      if (options?.excludeAntiPatterns !== false) {
+        const antiPatternMatch = playbook.applicability.antiPatterns.some(
+          (ap) => textSimilarity(context, ap) > 0.7
+        );
+        if (antiPatternMatch) continue;
+      }
+
+      // Score against situations
+      const situationScores = playbook.applicability.situations.map((s) =>
+        textSimilarity(context, s)
+      );
+      const maxSituationScore =
+        situationScores.length > 0 ? Math.max(...situationScores) : 0;
+
+      // Score against triggers (weighted higher for exact matches)
+      const triggerScores = playbook.applicability.triggers.map((t) =>
+        textSimilarity(context, t)
+      );
+      const maxTriggerScore =
+        triggerScores.length > 0 ? Math.max(...triggerScores) * 1.2 : 0;
+
+      // Combine scores
+      const score = Math.max(maxSituationScore, maxTriggerScore);
+      const matchType: 'situation' | 'trigger' =
+        maxTriggerScore > maxSituationScore ? 'trigger' : 'situation';
+
+      if (score > 0) {
+        scored.push({ playbook, score, matchType });
+      }
+    }
+
+    // Sort by score and return top k
+    scored.sort((a, b) => b.score - a.score);
+    const results = scored.slice(0, k);
+
+    // Apply minimum score filter
+    if (options?.minScore !== undefined) {
+      return results.filter((r) => r.score >= options.minScore!);
+    }
+
+    return results;
+  }
+
+  /**
+   * Find by specific trigger (for error messages, etc.)
+   */
+  async findByTrigger(trigger: string, threshold = 0.5): Promise<Playbook[]> {
+    await this.init();
+
+    return this.store.values().filter((playbook) =>
+      playbook.applicability.triggers.some(
+        (t) =>
+          t.toLowerCase().includes(trigger.toLowerCase()) ||
+          textSimilarity(trigger, t) >= threshold
+      )
+    );
+  }
+
+  /**
+   * Get playbooks with refinements for a specific context
+   */
+  async findWithRefinements(context: string): Promise<Playbook[]> {
+    await this.init();
+
+    return this.store.values().filter((playbook) =>
+      playbook.evolution.refinements.some(
+        (r) => textSimilarity(context, r.context) > 0.6
+      )
+    );
+  }
+
+  // === EVOLUTION ===
+
+  /**
+   * Record successful application
+   */
+  async recordSuccess(id: string, _trajectoryId: string): Promise<void> {
+    await this.init();
+    const playbook = this.store.get(id);
+    if (!playbook) return;
+
+    playbook.evolution.successCount++;
+    playbook.evolution.lastUsed = new Date();
+
+    // Increase confidence (exponential moving average)
+    const alpha = 0.1;
+    playbook.confidence = playbook.confidence * (1 - alpha) + 1 * alpha;
+    playbook.confidence = Math.min(playbook.confidence, 0.99); // Cap at 0.99
+
+    playbook.updatedAt = new Date();
+    this.store.set(id, playbook);
+    await this.store.save(id);
+  }
+
+  /**
+   * Record failure and capture context
+   */
+  async recordFailure(
+    id: string,
+    trajectoryId: string,
+    failureContext: string,
+    failureMode: string
+  ): Promise<void> {
+    await this.init();
+    const playbook = this.store.get(id);
+    if (!playbook) return;
+
+    playbook.evolution.failureCount++;
+    playbook.evolution.lastUsed = new Date();
+
+    // Add failure record
+    const failure: FailureRecord = {
+      trajectoryId,
+      context: failureContext,
+      failureMode,
+      timestamp: new Date(),
+    };
+    playbook.evolution.failures.push(failure);
+
+    // Keep only last 10 failures
+    if (playbook.evolution.failures.length > 10) {
+      playbook.evolution.failures = playbook.evolution.failures.slice(-10);
+    }
+
+    // Decrease confidence
+    const alpha = 0.15; // Failures have slightly more impact
+    playbook.confidence = playbook.confidence * (1 - alpha) + 0 * alpha;
+    playbook.confidence = Math.max(playbook.confidence, 0.1); // Floor at 0.1
+
+    playbook.updatedAt = new Date();
+    this.store.set(id, playbook);
+    await this.store.save(id);
+  }
+
+  /**
+   * Add a context-specific refinement
+   */
+  async addRefinement(
+    id: string,
+    context: string,
+    addition: string,
+    source: 'failure' | 'success' | 'manual'
+  ): Promise<void> {
+    await this.init();
+    const playbook = this.store.get(id);
+    if (!playbook) return;
+
+    // Check if similar refinement exists
+    const exists = playbook.evolution.refinements.some(
+      (r) => textSimilarity(r.context, context) > 0.85
+    );
+    if (exists) return;
+
+    const refinement: Refinement = {
+      context,
+      addition,
+      source,
+      addedAt: new Date(),
+    };
+
+    playbook.evolution.refinements.push(refinement);
+
+    // Bump patch version
+    playbook.evolution.version = bumpPlaybookVersion(playbook, 'patch');
+    playbook.updatedAt = new Date();
+
+    this.store.set(id, playbook);
+    await this.store.save(id);
+  }
+
+  /**
+   * Evolve playbook based on accumulated failures
+   * Should be called after several failures to update guidance
+   */
+  async evolve(
+    id: string,
+    newGuidance?: Partial<Playbook['guidance']>,
+    newAntiPatterns?: string[]
+  ): Promise<Playbook | undefined> {
+    await this.init();
+    const playbook = this.store.get(id);
+    if (!playbook) return undefined;
+
+    // Update guidance if provided
+    if (newGuidance) {
+      playbook.guidance = { ...playbook.guidance, ...newGuidance };
+    }
+
+    // Add new anti-patterns
+    if (newAntiPatterns) {
+      const unique = newAntiPatterns.filter(
+        (ap) => !playbook.applicability.antiPatterns.includes(ap)
+      );
+      playbook.applicability.antiPatterns.push(...unique);
+    }
+
+    // Bump minor version for evolution
+    playbook.evolution.version = bumpPlaybookVersion(playbook, 'minor');
+    playbook.updatedAt = new Date();
+
+    this.store.set(id, playbook);
+    await this.store.save(id);
+
+    return playbook;
+  }
+
+  // === LIFECYCLE ===
+
+  /**
+   * Add a new playbook
+   */
+  async add(playbook: Playbook): Promise<void> {
+    await this.init();
+    this.store.set(playbook.id, playbook);
+    await this.store.save(playbook.id);
+  }
+
+  /**
+   * Create and add a new playbook
+   */
+  async create(
+    input: Parameters<typeof createPlaybook>[0]
+  ): Promise<Playbook> {
+    const playbook = createPlaybook(input);
+    await this.add(playbook);
+    return playbook;
+  }
+
+  /**
+   * Get a playbook by ID
+   */
+  async get(id: string): Promise<Playbook | undefined> {
+    await this.init();
+    return this.store.get(id);
+  }
+
+  /**
+   * Get playbook by name
+   */
+  async getByName(name: string): Promise<Playbook | undefined> {
+    await this.init();
+    return this.store.values().find((p) => p.name === name);
+  }
+
+  /**
+   * Check if a similar playbook exists
+   */
+  async exists(
+    description: string,
+    threshold = 0.85
+  ): Promise<Playbook | undefined> {
+    await this.init();
+
+    // Check by exact name match
+    const byName = this.store.values().find(
+      (p) => p.name === description.toLowerCase().replace(/\s+/g, '-')
+    );
+    if (byName) return byName;
+
+    // Check by situation similarity
+    for (const playbook of this.store.values()) {
+      for (const situation of playbook.applicability.situations) {
+        if (textSimilarity(description, situation) >= threshold) {
+          return playbook;
+        }
+      }
+    }
+
+    return undefined;
+  }
+
+  /**
+   * Get playbooks by domain
+   */
+  async getByDomain(domain: string): Promise<Playbook[]> {
+    await this.init();
+    return this.store.values().filter((p) =>
+      p.applicability.domains.includes(domain)
+    );
+  }
+
+  /**
+   * Get most effective playbooks (by success rate)
+   */
+  async getMostEffective(k = 10): Promise<Playbook[]> {
+    await this.init();
+    return this.store
+      .values()
+      .filter((p) => p.evolution.successCount + p.evolution.failureCount >= 3)
+      .sort((a, b) => {
+        const rateA =
+          a.evolution.successCount /
+          (a.evolution.successCount + a.evolution.failureCount);
+        const rateB =
+          b.evolution.successCount /
+          (b.evolution.successCount + b.evolution.failureCount);
+        return rateB - rateA;
+      })
+      .slice(0, k);
+  }
+
+  /**
+   * Get playbooks by confidence threshold
+   */
+  async getHighConfidence(minConfidence = 0.8): Promise<Playbook[]> {
+    await this.init();
+    return this.store.values().filter((p) => p.confidence >= minConfidence);
+  }
+
+  /**
+   * Get all playbooks
+   */
+  async getAll(): Promise<Playbook[]> {
+    await this.init();
+    return this.store.values();
+  }
+
+  /**
+   * Delete a playbook
+   */
+  async delete(id: string): Promise<boolean> {
+    await this.init();
+    const existed = this.store.has(id);
+    if (existed) {
+      this.store.delete(id);
+    }
+    return existed;
+  }
+
+  /**
+   * Get count
+   */
+  async count(): Promise<number> {
+    await this.init();
+    return this.store.size();
+  }
+
+  /**
+   * Get all unique domains
+   */
+  async getDomains(): Promise<string[]> {
+    await this.init();
+    const domains = new Set<string>();
+    for (const playbook of this.store.values()) {
+      for (const domain of playbook.applicability.domains) {
+        domains.add(domain);
+      }
+    }
+    return Array.from(domains);
+  }
+
+  // === PROVENANCE ===
+
+  /**
+   * Get playbooks by origin type
+   */
+  async getByOrigin(origin: PlaybookOrigin): Promise<Playbook[]> {
+    await this.init();
+    return this.store.values().filter((p) => p.provenance?.origin === origin);
+  }
+
+  /**
+   * Delete all playbooks with a specific origin
+   * Returns the number of playbooks deleted
+   */
+  async deleteByOrigin(origin: PlaybookOrigin): Promise<number> {
+    await this.init();
+    const toDelete = this.store.values().filter((p) => p.provenance?.origin === origin);
+    for (const playbook of toDelete) {
+      this.store.delete(playbook.id);
+    }
+    return toDelete.length;
+  }
+
+  /**
+   * Get provenance summary across all playbooks
+   */
+  async getProvenanceSummary(): Promise<Record<PlaybookOrigin, number>> {
+    await this.init();
+    const summary: Record<string, number> = {
+      extracted: 0,
+      curated: 0,
+      imported: 0,
+      manual: 0,
+    };
+    for (const playbook of this.store.values()) {
+      const origin = playbook.provenance?.origin ?? 'extracted';
+      summary[origin] = (summary[origin] ?? 0) + 1;
+    }
+    return summary as Record<PlaybookOrigin, number>;
+  }
+
+  /**
+   * Close the store
+   */
+  async close(): Promise<void> {
+    await this.store.close();
+  }
+}
+
+/**
+ * Create a playbook library
+ */
+export function createPlaybookLibrary(baseDir: string): PlaybookLibrary {
+  return new PlaybookLibrary(baseDir);
+}