Create sync client + LRU cache + pull operation on extended client

Author: AlePouroullis

.fernignore

@@ -10,6 +10,8 @@ src/humanloop.client.ts
 src/overload.ts
 src/error.ts
 src/context.ts
+src/sync 
+src/cache
 
 # Tests
 

package.json

@@ -3,8 +3,8 @@
     "version": "0.8.21",
     "private": false,
     "repository": "https://github.com/humanloop/humanloop-node",
-    "main": "./index.js",
-    "types": "./index.d.ts",
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
     "scripts": {
         "format": "prettier . --write --ignore-unknown",
         "build": "tsc",

src/cache/LRUCache.ts

@@ -0,0 +1,48 @@
+/**
+ * LRU Cache implementation
+ */
+export default class LRUCache<K, V> {
+    private cache: Map<K, V>;
+    private readonly maxSize: number;
+
+    constructor(maxSize: number) {
+        this.cache = new Map<K, V>();
+        this.maxSize = maxSize;
+    }
+
+    get(key: K): V | undefined {
+        if (!this.cache.has(key)) {
+            return undefined;
+        }
+
+        // Get the value
+        const value = this.cache.get(key);
+        
+        // Remove key and re-insert to mark as most recently used
+        this.cache.delete(key);
+        this.cache.set(key, value!);
+
+        return value;
+    }
+
+    set(key: K, value: V): void {
+        // If key already exists, refresh its position
+        if (this.cache.has(key)) {
+            this.cache.delete(key);
+        }
+        // If cache is full, remove the least recently used item (first item in the map)
+        else if (this.cache.size >= this.maxSize) {
+            const lruKey = this.cache.keys().next().value;
+            if (lruKey) {
+                this.cache.delete(lruKey);
+            }
+        }
+
+        // Add new key-value pair
+        this.cache.set(key, value);
+    }
+
+    clear(): void {
+        this.cache.clear();
+    }
+}

src/cache/index.ts

@@ -0,0 +1 @@
+export { default as LRUCache } from './LRUCache';

src/humanloop.client.ts

@@ -4,6 +4,7 @@ import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
 import { AnthropicInstrumentation } from "@traceloop/instrumentation-anthropic";
 import { CohereInstrumentation } from "@traceloop/instrumentation-cohere";
 import { OpenAIInstrumentation } from "@traceloop/instrumentation-openai";
+import { SyncClient } from "./sync";
 
 import { HumanloopClient as BaseHumanloopClient } from "./Client";
 import { ChatMessage } from "./api";
@@ -210,6 +211,7 @@ export class HumanloopClient extends BaseHumanloopClient {
         Anthropic?: any;
         CohereAI?: any;
     };
+    protected readonly _syncClient: SyncClient;
 
     protected get opentelemetryTracer(): Tracer {
         return HumanloopTracerSingleton.getInstance({
@@ -254,6 +256,8 @@ export class HumanloopClient extends BaseHumanloopClient {
     ) {
         super(_options);
 
+        this._syncClient = new SyncClient(this);
+
         this.instrumentProviders = _options.instrumentProviders || {};
 
         this._prompts_overloaded = overloadLog(super.prompts);
@@ -560,6 +564,45 @@ ${RESET}`,
         );
     }
 
+    /**
+     * Pull Prompt and Agent files from Humanloop to local filesystem.
+     *
+     * This method will:
+     * 1. Fetch Prompt and Agent files from your Humanloop workspace
+     * 2. Save them to the local filesystem using the client's files_directory (set during initialization)
+     * 3. Maintain the same directory structure as in Humanloop
+     * 4. Add appropriate file extensions (.prompt or .agent)
+     *
+     * The path parameter can be used in two ways:
+     * - If it points to a specific file (e.g. "path/to/file.prompt" or "path/to/file.agent"), only that file will be pulled
+     * - If it points to a directory (e.g. "path/to/directory"), all Prompt and Agent files in that directory will be pulled
+     * - If no path is provided, all Prompt and Agent files will be pulled
+     *
+     * The operation will overwrite existing files with the latest version from Humanloop
+     * but will not delete local files that don't exist in the remote workspace.
+     *
+     * Currently only supports syncing prompt and agent files. Other file types will be skipped.
+     *
+     * The files will be saved with the following structure:
+     * ```
+     * {files_directory}/
+     * ├── prompts/
+     * │   ├── my_prompt.prompt
+     * │   └── nested/
+     * │       └── another_prompt.prompt
+     * └── agents/
+     *     └── my_agent.agent
+     * ```
+     *
+     * @param path - Optional path to either a specific file (e.g. "path/to/file.prompt") or a directory (e.g. "path/to/directory").
+     *              If not provided, all Prompt and Agent files will be pulled.
+     * @param environment - The environment to pull the files from.
+     * @returns List of successfully processed file paths.
+     */
+    public async pull(path?: string, environment?: string): Promise<string[]> {
+        return this._syncClient.pull(path, environment);
+    }
+
     public get evaluations(): ExtendedEvaluations {
         return this._evaluations;
     }

src/sync/MetadataHandler.ts

@@ -0,0 +1,76 @@
+import fs from "fs";
+import path from "path";
+
+/**
+ * Interface for operation log entries
+ */
+interface OperationLog {
+    operationType: string;
+    path: string;
+    environment?: string;
+    successfulFiles?: string[];
+    failedFiles?: string[];
+    error?: string;
+    startTime: number;
+    endTime: number;
+    duration: number;
+}
+
+/**
+ * Parameters for the logOperation method
+ */
+interface LogOperationParams {
+    operationType: string;
+    path: string;
+    environment?: string;
+    successfulFiles?: string[];
+    failedFiles?: string[];
+    error?: string;
+    startTime: number;
+}
+
+/**
+ * Handler for managing metadata and operation logs
+ */
+export default class MetadataHandler {
+    private baseDir: string;
+    private metadataDir: string;
+    private operationsLogPath: string;
+
+    constructor(baseDir: string) {
+        this.baseDir = baseDir;
+        this.metadataDir = path.join(baseDir, ".humanloop");
+        this.operationsLogPath = path.join(this.metadataDir, "operations.log");
+
+        // Create metadata directory if it doesn't exist
+        if (!fs.existsSync(this.metadataDir)) {
+            fs.mkdirSync(this.metadataDir, { recursive: true });
+        }
+    }
+
+    /**
+     * Log an operation to the operations log file
+     */
+    public logOperation(params: LogOperationParams): void {
+        const endTime = Date.now();
+        const duration = endTime - params.startTime;
+
+        const logEntry: OperationLog = {
+            ...params,
+            endTime,
+            duration,
+        };
+
+        try {
+            // Create the log file if it doesn't exist
+            if (!fs.existsSync(this.operationsLogPath)) {
+                fs.writeFileSync(this.operationsLogPath, "");
+            }
+
+            // Append the log entry to the file
+            fs.appendFileSync(this.operationsLogPath, JSON.stringify(logEntry) + "\n");
+        } catch (error) {
+            console.error(`Error logging operation: ${error}`);
+        }
+    }
+}