Batch message add API + return message uuids when adding messages (#153)

paul-paliychuk · fern-api[bot] · web-flow · commit c8789df31c89 · 2025-08-14T20:51:47.000-04:00
* SDK regeneration

* chore: Version bump

* chore: Version bump

* SDK regeneration

* wip

* chore: Add support for user and graph specific entity/edge types

* chore: Add support for ontology target

* SDK regeneration

* chore: Add support for multiple ontology targets

* SDK regeneration

* fix: redundant default to empty list

* fix: comment

* fix: comment

* chore: Bump version

* SDK regeneration

* feat: Update context string utility to include entity attributes and episodes

* SDK regeneration

* chore: Version bump

* SDK regeneration

---------

Co-authored-by: fern-api &lt;115122769+fern-api[bot]@users.noreply.github.com&gt;
diff --git a/.fernignore b/.fernignore
@@ -3,6 +3,7 @@ examples
 src/wrapper
 src/index.ts
 src/contextString.ts
+tests/unit/contextString.test.ts
 package.json
 yarn.lock
 .github
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
     "name": "@getzep/zep-cloud",
-    "version": "3.2.0",
+    "version": "3.4.0",
     "private": false,
     "repository": "https://github.com/getzep/zep-js",
     "description": "Zep: Fast, scalable building blocks for production LLM apps",
diff --git a/reference.md b/reference.md
@@ -471,7 +471,7 @@ await client.graph.create({
 <dl>
 <dd>
 
-List all graphs. In order to list users, use user.list_ordered instead
+Returns all graphs. In order to list users, use user.list_ordered instead
 
 </dd>
 </dl>
@@ -1198,6 +1198,84 @@ await client.thread.addMessages("threadId", {
 </dl>
 </details>
 
+<details><summary><code>client.thread.<a href="/src/api/resources/thread/client/Client.ts">addMessagesBatch</a>(threadId, { ...params }) -> Zep.AddThreadMessagesResponse</code></summary>
+<dl>
+<dd>
+
+#### 📝 Description
+
+<dl>
+<dd>
+
+<dl>
+<dd>
+
+Add messages to a thread in batch mode. This will process messages concurrently, which is useful for data migrations.
+
+</dd>
+</dl>
+</dd>
+</dl>
+
+#### 🔌 Usage
+
+<dl>
+<dd>
+
+<dl>
+<dd>
+
+```typescript
+await client.thread.addMessagesBatch("threadId", {
+    messages: [
+        {
+            content: "content",
+            role: "norole",
+        },
+    ],
+});
+```
+
+</dd>
+</dl>
+</dd>
+</dl>
+
+#### ⚙️ Parameters
+
+<dl>
+<dd>
+
+<dl>
+<dd>
+
+**threadId:** `string` — The ID of the thread to which messages should be added.
+
+</dd>
+</dl>
+
+<dl>
+<dd>
+
+**request:** `Zep.AddThreadMessagesRequest`
+
+</dd>
+</dl>
+
+<dl>
+<dd>
+
+**requestOptions:** `Thread.RequestOptions`
+
+</dd>
+</dl>
+</dd>
+</dl>
+
+</dd>
+</dl>
+</details>
+
 ## User
 
 <details><summary><code>client.user.<a href="/src/api/resources/user/client/Client.ts">add</a>({ ...params }) -> Zep.User</code></summary>
diff --git a/src/Client.ts b/src/Client.ts
@@ -45,8 +45,8 @@ export class ZepClient {
                 {
                     "X-Fern-Language": "JavaScript",
                     "X-Fern-SDK-Name": "zep-cloud",
-                    "X-Fern-SDK-Version": "3.2.0",
-                    "User-Agent": "zep-cloud/3.2.0",
+                    "X-Fern-SDK-Version": "3.4.0",
+                    "User-Agent": "zep-cloud/3.4.0",
                     "X-Fern-Runtime": core.RUNTIME.type,
                     "X-Fern-Runtime-Version": core.RUNTIME.version,
                 },
diff --git a/src/api/resources/graph/client/Client.ts b/src/api/resources/graph/client/Client.ts
@@ -852,7 +852,7 @@ export class Graph {
     }
 
     /**
-     * List all graphs. In order to list users, use user.list_ordered instead
+     * Returns all graphs. In order to list users, use user.list_ordered instead
      *
      * @param {Zep.GraphListAllRequest} request
      * @param {Graph.RequestOptions} requestOptions - Request-specific configuration.
diff --git a/src/api/resources/thread/client/Client.ts b/src/api/resources/thread/client/Client.ts
@@ -722,6 +722,113 @@ export class Thread {
         }
     }
 
+    /**
+     * Add messages to a thread in batch mode. This will process messages concurrently, which is useful for data migrations.
+     *
+     * @param {string} threadId - The ID of the thread to which messages should be added.
+     * @param {Zep.AddThreadMessagesRequest} request
+     * @param {Thread.RequestOptions} requestOptions - Request-specific configuration.
+     *
+     * @throws {@link Zep.InternalServerError}
+     *
+     * @example
+     *     await client.thread.addMessagesBatch("threadId", {
+     *         messages: [{
+     *                 content: "content",
+     *                 role: "norole"
+     *             }]
+     *     })
+     */
+    public addMessagesBatch(
+        threadId: string,
+        request: Zep.AddThreadMessagesRequest,
+        requestOptions?: Thread.RequestOptions,
+    ): core.HttpResponsePromise<Zep.AddThreadMessagesResponse> {
+        return core.HttpResponsePromise.fromPromise(this.__addMessagesBatch(threadId, request, requestOptions));
+    }
+
+    private async __addMessagesBatch(
+        threadId: string,
+        request: Zep.AddThreadMessagesRequest,
+        requestOptions?: Thread.RequestOptions,
+    ): Promise<core.WithRawResponse<Zep.AddThreadMessagesResponse>> {
+        const _response = await (this._options.fetcher ?? core.fetcher)({
+            url: core.url.join(
+                (await core.Supplier.get(this._options.baseUrl)) ??
+                    (await core.Supplier.get(this._options.environment)) ??
+                    environments.ZepEnvironment.Default,
+                `threads/${encodeURIComponent(threadId)}/messages-batch`,
+            ),
+            method: "POST",
+            headers: mergeHeaders(
+                this._options?.headers,
+                mergeOnlyDefinedHeaders({ ...(await this._getCustomAuthorizationHeaders()) }),
+                requestOptions?.headers,
+            ),
+            contentType: "application/json",
+            requestType: "json",
+            body: serializers.AddThreadMessagesRequest.jsonOrThrow(request, {
+                unrecognizedObjectKeys: "strip",
+                omitUndefined: true,
+            }),
+            timeoutMs: requestOptions?.timeoutInSeconds != null ? requestOptions.timeoutInSeconds * 1000 : 60000,
+            maxRetries: requestOptions?.maxRetries,
+            abortSignal: requestOptions?.abortSignal,
+        });
+        if (_response.ok) {
+            return {
+                data: serializers.AddThreadMessagesResponse.parseOrThrow(_response.body, {
+                    unrecognizedObjectKeys: "passthrough",
+                    allowUnrecognizedUnionMembers: true,
+                    allowUnrecognizedEnumValues: true,
+                    skipValidation: true,
+                    breadcrumbsPrefix: ["response"],
+                }),
+                rawResponse: _response.rawResponse,
+            };
+        }
+
+        if (_response.error.reason === "status-code") {
+            switch (_response.error.statusCode) {
+                case 500:
+                    throw new Zep.InternalServerError(
+                        serializers.ApiError.parseOrThrow(_response.error.body, {
+                            unrecognizedObjectKeys: "passthrough",
+                            allowUnrecognizedUnionMembers: true,
+                            allowUnrecognizedEnumValues: true,
+                            skipValidation: true,
+                            breadcrumbsPrefix: ["response"],
+                        }),
+                        _response.rawResponse,
+                    );
+                default:
+                    throw new errors.ZepError({
+                        statusCode: _response.error.statusCode,
+                        body: _response.error.body,
+                        rawResponse: _response.rawResponse,
+                    });
+            }
+        }
+
+        switch (_response.error.reason) {
+            case "non-json":
+                throw new errors.ZepError({
+                    statusCode: _response.error.statusCode,
+                    body: _response.error.rawBody,
+                    rawResponse: _response.rawResponse,
+                });
+            case "timeout":
+                throw new errors.ZepTimeoutError(
+                    "Timeout exceeded when calling POST /threads/{threadId}/messages-batch.",
+                );
+            case "unknown":
+                throw new errors.ZepError({
+                    message: _response.error.errorMessage,
+                    rawResponse: _response.rawResponse,
+                });
+        }
+    }
+
     protected async _getCustomAuthorizationHeaders() {
         const apiKeyValue = (await core.Supplier.get(this._options.apiKey)) ?? process?.env["ZEP_API_KEY"];
         return { Authorization: `Api-Key ${apiKeyValue}` };
diff --git a/src/api/resources/thread/client/requests/index.ts b/src/api/resources/thread/client/requests/index.ts
@@ -2,4 +2,3 @@ export { type ThreadListAllRequest } from "./ThreadListAllRequest.js";
 export { type CreateThreadRequest } from "./CreateThreadRequest.js";
 export { type ThreadGetUserContextRequest } from "./ThreadGetUserContextRequest.js";
 export { type ThreadGetRequest } from "./ThreadGetRequest.js";
-export { type AddThreadMessagesRequest } from "./AddThreadMessagesRequest.js";
diff --git a/src/api/types/AddThreadMessagesRequest.ts b/src/api/types/AddThreadMessagesRequest.ts
@@ -2,17 +2,8 @@
  * This file was auto-generated by Fern from our API Definition.
  */
 
-import * as Zep from "../../../../index.js";
+import * as Zep from "../index.js";
 
-/**
- * @example
- *     {
- *         messages: [{
- *                 content: "content",
- *                 role: "norole"
- *             }]
- *     }
- */
 export interface AddThreadMessagesRequest {
     /**
      * Optional list of role types to ignore when adding messages to graph memory.
diff --git a/src/api/types/AddThreadMessagesResponse.ts b/src/api/types/AddThreadMessagesResponse.ts
@@ -4,4 +4,5 @@
 
 export interface AddThreadMessagesResponse {
     context?: string;
+    messageUuids?: string[];
 }
diff --git a/src/api/types/index.ts b/src/api/types/index.ts
@@ -1,4 +1,5 @@
 export * from "./ApiError.js";
+export * from "./AddThreadMessagesRequest.js";
 export * from "./AddThreadMessagesResponse.js";
 export * from "./CloneGraphResponse.js";
 export * from "./EdgeType.js";
diff --git a/src/contextString.ts b/src/contextString.ts
@@ -1,7 +1,7 @@
-import { EntityEdge, EntityNode } from "./api/index.js";
+import { EntityEdge, EntityNode, Episode } from "./api/index.js";
 
 const TEMPLATE_STRING = `
-FACTS and ENTITIES represent relevant context to the current conversation.
+FACTS and ENTITIES%episodesHeader% represent relevant context to the current conversation.
 
 # These are the most relevant facts and their valid date ranges
 # format: FACT (Date range: from - to)
@@ -10,10 +10,15 @@ FACTS and ENTITIES represent relevant context to the current conversation.
 </FACTS>
 
 # These are the most relevant entities
-# ENTITY_NAME: entity summary
+# Name: ENTITY_NAME
+# Label: entity_label (if present)
+# Attributes: (if present)
+#   attr_name: attr_value
+# Summary: entity summary
 <ENTITIES>
 %entities%
 </ENTITIES>
+%episodesSection%
 `;
 
 /**
@@ -59,23 +64,81 @@ function formatDate(date: Date): string {
 }
 
 /**
- * Compose a search context from entity edges and nodes.
+ * Compose a search context from entity edges, nodes, and episodes.
  *
  * @param edges - List of entity edges.
  * @param nodes - List of entity nodes.
- * @returns A formatted string containing facts and entities.
+ * @param episodes - List of episodes.
+ * @returns A formatted string containing facts, entities, and episodes.
  */
-export function composeContextString(edges: EntityEdge[], nodes: EntityNode[]): string {
+export function composeContextString(edges: EntityEdge[], nodes: EntityNode[], episodes: Episode[] = []): string {
     const facts = edges.map((edge) => {
-        return `  - ${edge.fact} (${formatEdgeDateRange(edge)})`;
+        return `  - ${edge.fact} (Date range: ${formatEdgeDateRange(edge)})`;
     });
 
     const entities = nodes.map((node) => {
-        return `  - ${node.name}: ${node.summary}`;
+        const entityParts = [`Name: ${node.name}`];
+        
+        if (node.labels && node.labels.length > 0) {
+            const labels = [...node.labels];
+            const entityIndex = labels.indexOf('Entity');
+            if (entityIndex > -1) {
+                labels.splice(entityIndex, 1);
+            }
+            if (labels.length > 0) {
+                entityParts.push(`Label: ${labels[0]}`);
+            }
+        }
+        
+        if (node.attributes && Object.keys(node.attributes).length > 0) {
+            const filteredAttributes = { ...node.attributes };
+            delete filteredAttributes.labels;
+            if (Object.keys(filteredAttributes).length > 0) {
+                entityParts.push('Attributes:');
+                Object.entries(filteredAttributes).forEach(([key, value]) => {
+                    entityParts.push(`  ${key}: ${value}`);
+                });
+            }
+        }
+        
+        if (node.summary && node.summary.trim()) {
+            entityParts.push(`Summary: ${node.summary}`);
+        }
+        
+        return entityParts.join('\n');
     });
 
+    const episodesList: string[] = [];
+    if (episodes.length > 0) {
+        episodes.forEach((episode) => {
+            let rolePrefix = "";
+            if (episode.role && episode.roleType) {
+                rolePrefix = `${episode.role} (${episode.roleType}): `;
+            } else if (episode.role) {
+                rolePrefix = `${episode.role}: `;
+            } else if (episode.roleType) {
+                rolePrefix = `(${episode.roleType}): `;
+            }
+            
+            const timestamp = formatDate(new Date(episode.createdAt));
+            
+            const episodeStr = `  - ${rolePrefix}${episode.content} (${timestamp})`;
+            episodesList.push(episodeStr);
+        });
+    }
+
     const factsStr = facts.join("\n");
     const entitiesStr = entities.join("\n");
-
-    return TEMPLATE_STRING.replace("%facts%", factsStr).replace("%entities%", entitiesStr);
+    const episodesStr = episodesList.join("\n");
+    
+    const episodesHeader = episodes.length > 0 ? ", and EPISODES" : "";
+    const episodesSection = episodes.length > 0 
+        ? `\n# These are the most relevant episodes\n<EPISODES>\n${episodesStr}\n</EPISODES>` 
+        : "";
+    
+    return TEMPLATE_STRING
+        .replace("%episodesHeader%", episodesHeader)
+        .replace("%facts%", factsStr)
+        .replace("%entities%", entitiesStr)
+        .replace("%episodesSection%", episodesSection);
 }
diff --git a/src/serialization/resources/thread/client/requests/index.ts b/src/serialization/resources/thread/client/requests/index.ts
@@ -1,2 +1 @@
 export { CreateThreadRequest } from "./CreateThreadRequest.js";
-export { AddThreadMessagesRequest } from "./AddThreadMessagesRequest.js";
diff --git a/src/serialization/types/AddThreadMessagesRequest.ts b/src/serialization/types/AddThreadMessagesRequest.ts
diff --git a/src/serialization/types/AddThreadMessagesResponse.ts b/src/serialization/types/AddThreadMessagesResponse.ts
diff --git a/src/serialization/types/index.ts b/src/serialization/types/index.ts
diff --git a/src/version.ts b/src/version.ts
diff --git a/tests/unit/contextString.test.ts b/tests/unit/contextString.test.ts
diff --git a/tests/wire/thread.test.ts b/tests/wire/thread.test.ts

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "@getzep/zep-cloud",`
`3`		`- "version": "3.2.0",`
	`3`	`+ "version": "3.4.0",`
`4`	`4`	`"private": false,`
`5`	`5`	`"repository": "https://github.com/getzep/zep-js",`
`6`	`6`	`"description": "Zep: Fast, scalable building blocks for production LLM apps",`
Original file line number	Diff line number	Diff line change
`@@ -852,7 +852,7 @@ export class Graph {`
`852`	`852`	`}`
`853`	`853`
`854`	`854`	`/**`
`855`		`- * List all graphs. In order to list users, use user.list_ordered instead`
	`855`	`+ * Returns all graphs. In order to list users, use user.list_ordered instead`
`856`	`856`	`*`
`857`	`857`	`* @param {Zep.GraphListAllRequest} request`
`858`	`858`	`* @param {Graph.RequestOptions} requestOptions - Request-specific configuration.`
Original file line number	Diff line number	Diff line change
`@@ -4,4 +4,5 @@`
`4`	`4`
`5`	`5`	`export interface AddThreadMessagesResponse {`
`6`	`6`	`context?: string;`
	`7`	`+ messageUuids?: string[];`
`7`	`8`	`}`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,5 @@`
`1`	`1`	`export * from "./ApiError.js";`
	`2`	`+export * from "./AddThreadMessagesRequest.js";`
`2`	`3`	`export * from "./AddThreadMessagesResponse.js";`
`3`	`4`	`export * from "./CloneGraphResponse.js";`
`4`	`5`	`export * from "./EdgeType.js";`