dyadic 1.0.0 → 1.1.0

package/README.md

@@ -13,4 +13,47 @@ const client = new Dyadic({ apiKey: process.env.DYADIC_API_KEY });
 console.log(await client.ask("Hello!", { model: "iris" }));
 ```
 
+## Runs: your own agent, Dyadic's tools, your functions
+
+```ts
+const run = await client.runs.run({
+  agent: { id: "helpdesk", name: "Helpdesk", instructions: "You answer customers of a small shop." },
+  messages: [{ role: "user", content: "Where is order 1042?" }],
+  builtin_tools: ["data.web_search"],
+  functions: {
+    lookup_order: {
+      description: "Look up an order by id.",
+      parameters: { type: "object", properties: { order_id: { type: "string" } }, required: ["order_id"] },
+      handler: async ({ order_id }) => ({ order_id, status: "shipped" }),
+    },
+  },
+  end_user: "customer-17",
+});
+console.log(run.output_text);
+```
+
+`client.runs.create({ ..., stream: true })` streams the run's events.
+
+## Connected apps: saving into a person's Workspace
+
+With the person's approval, an application can save into their Dyadic
+Workspace, naming them by the Discord account linked to their Dyadic account.
+
+```ts
+const status = await client.connections.discord(discordId);
+if (!status.authorized) console.log("Allow this app:", status.authorize_url); // show the person this link
+
+try {
+  const saved = await client.workspace.saves.create({ discord_id: discordId, kind: "message", title: "From #general",
+    text: "Worth keeping", url: "https://discord.com/channels/1/2/3" });
+  console.log(saved.url);
+} catch (error) {
+  if (error instanceof DyadicError && error.code === "authorization_required") console.log("Allow this app:", error.body.authorize_url);
+}
+```
+
+`kind` is `message`, `conversation` (with `messages`, saved as a chat the
+person can continue unless `as_chat: false`), `image` or `file` (with `files`:
+base64, up to 10 of 8 MB).
+
 Full guide: https://dyadic.app/developers/

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export declare const VERSION = "1.0.0";
+export declare const VERSION = "1.1.0";
 export declare const DEFAULT_BASE_URL = "https://dyadic.app/api/openai/v1";
 export type Model = "iris" | "iris-think" | (string & {});
 export type Role = "system" | "developer" | "user" | "assistant" | "tool";
@@ -347,10 +347,120 @@ export interface Batch {
     expires_at: number | null;
     metadata: Record<string, string>;
 }
+/** Dyadic's built-in tools an application's run may use. */
+export type BuiltinTool = "data.web_search" | "data.web_fetch" | "image.generate" | "vision.describe_image";
+/** Your own agent, sent with the run: its name and instructions, optional
+ * behaviour overrides (tool_rules, safety, style, citations, research: text to
+ * replace the default, or false to turn it off) and model choices. */
+export interface AgentConfig {
+    id: string;
+    name: string;
+    instructions?: string;
+    behaviour?: Record<string, string | false>;
+    models?: Record<string, string>;
+    tools?: Record<string, boolean>;
+}
+export interface RunParams {
+    agent: string | AgentConfig;
+    messages: ChatMessage[];
+    builtin_tools?: BuiltinTool[];
+    functions?: Tool[];
+    end_user?: string;
+    conversation_id?: string;
+    max_tokens?: number;
+    temperature?: number;
+    think?: boolean;
+    research?: "auto" | "deep";
+    stream?: boolean;
+    /** Your own cap on what this run may spend, in USD (for example what your user has left). */
+    max_cost_usd?: number;
+    /** Ask for up to four suggested follow-up questions (`followups` on the completed run). */
+    followups?: boolean;
+}
+export interface Run {
+    object: "run";
+    type: "run.completed";
+    run_id: string;
+    status: "completed" | "requires_action";
+    agent: string;
+    output_text: string;
+    function_calls: ToolCall[];
+    messages: ChatMessage[];
+    images: {
+        url: string;
+        prompt?: string;
+        quality?: string;
+    }[];
+    sources: {
+        title?: string;
+        url: string;
+    }[];
+    tools: string[];
+    model: string;
+    models: string[];
+    usage: Usage;
+    credits: number;
+    cost_usd: number;
+    estimated: boolean;
+    model_calls: number;
+    operation_id: string;
+    seconds: number;
+    log_id?: string;
+    followups?: string[];
+}
+export interface RunEvent {
+    type: string;
+    [key: string]: unknown;
+}
+/** A function your application runs: its schema and the handler called with the parsed arguments. */
+export interface FunctionHandler {
+    description?: string;
+    parameters?: Record<string, unknown>;
+    handler: (args: any) => unknown | Promise<unknown>;
+}
+/** Connected apps: whether the person with a linked identity approved this application. */
+export interface Connection {
+    linked: boolean;
+    authorized: boolean;
+    scopes?: string[];
+    authorize_url?: string;
+    link_url?: string;
+}
+export interface SaveFile {
+    name?: string;
+    media_type?: string;
+    data: string;
+}
+export interface SaveMessage {
+    role: "user" | "assistant";
+    name?: string;
+    text: string;
+    url?: string;
+}
+export interface WorkspaceSaveParams {
+    discord_id: string | number;
+    kind: "message" | "conversation" | "image" | "file";
+    title?: string;
+    text?: string;
+    messages?: SaveMessage[];
+    as_chat?: boolean;
+    files?: SaveFile[];
+    url?: string;
+    source?: Record<string, unknown>;
+}
+export interface WorkspaceSave {
+    saved: {
+        type: "reference" | "chat" | "file";
+        id: string;
+    }[];
+    url: string;
+}
+/** `executes`: the request's work may already be done when it fails (a run), so it is retried only when refused before starting. */
 export interface RequestOptions {
     form?: FormData;
     query?: Record<string, string | number | undefined>;
     raw?: boolean;
+    executes?: boolean;
 }
 /** Bytes from the API (speech audio, file downloads). */
 export declare class Binary {
@@ -397,6 +507,8 @@ export declare class Stream<T> implements AsyncIterable<T> {
     usage: Usage | undefined;
     /** Responses streams: the final Response once response.completed arrives. */
     response: ResponseObject | undefined;
+    /** Run streams: the completed run once run.completed arrives. */
+    run: Run | undefined;
     readonly requestId: string;
     constructor(http: Response, controller: AbortController, onDone?: () => void);
     [Symbol.asyncIterator](): AsyncIterator<T>;
@@ -415,6 +527,27 @@ export declare class Dyadic {
     /** Low-level request: JSON (or multipart `options.form`) in; JSON, text, Binary (`options.raw`) or a Stream out,
      * with retries for busy or failing servers. */
     request<T>(method: string, path: string, body?: unknown, stream?: boolean, options?: RequestOptions): Promise<T>;
+    /** Dyadic's own endpoints sit beside the OpenAI-compatible base: .../api/openai/v1 -> .../api/v1. */
+    platformURL(path: string): string;
+    /** An agent answers a conversation: one of the account's agents by id ("iris") or your own agent inline,
+     * with Dyadic's built-in tools and your own functions. A run that calls your functions ends with status
+     * "requires_action": run `function_calls`, append `messages` and your results, and run again (or use `run`). */
+    readonly runs: {
+        create: {
+            (params: RunParams & {
+                stream: true;
+            }): Promise<Stream<RunEvent>>;
+            (params: RunParams & {
+                stream?: false;
+            }): Promise<Run>;
+        };
+        /** Run to completion, calling your functions whenever the agent asks. The result's `messages` hold
+         * everything the run added, ready to append to your conversation. */
+        run: (params: Omit<RunParams, "functions" | "stream"> & {
+            functions?: Record<string, FunctionHandler>;
+            maxRounds?: number;
+        }) => Promise<Run>;
+    };
     readonly models: {
         list: () => Promise<{
             object: "list";
@@ -529,6 +662,18 @@ export declare class Dyadic {
         retrieve: (id: string) => Promise<Batch>;
         cancel: (id: string) => Promise<Batch>;
     };
+    /** Connected apps. Show the person `authorize_url` when `authorized` is false. */
+    readonly connections: {
+        discord: (discordId: string | number) => Promise<Connection>;
+    };
+    /** Save into the Workspace of the person with this Discord account, once they approved this application.
+     * Not approved yet throws DyadicError with code "authorization_required" (`error.body.authorize_url`);
+     * no Dyadic account with that Discord account: "account_not_linked". */
+    readonly workspace: {
+        saves: {
+            create: ({ discord_id, ...fields }: WorkspaceSaveParams) => Promise<WorkspaceSave>;
+        };
+    };
     /** One question, one answer: the reply's text. */
     ask(prompt: string, options?: Omit<ChatCompletionParams, "messages" | "model" | "stream"> & {
         model?: Model;

package/dist/index.js

@@ -1,6 +1,6 @@
 // The official TypeScript SDK for the Dyadic API: Iris
 // through the OpenAI-compatible endpoints at https://dyadic.app/api/openai/v1.
-export const VERSION = "1.0.0";
+export const VERSION = "1.1.0";
 export const DEFAULT_BASE_URL = "https://dyadic.app/api/openai/v1";
 /** Bytes from the API (speech audio, file downloads). */
 export class Binary {
@@ -90,12 +90,18 @@ export class Stream {
                     }
                     if (chunk.usage)
                         this.usage = chunk.usage;
+                    if (chunk.type === "run.completed") {
+                        this.run = chunk;
+                        yield chunk;
+                        continue;
+                    }
                     if ((chunk.type === "response.completed" || chunk.type === "response.incomplete") && chunk.response) {
                         this.response = chunk.response;
                         this.usage = chunk.response.usage ?? undefined;
                     }
                     const choice = chunk.choices?.[0];
-                    this.text += chunk.type === "response.output_text.delta" ? chunk.delta ?? "" : choice?.delta?.content ?? choice?.text ?? "";
+                    this.text += chunk.type === "response.output_text.delta" ? chunk.delta ?? "" : chunk.type === "delta" ? chunk.text ?? ""
+                        : choice?.delta?.content ?? choice?.text ?? "";
                     yield chunk;
                 }
             }
@@ -110,9 +116,46 @@ export class Stream {
     abort() { this.controller.abort(); }
 }
 const RETRY = new Set([408, 409, 429, 500, 502, 503, 504]);
+// A run may have executed (and been billed) by the time it fails.
+const RUN_RETRY = new Set([429]);
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 export class Dyadic {
     constructor(options = {}) {
+        /** An agent answers a conversation: one of the account's agents by id ("iris") or your own agent inline,
+         * with Dyadic's built-in tools and your own functions. A run that calls your functions ends with status
+         * "requires_action": run `function_calls`, append `messages` and your results, and run again (or use `run`). */
+        this.runs = {
+            create: ((params) => this.request("POST", this.platformURL("/runs"), params, Boolean(params.stream), { executes: true })),
+            /** Run to completion, calling your functions whenever the agent asks. The result's `messages` hold
+             * everything the run added, ready to append to your conversation. */
+            run: async (params) => {
+                const { functions = {}, maxRounds = 8, ...rest } = params;
+                const schemas = Object.entries(functions).map(([name, f]) => ({ type: "function", function: { name, description: f.description ?? "", parameters: f.parameters ?? { type: "object", properties: {} } } }));
+                const conversation = [...rest.messages];
+                const added = [];
+                for (let round = 0; round < maxRounds; round++) {
+                    const result = await this.runs.create({ ...rest, messages: conversation, functions: schemas.length ? schemas : undefined, stream: false });
+                    if (result.status !== "requires_action")
+                        return { ...result, messages: [...added, { role: "assistant", content: result.output_text }] };
+                    const step = [...result.messages];
+                    for (const call of result.function_calls) {
+                        let args = {};
+                        try {
+                            args = JSON.parse(call.function.arguments || "{}");
+                        }
+                        catch {
+                            args = {};
+                        }
+                        const fn = functions[call.function.name];
+                        const output = fn ? await fn.handler(args) : { error: "unknown function" };
+                        step.push({ role: "tool", tool_call_id: call.id, content: typeof output === "string" ? output : JSON.stringify(output) });
+                    }
+                    conversation.push(...step);
+                    added.push(...step);
+                }
+                throw new DyadicError(`The run still wanted functions after ${maxRounds} rounds.`);
+            },
+        };
         this.models = {
             list: () => this.request("GET", "/models"),
             retrieve: (model) => this.request("GET", `/models/${model}`),
@@ -171,6 +214,18 @@ export class Dyadic {
             retrieve: (id) => this.request("GET", `/batches/${id}`),
             cancel: (id) => this.request("POST", `/batches/${id}/cancel`),
         };
+        /** Connected apps. Show the person `authorize_url` when `authorized` is false. */
+        this.connections = {
+            discord: (discordId) => this.request("GET", this.platformURL(`/connections/discord/${discordId}`)),
+        };
+        /** Save into the Workspace of the person with this Discord account, once they approved this application.
+         * Not approved yet throws DyadicError with code "authorization_required" (`error.body.authorize_url`);
+         * no Dyadic account with that Discord account: "account_not_linked". */
+        this.workspace = {
+            saves: {
+                create: ({ discord_id, ...fields }) => this.request("POST", this.platformURL("/workspace/saves"), { user: { discord_id: String(discord_id) }, ...fields }, false, { executes: true }),
+            },
+        };
         // process.env where it exists (Node, Bun, Deno with compat); browsers pass apiKey.
         const env = globalThis.process?.env ?? {};
         this.apiKey = options.apiKey ?? env.DYADIC_API_KEY ?? "";
@@ -189,7 +244,7 @@ export class Dyadic {
         if (body !== undefined && !options.form)
             headers["Content-Type"] = "application/json";
         const query = Object.entries(options.query ?? {}).filter(([, v]) => v !== undefined).map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(String(v))}`).join("&");
