cognitive-core 0.0.2 → 0.1.2

package/dist/embeddings/vector-store.js

@@ -0,0 +1,256 @@
+/**
+ * Vector Store using sqlite-vec
+ *
+ * Provides efficient vector similarity search using SQLite with the sqlite-vec extension.
+ * sqlite-vec is optimized for in-process vector search without the overhead of external services.
+ */
+import Database from 'better-sqlite3';
+import * as sqliteVec from 'sqlite-vec';
+/**
+ * Vector store using sqlite-vec for efficient similarity search
+ */
+export class SqliteVectorStore {
+    db;
+    dimension;
+    tableName;
+    initialized = false;
+    constructor(options) {
+        this.dimension = options.dimension;
+        this.tableName = options.tableName ?? 'atlas_embeddings';
+        // Create or open the database
+        this.db = new Database(options.dbPath);
+        // Load the sqlite-vec extension
+        sqliteVec.load(this.db);
+        this.initialize();
+    }
+    /**
+     * Initialize the database schema
+     */
+    initialize() {
+        if (this.initialized)
+            return;
+        // Create metadata table for storing content and type info
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS ${this.tableName}_meta (
+        id TEXT PRIMARY KEY,
+        type TEXT NOT NULL,
+        content TEXT NOT NULL,
+        created_at TEXT DEFAULT CURRENT_TIMESTAMP
+      )
+    `);
+        // Create virtual table for vector search using vec0
+        // Note: vec0 uses a separate storage model optimized for vector operations
+        this.db.exec(`
+      CREATE VIRTUAL TABLE IF NOT EXISTS ${this.tableName}_vec USING vec0(
+        id TEXT PRIMARY KEY,
+        embedding FLOAT[${this.dimension}]
+      )
+    `);
+        // Create index on type for filtering
+        this.db.exec(`
+      CREATE INDEX IF NOT EXISTS idx_${this.tableName}_type
+      ON ${this.tableName}_meta(type)
+    `);
+        this.initialized = true;
+    }
+    /**
+     * Insert or update a vector with metadata
+     */
+    insert(id, embedding, type, content) {
+        if (embedding.length !== this.dimension) {
+            throw new Error(`Embedding dimension mismatch: expected ${this.dimension}, got ${embedding.length}`);
+        }
+        // Use a transaction for atomicity
+        const transaction = this.db.transaction(() => {
+            // Insert or replace metadata
+            const metaStmt = this.db.prepare(`
+        INSERT OR REPLACE INTO ${this.tableName}_meta (id, type, content)
+        VALUES (?, ?, ?)
+      `);
+            metaStmt.run(id, type, content);
+            // Insert or replace vector
+            // sqlite-vec expects vectors as JSON arrays or binary blobs
+            const vecStmt = this.db.prepare(`
+        INSERT OR REPLACE INTO ${this.tableName}_vec (id, embedding)
+        VALUES (?, ?)
+      `);
+            vecStmt.run(id, JSON.stringify(embedding));
+        });
+        transaction();
+    }
+    /**
+     * Insert multiple vectors in batch
+     */
+    insertBatch(items) {
+        const transaction = this.db.transaction(() => {
+            const metaStmt = this.db.prepare(`
+        INSERT OR REPLACE INTO ${this.tableName}_meta (id, type, content)
+        VALUES (?, ?, ?)
+      `);
+            const vecStmt = this.db.prepare(`
+        INSERT OR REPLACE INTO ${this.tableName}_vec (id, embedding)
+        VALUES (?, ?)
+      `);
+            for (const item of items) {
+                if (item.embedding.length !== this.dimension) {
+                    throw new Error(`Embedding dimension mismatch for ${item.id}: expected ${this.dimension}, got ${item.embedding.length}`);
+                }
+                metaStmt.run(item.id, item.type, item.content);
+                vecStmt.run(item.id, JSON.stringify(item.embedding));
+            }
+        });
+        transaction();
+    }
+    /**
+     * Search for similar vectors
+     */
+    search(queryEmbedding, options = {}) {
+        if (queryEmbedding.length !== this.dimension) {
+            throw new Error(`Query embedding dimension mismatch: expected ${this.dimension}, got ${queryEmbedding.length}`);
+        }
+        const k = options.k ?? 10;
+        const threshold = options.threshold ?? 0;
+        // Build the query based on whether we're filtering by type
+        let query;
+        let params;
+        if (options.type) {
+            // Join with metadata table to filter by type
+            query = `
+        SELECT
+          v.id,
+          m.type,
+          m.content,
+          vec_distance_cosine(v.embedding, ?) as distance
+        FROM ${this.tableName}_vec v
+        JOIN ${this.tableName}_meta m ON v.id = m.id
+        WHERE m.type = ?
+        ORDER BY distance ASC
+        LIMIT ?
+      `;
+            params = [JSON.stringify(queryEmbedding), options.type, k];
+        }
+        else {
+            query = `
+        SELECT
+          v.id,
+          m.type,
+          m.content,
+          vec_distance_cosine(v.embedding, ?) as distance
+        FROM ${this.tableName}_vec v
+        JOIN ${this.tableName}_meta m ON v.id = m.id
+        ORDER BY distance ASC
+        LIMIT ?
+      `;
+            params = [JSON.stringify(queryEmbedding), k];
+        }
+        const stmt = this.db.prepare(query);
+        const results = stmt.all(...params);
+        // Convert distance to similarity score (1 - distance for cosine)
+        return results
+            .map((r) => ({
+            id: r.id,
+            type: r.type,
+            content: r.content,
+            score: 1 - r.distance,
+        }))
+            .filter((r) => r.score >= threshold);
+    }
+    /**
+     * Get a vector by ID
+     */
+    get(id) {
+        const metaStmt = this.db.prepare(`
+      SELECT type, content FROM ${this.tableName}_meta WHERE id = ?
+    `);
+        const meta = metaStmt.get(id);
+        if (!meta)
+            return null;
+        const vecStmt = this.db.prepare(`
+      SELECT embedding FROM ${this.tableName}_vec WHERE id = ?
+    `);
+        const vec = vecStmt.get(id);
+        if (!vec)
+            return null;
+        return {
+            embedding: JSON.parse(vec.embedding),
+            type: meta.type,
+            content: meta.content,
+        };
+    }
+    /**
+     * Check if an ID exists
+     */
+    has(id) {
+        const stmt = this.db.prepare(`
+      SELECT 1 FROM ${this.tableName}_meta WHERE id = ? LIMIT 1
+    `);
+        return stmt.get(id) !== undefined;
+    }
+    /**
+     * Delete a vector
+     */
+    delete(id) {
+        const transaction = this.db.transaction(() => {
+            const metaStmt = this.db.prepare(`DELETE FROM ${this.tableName}_meta WHERE id = ?`);
+            const vecStmt = this.db.prepare(`DELETE FROM ${this.tableName}_vec WHERE id = ?`);
+            const metaResult = metaStmt.run(id);
+            vecStmt.run(id);
+            return metaResult.changes > 0;
+        });
+        return transaction();
+    }
+    /**
+     * Get the number of vectors stored
+     */
+    get count() {
+        const stmt = this.db.prepare(`SELECT COUNT(*) as count FROM ${this.tableName}_meta`);
+        const result = stmt.get();
+        return result.count;
+    }
+    /**
+     * Get count by type
+     */
+    countByType(type) {
+        const stmt = this.db.prepare(`SELECT COUNT(*) as count FROM ${this.tableName}_meta WHERE type = ?`);
+        const result = stmt.get(type);
+        return result.count;
+    }
+    /**
+     * Clear all vectors
+     */
+    clear() {
+        const transaction = this.db.transaction(() => {
+            this.db.exec(`DELETE FROM ${this.tableName}_meta`);
+            this.db.exec(`DELETE FROM ${this.tableName}_vec`);
+        });
+        transaction();
+    }
+    /**
+     * Close the database connection
+     */
+    close() {
+        this.db.close();
+    }
+    /**
+     * Get database statistics
+     */
+    getStats() {
+        const types = ['experience', 'strategy', 'concept', 'skill'];
+        const byType = {};
+        for (const type of types) {
+            byType[type] = this.countByType(type);
+        }
+        return {
+            totalVectors: this.count,
+            byType,
+            dimension: this.dimension,
+        };
+    }
+}
+/**
+ * Create a new vector store
+ */
+export function createVectorStore(options) {
+    return new SqliteVectorStore(options);
+}
+//# sourceMappingURL=vector-store.js.map

package/dist/embeddings/vector-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vector-store.js","sourceRoot":"","sources":["../../src/embeddings/vector-store.ts"],"names":[],"mappings":"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"}

package/dist/factory.d.ts

@@ -0,0 +1,193 @@
+/**
+ * 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 } from './types/index.js';
+import { createTask, createTrajectory, createStep, successOutcome, failureOutcome } from './types/index.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;
+}
+/**
+ * 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 declare function createCognitiveCoreFactory(): CognitiveCoreFactory;
+/**
+ * Get the default factory instance
+ *
+ * This is a convenience for consumers who just need the factory functions
+ * without managing a factory instance.
+ */
+export declare const cognitiveCoreFactory: CognitiveCoreFactory;
+/**
+ * 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, };
+//# sourceMappingURL=factory.d.ts.map

package/dist/factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../src/factory.ts"],"names":[],"mappings":"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"}

package/dist/factory.js

@@ -0,0 +1,109 @@
+/**
+ * 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 { createTask, createTrajectory, createStep, successOutcome, failureOutcome } from './types/index.js';
+import { createMemorySystem } from './memory/system.js';
+import { createLearningPipeline } from './learning/pipeline.js';
+/**
+ * Implementation of the CognitiveCoreFactory
+ */
+class CognitiveCoreFactoryImpl {
+    createMemorySystem(storagePath) {
+        return createMemorySystem(storagePath);
+    }
+    createLearningPipeline(memory, config) {
+        return createLearningPipeline(memory, config);
+    }
+    createTrajectory(params) {
+        return createTrajectory(params);
+    }
+    createTask(params) {
+        return createTask(params);
+    }
+    createStep(params) {
+        return createStep(params);
+    }
+    createSuccessOutcome(solution) {
+        return successOutcome(solution);
+    }
+    createFailureOutcome(errorInfo) {
+        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() {
+    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, };
+//# sourceMappingURL=factory.js.map

package/dist/factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.js","sourceRoot":"","sources":["../src/factory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAE,UAAU,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAE5G,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAExD,OAAO,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAiIhE;;GAEG;AACH,MAAM,wBAAwB;IAC5B,kBAAkB,CAAC,WAAmB;QACpC,OAAO,kBAAkB,CAAC,WAAW,CAAkB,CAAC;IAC1D,CAAC;IAED,sBAAsB,CACpB,MAAqB,EACrB,MAA+B;QAE/B,OAAO,sBAAsB,CAC3B,MAAsB,EACtB,MAAiC,CACb,CAAC;IACzB,CAAC;IAED,gBAAgB,CAAC,MAAwB;QACvC,OAAO,gBAAgB,CAAC,MAAM,CAAC,CAAC;IAClC,CAAC;IAED,UAAU,CAAC,MAAkB;QAC3B,OAAO,UAAU,CAAC,MAAM,CAAC,CAAC;IAC5B,CAAC;IAED,UAAU,CAAC,MAAkB;QAC3B,OAAO,UAAU,CAAC,MAAM,CAAC,CAAC;IAC5B,CAAC;IAED,oBAAoB,CAAC,QAAiB;QACpC,OAAO,cAAc,CAAC,QAAQ,CAAC,CAAC;IAClC,CAAC;IAED,oBAAoB,CAAC,SAAiB;QACpC,OAAO,cAAc,CAAC,SAAS,CAAC,CAAC;IACnC,CAAC;CACF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,MAAM,UAAU,0BAA0B;IACxC,OAAO,IAAI,wBAAwB,EAAE,CAAC;AACxC,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,0BAA0B,EAAE,CAAC;AAEjE;;;;;GAKG;AACH,OAAO,EACL,kBAAkB,EAClB,sBAAsB,EACtB,UAAU,EACV,gBAAgB,EAChB,UAAU,EACV,cAAc,EACd,cAAc,GACf,CAAC"}