p_sync: FileSyncer + CLI + Local File Usage

.fernignore

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

README.md

@@ -91,6 +91,47 @@ try {
 }
 ```
 
+## Store Humanloop Files in Code
+
+Humanloop allows you to maintain Prompts and Agents in your local filesystem and version control, while still leveraging Humanloop's prompt management capabilities.
+
+### Syncing Files with the CLI
+
+```bash
+# Basic usage
+npx humanloop pull                               # Pull all files to 'humanloop/' directory
+npx humanloop pull --path="examples/chat"        # Pull specific directory
+npx humanloop pull --environment="production"    # Pull from specific environment
+npx humanloop pull --local-files-directory="ai"  # Specify local destination (default: "humanloop")
+
+# View available options
+npx humanloop pull --help
+```
+
+### Using Local Files in the SDK
+
+To use local Files in your code:
+
+```typescript
+// Enable local file support
+const client = new HumanloopClient({
+  apiKey: "YOUR_API_KEY",
+  useLocalFiles: true
+});
+
+// Call a local Prompt file
+const response = await client.prompts.call({
+  path: "examples/chat/basic",  // Looks for humanloop/examples/chat/basic.prompt
+  inputs: { query: "Hello world" }
+});
+
+// The same path-based approach works with prompts.log(), agents.call(), and agents.log()
+```
+
+For detailed instructions, see our [Guide on Storing Files in Code](https://humanloop.com/docs/v5/guides/prompts/store-prompts-in-code).
+
+For information about file formats, see our [File Format Reference](https://humanloop.com/docs/v5/reference/serialized-files).
+
 ## Pagination
 
 List endpoints are paginated. The SDK provides an iterator so that you can simply loop over the items:

jest.config.mjs

@@ -3,6 +3,11 @@ export default {
     preset: "ts-jest",
     testEnvironment: "node",
     moduleNameMapper: {
-        "(.+)\.js$": "$1",
+        // Only map .js files in our src directory, not node_modules
+        "^src/(.+)\\.js$": "<rootDir>/src/$1",
     },
+    // Add transformIgnorePatterns to handle ESM modules in node_modules
+    transformIgnorePatterns: [
+        "node_modules/(?!(@traceloop|js-tiktoken|base64-js)/)",
+    ],
 };

package.json

@@ -26,6 +26,8 @@
         "@traceloop/instrumentation-cohere": ">=0.11.1",
         "@traceloop/instrumentation-openai": ">=0.11.3",
         "@traceloop/ai-semantic-conventions": ">=0.11.6",
+        "dotenv": "^16.5.0",
+        "commander": "^14.0.0",
         "cli-progress": "^3.12.0",
         "lodash": "^4.17.21"
     },
@@ -46,7 +48,7 @@
         "openai": "^4.74.0",
         "@anthropic-ai/sdk": "^0.32.1",
         "cohere-ai": "^7.15.0",
-        "dotenv": "^16.4.6",
+        "ts-node": "^10.9.2",
         "jsonschema": "^1.4.1",
         "@types/cli-progress": "^3.11.6",
         "@types/lodash": "4.14.74",
@@ -56,5 +58,8 @@
         "fs": false,
         "os": false,
         "path": false
+    },
+    "bin": {
+        "humanloop": "./cli.js"
     }
 }

src/api/resources/agents/client/requests/AgentLogRequest.ts

@@ -93,6 +93,7 @@ export interface AgentLogRequest {
      * The Agent configuration to use. Two formats are supported:
      * - An object representing the details of the Agent configuration
      * - A string representing the raw contents of a .agent file
+     *
      * A new Agent version will be created if the provided details do not match any existing version.
      */
     agent?: Humanloop.AgentLogRequestAgent;

src/api/resources/agents/client/requests/AgentsCallRequest.ts

@@ -41,6 +41,7 @@ export interface AgentsCallRequest {
      * The Agent configuration to use. Two formats are supported:
      * - An object representing the details of the Agent configuration
      * - A string representing the raw contents of a .agent file
+     *
      * A new Agent version will be created if the provided details do not match any existing version.
      */
     agent?: Humanloop.AgentsCallRequestAgent;

src/api/resources/agents/client/requests/AgentsCallStreamRequest.ts

@@ -35,6 +35,7 @@ export interface AgentsCallStreamRequest {
      * The Agent configuration to use. Two formats are supported:
      * - An object representing the details of the Agent configuration
      * - A string representing the raw contents of a .agent file
+     *
      * A new Agent version will be created if the provided details do not match any existing version.
      */
     agent?: Humanloop.AgentsCallStreamRequestAgent;

src/api/resources/agents/types/AgentLogRequestAgent.ts

@@ -8,6 +8,7 @@ import * as Humanloop from "../../../index";
  * The Agent configuration to use. Two formats are supported:
  * - An object representing the details of the Agent configuration
  * - A string representing the raw contents of a .agent file
+ *
  * A new Agent version will be created if the provided details do not match any existing version.
  */
 export type AgentLogRequestAgent = Humanloop.AgentKernelRequest | string;

src/api/resources/agents/types/AgentsCallRequestAgent.ts

@@ -8,6 +8,7 @@ import * as Humanloop from "../../../index";
  * The Agent configuration to use. Two formats are supported:
  * - An object representing the details of the Agent configuration
  * - A string representing the raw contents of a .agent file
+ *
  * A new Agent version will be created if the provided details do not match any existing version.
  */
 export type AgentsCallRequestAgent = Humanloop.AgentKernelRequest | string;

src/api/resources/agents/types/AgentsCallStreamRequestAgent.ts

@@ -8,6 +8,7 @@ import * as Humanloop from "../../../index";
  * The Agent configuration to use. Two formats are supported:
  * - An object representing the details of the Agent configuration
  * - A string representing the raw contents of a .agent file
+ *
  * A new Agent version will be created if the provided details do not match any existing version.
  */
 export type AgentsCallStreamRequestAgent = Humanloop.AgentKernelRequest | string;

src/api/resources/prompts/client/requests/PromptLogRequest.ts

@@ -79,6 +79,7 @@ export interface PromptLogRequest {
      * The Prompt configuration to use. Two formats are supported:
      * - An object representing the details of the Prompt configuration
      * - A string representing the raw contents of a .prompt file
+     *
      * A new Prompt version will be created if the provided details do not match any existing version.
      */
     prompt?: Humanloop.PromptLogRequestPrompt;

src/api/resources/prompts/client/requests/PromptsCallRequest.ts

@@ -95,6 +95,7 @@ export interface PromptsCallRequest {
      * The Prompt configuration to use. Two formats are supported:
      * - An object representing the details of the Prompt configuration
      * - A string representing the raw contents of a .prompt file
+     *
      * A new Prompt version will be created if the provided details do not match any existing version.
      */
     prompt?: Humanloop.PromptsCallRequestPrompt;

src/api/resources/prompts/client/requests/PromptsCallStreamRequest.ts

@@ -35,6 +35,7 @@ export interface PromptsCallStreamRequest {
      * The Prompt configuration to use. Two formats are supported:
      * - An object representing the details of the Prompt configuration
      * - A string representing the raw contents of a .prompt file
+     *
      * A new Prompt version will be created if the provided details do not match any existing version.
      */
     prompt?: Humanloop.PromptsCallStreamRequestPrompt;

src/api/resources/prompts/types/PromptLogRequestPrompt.ts

@@ -8,6 +8,7 @@ import * as Humanloop from "../../../index";
  * The Prompt configuration to use. Two formats are supported:
  * - An object representing the details of the Prompt configuration
  * - A string representing the raw contents of a .prompt file
+ *
  * A new Prompt version will be created if the provided details do not match any existing version.
  */
 export type PromptLogRequestPrompt = Humanloop.PromptKernelRequest | string;

src/api/resources/prompts/types/PromptsCallRequestPrompt.ts

@@ -8,6 +8,7 @@ import * as Humanloop from "../../../index";
  * The Prompt configuration to use. Two formats are supported:
  * - An object representing the details of the Prompt configuration
  * - A string representing the raw contents of a .prompt file
+ *
  * A new Prompt version will be created if the provided details do not match any existing version.
  */
 export type PromptsCallRequestPrompt = Humanloop.PromptKernelRequest | string;

src/api/resources/prompts/types/PromptsCallStreamRequestPrompt.ts

@@ -8,6 +8,7 @@ import * as Humanloop from "../../../index";
  * The Prompt configuration to use. Two formats are supported:
  * - An object representing the details of the Prompt configuration
  * - A string representing the raw contents of a .prompt file
+ *
  * A new Prompt version will be created if the provided details do not match any existing version.
  */
 export type PromptsCallStreamRequestPrompt = Humanloop.PromptKernelRequest | string;

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';