Update attachments API to support cells & selection ranges

[dlqqq]

Description

This PR updates the attachments API to support attaching individual notebook cells and including selection ranges within both file & cell attachments.

This PR is being opened to prepare the main branch for @andrii-i's work, which will allow users to drag & drop notebook cells or selection ranges into the chat. This PR only changes the API, and should not have any user-facing impact in the application.

Technical details

Currently, each attachment is assigned an ID based on its type and value, and stored in a dictionary within the YChat model. When a user re-attaches a file with the same type and value, the matching entry in the attachments is updated, and the same ID is returned. This is defined in the set_attachment() method.

However, consider this scenario:

1. User attaches file untitled.txt and sends the message
2. Later, another user attaches a selection range within untitled.txt

If the existing logic were used, operation 2) would override the attachment entry added by operation 1). Hence, the set_attachment() method has been updated to always create a new ID for attachments w/ selections.

[github-actions]

👈 Launch a Binder on branch dlqqq/jupyter-chat/selections-in-attachments

[andrii-i]

Looks good, makes sense.
Thank you for working on this @dlqqq.

[ellisonbg]

Nice! I have some ideas for how we could improve the attachment architecture for text files and notebooks that will only require minor changes to this PR. We’ll post the ideas later this weekend or Monday. Thanks for working on this.

[dlqqq]

Brian raises a good point. Using NotebookAttachment instead of CellAttachment would also allow for multi-cell selections to be included in a single attachment.

[dlqqq]

@ellisonbg @brichet All comments have been addressed! Thank you both for the code review.

• JSON.stringify() is used to compare attachments & check for duplicates.

• The ICellAttachment model has been replaced with INotebookAttachment. It has a very simple interface:

type: 'notebook';
value: string; // path to the notebook
cells?: INotebookCellAttachment[]; // mostly the same as previous `ICellAttachment` model

@andrii-i This does introduce some breaking changes to the API you are using in #248, FYI. May be good to try creating a new branch that uses this as its base.

[andrii-i]

Updated types and interfaces look good to me.

[brichet]

Thanks for updating it @dlqqq.

I have one requirement below, otherwise it looks good to me.

[dlqqq]

TY! Merging. 👍

[ellisonbg]

Nice work folks!

…

On Wed, Jul 2, 2025 at 11:09 AM David L. Qiu ***@***.***> wrote: Merged #247 <#247> into main. — Reply to this email directly, view it on GitHub <#247 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAAGXUGVBPCVJN43PD4AFAL3GQN5DAVCNFSM6AAAAACAJ67D2GVHI2DSMVQWIX3LMV45UABCJFZXG5LFIV3GK3TUJZXXI2LGNFRWC5DJN5XDWMJYGQZTOMZQGMYTEMQ> . You are receiving this because you were mentioned.Message ID: ***@***.***>

-- Brian E. Granger Senior Principal Technologist, AWS AI/ML ***@***.***) On Leave - Professor of Physics and Data Science, Cal Poly @ellisonbg on GitHub

[brichet]

I missed this change from interface to type in the review.
Does it means that other extensions will not be able to extends it anymore, and creates their own attachment object ?
IIUC, only attachment types defined in @jupyter/chat will now be allowed as attachment.

@dlqqq don't you think that we should/could revert this change ?
I wonder if IFileAttachment and INotebookAttachment could not implement IAttachment, instead of having a type ?

[ellisonbg]

It would be helpful if this API was extensible, but @brichet not sure how it being an interface will help as each document type will likely have different metadata. Can you give more details about how this might work?

[brichet]

Indeed, the IAttachment interface (prior to this PR) probably didn't support any type of attachment (e.g. selection and cells options).

The attachment could be a minimal interface like

export interface IAttachment {
  type: string;
  value: string;
  content: any; // could be anything that is JSON serializable.
}

Then we would have

export interface IFileAttachment extends IAttachment {
  type: 'file';
  content: {
    mimetype?: string;
    selection?: IAttachmentSelection;
  };
}

export interface INotebookAttachment extends IAttachment {
  type: 'notebook';
  content: {
    cells?: INotebookAttachmentCell[];
  };
}

The attachmentOpenerRegistry already allows to set a dedicated function for each attachment type.
Maybe we should update this registry to also allow a displayName() function (e.g. attachmentManagerRegistry), now that the display name is configurable.

Like that, any attachment that extends this interface would be compatible with the message and input attachments.

Do you think it could work like that ?

[ellisonbg]

This sounds reasonable, @dlqqq is OOTO for a few days and would love to get his take on this.