cognitive-core 0.0.1 → 0.1.0

package/src/atlas.ts

@@ -0,0 +1,560 @@
+import type {
+  Task,
+  Trajectory,
+  AtlasConfig,
+  Playbook,
+} from './types/index.js';
+import { createDefaultConfig } from './types/index.js';
+import { MemorySystem, createMemorySystem } from './memory/index.js';
+import {
+  LearningPipeline,
+  createLearningPipeline,
+  type ProcessResult,
+  type BatchResult,
+} from './learning/index.js';
+import {
+  PlaybookUsageInference,
+  createUsageInference,
+} from './learning/usage-inference.js';
+import { TaskRouter, createRouter, type RoutingDecision } from './search/router.js';
+import { DirectSolver, createSolver } from './search/solver.js';
+import {
+  RefinementLoop,
+  createRefinementLoop,
+} from './search/refinement-loop.js';
+import type { RefinementResult } from './search/refinement-types.js';
+import type { LLMProvider } from './agents/types.js';
+import { AgentManager, createAgentManager } from './runtime/manager.js';
+import type { AgentBackend, AgentSpawnConfig } from './runtime/types.js';
+import {
+  SkillLibrary,
+  createSkillLibrary,
+} from './surfacing/skill-library.js';
+import {
+  PlaybookMCPServer,
+  createPlaybookMCPServer,
+} from './mcp/playbook-server.js';
+
+/**
+ * Atlas statistics
+ */
+export interface AtlasStats {
+  memory: {
+    experienceCount: number;
+    playbookCount: number;
+    metaObservationCount: number;
+  };
+  learning: {
+    trajectoriesProcessed: number;
+    pendingTrajectories: number;
+  };
+  execution?: {
+    agentManagerEnabled: boolean;
+    refinementEnabled: boolean;
+    backends: string[];
+  };
+  skillLibrary?: {
+    coreSkillCount: number;
+    domainSkillCounts: Record<string, number>;
+    mcpServerEnabled: boolean;
+  };
+}
+
+/**
+ * Playbook usage tracking
+ */
+export interface PlaybookUsage {
+  playbookId: string;
+  playbookName: string;
+  wasUsed: boolean;
+  usageConfidence: number;
+  wasSuccessful: boolean;
+}
+
+/**
+ * Extended solve result with refinement info
+ */
+export interface SolveResult {
+  /** The execution trajectory */
+  trajectory: Trajectory;
+  /** Whether memory was used */
+  usedMemory?: boolean;
+  /** Strategy used (from legacy solver) */
+  strategy?: string;
+  /** Routing decision (when using AgentManager) */
+  routing?: RoutingDecision;
+  /** Whether the result came from agent execution (vs direct solver) */
+  usedAgentManager: boolean;
+  /** Refinement result if refinement was performed */
+  refinement?: RefinementResult;
+  /** Playbooks that were injected for this task */
+  injectedPlaybooks?: Playbook[];
+  /** Playbook usage inference results */
+  playbookUsage?: PlaybookUsage[];
+}
+
+/**
+ * Atlas - Adaptive Trajectory Learning and Abstraction System
+ *
+ * Main orchestrator that combines:
+ * - Memory systems (experiences, playbooks, meta-observations)
+ * - Learning engine (trajectory analysis, playbook extraction)
+ * - Task routing (deciding how to solve tasks)
+ * - Skill surfacing (providing playbooks to agents)
+ */
+export class Atlas {
+  private memory: MemorySystem;
+  private learning: LearningPipeline;
+  private router: TaskRouter;
+  private solver: DirectSolver | null = null;
+  private agentManager: AgentManager | null = null;
+  private refinementLoop: RefinementLoop | null = null;
+  private config: AtlasConfig;
+  private provider: LLMProvider | null = null;
+  private trajectoriesProcessed = 0;
+
+  // Playbook-based components
+  private skillLibrary: SkillLibrary | null = null;
+  private usageInference: PlaybookUsageInference | null = null;
+  private mcpServer: PlaybookMCPServer | null = null;
+
+  constructor(config?: Partial<AtlasConfig>) {
+    this.config = createDefaultConfig(config);
+
+    // Initialize memory system
+    this.memory = createMemorySystem(
+      this.config.storage.baseDir,
+      this.config.memory
+    );
+
+    // Initialize learning pipeline
+    this.learning = createLearningPipeline(this.memory, this.config.learning);
+
+    // Initialize router
+    this.router = createRouter(this.memory, this.config.router);
+  }
+
+  /**
+   * Initialize Atlas (load persisted data)
+   */
+  async init(): Promise<void> {
+    await this.memory.init();
+
+    // Initialize playbook-based components if playbooks are available
+    if (this.memory.playbooks) {
+      this.skillLibrary = createSkillLibrary(
+        this.memory.playbooks,
+        this.config.skillLibrary
+      );
+      this.usageInference = createUsageInference();
+
+      // Refresh skill tiers on init
+      await this.skillLibrary.refreshTiers();
+    }
+  }
+
+  /**
+   * Set the LLM provider for solving (deprecated)
+   * @deprecated Use setAgentManager() with backends for real execution
+   */
+  setProvider(provider: LLMProvider): void {
+    this.provider = provider;
+    this.solver = createSolver(this.memory, provider);
+  }
+
+  /**
+   * Set up the AgentManager with backends for real action execution
+   * This is the recommended way to configure Atlas for execution
+   */
+  setAgentManager(backends: AgentBackend[]): void {
+    // Create AgentManager with memory system
+    this.agentManager = createAgentManager(this.memory);
+
+    // Register all backends
+    for (const backend of backends) {
+      this.agentManager.registerBackend(backend);
+    }
+
+    // Create refinement loop with config
+    this.refinementLoop = createRefinementLoop(
+      this.agentManager,
+      this.memory,
+      {
+        maxIterations: this.config.refinement.maxIterations,
+        minAcceptableScore: this.config.refinement.acceptableScore,
+        evaluatorConfig: {
+          evaluatorAgentType: this.config.refinement.evaluatorAgentType,
+        },
+        triggerOnStrategies: this.config.refinement.triggerOnStrategies,
+        confidenceThreshold: this.config.refinement.confidenceThreshold,
+      }
+    );
+  }
+
+  /**
+   * Get the AgentManager for direct access
+   */
+  getAgentManager(): AgentManager | null {
+    return this.agentManager;
+  }
+
+  /**
+   * Get the RefinementLoop for registering domain verifiers
+   */
+  getRefinementLoop(): RefinementLoop | null {
+    return this.refinementLoop;
+  }
+
+  /**
+   * Check if agent execution is available
+   */
+  hasAgentExecution(): boolean {
+    return this.agentManager !== null;
+  }
+
+  /**
+   * Solve a task using the best available method
+   * Prefers AgentManager with refinement when available
+   */
+  async solve(task: Task): Promise<SolveResult> {
+    // Route the task first
+    const routing = await this.router.route(task);
+
+    // Get skills for the agent if skill library is available
+    let injectedPlaybooks: Playbook[] = [];
+    let skillContext = '';
+    if (this.skillLibrary) {
+      const skills = await this.skillLibrary.getSkillsForAgent(task);
+      injectedPlaybooks = [...skills.core, ...skills.domain, ...skills.contextual];
+      skillContext = this.skillLibrary.formatForSystemPrompt(skills);
+    }
+
+    // Merge playbooks from router's memory context (deduplicating by ID)
+    // This ensures we track ALL playbooks that will be injected into the agent
+    const injectedIds = new Set(injectedPlaybooks.map(p => p.id));
+    for (const { playbook } of routing.memoryContext.playbooks) {
+      if (!injectedIds.has(playbook.id)) {
+        injectedPlaybooks.push(playbook);
+        injectedIds.add(playbook.id);
+      }
+    }
+
+    let result: SolveResult;
+
+    // Prefer AgentManager if available
+    if (this.agentManager) {
+      result = await this.solveWithAgent(task, routing, skillContext);
+    } else if (this.solver && this.provider) {
+      // Fall back to DirectSolver (deprecated)
+      const solverResult = await this.solver.solve(task, routing);
+      result = {
+        trajectory: solverResult.trajectory,
+        usedMemory: solverResult.usedMemory,
+        strategy: solverResult.strategy,
+        usedAgentManager: false,
+      };
+    } else {
+      throw new Error(
+        'No execution method available. Call setAgentManager() or setProvider().'
+      );
+    }
+
+    // Add injected playbooks to result
+    result.injectedPlaybooks = injectedPlaybooks;
+
+    // Infer playbook usage from trajectory
+    if (this.usageInference && this.skillLibrary && injectedPlaybooks.length > 0) {
+      const usageResults = await this.usageInference.inferUsage(
+        result.trajectory,
+        injectedPlaybooks
+      );
+
+      // Convert to PlaybookUsage format and record outcomes
+      result.playbookUsage = [];
+      for (const usage of usageResults) {
+        result.playbookUsage.push({
+          playbookId: usage.playbookId,
+          playbookName: usage.playbookName,
+          wasUsed: usage.wasUsed,
+          usageConfidence: usage.usageConfidence,
+          wasSuccessful: usage.wasSuccessful,
+        });
+
+        // Record outcome for tier management
+        if (usage.wasUsed) {
+          await this.skillLibrary.recordOutcome(
+            usage.playbookId,
+            result.trajectory.id,
+            usage.wasSuccessful,
+            usage.context
+          );
+        }
+      }
+    }
+
+    // Process the trajectory for learning
+    await this.learning.processTrajectory(result.trajectory);
+    this.trajectoriesProcessed++;
+
+    // Run batch learning if ready
+    if (this.learning.shouldRunBatch()) {
+      await this.runBatchLearning();
+    }
+
+    return result;
+  }
+
+  /**
+   * Solve using AgentManager with optional refinement
+   */
+  private async solveWithAgent(
+    task: Task,
+    routing: RoutingDecision,
+    skillContext?: string
+  ): Promise<SolveResult> {
+    if (!this.agentManager) {
+      throw new Error('AgentManager not available');
+    }
+
+    // Build spawn configuration
+    const spawnConfig: AgentSpawnConfig = {
+      agentType: this.config.execution.defaultAgentType,
+      task,
+      timeout: this.config.execution.maxExecutionTime * 1000,
+      captureToolCalls: this.config.execution.captureToolCalls,
+      // Inject skill context if available
+      systemPromptAdditions: skillContext || undefined,
+      // Pass router's memory context to avoid duplicate memory queries
+      injectedKnowledge: routing.memoryContext,
+    };
+
+    // Run initial execution
+    const agentResult = await this.agentManager.spawn(spawnConfig);
+
+    // Check if refinement should be triggered
+    const shouldRefine =
+      this.refinementLoop &&
+      this.config.refinement.useAgentEvaluation &&
+      this.refinementLoop.shouldTriggerRefinement(
+        routing.strategy,
+        routing.confidence
+      );
+
+    let refinementResult: RefinementResult | undefined;
+
+    if (shouldRefine && !agentResult.success) {
+      // Run refinement loop on failed trajectory
+      refinementResult = await this.refinementLoop!.refine(
+        agentResult.trajectory,
+        spawnConfig
+      );
+
+      return {
+        trajectory: refinementResult.trajectory,
+        routing,
+        usedAgentManager: true,
+        refinement: refinementResult,
+      };
+    }
+
+    return {
+      trajectory: agentResult.trajectory,
+      routing,
+      usedAgentManager: true,
+    };
+  }
+
+  /**
+   * Solve multiple tasks
+   */
+  async solveBatch(tasks: Task[]): Promise<SolveResult[]> {
+    const results: SolveResult[] = [];
+    for (const task of tasks) {
+      const result = await this.solve(task);
+      results.push(result);
+    }
+    return results;
+  }
+
+  /**
+   * Process an external trajectory (from another agent)
+   */
+  async processTrajectory(trajectory: Trajectory): Promise<ProcessResult> {
+    const result = await this.learning.processTrajectory(trajectory);
+    this.trajectoriesProcessed++;
+    return result;
+  }
+
+  /**
+   * Run batch learning explicitly
+   */
+  async runBatchLearning(): Promise<BatchResult> {
+    return this.learning.runBatchLearning();
+  }
+
+  /**
+   * Query memory for relevant context
+   */
+  async queryMemory(
+    query: string,
+    options?: {
+      domains?: string[];
+      includeExperiences?: boolean;
+      includePlaybooks?: boolean;
+    }
+  ) {
+    return this.memory.queryV2(query, options);
+  }
+
+  /**
+   * Get Atlas statistics
+   */
+  async getStats(): Promise<AtlasStats> {
+    const memoryStats = await this.memory.getStats();
+    const stats: AtlasStats = {
+      memory: memoryStats,
+      learning: {
+        trajectoriesProcessed: this.trajectoriesProcessed,
+        pendingTrajectories: this.learning.getAccumulatedCount(),
+      },
+    };
+
+    // Add execution stats if AgentManager is available
+    if (this.agentManager) {
+      stats.execution = {
+        agentManagerEnabled: true,
+        refinementEnabled: this.refinementLoop !== null,
+        backends: this.agentManager.listBackends(),
+      };
+    }
+
+    // Add skill library stats if available
+    if (this.skillLibrary) {
+      const libStats = this.skillLibrary.getStats();
+      stats.skillLibrary = {
+        coreSkillCount: libStats.coreSkillCount,
+        domainSkillCounts: libStats.domainSkillCounts,
+        mcpServerEnabled: this.mcpServer !== null,
+      };
+    }
+
+    return stats;
+  }
+
+  /**
+   * Get the memory system for direct access
+   */
+  getMemory(): MemorySystem {
+    return this.memory;
+  }
+
+  /**
+   * Get the learning pipeline for direct access
+   */
+  getLearning(): LearningPipeline {
+    return this.learning;
+  }
+
+  /**
+   * Get the skill library for direct access
+   */
+  getSkillLibrary(): SkillLibrary | null {
+    return this.skillLibrary;
+  }
+
+  /**
+   * Get the MCP server for direct access
+   */
+  getMCPServer(): PlaybookMCPServer | null {
+    return this.mcpServer;
+  }
+
+  /**
+   * Start the MCP server for playbook access
+   */
+  async startMCPServer(): Promise<void> {
+    if (!this.memory.playbooks) {
+      throw new Error('Playbook library not available. Initialize Atlas first.');
+    }
+
+    if (this.mcpServer) {
+      return; // Already started
+    }
+
+    this.mcpServer = createPlaybookMCPServer(
+      this.memory.playbooks,
+      this.skillLibrary ?? undefined,
+      this.config.mcp
+    );
+  }
+
+  /**
+   * Stop the MCP server
+   */
+  async stopMCPServer(): Promise<void> {
+    if (this.mcpServer) {
+      this.mcpServer = null;
+    }
+  }
+
+  /**
+   * Update configuration
+   */
+  updateConfig(config: Partial<AtlasConfig>): void {
+    if (config.learning) {
+      this.learning.updateConfig(config.learning);
+    }
+    if (config.router) {
+      this.router.updateConfig(config.router);
+    }
+    this.config = { ...this.config, ...config };
+  }
+
+  /**
+   * Close Atlas (flush data to disk)
+   */
+  async close(): Promise<void> {
+    // Stop MCP server if running
+    await this.stopMCPServer();
+
+    // Flush learning pipeline
+    if (this.learning.getAccumulatedCount() > 0) {
+      await this.learning.runBatchLearning();
+    }
+    // Close memory system
+    await this.memory.close();
+  }
+}
+
+/**
+ * Create an Atlas instance
+ */
+export function createAtlas(config?: Partial<AtlasConfig>): Atlas {
+  return new Atlas(config);
+}
+
+/**
+ * Create an Atlas instance with an LLM provider
+ * @deprecated Use createAtlasWithAgents() for real action execution
+ */
+export function createAtlasWithProvider(
+  provider: LLMProvider,
+  config?: Partial<AtlasConfig>
+): Atlas {
+  const atlas = new Atlas(config);
+  atlas.setProvider(provider);
+  return atlas;
+}
+
+/**
+ * Create an Atlas instance with AgentManager backends
+ * This is the recommended way to create Atlas for production use
+ */
+export function createAtlasWithAgents(
+  backends: AgentBackend[],
+  config?: Partial<AtlasConfig>
+): Atlas {
+  const atlas = new Atlas(config);
+  atlas.setAgentManager(backends);
+  return atlas;
+}