@ruvector/ruvllm 0.2.0

package/dist/cjs/federated.d.ts

@@ -0,0 +1,233 @@
+/**
+ * Federated Learning for SONA
+ *
+ * Enable distributed learning across ephemeral agents that share
+ * trajectories with a central coordinator.
+ *
+ * Architecture:
+ * ```
+ * ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
+ * │  Agent A    │     │  Agent B    │     │  Agent C    │
+ * │ (ephemeral) │     │ (ephemeral) │     │ (ephemeral) │
+ * └──────┬──────┘     └──────┬──────┘     └──────┬──────┘
+ *        │                   │                   │
+ *        │    export()       │    export()       │    export()
+ *        ▼                   ▼                   ▼
+ *   ┌────────────────────────────────────────────────┐
+ *   │            Federated Coordinator               │
+ *   │         (persistent, large capacity)           │
+ *   └────────────────────────────────────────────────┘
+ * ```
+ *
+ * @example
+ * ```typescript
+ * import { EphemeralAgent, FederatedCoordinator } from '@ruvector/ruvllm';
+ *
+ * // Create coordinator (persistent)
+ * const coordinator = new FederatedCoordinator('coord-1', { hiddenDim: 256 });
+ *
+ * // Create ephemeral agent
+ * const agent = new EphemeralAgent('agent-1', { hiddenDim: 256 });
+ *
+ * // Agent processes tasks
+ * agent.processTask([0.1, 0.2, ...], 0.85);
+ * agent.processTask([0.3, 0.4, ...], 0.92);
+ *
+ * // Export and aggregate before agent terminates
+ * const exportData = agent.exportState();
+ * const result = coordinator.aggregate(exportData);
+ *
+ * console.log(`Accepted: ${result.trajectoriesAccepted}`);
+ * ```
+ */
+import { Embedding, LearnedPattern, FederatedConfig, AgentExportStats, AgentExport, AgentContribution, AggregationResult, CoordinatorStats } from './types';
+/**
+ * Ephemeral Agent for federated learning
+ *
+ * Collects trajectories during its session and exports state before termination.
+ *
+ * @example
+ * ```typescript
+ * const agent = new EphemeralAgent('agent-1', { hiddenDim: 256 });
+ *
+ * // Process tasks during session
+ * agent.processTask(embedding1, 0.85);
+ * agent.processTaskWithRoute(embedding2, 0.92, 'code-model');
+ *
+ * // Export before termination
+ * const exportData = agent.exportState();
+ * ```
+ */
+export declare class EphemeralAgent {
+    private agentId;
+    private config;
+    private trajectories;
+    private startTime;
+    private qualitySamples;
+    private reasoningBank;
+    private loraWeights;
+    constructor(agentId: string, config?: FederatedConfig);
+    /**
+     * Get agent ID
+     */
+    getAgentId(): string;
+    /**
+     * Process a task and record trajectory
+     */
+    processTrajectory(embedding: Embedding, activations: Embedding, quality: number, route?: string, context?: string[]): void;
+    /**
+     * Simple process task method
+     */
+    processTask(embedding: Embedding, quality: number): void;
+    /**
+     * Process task with route information
+     */
+    processTaskWithRoute(embedding: Embedding, quality: number, route: string): void;
+    /**
+     * Apply micro-LoRA to hidden states
+     */
+    applyMicroLora(input: number[], output: number[]): void;
+    /**
+     * Get number of collected trajectories
+     */
+    trajectoryCount(): number;
+    /**
+     * Get average quality
+     */
+    avgQuality(): number;
+    /**
+     * Get uptime in seconds
+     */
+    uptimeSeconds(): number;
+    /**
+     * Get agent stats
+     */
+    stats(): AgentExportStats;
+    /**
+     * Force local learning
+     */
+    forceLearn(): string;
+    /**
+     * Get learned patterns
+     */
+    getPatterns(): LearnedPattern[];
+    /**
+     * Clear trajectories (after export)
+     */
+    clear(): void;
+    /**
+     * Export agent state for federation
+     *
+     * Call this before terminating the agent.
+     */
+    exportState(): AgentExport;
+    /**
+     * Serialize to JSON
+     */
+    toJSON(): string;
+    private updateLoraWeights;
+}
+/**
+ * Federated Learning Coordinator
+ *
+ * Aggregates learning from multiple ephemeral agents.
+ *
+ * @example
+ * ```typescript
+ * const coordinator = new FederatedCoordinator('coord-1', { hiddenDim: 256 });
+ *
+ * // Aggregate exports from multiple agents
+ * for (const agentExport of agentExports) {
+ *   const result = coordinator.aggregate(agentExport);
+ *   console.log(`Agent ${result.agentId}: ${result.trajectoriesAccepted} accepted`);
+ * }
+ *
+ * // Get coordinator statistics
+ * const stats = coordinator.stats();
+ * console.log(`Total patterns: ${stats.patternsLearned}`);
+ * ```
+ */
+export declare class FederatedCoordinator {
+    private coordinatorId;
+    private config;
+    private contributions;
+    private totalTrajectories;
+    private consolidationInterval;
+    private reasoningBank;
+    private qualitySamples;
+    private masterLoraWeights;
+    constructor(coordinatorId: string, config?: FederatedConfig);
+    /**
+     * Get coordinator ID
+     */
+    getCoordinatorId(): string;
+    /**
+     * Set quality threshold for accepting trajectories
+     */
+    setQualityThreshold(threshold: number): void;
+    /**
+     * Set consolidation interval
+     */
+    setConsolidationInterval(interval: number): void;
+    /**
+     * Aggregate agent export into coordinator
+     */
+    aggregate(exportData: AgentExport): AggregationResult;
+    /**
+     * Force consolidation (learning)
+     */
+    forceConsolidate(): string;
+    /**
+     * Consolidate learning (alias)
+     */
+    consolidate(): string;
+    /**
+     * Get initial patterns for new agents (warm start)
+     */
+    getInitialPatterns(k?: number): LearnedPattern[];
+    /**
+     * Get all learned patterns
+     */
+    getAllPatterns(): LearnedPattern[];
+    /**
+     * Find similar patterns
+     */
+    findPatterns(query: Embedding, k: number): LearnedPattern[];
+    /**
+     * Apply coordinator's LoRA to input
+     * OPTIMIZED: Pre-compute hidden layer once, reuse typed arrays
+     */
+    applyLora(input: number[]): number[];
+    /**
+     * Get coordinator statistics
+     */
+    stats(): CoordinatorStats;
+    /**
+     * Get contribution history
+     */
+    getContributions(): Map<string, AgentContribution>;
+    /**
+     * Get total agent count
+     */
+    agentCount(): number;
+    /**
+     * Get total trajectory count
+     */
+    getTotalTrajectories(): number;
+    /**
+     * Clear all contributions
+     */
+    clear(): void;
+    /**
+     * Export coordinator state
+     */
+    toJSON(): string;
+    /**
+     * Create agent with coordinator's learned patterns
+     */
+    createAgent(agentId: string): EphemeralAgent;
+    private shouldConsolidate;
+    private routeToPatternType;
+    private updateMasterLora;
+}
+//# sourceMappingURL=federated.d.ts.map

package/dist/cjs/federated.d.ts.map

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