agentdb 1.0.0

package/dist/plugins/base-plugin.mjs

@@ -0,0 +1,275 @@
+/**
+ * Base class for learning plugins providing common functionality
+ */
+import { SQLiteVectorDB } from '../core/vector-db.mjs';
+/**
+ * Abstract base class that provides common functionality for all learning plugins
+ */
+export class BasePlugin {
+    constructor() {
+        /** Whether plugin is initialized */
+        this.initialized = false;
+        /** Experience counter */
+        this.experienceCount = 0;
+        /** Episode counter */
+        this.episodeCount = 0;
+        /** Success counter */
+        this.successCount = 0;
+        /** Total reward accumulated */
+        this.totalReward = 0;
+        /** Total duration accumulated */
+        this.totalDuration = 0;
+    }
+    /**
+     * Initialize the plugin with configuration
+     */
+    async initialize(config) {
+        this.config = config;
+        // Initialize vector database
+        const dbConfig = {
+            path: config.storage.path,
+            memoryMode: false,
+            queryCache: {
+                enabled: true,
+                maxSize: 1000,
+            },
+        };
+        // Add quantization if properly configured
+        if (config.storage.quantization?.enabled) {
+            dbConfig.quantization = {
+                enabled: true,
+                dimensions: config.algorithm.stateDim || 768,
+                subvectors: 8,
+                bits: config.storage.quantization.bits || 8,
+            };
+        }
+        this.vectorDB = new SQLiteVectorDB(dbConfig);
+        // If using WASM backend, initialize async
+        if (this.vectorDB.getBackendType() === 'wasm') {
+            await this.vectorDB.initializeAsync();
+        }
+        this.initialized = true;
+        // Call custom initialization
+        await this.onInitialize();
+    }
+    /**
+     * Destroy the plugin and cleanup resources
+     */
+    async destroy() {
+        if (this.vectorDB) {
+            this.vectorDB.close();
+        }
+        this.initialized = false;
+        // Call custom cleanup
+        await this.onDestroy();
+    }
+    /**
+     * Store a single experience
+     */
+    async storeExperience(experience) {
+        this.checkInitialized();
+        // Generate ID if not provided
+        if (!experience.id) {
+            experience.id = this.generateId();
+        }
+        // Store in vector database
+        this.vectorDB.insert({
+            id: experience.id,
+            embedding: experience.state,
+            metadata: {
+                action: experience.action,
+                reward: experience.reward,
+                nextState: experience.nextState,
+                done: experience.done,
+                episodeId: experience.episodeId,
+                stepIndex: experience.stepIndex,
+                ...experience.metadata,
+                timestamp: experience.timestamp || Date.now(),
+            },
+        });
+        // Update counters
+        this.experienceCount++;
+        this.totalReward += experience.reward;
+        if (experience.metadata?.duration) {
+            this.totalDuration += experience.metadata.duration;
+        }
+        if (experience.metadata?.success) {
+            this.successCount++;
+        }
+        // Track unique episodes
+        if (experience.done && experience.episodeId) {
+            this.episodeCount++;
+        }
+        // Call custom hook
+        await this.onStoreExperience(experience);
+    }
+    /**
+     * Store a batch of experiences
+     */
+    async storeBatch(experiences) {
+        this.checkInitialized();
+        for (const experience of experiences) {
+            await this.storeExperience(experience);
+        }
+    }
+    /**
+     * Retrieve similar experiences from storage
+     */
+    async retrieveSimilar(state, k) {
+        this.checkInitialized();
+        const results = this.vectorDB.search(state, k, 'cosine');
+        return results.map(r => ({
+            id: r.id,
+            score: r.score,
+            embedding: r.embedding,
+            metadata: {
+                id: r.id,
+                state: r.embedding,
+                action: r.metadata.action,
+                reward: r.metadata.reward,
+                nextState: r.metadata.nextState,
+                done: r.metadata.done,
+                episodeId: r.metadata.episodeId,
+                stepIndex: r.metadata.stepIndex,
+                metadata: r.metadata,
+                timestamp: r.metadata.timestamp,
+            },
+        }));
+    }
+    /**
+     * Get current plugin metrics
+     */
+    async getMetrics() {
+        return {
+            totalExperiences: this.experienceCount,
+            totalEpisodes: this.episodeCount,
+            successRate: this.experienceCount > 0 ? this.successCount / this.experienceCount : 0,
+            avgReward: this.experienceCount > 0 ? this.totalReward / this.experienceCount : 0,
+            avgDuration: this.experienceCount > 0 ? this.totalDuration / this.experienceCount : 0,
+        };
+    }
+    /**
+     * Get plugin configuration
+     */
+    getConfig() {
+        return this.config;
+    }
+    /**
+     * Save plugin state to disk
+     */
+    async save(path) {
+        this.checkInitialized();
+        // Export database if WASM
+        if (this.vectorDB.getBackendType() === 'wasm') {
+            const data = this.vectorDB.export();
+            if (data) {
+                const fs = await import('fs/promises');
+                await fs.writeFile(path, data);
+            }
+        }
+        // Call custom save
+        await this.onSave(path);
+    }
+    /**
+     * Load plugin state from disk
+     */
+    async load(path) {
+        this.checkInitialized();
+        // Import database if WASM
+        if (this.vectorDB.getBackendType() === 'wasm') {
+            const fs = await import('fs/promises');
+            const data = await fs.readFile(path);
+            await this.vectorDB.importAsync(new Uint8Array(data));
+        }
+        // Call custom load
+        await this.onLoad(path);
+    }
+    // Lifecycle hooks (can be overridden by subclasses)
+    /**
+     * Called after initialize() completes
+     */
+    async onInitialize() {
+        // Override in subclass if needed
+    }
+    /**
+     * Called before destroy() completes
+     */
+    async onDestroy() {
+        // Override in subclass if needed
+    }
+    /**
+     * Called after each experience is stored
+     */
+    async onStoreExperience(experience) {
+        // Override in subclass if needed
+    }
+    /**
+     * Called during save()
+     */
+    async onSave(path) {
+        // Override in subclass if needed
+    }
+    /**
+     * Called during load()
+     */
+    async onLoad(path) {
+        // Override in subclass if needed
+    }
+    // Utility methods
+    /**
+     * Check if plugin is initialized
+     */
+    checkInitialized() {
+        if (!this.initialized) {
+            throw new Error(`Plugin ${this.name} not initialized. Call initialize() first.`);
+        }
+    }
+    /**
+     * Generate unique ID
+     */
+    generateId() {
+        return `${this.name}-${Date.now()}-${Math.random().toString(36).substring(7)}`;
+    }
+    /**
+     * Compute discounted returns for an episode
+     */
+    computeReturns(rewards, gamma) {
+        const returns = new Array(rewards.length);
+        let futureReturn = 0;
+        for (let i = rewards.length - 1; i >= 0; i--) {
+            futureReturn = rewards[i] + gamma * futureReturn;
+            returns[i] = futureReturn;
+        }
+        return returns;
+    }
+    /**
+     * Compute custom reward based on configuration
+     */
+    computeReward(experience) {
+        if (!this.config.reward) {
+            return experience.reward;
+        }
+        const { type } = this.config.reward;
+        const metadata = experience.metadata || {};
+        switch (type) {
+            case 'success_based':
+                return metadata.success ? 1.0 : -1.0;
+            case 'time_aware': {
+                const baseReward = metadata.success ? 1.0 : -1.0;
+                const timePenalty = -0.1 * ((metadata.duration || 0) / 1000);
+                return baseReward + timePenalty;
+            }
+            case 'token_aware': {
+                const baseReward = metadata.success ? 1.0 : -1.0;
+                const tokenPenalty = -0.01 * ((metadata.tokensUsed || 0) / 100);
+                return baseReward + tokenPenalty;
+            }
+            case 'custom':
+                // Custom reward function would be evaluated here
+                // For now, return the base reward
+                return experience.reward;
+            default:
+                return experience.reward;
+        }
+    }
+}

