cognitive-core 0.0.2 → 0.1.2

package/scripts/migrate-to-playbooks.ts

@@ -0,0 +1,307 @@
+#!/usr/bin/env npx tsx
+/**
+ * Migration Script: Strategy + Skill → Playbook
+ *
+ * Converts existing Strategy and Skill data to the new Playbook format.
+ * Run this script to migrate your data after updating to the new architecture.
+ *
+ * Usage:
+ *   npx tsx scripts/migrate-to-playbooks.ts [--data-dir=.atlas] [--dry-run]
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import type { Strategy, Skill, Playbook } from '../src/types/index.js';
+import { createPlaybook } from '../src/types/index.js';
+import { textSimilarity } from '../src/utils/similarity.js';
+
+// Parse command line arguments
+const args = process.argv.slice(2);
+const dryRun = args.includes('--dry-run');
+const dataDirArg = args.find((a) => a.startsWith('--data-dir='));
+const dataDir = dataDirArg ? dataDirArg.split('=')[1] : '.atlas';
+
+console.log('=== Playbook Migration Script ===\n');
+console.log(`Data directory: ${dataDir}`);
+console.log(`Dry run: ${dryRun}\n`);
+
+/**
+ * Load JSON data from a file
+ */
+function loadJsonData<T>(filePath: string): T | null {
+  if (!existsSync(filePath)) {
+    console.log(`  File not found: ${filePath}`);
+    return null;
+  }
+
+  try {
+    const content = readFileSync(filePath, 'utf-8');
+    return JSON.parse(content) as T;
+  } catch (error) {
+    console.error(`  Error reading ${filePath}:`, error);
+    return null;
+  }
+}
+
+/**
+ * Save JSON data to a file
+ */
+function saveJsonData(filePath: string, data: unknown): void {
+  if (dryRun) {
+    console.log(`  [DRY RUN] Would write to: ${filePath}`);
+    return;
+  }
+
+  const dir = filePath.substring(0, filePath.lastIndexOf('/'));
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+
+  writeFileSync(filePath, JSON.stringify(data, null, 2));
+  console.log(`  Written: ${filePath}`);
+}
+
+/**
+ * Generate a kebab-case playbook name
+ */
+function generatePlaybookName(text: string): string {
+  return text
+    .toLowerCase()
+    .replace(/[^\w\s]/g, '')
+    .split(/\s+/)
+    .filter((w) => w.length > 2)
+    .slice(0, 4)
+    .join('-') || `playbook-${Date.now()}`;
+}
+
+/**
+ * Convert a Skill to a Playbook
+ */
+function skillToPlaybook(skill: Skill): Playbook {
+  return createPlaybook({
+    id: `playbook-skill-${skill.id}`,
+    name: skill.name,
+    applicability: {
+      situations: [skill.description],
+      triggers: skill.triggers || [],
+      antiPatterns: [],
+      domains: skill.domain ? [skill.domain] : [],
+    },
+    guidance: {
+      strategy: skill.description,
+      tactics: skill.solution || [],
+      steps: skill.solution || [],
+    },
+    verification: {
+      successIndicators: skill.verification ? [skill.verification] : [],
+      failureIndicators: [],
+    },
+    evolution: {
+      version: skill.version || '1.0.0',
+      createdFrom: [],
+      failures: [],
+      refinements: [],
+      successCount: Math.round((skill.usageCount || 0) * (skill.successRate || 0.5)),
+      failureCount: Math.round((skill.usageCount || 0) * (1 - (skill.successRate || 0.5))),
+    },
+    confidence: skill.successRate || 0.5,
+    complexity: (skill.solution?.length || 0) > 5 ? 'complex' : 'moderate',
+    estimatedEffort: skill.solution?.length || 3,
+    createdAt: skill.createdAt ? new Date(skill.createdAt) : new Date(),
+    updatedAt: skill.updatedAt ? new Date(skill.updatedAt) : new Date(),
+  });
+}
+
+/**
+ * Convert a Strategy to a Playbook
+ */
+function strategyToPlaybook(strategy: Strategy): Playbook {
+  return createPlaybook({
+    id: `playbook-strategy-${strategy.id}`,
+    name: generatePlaybookName(strategy.situation),
+    applicability: {
+      situations: [strategy.situation],
+      triggers: [], // Strategies are more abstract, fewer triggers
+      antiPatterns: [],
+      domains: strategy.domain ? [strategy.domain] : [],
+    },
+    guidance: {
+      strategy: strategy.suggestion,
+      tactics: (strategy.parameters as Record<string, unknown>)?.steps as string[] || [],
+    },
+    verification: {
+      successIndicators: [],
+      failureIndicators: [],
+    },
+    evolution: {
+      version: '1.0.0',
+      createdFrom: strategy.sourceTrajectoryIds || [],
+      failures: [],
+      refinements: [],
+      successCount: Math.round((strategy.usageCount || 0) * (strategy.successRate || 0.5)),
+      failureCount: Math.round((strategy.usageCount || 0) * (1 - (strategy.successRate || 0.5))),
+    },
+    confidence: strategy.confidence || 0.5,
+    complexity: 'moderate',
+    estimatedEffort: 3,
+    createdAt: strategy.createdAt ? new Date(strategy.createdAt) : new Date(),
+    updatedAt: strategy.updatedAt ? new Date(strategy.updatedAt) : new Date(),
+  });
+}
+
+/**
+ * Merge similar playbooks
+ */
+function mergePlaybooks(playbooks: Playbook[]): Playbook[] {
+  const merged: Playbook[] = [];
+  const used = new Set<string>();
+
+  for (const playbook of playbooks) {
+    if (used.has(playbook.id)) continue;
+
+    // Find similar playbooks
+    let current = playbook;
+    for (const other of playbooks) {
+      if (used.has(other.id) || other.id === current.id) continue;
+
+      // Check similarity
+      const situationSimilarity = Math.max(
+        ...current.applicability.situations.flatMap((s1) =>
+          other.applicability.situations.map((s2) => textSimilarity(s1, s2))
+        ),
+        0
+      );
+
+      if (situationSimilarity > 0.85) {
+        // Merge
+        console.log(`  Merging: ${other.name} into ${current.name}`);
+        current = {
+          ...current,
+          applicability: {
+            ...current.applicability,
+            situations: [...new Set([...current.applicability.situations, ...other.applicability.situations])],
+            triggers: [...new Set([...current.applicability.triggers, ...other.applicability.triggers])],
+            domains: [...new Set([...current.applicability.domains, ...other.applicability.domains])],
+          },
+          guidance: {
+            ...current.guidance,
+            tactics: [...new Set([...current.guidance.tactics, ...other.guidance.tactics])],
+          },
+          evolution: {
+            ...current.evolution,
+            createdFrom: [...new Set([...current.evolution.createdFrom, ...other.evolution.createdFrom])],
+            successCount: current.evolution.successCount + other.evolution.successCount,
+            failureCount: current.evolution.failureCount + other.evolution.failureCount,
+          },
+          confidence: Math.max(current.confidence, other.confidence),
+        };
+        used.add(other.id);
+      }
+    }
+
+    merged.push(current);
+    used.add(current.id);
+  }
+
+  return merged;
+}
+
+/**
+ * Main migration function
+ */
+async function migrate(): Promise<void> {
+  console.log('Step 1: Loading existing data...\n');
+
+  // Load strategies
+  const strategiesPath = join(dataDir, 'strategies.json');
+  const strategiesData = loadJsonData<Record<string, Strategy>>(strategiesPath);
+  const strategies = strategiesData ? Object.values(strategiesData) : [];
+  console.log(`  Found ${strategies.length} strategies`);
+
+  // Load skills
+  const skillsPath = join(dataDir, 'skills.json');
+  const skillsData = loadJsonData<Record<string, Skill>>(skillsPath);
+  const skills = skillsData ? Object.values(skillsData) : [];
+  console.log(`  Found ${skills.length} skills`);
+
+  if (strategies.length === 0 && skills.length === 0) {
+    console.log('\nNo data to migrate. Exiting.');
+    return;
+  }
+
+  console.log('\nStep 2: Converting to playbooks...\n');
+
+  // Convert skills first (they're more concrete)
+  const fromSkills = skills.map(skillToPlaybook);
+  console.log(`  Converted ${fromSkills.length} skills to playbooks`);
+
+  // Convert strategies
+  const fromStrategies = strategies.map(strategyToPlaybook);
+  console.log(`  Converted ${fromStrategies.length} strategies to playbooks`);
+
+  // Combine
+  const allPlaybooks = [...fromSkills, ...fromStrategies];
+
+  console.log('\nStep 3: Merging similar playbooks...\n');
+  const mergedPlaybooks = mergePlaybooks(allPlaybooks);
+  console.log(`  Merged to ${mergedPlaybooks.length} unique playbooks`);
+
+  console.log('\nStep 4: Saving playbooks...\n');
+
+  // Create playbooks record
+  const playbooksRecord: Record<string, Playbook> = {};
+  for (const playbook of mergedPlaybooks) {
+    playbooksRecord[playbook.id] = playbook;
+  }
+
+  // Save playbooks
+  const playbooksPath = join(dataDir, 'playbooks.json');
+  saveJsonData(playbooksPath, playbooksRecord);
+
+  console.log('\nStep 5: Creating migration report...\n');
+
+  const report = {
+    timestamp: new Date().toISOString(),
+    dryRun,
+    source: {
+      strategiesCount: strategies.length,
+      skillsCount: skills.length,
+    },
+    result: {
+      playbooksCount: mergedPlaybooks.length,
+      mergedCount: allPlaybooks.length - mergedPlaybooks.length,
+    },
+    playbooks: mergedPlaybooks.map((p) => ({
+      id: p.id,
+      name: p.name,
+      domains: p.applicability.domains,
+      confidence: p.confidence,
+      successCount: p.evolution.successCount,
+    })),
+  };
+
+  const reportPath = join(dataDir, 'migration-report.json');
+  saveJsonData(reportPath, report);
+
+  console.log('\n=== Migration Complete ===\n');
+  console.log('Summary:');
+  console.log(`  - Strategies migrated: ${strategies.length}`);
+  console.log(`  - Skills migrated: ${skills.length}`);
+  console.log(`  - Playbooks created: ${mergedPlaybooks.length}`);
+  console.log(`  - Playbooks merged: ${allPlaybooks.length - mergedPlaybooks.length}`);
+
+  if (dryRun) {
+    console.log('\n[DRY RUN] No files were modified. Run without --dry-run to apply changes.');
+  } else {
+    console.log('\nPlaybooks saved to:', playbooksPath);
+    console.log('Migration report saved to:', reportPath);
+    console.log('\nNote: Original strategy and skill files were not modified.');
+    console.log('You can delete them after verifying the migration.');
+  }
+}
+
+// Run migration
+migrate().catch((error) => {
+  console.error('Migration failed:', error);
+  process.exit(1);
+});

