@relevanceai/sdk 2.0.1 → 3.0.0-alpha.0

package/esm/agent-task.d.ts

@@ -0,0 +1,61 @@
+import type { Agent } from "./agent.js";
+import { TaskMessage } from "./message.js";
+import { Task, type TaskStatus } from "./task.js";
+type AgentTaskEvents = {
+    start: {
+        status: TaskStatus;
+    };
+    status: {
+        status: TaskStatus;
+    };
+    message: {
+        message: TaskMessage<"agent-message" | "user-message">;
+    };
+    update: {
+        message: TaskMessage<"tool-run">;
+    };
+};
+export type AgentTaskState = "idle" | "starting-up" | "running" | "pending-approval" | "waiting-for-capacity" | "cancelled" | "timed-out" | "escalated" | "unrecoverable" | "paused" | "completed" | "errored-pending-approval" | "queued-for-approval" | "queued-for-rerun";
+/**
+ * AgentTask represents a conversation task with an AI agent. It extends the
+ * base Task class with agent-specific functionality for sending messages and
+ * retrieving conversation history.
+ *
+ * @see {@link Task} for the base task functionality.
+ * @see {@link Agent} for the agent this task is associated with.
+ *
+ * @class AgentTask
+ * @extends Task<Agent, AgentTaskEvents>
+ */
+export declare class AgentTask extends Task<Agent, AgentTaskEvents> {
+    /**
+     * Sends a message to the agent. This method triggers the agent with the
+     * message and updates the task ID if this is the first message.
+     *
+     * Note: This method is asynchronous but doesn't return a promise. Use event
+     * listeners to track the response.
+     *
+     * @param {string} message
+     */
+    sendMessage(message: string): void;
+    /**
+     * Fetches the current status of the task from the API.
+     *
+     * @returns {Promise<TaskStatus>} The current task status.
+     * @throws {Error} if the agent or task ID is missing.
+     */
+    fetchStatus(): Promise<TaskStatus>;
+    /**
+     * Fetches messages from the conversation.
+     *
+     * @param {Object} [options] Optional fetch options.
+     * @param {Date} [options.from] Fetch messages after this timestamp.
+     *
+     * @returns {Promise<TaskMessage[]>} Array of messages in ascending order.
+     * @throws {Error} if the agent or task ID is missing.
+     */
+    fetchMessages({ from }?: {
+        from?: Date;
+    }): Promise<TaskMessage[]>;
+}
+export {};

package/esm/agent-task.js

@@ -0,0 +1,112 @@
+import { TaskMessage } from "./message.js";
+import { Task } from "./task.js";
+/**
+ * Converts an AgentTaskState to a simplified TaskStatus.
+ *
+ * @internal
+ *
+ * @param {AgentTaskState} state The agent task state to convert.
+ * @returns {TaskStatus} The simplified task status.
+ */
+function stateToStatus(state) {
+    switch (state) {
+        case "paused":
+        case "idle":
+            return "idle";
+        case "starting-up":
+        case "waiting-for-capacity":
+        case "queued-for-approval":
+        case "queued-for-rerun":
+            return "queued";
+        case "running":
+            return "running";
+        case "pending-approval":
+        case "escalated":
+            return "action";
+        case "timed-out":
+            return "error";
+        case "cancelled":
+        case "completed":
+            return "complete";
+        case "unrecoverable":
+        case "errored-pending-approval":
+            return "error";
+        default:
+            throw new Error(`unhandled task state: ${state}`);
+    }
+}
+/**
+ * AgentTask represents a conversation task with an AI agent. It extends the
+ * base Task class with agent-specific functionality for sending messages and
+ * retrieving conversation history.
+ *
+ * @see {@link Task} for the base task functionality.
+ * @see {@link Agent} for the agent this task is associated with.
+ *
+ * @class AgentTask
+ * @extends Task<Agent, AgentTaskEvents>
+ */
+export class AgentTask extends Task {
+    /**
+     * Sends a message to the agent. This method triggers the agent with the
+     * message and updates the task ID if this is the first message.
+     *
+     * Note: This method is asynchronous but doesn't return a promise. Use event
+     * listeners to track the response.
+     *
+     * @param {string} message
+     */
+    sendMessage(message) {
+        this.subject.trigger(message, this.id || undefined).then(({ id, state }) => {
+            // started
+            if (!this.id) {
+                this.setId(id, stateToStatus(state));
+            }
+        });
+    }
+    /**
+     * Fetches the current status of the task from the API.
+     *
+     * @returns {Promise<TaskStatus>} The current task status.
+     * @throws {Error} if the agent or task ID is missing.
+     */
+    async fetchStatus() {
+        if (!this.subject.id) {
+            throw new Error("expecting agent id");
+        }
+        if (!this.id) {
+            return "not-started";
+        }
+        const url = `/agents/${this.subject.id}/tasks/${this.id}/metadata`;
+        const res = await this.client.fetch(url);
+        return stateToStatus(res.metadata.conversation.state);
+    }
+    /**
+     * Fetches messages from the conversation.
+     *
+     * @param {Object} [options] Optional fetch options.
+     * @param {Date} [options.from] Fetch messages after this timestamp.
+     *
+     * @returns {Promise<TaskMessage[]>} Array of messages in ascending order.
+     * @throws {Error} if the agent or task ID is missing.
+     */
+    async fetchMessages({ from = new Date(0) } = {}) {
+        if (!this.subject.id) {
+            throw new Error("expecting agent id");
+        }
+        if (!this.id) {
+            throw new Error("expecting task id");
+        }
+        const url = `/agents/${this.subject.id}/tasks/${this.id}/view`;
+        const res = await this.client.fetch(url, {
+            method: "POST",
+            body: JSON.stringify({
+                cursor: {
+                    after: from.toISOString(),
+                },
+            }),
+        });
+        // message should be in ascending order
+        return res.results.reverse().map((data) => new TaskMessage(data));
+    }
+}

