@promptev/client 1.0.0 → 1.2.0

package/dist/cjs/index.cjs

@@ -305,8 +305,8 @@ class PromptevClient {
      * @param agentSlug The agent's slug, as shown on its page in Promptev. Only
      *   PUBLISHED agents in the key's own project can be reached; anything else
      *   answers 404 ({@link NotFoundError}).
-     * @param message What to say. Required, non-empty after trimming, at most
-     *   {@link MAX_MESSAGE_CHARS} characters.
+     * @param message What to say. Non-empty after trimming unless
+     *   `options.files` are sent, at most {@link MAX_MESSAGE_CHARS} characters.
      *
      * @example Stream the answer
      * ```ts
@@ -333,10 +333,11 @@ class PromptevClient {
             throw new ValidationError("Name the agent to talk to.", undefined, undefined, "agentSlug");
         }
         const text = String(message ?? "").trim();
-        if (!text) {
+        const files = options?.files ?? [];
+        if (!text && files.length === 0) {
             // The server answers 422 for this; refusing here saves the round trip
             // AND the api_call the workspace would still have been metered for.
-            throw new ValidationError("Say something to the agent.", undefined, undefined, "message");
+            throw new ValidationError("Say something to the agent, or attach a file.", undefined, undefined, "message");
         }
         if (text.length > exports.MAX_MESSAGE_CHARS) {
             throw new ValidationError(`A message can be at most ${exports.MAX_MESSAGE_CHARS} characters.`, undefined, undefined, "message");
@@ -350,16 +351,16 @@ class PromptevClient {
                 obo.groups = options.onBehalfOf.groups;
             payload.on_behalf_of = obo;
         }
+        if (options?.model != null)
+            payload.model = options.model;
+        if (options?.toolInputs != null)
+            payload.tool_inputs = options.toolInputs;
         const url = `${this.baseUrl}/api/v1/agents/${encodeURIComponent(slug)}/chat`;
         // Deliberately NOT fetchWithRetry: a turn is not idempotent — a retried
         // POST could run the agent, and its tools, a second time.
         const resp = await this.fetchOnce(url, {
             method: "POST",
-            headers: this.authHeaders({
-                "Content-Type": "application/json",
-                Accept: "text/event-stream",
-            }),
-            body: JSON.stringify(payload),
+            ...chatBody(payload, files, (extra) => this.authHeaders(extra)),
             signal: options?.signal,
         });
         if (resp.status >= 400) {
@@ -532,6 +533,33 @@ class PromptevClient {
     }
 }
 exports.PromptevClient = PromptevClient;
+/**
+ * The body of a chat call: JSON when there are no files; MULTIPART when there
+ * are, the JSON in a `payload` part and each file in a `files` part. Count and
+ * size are judged here, before the wire.
+ */
+function chatBody(payload, files, headers) {
+    if (files.length === 0) {
+        return {
+            headers: headers({ "Content-Type": "application/json", Accept: "text/event-stream" }),
+            body: JSON.stringify(payload),
+        };
+    }
+    if (files.length > exports.MAX_FILES_PER_RUN) {
+        throw new ValidationError(`At most ${exports.MAX_FILES_PER_RUN} files can be sent with one call.`, undefined, undefined, "files");
+    }
+    const form = new FormData();
+    form.append("payload", JSON.stringify(payload));
+    for (const file of files) {
+        const [name, blob] = toBlob(file);
+        if (blob.size > exports.MAX_UPLOAD_BYTES) {
+            throw new ValidationError(`${name}: larger than ${exports.MAX_UPLOAD_BYTES / (1024 * 1024)} MB — add bigger files to the agent's knowledge instead.`, undefined, undefined, "files");
+        }
+        form.append("files", blob, name);
+    }
+    // NO Content-Type — fetch sets the multipart boundary itself.
+    return { headers: headers({ Accept: "text/event-stream" }), body: form };
+}
 /** One upload input, as a named Blob — the only shape `FormData` accepts. */
 function toBlob(file) {
     if (typeof Blob !== "undefined" && file instanceof Blob) {

package/dist/esm/index.d.ts

@@ -72,6 +72,34 @@ export interface OnBehalfOf {
     /** The end user's groups, as your system knows them. Omit for the key's full grant. */
     groups?: string[];
 }
+/** A model of a provider the workspace has connected, by the ids its model list shows. */
+export interface ModelChoice {
+    provider: string;
+    model: string;
+}
+/**
+ * What one call overrides on one of the agent's tools, by where each value
+ * goes. Only what the tool already has in that place can be overridden; any
+ * other name answers 400, and nothing is stored: the next call runs the agent
+ * as it was published.
+ *
+ * - An HTTP tool has `headers`, `query`, `body` and `path` (a `{{name}}` in
+ *   its URL). A GET or DELETE has no body: all its parameters are `query`.
+ * - An MCP server has `headers` (sent to the server) and `arguments` (of its
+ *   functions; a value reaches every function that takes that argument).
+ *
+ * A value the model would have filled is fixed for the call: the model neither
+ * sees nor changes it, and it shows wherever tool arguments show (the
+ * `tool_call` event, approvals). A header, or a value the tool was saved with,
+ * never appears in the stream. Put secrets in `headers`.
+ */
+export interface ToolInput {
+    headers?: Record<string, string>;
+    query?: Record<string, unknown>;
+    body?: Record<string, unknown>;
+    path?: Record<string, unknown>;
+    arguments?: Record<string, unknown>;
+}
 export interface ChatOptions {
     /**
      * Continue an existing thread. Read it off the first `conversation` event
@@ -89,6 +117,26 @@ export interface ChatOptions {
     conversationId?: string;
     /** Act for one of your end users — see {@link OnBehalfOf}. */
     onBehalfOf?: OnBehalfOf;
+    /**
+     * Run this one call on another model. The workspace's own provider key is
+     * used; a model it cannot call answers 400 before the turn starts.
+     */
+    model?: ModelChoice;
+    /**
+     * Override what the agent's tools are configured with, for this one call,
+     * keyed by tool id (shown on the tool's page) — see {@link ToolInput}.
+     */
+    toolInputs?: Record<string, ToolInput>;
+    /**
+     * Files for the agent to read on this turn, sent in the same call: at most
+     * {@link MAX_FILES_PER_RUN}, each at most 25 MB. Accepted only when the
+     * agent's "Chat attachments" is on (409 otherwise), and only the types the
+     * promptev chat takes (415 otherwise). An image is shown to a model that can
+     * see, and read into text for one that cannot. A document is read before
+     * the answer starts, so a long scan makes a slower first event. With files,
+     * `message` may be empty.
+     */
+    files?: UploadInput[];
     /** Abort the turn from your own signal (in addition to the client timeout). */
     signal?: AbortSignal;
 }
@@ -413,8 +461,8 @@ export declare class PromptevClient {
      * @param agentSlug The agent's slug, as shown on its page in Promptev. Only
      *   PUBLISHED agents in the key's own project can be reached; anything else
      *   answers 404 ({@link NotFoundError}).
-     * @param message What to say. Required, non-empty after trimming, at most
-     *   {@link MAX_MESSAGE_CHARS} characters.
+     * @param message What to say. Non-empty after trimming unless
+     *   `options.files` are sent, at most {@link MAX_MESSAGE_CHARS} characters.
      *
      * @example Stream the answer
      * ```ts

package/dist/esm/index.js

@@ -294,8 +294,8 @@ export class PromptevClient {
      * @param agentSlug The agent's slug, as shown on its page in Promptev. Only
      *   PUBLISHED agents in the key's own project can be reached; anything else
      *   answers 404 ({@link NotFoundError}).
-     * @param message What to say. Required, non-empty after trimming, at most
-     *   {@link MAX_MESSAGE_CHARS} characters.
+     * @param message What to say. Non-empty after trimming unless
+     *   `options.files` are sent, at most {@link MAX_MESSAGE_CHARS} characters.
      *
      * @example Stream the answer
      * ```ts
@@ -322,10 +322,11 @@ export class PromptevClient {
             throw new ValidationError("Name the agent to talk to.", undefined, undefined, "agentSlug");
         }
         const text = String(message ?? "").trim();
-        if (!text) {
+        const files = options?.files ?? [];
+        if (!text && files.length === 0) {
             // The server answers 422 for this; refusing here saves the round trip
             // AND the api_call the workspace would still have been metered for.
-            throw new ValidationError("Say something to the agent.", undefined, undefined, "message");
+            throw new ValidationError("Say something to the agent, or attach a file.", undefined, undefined, "message");
         }
         if (text.length > MAX_MESSAGE_CHARS) {
             throw new ValidationError(`A message can be at most ${MAX_MESSAGE_CHARS} characters.`, undefined, undefined, "message");
@@ -339,16 +340,16 @@ export class PromptevClient {
                 obo.groups = options.onBehalfOf.groups;
             payload.on_behalf_of = obo;
         }
+        if (options?.model != null)
+            payload.model = options.model;
+        if (options?.toolInputs != null)
+            payload.tool_inputs = options.toolInputs;
         const url = `${this.baseUrl}/api/v1/agents/${encodeURIComponent(slug)}/chat`;
         // Deliberately NOT fetchWithRetry: a turn is not idempotent — a retried
         // POST could run the agent, and its tools, a second time.
         const resp = await this.fetchOnce(url, {
             method: "POST",
-            headers: this.authHeaders({
-                "Content-Type": "application/json",
-                Accept: "text/event-stream",
-            }),
-            body: JSON.stringify(payload),
+            ...chatBody(payload, files, (extra) => this.authHeaders(extra)),
             signal: options?.signal,
         });
         if (resp.status >= 400) {
@@ -520,6 +521,33 @@ export class PromptevClient {
         return JSON.parse(text);
     }
 }
+/**
+ * The body of a chat call: JSON when there are no files; MULTIPART when there
+ * are, the JSON in a `payload` part and each file in a `files` part. Count and
+ * size are judged here, before the wire.
+ */
+function chatBody(payload, files, headers) {
+    if (files.length === 0) {
+        return {
+            headers: headers({ "Content-Type": "application/json", Accept: "text/event-stream" }),
+            body: JSON.stringify(payload),
+        };
+    }
+    if (files.length > MAX_FILES_PER_RUN) {
+        throw new ValidationError(`At most ${MAX_FILES_PER_RUN} files can be sent with one call.`, undefined, undefined, "files");
+    }
+    const form = new FormData();
+    form.append("payload", JSON.stringify(payload));
+    for (const file of files) {
+        const [name, blob] = toBlob(file);
+        if (blob.size > MAX_UPLOAD_BYTES) {
+            throw new ValidationError(`${name}: larger than ${MAX_UPLOAD_BYTES / (1024 * 1024)} MB — add bigger files to the agent's knowledge instead.`, undefined, undefined, "files");
+        }
+        form.append("files", blob, name);
+    }
+    // NO Content-Type — fetch sets the multipart boundary itself.
+    return { headers: headers({ Accept: "text/event-stream" }), body: form };
+}
 /** One upload input, as a named Blob — the only shape `FormData` accepts. */
 function toBlob(file) {
     if (typeof Blob !== "undefined" && file instanceof Blob) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@promptev/client",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "JavaScript/TypeScript client for Promptev — stream your AI agents and upload documents with a workspace API key",
   "type": "module",
   "main": "./dist/cjs/index.cjs",

package/readme.md

@@ -76,6 +76,8 @@ client.chat(agentSlug, message, options?): AsyncGenerator<AgentEvent>
 | `message` | `string` | What to say. Required, non-empty after trimming, at most 20,000 characters. |
 | `options.conversationId` | `string?` | Continue a thread. Take it from the first `conversation` event. |
 | `options.onBehalfOf` | `object?` | Act for one of your end users — see [On behalf of your users](#on-behalf-of-your-users). |
+| `options.model` | `{ provider, model }?` | Run this one call on another model. See [Changing the model or a tool's values for one call](#changing-the-model-or-a-tools-values-for-one-call). |
+| `options.toolInputs` | `Record<toolId, ToolInput>?` | Override what the agent's tools are set up with, for this one call. Same section. |
 | `options.signal` | `AbortSignal?` | Cancel the turn. |
 
 Returns an async generator of [events](#events). It ends after `done`, or after `error`.
@@ -103,6 +105,82 @@ Passing `conversationId` is worth doing for a second reason: a tool set to **Ask
 
 A thread belongs to the agent, to this API, **and** to the `onBehalfOf.subject` it was opened under. Keep the subject the same across a conversation's turns, and never reuse an id from the app, the portal or an embed — any mismatch answers `404`, not a fresh thread.
 
+## Sending files with a message
+
+Pass `files` and the agent reads them on that turn, in the same call. This is the paperclip of the promptev chat: the agent takes files only when **Chat attachments** is switched on in its builder, and only the types that chat takes.
+
+```ts
+import { readFile } from "node:fs/promises";
+
+for await (const ev of client.chat("support-agent", "What is the total on this receipt?", {
+  files: [{ name: "receipt.png", content: await readFile("receipt.png") }],   // or a File / Blob
+})) {
+  if (ev.type === "token") process.stdout.write(ev.content);
+}
+```
+
+Up to **five files per call**, 25 MB each. An image is shown to a model that can see, and read into text for one that cannot. A document is read before the answer starts, so a long scan makes a slower first event. A call may carry files and an empty message.
+
+| Status | When |
+|---|---|
+| 409 | The agent's Chat attachments is off |
+| 415 | A file type the agent cannot take |
+| 413 | The workspace is out of storage |
+
+## Changing the model or a tool's values for one call
+
+Both options are optional. Leave them out and the agent runs exactly as it was published. Nothing a call sends is stored: the next call runs the published agent again.
+
+### `model`
+
+```ts
+for await (const ev of client.chat("support-agent", question, {
+  model: { provider: "openai", model: "gpt-5-mini" },
+})) { /* … */ }
+```
+
+`provider` and `model` are the ids shown in your workspace's model list. The workspace's own provider key is used; a call never carries a key. The model runs on its default settings, because the agent's saved settings (temperature and the like) were tuned for its own model.
+
+The call answers `400` (a `ValidationError`, with `field` set) before the model is called when the workspace has no such provider, the provider has no key, the model is not in its list or has been retired, or the model cannot call tools and the agent has tools.
+
+### `toolInputs`
+
+Override what a tool is set up with, keyed by the tool's **id** (shown on the tool's page in promptev, with a copy button). Each value goes under the place it belongs to:
+
+```ts
+for await (const ev of client.chat("support-agent", "How many open orders does ACME have?", {
+  toolInputs: {
+    "0b6f2c1e-…": {                              // an HTTP tool
+      headers: { Authorization: `Bearer ${endUserToken}` },
+      query:   { region: "us" },
+      body:    { account_id: "acme" },
+      path:    { customer: "acme" },              // a {{customer}} in the tool's URL
+    },
+    "7d41a9c3-…": {                              // an MCP server
+      headers:   { Authorization: `Bearer ${endUserToken}` },
+      arguments: { project_id: "p_123" },
+    },
+  },
+})) { /* … */ }
+```
+
+| Tool | Place | What it is |
+|---|---|---|
+| HTTP | `headers` | A header the tool was saved with. Names match in any letter case. |
+| HTTP | `query` | A query parameter: one the tool was saved with, or one the model fills. A `GET` or `DELETE` tool has no body, so all of its parameters are `query`. |
+| HTTP | `body` | A body value (`POST`, `PUT`, `PATCH`): a key of the saved body, or a parameter the model fills. |
+| HTTP | `path` | A `{{name}}` in the tool's URL. |
+| MCP server | `headers` | A header the server was saved with (`Authorization` when it was saved with a token). |
+| MCP server | `arguments` | An argument of the server's functions. The value reaches every function that takes an argument of that name. |
+
+The rules:
+
+- **Override only.** A name the tool does not have in that place answers `400`, and the message lists what the tool does have there. Nothing extra is ever passed through.
+- **A value the model would have filled is fixed for the call.** The model neither sees that parameter nor can change it, so the answer's wording follows the question while the tool gets your value.
+- **What is visible.** A value the model would have filled shows wherever tool arguments show: the `tool_call` event and approval requests. A header, and any value the tool was saved with, never appears in the stream. **Put secrets in `headers`.**
+- **Limits.** 20 tools per call, 20 names per place, 16 KB per tool.
+- Overriding a value the tool was **saved with** (a header, a fixed query parameter, a key of the saved body) needs a server that supports it. One that does not answers `400` saying so; it never runs the call without your value.
+
 ## Events
 
 Every frame the server can send, typed. Narrow on `event.type`.