Merge custom code from old p_sync/pull branch with latest autogenerated SDK

Author: AlePouroullis

.fernignore

@@ -10,11 +10,16 @@ src/humanloop.client.ts
 src/overload.ts
 src/error.ts
 src/context.ts
+src/cli.ts
+src/cache
+src/sync 
+src/utils
 
 # Tests
 
 # Modified due to issues with OTEL
 tests/unit/fetcher/stream-wrappers/webpack.test.ts
+tests/custom/
 
 # CI Action
 

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/cli.ts

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+import * as dotenv from "dotenv";
+import { Command } from "commander";
+
+import { HumanloopClient } from "./humanloop.client";
+import Logger from "./utils/Logger";
+
+const { version } = require("../package.json");
+
+// Load environment variables
+dotenv.config();
+
+const program = new Command();
+program
+    .name("humanloop")
+    .description("Humanloop CLI for managing sync operations")
+    .version(version);
+
+// Common auth options
+const addAuthOptions = (command: Command) =>
+    command
+        .option("--api-key <apiKey>", "Humanloop API key")
+        .option("--env-file <envFile>", "Path to .env file")
+        .option("--base-url <baseUrl>", "Base URL for Humanloop API");
+
+// Helper to get client
+function getClient(options: {
+    envFile?: string;
+    apiKey?: string;
+    baseUrl?: string;
+    baseDir?: string;
+}): HumanloopClient {
+    if (options.envFile) dotenv.config({ path: options.envFile });
+    const apiKey = options.apiKey || process.env.HUMANLOOP_API_KEY;
+    if (!apiKey) {
+        Logger.error(
+            "No API key found. Set HUMANLOOP_API_KEY in .env file or use --api-key",
+        );
+        process.exit(1);
+    }
+    return new HumanloopClient({
+        apiKey,
+        baseUrl: options.baseUrl,
+        sync: { baseDir: options.baseDir },
+    });
+}
+
+// Pull command
+addAuthOptions(
+    program
+        .command("pull")
+        .description("Pull files from Humanloop to local filesystem")
+        .option("-p, --path <path>", "Path to pull (file or directory)")
+        .option("-e, --environment <env>", "Environment to pull from")
+        .option("--base-dir <baseDir>", "Base directory for synced files", "humanloop"),
+).action(async (options) => {
+    Logger.info("Pulling files from Humanloop...");
+    // try {
+    //     Logger.info("Pulling files from Humanloop...");
+    //     const client = getClient(options);
+    //     const files = await client.pull(options.path, options.environment);
+    //     Logger.success(`Successfully synced ${files.length} files`);
+    // } catch (error) {
+    //     Logger.error(`Error: ${error}`);
+    //     process.exit(1);
+    // }
+});
+
+program.parse(process.argv);

src/humanloop.client.ts

@@ -29,6 +29,7 @@ import {
 import { HumanloopSpanExporter } from "./otel/exporter";
 import { HumanloopSpanProcessor } from "./otel/processor";
 import { overloadCall, overloadLog } from "./overload";
+import { SyncClient, SyncClientOptions } from "./sync";
 import { SDK_VERSION } from "./version";
 
 const RED = "\x1b[91m";
@@ -210,6 +211,7 @@ export class HumanloopClient extends BaseHumanloopClient {
         Anthropic?: any;
         CohereAI?: any;
     };
+    protected readonly _syncClient: SyncClient;
 
     protected get opentelemetryTracer(): Tracer {
         return HumanloopTracerSingleton.getInstance({
@@ -250,10 +252,13 @@ export class HumanloopClient extends BaseHumanloopClient {
                 Anthropic?: any;
                 CohereAI?: any;
             };
+            sync?: SyncClientOptions;
         },
     ) {
         super(_options);
 
+        this._syncClient = new SyncClient(this, _options.sync);
+
         this.instrumentProviders = _options.instrumentProviders || {};
 
         this._prompts_overloaded = overloadLog(super.prompts);
@@ -560,6 +565,48 @@ ${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;
     }