package/esm/agent.d.ts

@@ -0,0 +1,17 @@
+import type { AgentTaskState } from "./agent-task.js";
+import { Client } from "./client.js";
+export declare class Agent {
+    #private;
+    private readonly client;
+    static fetch(agentId: string, cli?: Client): Promise<Agent>;
+    private constructor();
+    get id(): string;
+    get name(): string | undefined;
+    get description(): string | undefined;
+    get avatar(): string | undefined;
+    isPublic(): boolean;
+    trigger(message: string, taskId?: string): Promise<{
+        id: string;
+        state: AgentTaskState;
+    }>;
+}

package/esm/agent.js

@@ -0,0 +1,52 @@
+import { Client } from "./client.js";
+import { randomUUID } from "./utils.js";
+const taskPrefixDelimiter = "_-_";
+export class Agent {
+    #config;
+    client;
+    static async fetch(agentId, cli = Client.default()) {
+        const config = await cli.fetch(`/agents/${agentId}/get`);
+        return new Agent(config.agent, cli);
+    }
+    constructor(config, client) {
+        this.#config = config;
+        this.client = client;
+    }
+    get id() {
+        return this.#config.agent_id;
+    }
+    get name() {
+        return this.#config.name;
+    }
+    get description() {
+        return this.#config.description;
+    }
+    get avatar() {
+        return this.#config.emoji;
+    }
+    isPublic() {
+        return this.#config.public;
+    }
+    async trigger(message, taskId) {
+        // embed keys require a task prefixing for new tasks
+        if (!taskId && this.client.isEmbedKey()) {
+            taskId = [this.client.key.taskPrefix, await randomUUID()].join(taskPrefixDelimiter);
+        }
+        const res = await this.client.fetch("/agents/trigger", {
+            method: "POST",
+            body: JSON.stringify({
+                agent_id: this.#config.agent_id,
+                conversation_id: taskId,
+                message: {
+                    role: "user",
+                    content: message,
+                    attachments: [], // @todo
+                },
+            }),
+        });
+        return {
+            id: res.conversation_id,
+            state: res.state,
+        };
+    }
+}

package/esm/client.d.ts

