@relevanceai/sdk 2.0.2 → 3.0.0-alpha.1

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2021 Relevance AI
+Copyright (c) 2025 Relevance AI
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,121 +1,320 @@
-# relevance-js-sdk
-Install with npm using:
-```
-npm i @relevanceai/sdk
-```
-## Features
-- Node and Browser support
-- Typescript definitions for almost all [relevanceai.com](https://relevanceai.com/) apis
-- Insert millions of documents with one function call
-- Our SearchBuilder makes searching, filtering, and aggregating your data simple
-# Getting started
-Get started by creating an account in [cloud.relevanceai.com](https://cloud.relevanceai.com) - select the Vector Database onboarding option. Once set up you can fetch your API key and use the below snippet.
-
-```javascript
-import {VecDBClient,QueryBuilder} from "@relevanceai/sdk";
-
-const discovery = new VecDBClient({
-  project: '',
-  api_key: '',
-  endpoint: ''
+# Relevance AI JavaScript SDK
+
+Build full-stack AI applications using our JavaScript SDK. This multi-environment
+SDK enables you to integrate, extend, or build end-to-end solutions on top of
+our powerful AI Workforce platform.
+
+> **Note:** The SDK is in active development and not all features are available
+> yet. Please refer to our roadmap for updates.
+
+## Quickstart
+
+```js
+import { createClient, AU_REGION } from "@relevanceai/sdk";
+
+// Create a client with your credentials
+const client = createClient({
+  apiKey: "sk-abcdefghijklmnopqrstuvwxyz1234567890ABCDEFGHIJKL",
+  region: AU_REGION,
+  project: "12345678-90ab-cdef-1234-567890abcdef",
+});
+
+// Create a task for an agent
+const task = client.createTask({
+  agent: "fedcba09-8765-4321-fedc-ba0987654321",
 });
-const dataset = discovery.dataset('1000-movies');
 
-const movies = [{ title: 'Lord of the Rings: The Fellowship of the Ring', grenre: 'action', budget: 100 }, ...]
-await dataset.insertDocuments(movies, [{ model_name: 'text-embedding-ada-002', field: 'title' }]);
+// Send a message to the agent
+task.sendMessage(
+  "What is the weather like in Sydney, Australia this weekend?"
+);
 
-const {results} = await dataset.search(QueryBuilder().vector('title_vector_', { query: 'LOTR', model: 'text-embeddings-ada-002' }));
+// Listen for responses
+task.addEventListener("message", ({ detail }) => {
+  const { message } = detail;
+  console.log(message.text);
+
+  task.sendMessage("Thanks!");
+  
+  // Important: Stop listening when done to prevent memory leaks
+  task.stopListening();
+});
 ```
-## Set up your credentials
-### Option 1 - Use environment variables
-First, set environment variables in your shell before you run your code. 
 
-set RELEVANCE_PROJECT to your project name.
+## Getting Started
+
+The JavaScript SDK is a stateless, event-driven toolkit that provides the
+flexibility to build any application you need. It sits on top of our API and
+offers a streamlined developer experience, making it easier for your apps to
+integrate with agents, tools, and workforces.
+
+This multi-environment library allows you to build wherever modern JavaScript
+runs:
 
-set RELEVANCE_API_KEY to your api key.
-for more information, view the docs here: [Authorization docs](https://discovery.relevanceai.com/reference/api-usage)
+- Node.js
+- Deno
+- Bun
+- Cloudflare Workers
+- Browser
+
+### Installation
+
+Install the SDK for your environment:
 
-Heres a template to copy and paste in for linux environments:
 ```bash
-export RELEVANCE_PROJECT=#########
-export RELEVANCE_API_KEY=#########
-```
-The SDK will use these variables when making api calls. You can then initialise your client like this:
-```javascript
-import {VecDBClient} from "@relevanceai/sdk";
-const client = new VecDBClient({});
-```
-### Option 2 - Passing them in code.
-```javascript
-import {VecDBClient} from "@relevanceai/sdk";
-const client = new VecDBClient({
-  project:'########',
-  api_key:'########',
+# Node.js / Cloudflare Workers / Browser (with bundler)
+npm install @relevanceai/sdk@latest
+
+# Deno
+deno add jsr:@relevanceai/sdk
+
+# Bun
+bun add @relevanceai/sdk@latest
+```
+
+#### Browser (CDN)
+
+If you are developing a frontend application and not using a bundler like
+[Vite](https://vite.dev) or [Webpack](https://webpack.js.org), you can use the
+CDN version directly:
+
+```html
+<script type="importmap">
+{
+  "imports": {
+    "@relevanceai/sdk": "https://esm.run/@relevanceai/sdk"
+  }
+}
+</script>
+<script type="module">
+import { createClient } from "@relevanceai/sdk";
+// ...
+</script>
+```
+
+## Usage
+
+### Keys
+
+To communicate with Relevance AI, you will need a key. Keys authenticate your
+requests and grant access to your project.
+
+There are two types of keys: _API_ and _Embed_.
+
+#### API Key
+
+API keys grant access to the entire project, including agents, tools, and
+workforces. This key is best used for server-side applications or protected web
+apps where third parties do not have access.
+
+Using the default client `createClient({ apiKey, region, project })` will create
+an API Key for convenience. Alternatively, you can create a `Key` instance and
+pass it to the client.
+
+```js
+import { createClient, Key, AU_REGION } from "@relevanceai/sdk";
+
+const apiKey = "sk-...";
+const region = AU_REGION;
+const project = "1234...";
+
+const key = new Key({ apiKey, region, project });
+const client = createClient(key);
+```
+
+#### Embed Key
+
+If you are developing a web app that allows third-party access, such as for your
+customers, it's best to share resources from the Relevance AI platform. This
+makes them available for public use and requires an embed key scoped only to
+that resource.
+
+To get an embed key, specify which public resource you wish to scope it to. For
+example, to create an embed key for a publicly available agent in your project:
+
+```js
+import { createClient, Key, AU_REGION } from "@relevanceai/sdk";
+
+const region = AU_REGION;
+const project = "1234...";
+const agent = "abcd..."; // a *public* agent
+
+const embedKey = await Key.generateEmbedKey({ region, project, agent });
+const client = createClient(embedKey);
+```
+
+### Clients
+
+A client is the main entry point for the SDK. It configures communication with
+Relevance AI and manages authentication.
+
+You can create multiple clients, which is useful for multi-project setups.
+
+```js
+import { Client, Key, AU_REGION } from "@relevanceai/sdk";
+
+const apiKey = "sk-...";
+const region = AU_REGION;
+const projectOne = "1234...";
+const projectTwo = "abcd...";
+
+const oneKey = new Key({ apiKey, region, project: projectOne });
+const twoKey = new Key({ apiKey, region, project: projectTwo });
+
+const oneClient = new Client(oneKey);
+const twoClient = new Client(twoKey);
+```
+
+#### Default client
+
+Typically, you will only need a single client. In this case, use the default
+client factory as shown in the quickstart:
+
+```js
+import { createClient, Client } from "@relevanceai/sdk";
+
+const client = createClient({ apiKey, region, project });
+
+// elsewhere in your app
+Client.default();
+```
+
+Attempting to create more than one default client will throw an error. Referencing
+the default client before creating one will also throw an error.
+
+### Tasks
+
+Whenever you run anything in Relevance AI, these are known as tasks. Tasks have
+a subject: an agent, tool, or workforce. You can send messages to these subjects,
+receive replies, and follow updates and errors.
+
+> **Important:** Always call `task.stopListening()` when you're done with a task
+> to prevent memory leaks and clean up resources properly.
+
+#### Creating Tasks
+
+The easiest way to create a new task is to use the client's convenient method
+`createTask` and provide the subject ID.
+
+```js
+const agentId = "1234...";
+const task = client.createTask({ agent: agentId });
+```
+
+#### Sending a Message
+
+Once you have a task instance, you can send messages to the subject using the
+`sendMessage()` method.
+
+```js
+task.sendMessage("How many letter r's are there in the word 'strawberry'?");
+```
+
+Note that this call is not `async`. It sends the message and does not `await`
+a reply. This is intentional, as tasks are event-driven.
+
+### Events
+
+Tasks are event-driven and an application must listen to predefined events to
+manage the status and messages of a task.
+
+Use `.addEventListener()` to listen for task events.
+
+```js
+task.sendMessage("What came first; the chicken or the egg?");
+
+task.addEventListener("message", ({ detail }) => {
+  const { message } = detail;
+  console.log("> %s", message.text);
 });
 ```
-# Examples
-### You can import builders and type definitions like this
-```javascript
-import {QueryBuilder,VecDBClient,BulkInsertOutput} from "@relevanceai/sdk";
-```
-## Insert millions of items with one function call
-```javascript
-const discovery = new VecDBClient({ ... });
-const dataset = discovery.dataset('tshirts-prod');
- // Here we create some demo data. Replace this with your real data
-const fakeVector = [];
-for (let i = 0; i < 768; i++) fakeVector.push(1);
-const tshirtsData = [];
-for (let i = 0; i < 10000; i++) {
-  tshirtsData.push({_id:`tshirt-${i}1`,color:'red',price:i/1000,'title-fake_vector_':fakeVector});
-  tshirtsData.push({_id:`tshirt-${i}2`,color:'blue',price:i/1000});
-  tshirtsData.push({_id:`tshirt-${i}3`,color:'orange',price:i/1000});
+
+Tasks dispatch `CustomEvent`. Event properties will be set in the `detail`
+field of the event. You can see the types of events for more information about
+the properties associated with different events.
+
+Remember to call `task.stopListening()` once you no longer need to listen to
+the task.
+
+---
+
+The following events are available for agent subjects.
+
+#### `start`
+
+When a _new_ task starts.
+
+**Details**
+
+```ts
+interface StartEventDetails {
+  id: string;
+  status: TaskStatus;
 }
-const res = await dataset.insertDocuments(tshirtsData,{batchSize:10000});
-```
-### insertDocuments will output:
-```javascript
-{"inserted":30000,"failed_documents":[]}
-```
-## Text Search and Vector Search
-```javascript
-const builder = QueryBuilder();
-builder.query('red').text().vector('title-fake_vector_',0.5).minimumRelevance(0.1);
-// .text() searches all fields. alternatively, use .text(field1).text(field2)... to search specific fields
-const searchResults = await dataset.search(builder);
-```
-## Filter and retrieve items
-```javascript
-const filters = QueryBuilder();
-filters.match('color',['blue','red']).range('price',{lessThan:50});
-const filteredItems = await dataset.search(filters);
-```
-### search will output:
-```javascript
-{
-  results: [
-    {
-      color: 'red',
-      price: 0,
-      insert_date_: '2021-11-16T03:14:28.509Z',
-      _id: 'tshirt-01',
-      _relevance: 0
-    }
-    ...
-  ],
-  resultsSize: 10200,
-  aggregations: {},
-  aggregates: {},
-  aggregateStats: {}
+```
+
+#### `status`
+
+Whenever the task's _status_ changes.
+
+> **Note:** this event does **not** fire for starting status. Use the `start`
+> event if you need the initial status.
+
+**Details**
+
+```ts
+interface StatusEventDetails {
+  status: TaskStatus;
+}
+```
+
+##### `update`
+
+A task has updated. This update will always be a tool for now but may expand in
+the future.
+
+**Details**
+
+```ts
+interface UpdateEventDetails {
+  update: TaskMessage<"tool">;
+}
+```
+
+#### `message`
+
+A task has received a message.
+
+> **Note:** you will receive messages from _both_ subjects and users.
+
+**Details**
+
+```ts
+interface MessageEventDetails {
+  message: TaskMessage<"agent" | "user">;
 }
 ```
 
+#### `error`
+
+Whenever the task has failed.
 
+**Details**
+
+```ts
+interface ErrorEventDetails {
+  error: TaskMessage<"error">;
+}
+```
+
+**Example**
+
+```js
+task.addEventListener("error", ({ detail }) => {
+  const { error } = detail;
+  console.error("Task failed:", error.text);
+  
+  // clean up
+  task.stopListening();
+});
 ```
-## Call raw api methods directly
-```javascript
-const discovery = new VecDBClient({ ... });
-const dataset = discovery.dataset('tshirts-prod');
-const {body} = await dataset.apiClient.FastSearch({filters:[{match:{key:'_id',value:`tshirt-01`}}]});
-expect((body.results[0] as any).color).toBe('red')
-```

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,
+        };
+    }
+}