package/src/agents/index.ts

@@ -0,0 +1,14 @@
+// Types and base classes
+export {
+  Agent,
+  type LLMProvider,
+  type Message,
+  type CompletionOptions,
+  type AgentConfig,
+  type ToolDefinition,
+  type ToolCall,
+  type ToolAgent,
+} from './types.js';
+
+// Mock provider for testing
+export { MockLLMProvider, createMockProvider } from './mock-provider.js';

package/src/agents/mock-provider.ts

@@ -0,0 +1,93 @@
+import type { LLMProvider, Message, CompletionOptions } from './types.js';
+
+/**
+ * Mock LLM provider for testing
+ * Returns predefined responses based on input patterns
+ */
+export class MockLLMProvider implements LLMProvider {
+  readonly name = 'mock';
+
+  private responses: Map<RegExp, string> = new Map();
+
+  constructor() {
+    // Default mock responses
+    this.addResponse(
+      /extract.*strateg/i,
+      `STRATEGY:
+- Situation: When facing a debugging task with unclear error messages
+- Suggestion: Start by reproducing the issue, then use binary search to isolate the problem
+- Parameters: error_message, codebase_size
+- Confidence: 0.7`
+    );
+
+    this.addResponse(
+      /extract.*concept/i,
+      `CONCEPT:
+- Name: error-handler
+- Description: Generic error handling wrapper function
+- Code: \`\`\`typescript
+function handleError<T>(fn: () => T): T | null {
+  try {
+    return fn();
+  } catch (e) {
+    console.error(e);
+    return null;
+  }
+}
+\`\`\`
+- Signature: (() => T) -> T | null`
+    );
+
+    this.addResponse(
+      /extract.*skill|codify.*skill/i,
+      `SKILL:
+- Name: fix-typescript-import-error
+- Problem: Resolve TypeScript module import errors
+- Triggers: Cannot find module, Module not found, TS2307
+- Steps:
+  1. Check if the module is installed in package.json
+  2. Verify the import path is correct
+  3. Check tsconfig.json module resolution settings
+  4. Run npm install or yarn if module is missing
+- Verification: Run tsc --noEmit to verify no import errors`
+    );
+  }
+
+  /**
+   * Add a custom response pattern
+   */
+  addResponse(pattern: RegExp, response: string): void {
+    this.responses.set(pattern, response);
+  }
+
+  /**
+   * Generate a completion (mock)
+   */
+  async complete(
+    messages: Message[],
+    _options?: CompletionOptions
+  ): Promise<string> {
+    // Get the last user message
+    const lastMessage = messages.filter((m) => m.role === 'user').pop();
+    if (!lastMessage) {
+      return 'No user message found.';
+    }
+
+    // Check patterns
+    for (const [pattern, response] of this.responses) {
+      if (pattern.test(lastMessage.content)) {
+        return response;
+      }
+    }
+
+    // Default response
+    return 'No matching pattern found for this request.';
+  }
+}
+
+/**
+ * Create a mock provider for testing
+ */
+export function createMockProvider(): MockLLMProvider {
+  return new MockLLMProvider();
+}