@@ -0,0 +1,36 @@
+import { Agent } from "./agent.js";
+import { type Region } from "./region.js";
+import { AgentTask } from "./agent-task.js";
+import { Key } from "./key.js";
+type CreateClientOptions = {
+    apiKey: string;
+    region: Region;
+    project: string;
+};
+/**
+ * Creates and returns the _default_ client instance.
+ *
+ * @throws {Error} if a default client already exists.
+ * @see {Client.default}
+ */
+export declare function createClient(keyOrOptions: Key | CreateClientOptions): Client;
+export declare class Client {
+    /**
+     * Returns the _default_ client instance.
+     *
+     * @throws {Error} if there is no default client.
+     * @see {createClient}
+     */
+    static default(): Client;
+    readonly key: Key;
+    private readonly baseURL;
+    constructor(key: Key);
+    get region(): Region;
+    get project(): string;
+    isEmbedKey(): boolean;
+    createTask({ agent }: {
+        agent: string | Agent;
+    }): Promise<AgentTask>;
+    fetch<T>(input: `/agents/trigger` | `/agents/${string}/get` | `/agents/${string}/tasks/${string}/metadata` | `/agents/${string}/tasks/${string}/view`, init?: RequestInit): Promise<T>;
+}
+export {};

package/esm/client.js

@@ -0,0 +1,69 @@
+import { Agent } from "./agent.js";
+import { regionBaseURL } from "./region.js";
+import { AgentTask } from "./agent-task.js";
+import { cleanPath } from "./utils.js";
+import { Key } from "./key.js";
+let defaultClient;
+/**
+ * Creates and returns the _default_ client instance.
+ *
+ * @throws {Error} if a default client already exists.
+ * @see {Client.default}
+ */
+export function createClient(keyOrOptions) {
+    if (defaultClient) {
+        throw new Error("default client already exists");
+    }
+    const key = keyOrOptions instanceof Key ? keyOrOptions : new Key({
+        key: keyOrOptions.apiKey,
+        region: keyOrOptions.region,
+        project: keyOrOptions.project,
+    });
+    defaultClient = new Client(key);
+    return defaultClient;
+}
+export class Client {
+    /**
+     * Returns the _default_ client instance.
+     *
+     * @throws {Error} if there is no default client.
+     * @see {createClient}
+     */
+    static default() {
+        if (!defaultClient) {
+            throw new Error("no default client");
+        }
+        return defaultClient;
+    }
+    key;
+    baseURL;
+    constructor(key) {
+        this.key = key;
+        this.baseURL = regionBaseURL(this.key.region);
+    }
+    get region() {
+        return this.key.region;
+    }
+    get project() {
+        return this.key.project;
+    }
+    isEmbedKey() {
+        return this.key.isEmbed();
+    }
+    async createTask({ agent }) {
+        if (agent) {
+            return new AgentTask(typeof agent === "string" ? await Agent.fetch(agent) : agent, undefined, this);
+        }
+        throw new Error("task not implemented");
+    }
+    async fetch(input, init) {
+        const url = new URL(cleanPath(input), this.baseURL);
+        const headers = new Headers(this.key.fetchHeaders());
+        const response = await fetch(url, Object.assign({ headers }, init));
+        if (!response.ok) {
+            console.error(url, init, headers);
+            throw new Error(response.statusText);
+        }
+        return response.json();
+    }
+}

package/esm/events.d.ts

@@ -0,0 +1,40 @@
+import type { TaskMessage } from "./message.js";
+import type { TaskStatus } from "./task.js";
+export declare class TaskStartEvent extends CustomEvent<{
+    id: string;
+    status: TaskStatus;
+}> {
+    readonly type = "start";
+    constructor(id: string, status: TaskStatus);
+}
+export declare class TaskStatusEvent extends CustomEvent<{
+    status: TaskStatus;
+}> {
+    readonly type = "status";
+    constructor(status: TaskStatus);
+}
+export declare class TaskMessageEvent extends CustomEvent<{
+    message: TaskMessage;
+}> {
+    readonly type = "message";
+    constructor(message: TaskMessage);
+    isUserMessage(): boolean;
+}
+export declare class TaskUpdateEvent extends CustomEvent<{
+    message: TaskMessage;
+}> {
+    readonly type = "update";
+    constructor(message: TaskMessage);
+}
+export declare class TaskActionEvent extends CustomEvent<{
+    message: TaskMessage;
+}> {
+    readonly type = "action";
+    constructor(message: TaskMessage);
+}
+export declare class TaskErrorEvent extends CustomEvent<{
+    message: TaskMessage;
+}> {
+    readonly type = "error";
+    constructor(message: TaskMessage);
+}

package/esm/events.js

