assistan-ts v0.0.15

OpenAI Assistan(ts)

npm i assistan-ts

A lightweight framework for building and running code first, type-safe "Agents".

This library aims to make it easy to create & run assistants, without introducing heavy abstractions or departing too far from the official openai library.

Demo Video (1min)

Key Features:

• Define Assistants using typebox schemas
• Sync changes with OpenAI
• Parse & validate arguments to tool calls
• Automatically poll runs for completion

!WARNING Both this library & openai's assistants api are still in early development and is subject to change.

Usage

Define your Assistant

import { Type, definition, assistant } from 'assistan-ts';

  const def = definition({
    key: "Schedul-O-Bot-3000", // 'unique' key added to metadata for linking
    model: "gpt-4",
    name: "Schedul-O-Bot-3000",
    instructions: "You help schedule meetings for E-Corp.",
    codeInterpreter: true,
    functionTools: {
      employee_directory: {
        description: "List all employees with contact and role information",
        parameters: Type.Void(),
      },
      schedule_meeting: {
        description: "Schedule a meeting with an employee",
        parameters: Type.Object({
          employee: Type.Number({
            description: "The Employee Id to schedule the meeting with",
          }),
          date: Type.String({
            description: "The date to schedule the meeting on",
            format: "date-time",
          }),
          duration: Type.Number({
            description: "The duration of the meeting in minutes",
            minimum: 15,
            maximum: 60 * 3,
          }),
        }),
      },
    },
  });

!NOTE Not all typebox types are supported by OpenAI at this time

Syncing Files

You can sync files by setting the files.resolve property of the definition. This allows you to sync files from the filesystem or a remote location.

import { toFile } from "openai/uploads";
import { readFile, readdir } from "fs/promises";

const def = definition({
   //...
    retrieval: true,
    files: {
      resolve: async () => {
        const fileName = 'time-off-policy.md';
        const content = await readFile(path.join('docs', fileName));
        return [ toFile(content, filename) ];
      },
    },
});

Files will be compared for equality using the filename by default, but you can overrides this by setting files.keyFn.

Link the Assistant to OpenAI

const linked = await def.link(openai);

This will create the assistant if it doesn't exist, and update it to match the schema if there is any drift.

!WARNING By default, this will update the assistant to match the schema. If you want to disable this behavior, pass { updateMode: "skip" } to the link function.

Create an instance of your assistant

For any tools you defined, you must provide an implementation with a matching signature.

  const scheduleBot = assistant({
    definition: linked,
    tools: {
      employee_directory: async () => {
        return [
          {
            id: 1000,
            name: "John Chen",
            email: "ariachen@example.com",
            department: "Marketing",
            role: "Marketing Manager",
          },
          //...
        ];
      },
      schedule_meeting: async ({ employee, date, duration }) => {
        return {
          status: "success",
          meeting_id: "123",
        };
      },
    },
    toolOptions: {
        // override defaults
    }
  });

Create a thread and run

const thread = await openai.beta.threads.create({
  messages: [
    {
      role: "user",
      content: "Schedule a 45m meeting with Alana on Tuesday at 3pm",
    },
  ],
});

const { run, complete } = await scheduleBot.run.create({
  threadId: thread.id,
});

await complete({ interval: 1500 });

const messages = await openai.beta.threads.messages.list(thread.id);

Alternately, you can use toolsRequired to better control the execution of the tools:

const { toolsRequired } = await scheduleBot.run.create({
  threadId: thread.id,
});

let toolActions = await toolsRequired();

while (toolActions) {
  //let user confirm
  if(confirm(`Continue with ${JSON.stringify(toolActions.toolCalls, null, 2)}?`)){
    toolActions = await toolActions.execute( /* you may provide overrides outputs here */ );
  }
}

Running Examples

pg-bot connected to coffee roasting db

This project contains a number of examples to demonstrate the use of the library.

• schedulo-bot-3000: simple demo, not actually connected to anything
• bash-bot: Agent with full control to execute in your terminal and upload files to for the code interpreter
• pg-bot: Agent connected to a postgres database. Can explore schema and execute queries.

To run an example:

1. cd examples
2. npm i
3. Set the OAI_KEY environment variable to your OpenAI API key (export OAI_KEY=<your key>)
4. use bun to run the index file:

npx bun <example name>/index.ts

!NOTE Checkout the agentCli.ts to see a simple demo of how to manage the agent lifecycle.

Configuration

Link Options

Tool Options

Run Options