package/dist/plugins/implementations/active-learning.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Active Learning Plugin
+ *
+ * Implements query-based learning where the agent actively selects
+ * the most informative samples to learn from, maximizing data efficiency.
+ *
+ * Key features:
+ * - Uncertainty sampling
+ * - Query-by-committee
+ * - Expected model change
+ * - Diversity-based sampling
+ * - Budget-aware querying
+ */
+import { BasePlugin } from '../base-plugin';
+import { Action, Experience, TrainOptions, TrainingMetrics, Vector } from '../learning-plugin.interface';
+/**
+ * Sample with query information
+ */
+interface QuerySample {
+    state: Vector;
+    uncertainty: number;
+    queryValue: number;
+    metadata?: Record<string, any>;
+}
+/**
+ * Active Learning Plugin Implementation
+ */
+export declare class ActiveLearningPlugin extends BasePlugin {
+    name: string;
+    version: string;
+    private experiences;
+    private queryStrategy;
+    private labelingBudget;
+    private queriedSamples;
+    private unlabeledPool;
+    private committee;
+    private committeeSize;
+    private diversityThreshold;
+    constructor(config?: Partial<any>);
+    /**
+     * Override to skip initialization check for in-memory operation
+     */
+    protected checkInitialized(): void;
+    /**
+     * Override selectAction to provide base implementation
+     */
+    selectAction(state: any, context?: any): Promise<Action>;
+    /**
+     * Override to store experiences in-memory without vectorDB
+     */
+    storeExperience(experience: Experience): Promise<void>;
+    /**
+     * Override to retrieve from local experiences
+     */
+    retrieveSimilar(state: number[], k: number): Promise<import('../..').SearchResult<Experience>[]>;
+    /**
+     * Initialize committee for query-by-committee
+     */
+    private initializeCommittee;
+    /**
+     * Add unlabeled sample to pool
+     */
+    addUnlabeledSample(state: Vector, metadata?: Record<string, any>): Promise<void>;
+    /**
+     * Calculate uncertainty for a sample
+     */
+    private calculateUncertainty;
+    /**
+     * Uncertainty sampling: Select samples with highest prediction uncertainty
+     */
+    private uncertaintySampling;
+    /**
+     * Margin sampling: Select samples where top two predictions are close
+     */
+    private marginSampling;
+    /**
+     * Entropy sampling: Select samples with highest prediction entropy
+     */
+    private entropySampling;
+    /**
+     * Query-by-committee: Select samples where committee disagrees most
+     */
+    private queryByCommittee;
+    /**
+     * Expected model change: Select samples that would change model most
+     */
+    private expectedModelChange;
+    /**
+     * Diversity sampling: Select diverse batch of samples
+     */
+    private diversitySampling;
+    /**
+     * Get top K predictions for a state
+     */
+    private getTopPredictions;
+    /**
+     * Predict using specific weights
+     */
+    private predictWithWeights;
+    /**
+     * Hash state for tracking
+     */
+    private hashState;
+    /**
+     * Euclidean distance between states
+     */
+    private euclideanDistance;
+    /**
+     * Select next batch of samples to query (label)
+     */
+    selectQueryBatch(batchSize: number): Promise<QuerySample[]>;
+    /**
+     * Train with active learning
+     */
+    train(options?: TrainOptions): Promise<TrainingMetrics>;
+    /**
+     * Update committee members
+     */
+    private updateCommittee;
+    /**
+     * Get active learning statistics
+     */
+    getStats(): {
+        queriedCount: number;
+        remainingBudget: number;
+        unlabeledCount: number;
+        averageUncertainty: number;
+    };
+    /**
+     * Reset querying state
+     */
+    resetQuery(): void;
+}
+export {};
+//# sourceMappingURL=active-learning.d.ts.map

