attocode 0.1.0

package/dist/src/integrations/semantic-cache.js

@@ -0,0 +1,372 @@
+/**
+ * Semantic Cache Integration
+ *
+ * Caches LLM responses based on semantic similarity of queries.
+ * Returns cached response if a query is similar enough to a previous one.
+ * Adapted from tricks/semantic-cache.ts.
+ *
+ * Usage:
+ *   const cache = createSemanticCacheManager({ threshold: 0.95 });
+ *   const hit = await cache.get("What is X?");
+ *   if (hit) return hit.response;
+ *   // else call LLM and cache result
+ *   await cache.set("What is X?", response);
+ */
+// =============================================================================
+// EMBEDDING UTILITIES
+// =============================================================================
+/**
+ * Simple word-based embedding (for demo purposes).
+ * Production should use real embedding model (OpenAI, Sentence Transformers, etc.)
+ */
+async function simpleEmbed(text) {
+    // Normalize text
+    const normalized = text.toLowerCase().replace(/[^\w\s]/g, '');
+    const words = normalized.split(/\s+/);
+    // Create a simple bag-of-words style embedding
+    // Use a fixed vocabulary size with hashing
+    const vocabSize = 256;
+    const embedding = new Array(vocabSize).fill(0);
+    for (const word of words) {
+        const hash = simpleHash(word) % vocabSize;
+        embedding[hash] += 1;
+    }
+    // Normalize
+    const magnitude = Math.sqrt(embedding.reduce((sum, val) => sum + val * val, 0));
+    if (magnitude > 0) {
+        for (let i = 0; i < embedding.length; i++) {
+            embedding[i] /= magnitude;
+        }
+    }
+    return embedding;
+}
+/**
+ * Simple hash function.
+ */
+function simpleHash(str) {
+    let hash = 0;
+    for (let i = 0; i < str.length; i++) {
+        const char = str.charCodeAt(i);
+        hash = (hash << 5) - hash + char;
+        hash = hash & hash; // Convert to 32-bit integer
+    }
+    return Math.abs(hash);
+}
+/**
+ * Cosine similarity between two vectors.
+ */
+export function cosineSimilarity(a, b) {
+    if (a.length !== b.length) {
+        throw new Error('Vectors must have same length');
+    }
+    let dotProduct = 0;
+    let magnitudeA = 0;
+    let magnitudeB = 0;
+    for (let i = 0; i < a.length; i++) {
+        dotProduct += a[i] * b[i];
+        magnitudeA += a[i] * a[i];
+        magnitudeB += b[i] * b[i];
+    }
+    magnitudeA = Math.sqrt(magnitudeA);
+    magnitudeB = Math.sqrt(magnitudeB);
+    if (magnitudeA === 0 || magnitudeB === 0) {
+        return 0;
+    }
+    return dotProduct / (magnitudeA * magnitudeB);
+}
+/**
+ * Generate unique ID.
+ */
+function generateId() {
+    return `${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
+}
+// =============================================================================
+// SEMANTIC CACHE MANAGER
+// =============================================================================
+/**
+ * Manages semantic caching of LLM responses.
+ */
+export class SemanticCacheManager {
+    entries = new Map();
+    config;
+    eventListeners = new Set();
+    totalQueries = 0;
+    totalHits = 0;
+    constructor(config = {}) {
+        this.config = {
+            enabled: config.enabled ?? true,
+            threshold: config.threshold ?? 0.95,
+            maxSize: config.maxSize ?? 1000,
+            ttl: config.ttl ?? 0, // No expiry by default
+            embedFunction: config.embedFunction ?? simpleEmbed,
+        };
+    }
+    /**
+     * Get cached response for a query.
+     */
+    async get(query, threshold) {
+        if (!this.config.enabled)
+            return null;
+        this.totalQueries++;
+        const effectiveThreshold = threshold ?? this.config.threshold;
+        const queryEmbedding = await this.config.embedFunction(query);
+        // Clean expired entries
+        this.cleanExpired();
+        let bestMatch = null;
+        let bestSimilarity = 0;
+        for (const entry of this.entries.values()) {
+            if (!entry.embedding)
+                continue;
+            const similarity = cosineSimilarity(queryEmbedding, entry.embedding);
+            if (similarity >= effectiveThreshold && similarity > bestSimilarity) {
+                bestSimilarity = similarity;
+                bestMatch = { entry, similarity };
+            }
+        }
+        if (bestMatch) {
+            // Update hit count
+            bestMatch.entry.hitCount++;
+            this.totalHits++;
+            this.emit({ type: 'cache.hit', query, similarity: bestMatch.similarity, entryId: bestMatch.entry.id });
+        }
+        else {
+            this.emit({ type: 'cache.miss', query });
+        }
+        return bestMatch;
+    }
+    /**
+     * Store a query/response pair.
+     */
+    async set(query, response, metadata) {
+        if (!this.config.enabled)
+            return '';
+        // Enforce max size with LRU eviction
+        if (this.entries.size >= this.config.maxSize) {
+            this.evictLRU();
+        }
+        const embedding = await this.config.embedFunction(query);
+        const now = new Date();
+        const entry = {
+            id: generateId(),
+            query,
+            response,
+            embedding,
+            createdAt: now,
+            expiresAt: this.config.ttl ? new Date(now.getTime() + this.config.ttl) : undefined,
+            hitCount: 0,
+            metadata,
+        };
+        this.entries.set(entry.id, entry);
+        this.emit({ type: 'cache.set', query, entryId: entry.id });
+        return entry.id;
+    }
+    /**
+     * Check if a similar query exists (without incrementing hit count).
+     */
+    async has(query, threshold) {
+        if (!this.config.enabled)
+            return false;
+        const effectiveThreshold = threshold ?? this.config.threshold;
+        const queryEmbedding = await this.config.embedFunction(query);
+        for (const entry of this.entries.values()) {
+            if (!entry.embedding)
+                continue;
+            const similarity = cosineSimilarity(queryEmbedding, entry.embedding);
+            if (similarity >= effectiveThreshold) {
+                return true;
+            }
+        }
+        return false;
+    }
+    /**
+     * Delete an entry by ID.
+     */
+    delete(id) {
+        return this.entries.delete(id);
+    }
+    /**
+     * Clear all entries.
+     */
+    clear() {
+        this.entries.clear();
+        this.emit({ type: 'cache.cleared' });
+    }
+    /**
+     * Get cache statistics.
+     */
+    getStats() {
+        let totalHitCount = 0;
+        for (const entry of this.entries.values()) {
+            totalHitCount += entry.hitCount;
+        }
+        return {
+            size: this.entries.size,
+            totalHits: this.totalHits,
+            avgHits: this.entries.size > 0 ? totalHitCount / this.entries.size : 0,
+            hitRate: this.totalQueries > 0 ? this.totalHits / this.totalQueries : 0,
+            totalQueries: this.totalQueries,
+        };
+    }
+    /**
+     * Find similar entries (for debugging/inspection).
+     */
+    async findSimilar(query, limit = 5) {
+        if (!this.config.enabled)
+            return [];
+        const queryEmbedding = await this.config.embedFunction(query);
+        const results = [];
+        for (const entry of this.entries.values()) {
+            if (!entry.embedding)
+                continue;
+            const similarity = cosineSimilarity(queryEmbedding, entry.embedding);
+            results.push({ entry, similarity });
+        }
+        return results.sort((a, b) => b.similarity - a.similarity).slice(0, limit);
+    }
+    /**
+     * Get all entries (for debugging).
+     */
+    getAllEntries() {
+        return Array.from(this.entries.values());
+    }
+    /**
+     * Update configuration.
+     */
+    setConfig(updates) {
+        if (updates.enabled !== undefined)
+            this.config.enabled = updates.enabled;
+        if (updates.threshold !== undefined)
+            this.config.threshold = updates.threshold;
+        if (updates.maxSize !== undefined)
+            this.config.maxSize = updates.maxSize;
+        if (updates.ttl !== undefined)
+            this.config.ttl = updates.ttl;
+        if (updates.embedFunction)
+            this.config.embedFunction = updates.embedFunction;
+    }
+    /**
+     * Get current configuration.
+     */
+    getConfig() {
+        return {
+            enabled: this.config.enabled,
+            threshold: this.config.threshold,
+            maxSize: this.config.maxSize,
+            ttl: this.config.ttl,
+        };
+    }
+    /**
+     * Subscribe to cache events.
+     */
+    subscribe(listener) {
+        this.eventListeners.add(listener);
+        return () => this.eventListeners.delete(listener);
+    }
+    /**
+     * Cleanup resources.
+     */
+    cleanup() {
+        this.entries.clear();
+        this.eventListeners.clear();
+        this.totalQueries = 0;
+        this.totalHits = 0;
+    }
+    // Internal methods
+    /**
+     * Clean expired entries.
+     */
+    cleanExpired() {
+        if (!this.config.ttl)
+            return;
+        const now = new Date();
+        for (const [id, entry] of this.entries) {
+            if (entry.expiresAt && entry.expiresAt < now) {
+                this.entries.delete(id);
+                this.emit({ type: 'cache.evict', entryId: id, reason: 'ttl' });
+            }
+        }
+    }
+    /**
+     * Evict least recently used entry.
+     */
+    evictLRU() {
+        let oldest = null;
+        let oldestId = null;
+        for (const [id, entry] of this.entries) {
+            if (!oldest || entry.createdAt < oldest.createdAt) {
+                oldest = entry;
+                oldestId = id;
+            }
+        }
+        if (oldestId) {
+            this.entries.delete(oldestId);
+            this.emit({ type: 'cache.evict', entryId: oldestId, reason: 'size' });
+        }
+    }
+    /**
+     * Emit a cache event.
+     */
+    emit(event) {
+        for (const listener of this.eventListeners) {
+            try {
+                listener(event);
+            }
+            catch {
+                // Ignore listener errors
+            }
+        }
+    }
+}
+// =============================================================================
+// FACTORY FUNCTIONS
+// =============================================================================
+/**
+ * Create a semantic cache manager.
+ */
+export function createSemanticCacheManager(config) {
+    return new SemanticCacheManager(config);
+}
+/**
+ * Create a strict cache (higher similarity threshold).
+ */
+export function createStrictCache() {
+    return new SemanticCacheManager({
+        enabled: true,
+        threshold: 0.98,
+        maxSize: 500,
+        ttl: 3600000, // 1 hour
+    });
+}
+/**
+ * Create a lenient cache (lower similarity threshold).
+ */
+export function createLenientCache() {
+    return new SemanticCacheManager({
+        enabled: true,
+        threshold: 0.85,
+        maxSize: 2000,
+        ttl: 0, // No expiry
+    });
+}
+// =============================================================================
+// WRAPPER UTILITY
+// =============================================================================
+/**
+ * Create a cached wrapper around an LLM call function.
+ */
+export function withSemanticCache(fn, cache) {
+    return (async (...args) => {
+        const query = args.join('\n');
+        // Check cache
+        const hit = await cache.get(query);
+        if (hit) {
+            return hit.entry.response;
+        }
+        // Call function
+        const response = await fn(...args);
+        // Cache result
+        await cache.set(query, response);
+        return response;
+    });
+}
+//# sourceMappingURL=semantic-cache.js.map

package/dist/src/integrations/semantic-cache.js.map

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

package/dist/src/integrations/session-store.d.ts

@@ -0,0 +1,183 @@
+/**
+ * Lesson 25: Session Persistence
+ *
+ * Saves and loads conversation sessions to/from disk.
+ * Uses JSONL format for append-only, crash-safe storage.
+ */
+import type { Message, ToolCall } from '../types.js';
+/**
+ * Session metadata stored in index.
+ */
+export interface SessionMetadata {
+    id: string;
+    name?: string;
+    createdAt: string;
+    lastActiveAt: string;
+    messageCount: number;
+    tokenCount: number;
+    summary?: string;
+}
+/**
+ * Entry types that can be stored in a session.
+ */
+export type SessionEntryType = 'message' | 'tool_call' | 'tool_result' | 'checkpoint' | 'compaction' | 'metadata';
+/**
+ * A single entry in the session log.
+ */
+export interface SessionEntry {
+    timestamp: string;
+    type: SessionEntryType;
+    data: unknown;
+}
+/**
+ * Session store configuration.
+ */
+export interface SessionStoreConfig {
+    /** Base directory for sessions (default: .agent/sessions) */
+    baseDir?: string;
+    /** Auto-save on each entry (default: true) */
+    autoSave?: boolean;
+    /** Max sessions to keep (default: 50) */
+    maxSessions?: number;
+}
+/**
+ * Session store events.
+ */
+export type SessionEvent = {
+    type: 'session.created';
+    sessionId: string;
+} | {
+    type: 'session.loaded';
+    sessionId: string;
+    entryCount: number;
+} | {
+    type: 'session.saved';
+    sessionId: string;
+} | {
+    type: 'session.deleted';
+    sessionId: string;
+} | {
+    type: 'entry.appended';
+    sessionId: string;
+    entryType: SessionEntryType;
+};
+export type SessionEventListener = (event: SessionEvent) => void;
+/**
+ * Manages session persistence.
+ */
+export declare class SessionStore {
+    private config;
+    private currentSessionId;
+    private index;
+    private listeners;
+    private writeQueue;
+    constructor(config?: SessionStoreConfig);
+    /**
+     * Initialize the session store.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Load the session index.
+     */
+    private loadIndex;
+    /**
+     * Save the session index.
+     */
+    private saveIndex;
+    /**
+     * Create a new session.
+     */
+    createSession(name?: string): Promise<string>;
+    /**
+     * Get the current session ID.
+     */
+    getCurrentSessionId(): string | null;
+    /**
+     * Set the current session ID.
+     */
+    setCurrentSessionId(sessionId: string): void;
+    /**
+     * Append an entry to the current session.
+     */
+    appendEntry(entry: Omit<SessionEntry, 'timestamp'>): Promise<void>;
+    /**
+     * Append a message to the current session.
+     */
+    appendMessage(message: Message): Promise<void>;
+    /**
+     * Append a tool call to the current session.
+     */
+    appendToolCall(toolCall: ToolCall): Promise<void>;
+    /**
+     * Append a tool result to the current session.
+     */
+    appendToolResult(callId: string, result: unknown): Promise<void>;
+    /**
+     * Append a compaction summary.
+     */
+    appendCompaction(summary: string, compactedCount: number): Promise<void>;
+    /**
+     * Append a checkpoint for session restoration.
+     * Checkpoints store the full conversation state at a point in time.
+     */
+    appendCheckpoint(checkpoint: {
+        id: string;
+        label?: string;
+        messages: Message[];
+        iteration: number;
+        metrics?: unknown;
+    }): Promise<void>;
+    /**
+     * Load a session by ID.
+     */
+    loadSession(sessionId: string): Promise<SessionEntry[]>;
+    /**
+     * Reconstruct messages from session entries.
+     */
+    loadSessionMessages(sessionId: string): Promise<Message[]>;
+    /**
+     * Delete a session.
+     */
+    deleteSession(sessionId: string): Promise<void>;
+    /**
+     * List all sessions.
+     */
+    listSessions(): SessionMetadata[];
+    /**
+     * Get the most recent session.
+     */
+    getRecentSession(): SessionMetadata | null;
+    /**
+     * Get session metadata by ID.
+     */
+    getSessionMetadata(sessionId: string): SessionMetadata | undefined;
+    /**
+     * Update session metadata.
+     */
+    updateSessionMetadata(sessionId: string, updates: Partial<Pick<SessionMetadata, 'name' | 'summary' | 'tokenCount'>>): Promise<void>;
+    /**
+     * Prune old sessions if over limit.
+     */
+    private pruneOldSessions;
+    /**
+     * Subscribe to events.
+     */
+    on(listener: SessionEventListener): () => void;
+    /**
+     * Emit an event.
+     */
+    private emit;
+    /**
+     * Cleanup - save index on exit.
+     */
+    cleanup(): Promise<void>;
+}
+/**
+ * Create and initialize a session store.
+ */
+export declare function createSessionStore(config?: SessionStoreConfig): Promise<SessionStore>;
+/**
+ * Format session metadata for display.
+ */
+export declare function formatSessionList(sessions: SessionMetadata[]): string;
+//# sourceMappingURL=session-store.d.ts.map

package/dist/src/integrations/session-store.d.ts.map

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