-        const url = `${this.baseURL}${path}${query ? `?${query}` : ""}`;
+        const url = `${path.startsWith("http") ? path : this.baseURL + path}${query ? `?${query}` : ""}`;
         const payload = options.form ?? (body === undefined ? undefined : JSON.stringify(body));
         if (this.appName)
             headers["X-Title"] = this.appName;
@@ -203,7 +258,7 @@ export class Dyadic {
             }
             catch (error) {
                 clearTimeout(timer);
-                if (attempt < this.maxRetries) {
+                if (attempt < this.maxRetries && !options.executes) {
                     await sleep(500 * 2 ** attempt);
                     continue;
                 }
@@ -224,7 +279,7 @@ export class Dyadic {
             clearTimeout(timer);
             const data = await response.json().catch(() => ({ error: { message: `HTTP ${response.status}` } }));
             const error = data?.error ?? {};
-            if (RETRY.has(response.status) && attempt < this.maxRetries && error.type !== "insufficient_quota") {
+            if ((options.executes ? RUN_RETRY : RETRY).has(response.status) && attempt < this.maxRetries && error.type !== "insufficient_quota") {
                 const after = Number(response.headers.get("retry-after"));
                 await sleep(Number.isFinite(after) && after > 0 ? Math.min(after, 30) * 1000 : 500 * 2 ** attempt);
                 continue;
@@ -233,6 +288,8 @@ export class Dyadic {
                 requestId: response.headers.get("x-request-id") ?? "", body: data });
         }
     }
+    /** Dyadic's own endpoints sit beside the OpenAI-compatible base: .../api/openai/v1 -> .../api/v1. */
+    platformURL(path) { return this.baseURL.replace(/\/openai(\/v1)?$/, "/v1") + path; }
     /** One question, one answer: the reply's text. */
     async ask(prompt, options = {}) {
         const { model = "iris", system, ...params } = options;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dyadic",
-  "version": "1.0.0",
-  "description": "The official TypeScript and JavaScript SDK for the Dyadic API (Iris, OpenAI-compatible).",
+  "version": "1.1.0",
+  "description": "The official TypeScript and JavaScript SDK for the Dyadic API: runs with your own agents and functions, plus the OpenAI-compatible API.",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",