package/dist/plugins/implementations/active-learning.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"active-learning.d.ts","sourceRoot":"","sources":["../../../src/plugins/implementations/active-learning.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAC5C,OAAO,EACL,MAAM,EAEN,UAAU,EACV,YAAY,EACZ,eAAe,EACf,MAAM,EACP,MAAM,8BAA8B,CAAC;AAatC;;GAEG;AACH,UAAU,WAAW;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAChC;AAWD;;GAEG;AACH,qBAAa,oBAAqB,SAAQ,UAAU;IAClD,IAAI,SAAqB;IACzB,OAAO,SAAW;IAElB,OAAO,CAAC,WAAW,CAAoB;IACvC,OAAO,CAAC,aAAa,CAAgC;IACrD,OAAO,CAAC,cAAc,CAAgB;IACtC,OAAO,CAAC,cAAc,CAA0B;IAChD,OAAO,CAAC,aAAa,CAAqB;IAG1C,OAAO,CAAC,SAAS,CAAyB;IAC1C,OAAO,CAAC,aAAa,CAAa;IAGlC,OAAO,CAAC,kBAAkB,CAAe;gBAE7B,MAAM,CAAC,EAAE,OAAO,CAAC,GAAG,CAAC;IAiBjC;;OAEG;IACH,SAAS,CAAC,gBAAgB,IAAI,IAAI;IAIlC;;OAEG;IACG,YAAY,CAAC,KAAK,EAAE,GAAG,EAAE,OAAO,CAAC,EAAE,GAAG,GAAG,OAAO,CAAC,MAAM,CAAC;IAS9D;;OAEG;IACG,eAAe,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAI5D;;OAEG;IACG,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,OAAO,EAAE,YAAY,CAAC,UAAU,CAAC,EAAE,CAAC;IAStG;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAY3B;;OAEG;IACG,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAStF;;OAEG;YACW,oBAAoB;IAmBlC;;OAEG;YACW,mBAAmB;IAQjC;;OAEG;YACW,cAAc;IAa5B;;OAEG;YACW,eAAe;IAiB7B;;OAEG;YACW,gBAAgB;IAiB9B;;OAEG;YACW,mBAAmB;IAcjC;;OAEG;YACW,iBAAiB;IAsB/B;;OAEG;YACW,iBAAiB;IAW/B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAU1B;;OAEG;IACH,OAAO,CAAC,SAAS;IAIjB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAUzB;;OAEG;IACG,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAmCjE;;OAEG;IACG,KAAK,CAAC,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,eAAe,CAAC;IAwD7D;;OAEG;YACW,eAAe;IAyB7B;;OAEG;IACH,QAAQ,IAAI;QACV,YAAY,EAAE,MAAM,CAAC;QACrB,eAAe,EAAE,MAAM,CAAC;QACxB,cAAc,EAAE,MAAM,CAAC;QACvB,kBAAkB,EAAE,MAAM,CAAC;KAC5B;IAaD;;OAEG;IACH,UAAU,IAAI,IAAI;CAInB"}