@@ -0,0 +1,39 @@
+export class TaskStartEvent extends CustomEvent {
+    type = "start";
+    constructor(id, status) {
+        super("start", { detail: { id, status } });
+    }
+}
+export class TaskStatusEvent extends CustomEvent {
+    type = "status";
+    constructor(status) {
+        super("status", { detail: { status } });
+    }
+}
+export class TaskMessageEvent extends CustomEvent {
+    type = "message";
+    constructor(message) {
+        super("message", { detail: { message } });
+    }
+    isUserMessage() {
+        return this.detail.message.type === "user-message";
+    }
+}
+export class TaskUpdateEvent extends CustomEvent {
+    type = "update";
+    constructor(message) {
+        super("update", { detail: { message } });
+    }
+}
+export class TaskActionEvent extends CustomEvent {
+    type = "action";
+    constructor(message) {
+        super("action", { detail: { message } });
+    }
+}
+export class TaskErrorEvent extends CustomEvent {
+    type = "error";
+    constructor(message) {
+        super("error", { detail: { message } });
+    }
+}

package/esm/key.d.ts

@@ -0,0 +1,86 @@
+import type { Region } from "./mod.js";
+type CreateKeyOptions = {
+    key: string;
+    region: Region;
+    project: string;
+    agentId?: string;
+    taskPrefix?: string;
+};
+type GenerateEmbedKeyOptions = Omit<CreateKeyOptions, "key" | "taskPrefix">;
+/**
+ * Key is used to authenticate requests for the {@link Client}. A Key can be
+ * either a _full_ key or an _embed_ key.
+ *
+ * A full key has access to SDK features. An embed key is scoped to a specific
+ * agent and is only used to create and interact with tasks for that agent.
+ *
+ * @see {@link Key.generateEmbedKey} to generate an embed key for a specific agent.
+ *
+ * @class Key
+ */
+export declare class Key {
+    #private;
+    /**
+     * Generates an embed key for the specified agent. The embed key can then be
+     * used to create a {@link Client} instance that can create and interact with
+     * tasks for that agent.
+     *
+     * @throws {Error} if the request to generate an embed key fails.
+     *
+     * @param {GenerateEmbedKeyOptions} options The generation options.
+     *
+     * @returns {Promise<Key>}
+     */
+    static generateEmbedKey({ region, project, agentId, }: GenerateEmbedKeyOptions): Promise<Key>;
+    /**
+     * The region the key is scoped to.
+     *
+     * @property {string} region
+     */
+    readonly region: Region;
+    /**
+     * The project the key is scoped to.
+     *
+     * @property {string} project
+     */
+    readonly project: string;
+    /**
+     * The agent ID the embed key is scoped to. This is `undefined` for full
+     * keys.
+     *
+     * @property {string | undefined} agentId
+     */
+    readonly agentId: string | undefined;
+    /**
+     * The task prefix used to namespace tasks created with the embed key. This
+     * is `undefined` for full keys.
+     *
+     * @property {string | undefined} taskPrefix
+     */
+    readonly taskPrefix: string | undefined;
+    /**
+     * Creates a new {@link Key} instance with the provided options.
+     *
+     * @param {CreateKeyOptions} options
+     */
+    constructor({ key, region, project, agentId, taskPrefix }: CreateKeyOptions);
+    /**
+     * Returns whether the key is an embed key.
+     *
+     * @returns {boolean}
+     */
+    isEmbed(): boolean;
+    /**
+     * Returns the headers required for authenticating requests with this key.
+     *
+     * @returns {HeadersInit}
+     */
+    fetchHeaders(): HeadersInit;
+    /**
+     * Returns a JSON representation of the key.
+     *
+     * @returns {CreateKeyOptions}
+     */
+    toJSON(): CreateKeyOptions;
+}
+export {};

package/esm/key.js

