feat(attachments): create context-aware helper for attachments

[Dam-Buty]

Non-Breaking

This creates a new context-aware helper that abstracts the logic around creating attachments, as well as providing the following enhancements :

• Make threadId optional (it is already optional on the API)
• Fix typing to enforce either content or path at compile time
• Accept a variety of formats as input content (ReadableStream, ReadStream, Buffer, File, Blob & ArrayBuffer)
• As a treat i squashed the chainlit-logo to hell so it is <3KB ⚡

Old syntax

// Upload the file
const { objectKey } = await literalClient.api.uploadFile({
  threadId: thread.id,
  content: fileStream,
  mime
});

// Create the Attachment
const attachment = new Attachment({ name: 'Attachment', objectKey, mime });

// Attach it to the step
await thread
  .step({
    name: 'Assistant',
    type: 'assistant_message',
    output: { content: 'Here is the generated image!' },
    attachments: [attachment]
  })
  .send();

New syntax

await literalClient
  .step({
    name: 'Assistant',
    type: 'assistant_message',
    output: { content: 'Here is the generated image!' }
  })
  .wrap(async () => {
    // This will upload the file, create the attachment
    // and automatically attach it to the wrapped step
    await client.api.createAttachment({
      content: fileStream,
      mime,
      name: 'Attachment'
    });
  });

[linear]

ENG-1590 TS SDK : inconsistencies on uploadFile

The uploadFile method on the TS SDK has the following signature :

{
    content?: Maybe<any>;
    path?: Maybe<string>;
    id?: Maybe<string>;
    threadId: string;
    mime?: Maybe<string>;
}

• threadId is mandatory but it is optional on the API, both in the upload/file endpoint & in the Attachment type
• content on the other hand should be mandatory
• content is typed any but it will definitely break if you don't provide it with a Readable

For the content part, it is a bit impractical when the file comes from a web form. In this case it is presented to you as a File , and it took me a hot minute to figure out that i had to transform it like that :

const nodeStream = Readable.fromWeb(
  formAudio.stream() as ReadableStream<any>
);
// nodeStream can now be used in uploadFile

In a similar situation, the openai SDK provides a toFile helper which takes as input a wide variety of File, Blob, ArrayBuffer, ReadStream and more, and converts it to something you can upload.

As a general rule we want to change the API for attachments, instead of first uploading the file then creating the Attachment instance we should have client.api.createAttachment which uploads the file & returns an Attachment instance. uploadFile stays as is in case some use cases need it.

• Make threadId optional
• Fix typing to have either content or path
• Accept ReadableStream, ReadStream, Buffer, File, Blob & ArrayBuffer as input content
• abstract upload + Attachment instantiation with a helper method createAttachment

[desaxce]

Looks great to me!

[desaxce]

It's still a png, what was the trick to reduce size? # of RGB channels?

[Dam-Buty]

yes ! i used one of those online squashers, and reduced the color depth (to <10 colors iirc)

[desaxce]

I didn't know we could declare prototypes for doc/autocompletion purposes.

[desaxce]

Just realized you mentioned "Fix typing to enforce either content or path at compile time" -> very clear.

[Dam-Buty]

yes overloading function types is a great way to handle this kind of either/or parameters. It's a bit verbose but the end result is satisfying from the POV of the dev using the function.

[desaxce]

Thank you so much for splitting tests in their own file!

[Dam-Buty]

you're welcome, i'm unable to focus on a 700 line test file anyway 😅

[desaxce]

png maybe?

[desaxce]

When I debug, I expect caught errors to appear somewhere in the logs, it helps me navigate through the code and quickly identify the location of a bug. I think it's only me in the team though.

[Dam-Buty]

In this case, there is genuinely nothing to log. You may or may not be inside of a context, both of which are valid states. But you're right, that's a code smell so i added _currentThread and _currentStep methods which do not throw outside of context. It is much cleaner.

I couldn't make them private (as they are consumed from outside of the LiteralClient class) but they are undocumented.

[desaxce]

I see, it's like using try/catch as an if condition.

[desaxce]

I don't think the openai e2e test should be impacted by this change, there are no attachments in those tests.

[Dam-Buty]

I don't think the openai e2e test should be impacted by this change, there are no attachments in those tests.

yes, confirmed, they do work in local