package/src/agents/types.ts

@@ -0,0 +1,137 @@
+/**
+ * Agent types and protocols for Atlas
+ */
+
+/**
+ * Message in a conversation
+ */
+export interface Message {
+  role: 'system' | 'user' | 'assistant';
+  content: string;
+}
+
+/**
+ * LLM completion options
+ */
+export interface CompletionOptions {
+  temperature?: number;
+  maxTokens?: number;
+  stopSequences?: string[];
+}
+
+/**
+ * LLM provider interface
+ * Implement this to use different LLM backends
+ */
+export interface LLMProvider {
+  /**
+   * Generate a completion
+   */
+  complete(
+    messages: Message[],
+    options?: CompletionOptions
+  ): Promise<string>;
+
+  /**
+   * Get the provider name
+   */
+  readonly name: string;
+}
+
+/**
+ * Agent configuration
+ */
+export interface AgentConfig {
+  /** Name of this agent */
+  name: string;
+  /** System prompt */
+  systemPrompt: string;
+  /** LLM provider to use */
+  provider: LLMProvider;
+  /** Default completion options */
+  defaultOptions?: CompletionOptions;
+}
+
+/**
+ * Base agent class
+ */
+export abstract class Agent {
+  protected config: AgentConfig;
+  protected conversationHistory: Message[] = [];
+
+  constructor(config: AgentConfig) {
+    this.config = config;
+    this.reset();
+  }
+
+  /**
+   * Reset the agent state
+   */
+  reset(): void {
+    this.conversationHistory = [
+      { role: 'system', content: this.config.systemPrompt },
+    ];
+  }
+
+  /**
+   * Send a message and get a response
+   */
+  async chat(content: string, options?: CompletionOptions): Promise<string> {
+    this.conversationHistory.push({ role: 'user', content });
+
+    const response = await this.config.provider.complete(
+      this.conversationHistory,
+      { ...this.config.defaultOptions, ...options }
+    );
+
+    this.conversationHistory.push({ role: 'assistant', content: response });
+
+    return response;
+  }
+
+  /**
+   * Get conversation history
+   */
+  getHistory(): Message[] {
+    return [...this.conversationHistory];
+  }
+
+  /**
+   * Get agent name
+   */
+  get name(): string {
+    return this.config.name;
+  }
+}
+
+/**
+ * Tool definition for function calling
+ */
+export interface ToolDefinition {
+  name: string;
+  description: string;
+  parameters: Record<string, unknown>;
+}
+
+/**
+ * Tool call result
+ */
+export interface ToolCall {
+  name: string;
+  arguments: Record<string, unknown>;
+}
+
+/**
+ * Agent with tool use capabilities
+ */
+export interface ToolAgent extends Agent {
+  /**
+   * Available tools
+   */
+  readonly tools: ToolDefinition[];
+
+  /**
+   * Execute a tool
+   */
+  executeTool(call: ToolCall): Promise<unknown>;
+}