@@ -0,0 +1,121 @@
+import { regionBaseURL } from "./region.js";
+import { cleanPath } from "./utils.js";
+/**
+ * Key is used to authenticate requests for the {@link Client}. A Key can be
+ * either a _full_ key or an _embed_ key.
+ *
+ * A full key has access to SDK features. An embed key is scoped to a specific
+ * agent and is only used to create and interact with tasks for that agent.
+ *
+ * @see {@link Key.generateEmbedKey} to generate an embed key for a specific agent.
+ *
+ * @class Key
+ */
+export class Key {
+    /**
+     * Generates an embed key for the specified agent. The embed key can then be
+     * used to create a {@link Client} instance that can create and interact with
+     * tasks for that agent.
+     *
+     * @throws {Error} if the request to generate an embed key fails.
+     *
+     * @param {GenerateEmbedKeyOptions} options The generation options.
+     *
+     * @returns {Promise<Key>}
+     */
+    static async generateEmbedKey({ region, project, agentId, }) {
+        const embedKeyURL = new URL(cleanPath("/agents/get_embed_key"), regionBaseURL(region));
+        const response = await fetch(embedKeyURL, {
+            method: "POST",
+            body: JSON.stringify({ agent_id: agentId, project }),
+        });
+        if (!response.ok) {
+            throw new Error("failed to fetch embed key", { cause: response });
+        }
+        const { embed_key: embedKey, conversation_prefix: taskPrefix } = await response.json();
+        return new Key({
+            key: embedKey,
+            region,
+            project,
+            agentId,
+            taskPrefix,
+        });
+    }
+    /**
+     * The region the key is scoped to.
+     *
+     * @property {string} region
+     */
+    region;
+    /**
+     * The project the key is scoped to.
+     *
+     * @property {string} project
+     */
+    project;
+    /**
+     * The API key used for authentication.
+     *
+     * @private
+     * @property {string} key
+     */
+    #key;
+    /**
+     * The agent ID the embed key is scoped to. This is `undefined` for full
+     * keys.
+     *
+     * @property {string | undefined} agentId
+     */
+    agentId;
+    /**
+     * The task prefix used to namespace tasks created with the embed key. This
+     * is `undefined` for full keys.
+     *
+     * @property {string | undefined} taskPrefix
+     */
+    taskPrefix;
+    /**
+     * Creates a new {@link Key} instance with the provided options.
+     *
+     * @param {CreateKeyOptions} options
+     */
+    constructor({ key, region, project, agentId, taskPrefix }) {
+        this.#key = key;
+        this.region = region;
+        this.project = project;
+        this.agentId = agentId;
+        this.taskPrefix = taskPrefix;
+    }
+    /**
+     * Returns whether the key is an embed key.
+     *
+     * @returns {boolean}
+     */
+    isEmbed() {
+        return (this.agentId !== undefined && this.taskPrefix !== undefined);
+    }
+    /**
+     * Returns the headers required for authenticating requests with this key.
+     *
+     * @returns {HeadersInit}
+     */
+    fetchHeaders() {
+        return {
+            Authorization: `${this.project}:${this.#key}`,
+        };
+    }
+    /**
+     * Returns a JSON representation of the key.
+     *
+     * @returns {CreateKeyOptions}
+     */
+    toJSON() {
+        return {
+            key: this.#key,
+            region: this.region,
+            project: this.project,
+            agentId: this.agentId,
+            taskPrefix: this.taskPrefix,
+        };
+    }
+}

package/esm/message.d.ts

@@ -0,0 +1,18 @@
+type TaskMessageType = "user-message" | "agent-message" | "tool-run" | "agent-error";
+export type MessageData = {
+    item_id: string;
+    insert_date_: string;
+    content: {
+        type: TaskMessageType;
+        text: string;
+    };
+};
+export declare class TaskMessage<T extends TaskMessageType = TaskMessageType> {
+    #private;
+    constructor(data: MessageData);
+    get id(): string;
+    get type(): T;
+    get createdAt(): Date;
+    get text(): string;
+}
+export {};

package/esm/message.js

@@ -0,0 +1,18 @@
+export class TaskMessage {
+    #data;
+    constructor(data) {
+        this.#data = data;
+    }
+    get id() {
+        return this.#data.item_id;
+    }
+    get type() {
+        return this.#data.content.type;
+    }
+    get createdAt() {
+        return new Date(this.#data.insert_date_);
+    }
+    get text() {
+        return this.#data.content.text;
+    }
+}

package/esm/mod.d.ts

@@ -0,0 +1,7 @@
+export { Agent } from "./agent.js";
+export { Client, createClient } from "./client.js";
+export { Key } from "./key.js";
+export { type Region, REGION_AU, REGION_EU, REGION_US } from "./region.js";
+export type { AgentTask } from "./agent-task.js";
+export type { TaskMessage } from "./message.js";
+export type { Task, TaskStatus } from "./task.js";

package/esm/mod.js

@@ -0,0 +1,4 @@
+export { Agent } from "./agent.js";
+export { Client, createClient } from "./client.js";
+export { Key } from "./key.js";
+export { REGION_AU, REGION_EU, REGION_US } from "./region.js";