cognitive-core 0.0.2 → 0.1.0

package/src/factory.ts

@@ -0,0 +1,263 @@
+/**
+ * Factory Interface for External Integration
+ *
+ * Provides a unified factory interface for creating cognitive-core components.
+ * This is primarily used by skill-tree and other external consumers who need
+ * to inject cognitive-core functionality without direct imports.
+ *
+ * @example
+ * ```typescript
+ * import { createCognitiveCoreFactory } from 'cognitive-core';
+ *
+ * const factory = createCognitiveCoreFactory();
+ *
+ * const memory = factory.createMemorySystem('./.memory');
+ * await memory.init();
+ *
+ * const pipeline = factory.createLearningPipeline(memory, {
+ *   minTrajectories: 5,
+ * });
+ * ```
+ */
+
+import type { Task, Trajectory, Step, Outcome, LearningConfig } from './types/index.js';
+import { createTask, createTrajectory, createStep, successOutcome, failureOutcome } from './types/index.js';
+import type { MemorySystem } from './memory/system.js';
+import { createMemorySystem } from './memory/system.js';
+import type { ProcessResult, BatchResult } from './learning/pipeline.js';
+import { createLearningPipeline } from './learning/pipeline.js';
+
+/**
+ * Parameters for creating a Task
+ */
+export interface TaskParams {
+  id?: string;
+  domain: string;
+  description: string;
+  context?: Record<string, unknown>;
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Parameters for creating a Trajectory
+ */
+export interface TrajectoryParams {
+  id?: string;
+  task: Task;
+  steps: Step[];
+  outcome: Outcome;
+  agentId: string;
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Parameters for creating a Step
+ */
+export interface StepParams {
+  thought?: string;
+  action: string;
+  observation: string;
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Parameters for creating an Outcome
+ */
+export interface OutcomeParams {
+  success: boolean;
+  solution?: unknown;
+  errorInfo?: string;
+  partialScore?: number;
+}
+
+/**
+ * Learning pipeline configuration
+ */
+export interface LearningPipelineConfig {
+  creditStrategy?: 'simple' | 'contribution';
+  minTrajectories?: number;
+  deduplicationThreshold?: number;
+  minSuccessRate?: number;
+}
+
+/**
+ * Interface for the LearningPipeline that external consumers need
+ */
+export interface ILearningPipeline {
+  processTrajectory(trajectory: Trajectory): Promise<ProcessResult>;
+  shouldRunBatch(): boolean;
+  runBatchLearning(): Promise<BatchResult>;
+  getAccumulatedCount(): number;
+  clearAccumulated(): void;
+}
+
+/**
+ * Interface for the MemorySystem that external consumers need
+ */
+export interface IMemorySystem {
+  init(): Promise<void>;
+  close(): Promise<void>;
+  playbooks: {
+    getAll(): Promise<import('./types/playbook.js').Playbook[]>;
+    get(id: string): Promise<import('./types/playbook.js').Playbook | undefined>;
+    add(playbook: import('./types/playbook.js').Playbook): Promise<void>;
+    recordSuccess(id: string, trajectoryId: string): Promise<void>;
+    recordFailure(id: string, trajectoryId: string, context: string, failureMode: string): Promise<void>;
+  };
+  storeTrajectory(trajectory: Trajectory): Promise<import('./types/memory.js').Experience>;
+}
+
+/**
+ * Factory interface for creating cognitive-core components
+ *
+ * This interface allows external consumers (like skill-tree) to create
+ * cognitive-core components without directly importing the implementation.
+ * This enables dependency injection and cleaner integration.
+ */
+export interface CognitiveCoreFactory {
+  /**
+   * Create a memory system for storing experiences and playbooks
+   */
+  createMemorySystem(storagePath: string): IMemorySystem;
+
+  /**
+   * Create a learning pipeline for processing trajectories
+   */
+  createLearningPipeline(
+    memory: IMemorySystem,
+    config?: LearningPipelineConfig
+  ): ILearningPipeline;
+
+  /**
+   * Create a trajectory from parameters
+   */
+  createTrajectory(params: TrajectoryParams): Trajectory;
+
+  /**
+   * Create a task from parameters
+   */
+  createTask(params: TaskParams): Task;
+
+  /**
+   * Create a step from parameters
+   */
+  createStep(params: StepParams): Step;
+
+  /**
+   * Create a success outcome
+   */
+  createSuccessOutcome(solution: unknown): Outcome;
+
+  /**
+   * Create a failure outcome
+   */
+  createFailureOutcome(errorInfo: string): Outcome;
+}
+
+/**
+ * Implementation of the CognitiveCoreFactory
+ */
+class CognitiveCoreFactoryImpl implements CognitiveCoreFactory {
+  createMemorySystem(storagePath: string): IMemorySystem {
+    return createMemorySystem(storagePath) as IMemorySystem;
+  }
+
+  createLearningPipeline(
+    memory: IMemorySystem,
+    config?: LearningPipelineConfig
+  ): ILearningPipeline {
+    return createLearningPipeline(
+      memory as MemorySystem,
+      config as Partial<LearningConfig>
+    ) as ILearningPipeline;
+  }
+
+  createTrajectory(params: TrajectoryParams): Trajectory {
+    return createTrajectory(params);
+  }
+
+  createTask(params: TaskParams): Task {
+    return createTask(params);
+  }
+
+  createStep(params: StepParams): Step {
+    return createStep(params);
+  }
+
+  createSuccessOutcome(solution: unknown): Outcome {
+    return successOutcome(solution);
+  }
+
+  createFailureOutcome(errorInfo: string): Outcome {
+    return failureOutcome(errorInfo);
+  }
+}
+
+/**
+ * Create a factory instance for cognitive-core components
+ *
+ * @returns A factory that can create memory systems, learning pipelines,
+ *          trajectories, tasks, steps, and outcomes.
+ *
+ * @example
+ * ```typescript
+ * const factory = createCognitiveCoreFactory();
+ *
+ * // Create memory system
+ * const memory = factory.createMemorySystem('./.atlas');
+ * await memory.init();
+ *
+ * // Create learning pipeline
+ * const pipeline = factory.createLearningPipeline(memory, {
+ *   minTrajectories: 10,
+ *   deduplicationThreshold: 0.85,
+ * });
+ *
+ * // Create and process trajectory
+ * const task = factory.createTask({
+ *   domain: 'code',
+ *   description: 'Fix the bug',
+ * });
+ *
+ * const trajectory = factory.createTrajectory({
+ *   task,
+ *   steps: [
+ *     factory.createStep({
+ *       action: 'read file',
+ *       observation: 'found bug',
+ *     }),
+ *   ],
+ *   outcome: factory.createSuccessOutcome('Fixed'),
+ *   agentId: 'my-agent',
+ * });
+ *
+ * await pipeline.processTrajectory(trajectory);
+ * ```
+ */
+export function createCognitiveCoreFactory(): CognitiveCoreFactory {
+  return new CognitiveCoreFactoryImpl();
+}
+
+/**
+ * Get the default factory instance
+ *
+ * This is a convenience for consumers who just need the factory functions
+ * without managing a factory instance.
+ */
+export const cognitiveCoreFactory = createCognitiveCoreFactory();
+
+/**
+ * Individual factory functions (for direct imports)
+ *
+ * These are re-exports of the underlying creation functions for consumers
+ * who prefer direct imports over the factory pattern.
+ */
+export {
+  createMemorySystem,
+  createLearningPipeline,
+  createTask,
+  createTrajectory,
+  createStep,
+  successOutcome,
+  failureOutcome,
+};

package/src/index.ts

@@ -0,0 +1,246 @@
+/**
+ * Atlas - Adaptive Trajectory Learning and Abstraction System
+ *
+ * A TypeScript-native cognitive core for building agents that learn
+ * from experience. Extracts playbooks from problem-solving trajectories
+ * to guide future task solving.
+ *
+ * @example
+ * ```typescript
+ * import { createAtlas, createTask } from 'cognitive-core';
+ *
+ * const atlas = createAtlas();
+ * await atlas.init();
+ *
+ * // Set your LLM provider
+ * atlas.setProvider(myProvider);
+ *
+ * // Solve a task
+ * const task = createTask({
+ *   domain: 'code',
+ *   description: 'Write a function that...',
+ * });
+ *
+ * const result = await atlas.solve(task);
+ * console.log(result.trajectory.outcome);
+ *
+ * // Close when done
+ * await atlas.close();
+ * ```
+ */
+
+// Main Atlas class
+export {
+  Atlas,
+  createAtlas,
+  createAtlasWithProvider,
+  createAtlasWithAgents,
+  type AtlasStats,
+  type SolveResult,
+} from './atlas.js';
+
+// Types
+export * from './types/index.js';
+
+// Memory system
+export {
+  MemorySystem,
+  createMemorySystem,
+  ExperienceMemory,
+  type MemoryQueryResult,
+  type MemoryQueryResultV2,
+  // Playbook-based memory
+  PlaybookLibrary,
+  createPlaybookLibrary,
+  type PlaybookMatch,
+  // Meta-learning memory
+  MetaMemory,
+  createMetaMemory,
+} from './memory/index.js';
+
+// Learning engine
+export {
+  LearningPipeline,
+  createLearningPipeline,
+  TrajectoryAnalyzer,
+  createAnalyzer,
+  type ProcessResult,
+  type BatchResult,
+  type AnalysisResult,
+  // Playbook-based learning
+  PlaybookExtractor,
+  createPlaybookExtractor,
+  type ExtractedPlaybooks,
+  type PlaybookUpdate,
+  type PlaybookExtractorConfig,
+  // Meta-learning
+  MetaLearner,
+  createMetaLearner,
+  type MetaLearnerConfig,
+  // Usage inference
+  PlaybookUsageInference,
+  createUsageInference,
+  type PlaybookUsageResult,
+  type UsageInferenceConfig,
+  // LLM-based extraction
+  LLMPlaybookExtractor,
+  createLLMExtractor,
+  type LLMExtractorConfig,
+  type LLMExtractionResult,
+} from './learning/index.js';
+
+// Search/solving
+export {
+  TaskRouter,
+  createRouter,
+  DirectSolver,
+  createSolver,
+  type RoutingDecision,
+  type SolverResult,
+  // Refinement
+  SolutionEvaluator,
+  createSolutionEvaluator,
+  RefinementLoop,
+  createRefinementLoop,
+  createEvaluationResult,
+  scoreToQuality,
+  isQualityAcceptable,
+  type EvaluationResult,
+  type EvaluationIssue,
+  type EvaluationMethod,
+  type QualityLevel,
+  type FailureContext,
+  type RefinementResult,
+  type EvaluatorConfig,
+  type VerificationFunction,
+  type VerificationResult,
+  type RefinementLoopConfig,
+  // Verification runner
+  VerificationRunner,
+  createVerificationRunner,
+  TestRunners,
+  type CommandVerificationConfig,
+  type CommandResult,
+  type VerificationIssue,
+} from './search/index.js';
+
+// Agents
+export {
+  Agent,
+  MockLLMProvider,
+  createMockProvider,
+  type LLMProvider,
+  type Message,
+  type CompletionOptions,
+  type AgentConfig,
+} from './agents/index.js';
+
+// Utilities
+export {
+  cosineSimilarity,
+  textSimilarity,
+  findTopK,
+  JsonStore,
+  saveJson,
+  loadJson,
+} from './utils/index.js';
+
+// Embeddings - Vector search and similarity
+export {
+  // Provider interface and implementations
+  type EmbeddingProvider,
+  type EmbeddingProviderConfig,
+  OpenAIEmbeddingProvider,
+  VoyageEmbeddingProvider,
+  LocalEmbeddingProvider,
+  createEmbeddingProvider,
+  // BM25 text search fallback
+  BM25Index,
+  createBM25Index,
+  type MemoryItemType,
+  // Vector store
+  SqliteVectorStore,
+  createVectorStore,
+  type VectorSearchResult,
+  // Embedding manager
+  EmbeddingManager,
+  createEmbeddingManager,
+  type EmbeddingManagerOptions,
+  type SearchResult,
+} from './embeddings/index.js';
+
+// Runtime - Agent management and flows
+export {
+  // Manager
+  AgentManager,
+  createAgentManager,
+  DefaultKnowledgeInjector,
+  DefaultTrajectoryExtractor,
+  // Backends
+  SubprocessBackend,
+  createSubprocessBackend,
+  claudeCodeConfig,
+  MockBackend,
+  createMockBackend,
+  ACPBackend,
+  createACPBackend,
+  claudeCodeACPConfig,
+  claudeCodeDirectConfig,
+  // Flows
+  LearningFlow,
+  createLearningFlow,
+  ValidationFlow,
+  createValidationFlow,
+  // Types
+  type AgentMessage,
+  type ToolCall,
+  type AgentState,
+  type AgentSession,
+  type AgentSpawnConfig,
+  type AgentResult,
+  type AgentBackend,
+  type KnowledgeInjector,
+  type TrajectoryExtractor,
+  type AgentObserverCallbacks,
+  type SubprocessAgentConfig,
+  type MockAgentBehavior,
+  type ACPAgentConfig,
+  type LearningFlowConfig,
+  type LearningFlowResult,
+  type ValidationFlowConfig,
+  type ValidationFlowResult,
+  type ValidationMetrics,
+} from './runtime/index.js';
+
+// Surfacing - Skill library for agent consumption
+export {
+  SkillLibrary,
+  createSkillLibrary,
+  type AgentSkills,
+  type TierRefreshResult,
+} from './surfacing/index.js';
+
+// MCP Server - On-demand playbook access
+// @deprecated Use the CLI (bin/cognitive-core) + SKILL.md approach instead
+export {
+  PlaybookMCPServer,
+  createPlaybookMCPServer,
+  type MCPTool,
+  type MCPToolCall,
+  type MCPToolResult,
+  type PlaybookSearchResult,
+} from './mcp/index.js';
+
+// Factory - Unified interface for external integration (e.g., skill-tree)
+export {
+  createCognitiveCoreFactory,
+  cognitiveCoreFactory,
+  type CognitiveCoreFactory,
+  type ILearningPipeline,
+  type IMemorySystem,
+  type TaskParams,
+  type TrajectoryParams,
+  type StepParams,
+  type OutcomeParams,
+  type LearningPipelineConfig,
+} from './factory.js';