Annotate the version of an item

[tuscland]

Is your feature request related to a problem? Please describe.

As a data scientist, I want to annotate the specific version of an item because it helps me keep track of what is happening.

As a data scientist, I want to update or delete the note I have previously created.

As a data scientist, the notes I create from the Python API must be visible in the UI.

Describe the solution you'd like

Python API

The value of the note kwarg is some Markdown text.

Add an note:

skore.put(
    "feat_imps",
    fig,
    note="added AggJoiner with max_observation=2"
)

More programmatic CRUD:

item_version = skore.get_item_versions("feat_imps")[0]

# If there is no note, it creates a note, otherwise update the note
item_version.set_note("set frunobulax level at 11")
note = item_version.get_note()

item_version.delete_note()

UI

Let the user interact with an item version:

• Create / Update a note using Markdown text.
• Delete the note.
• View the note of an item (last version)
• View the note of a specific item version

Describe alternatives you've considered, if relevant

No response

Additional context

Related to #889

• (UI) feat: allow to add a description to an item in views #905
• feat: Implement note-related methods #1084
• feat(project.put): Add note argument #1101
• feat(UI): Add markdown editor to annotate item #1082

[augustebaum]

Without put_item it seems harder to achieve the set_note behaviour, as Items are just dataclasses with no link to a Project.

[rouk1]

To me, we need to introduce IDs for items. They could be a simple string interpolation {name}-{counter}.
Then note may be a new entity with a foreign key. Even without a proper db engine we can do this in repositories.

[augustebaum]

Yes, then set_note could be a method of Project instead:

project.put("my_key", 3)

# Annotates the latest version by default
project.set_note("my_key", "this is 3 because 3 is good")

# Annotates version 10
project.set_note("my_key-10", "this is 3 because 3 is good")

[thomass-dev]

@augustebaum , we shouldn't add the version in the key, prefer a dedicated parameter.

In your example, imagine you have two items in your project with keys my_key (10 versions) and my_key-10 (1 version).
How to differentiate the version 10 of the my_key item from the my_key-10 item?

I would prefer something like:

 class Project:
     def set_note(self, key, note, *, version=-1):
         ...

Edit:

We can maybe add a new parameter to the put function too put(key, value, *, note=None).

[MarieS-WiMLDS]

agree with Thomas's solution, I like it, it seems fluid. I also like to be able to put a note at first and also afterwards.

[MarieS-WiMLDS]

The UI has been defined :)!
It can be found in this figma: https://www.figma.com/design/Qzjyxv0lPDU2kKtsH9dcp3/Skore---Workstation---High-fidelity-mock-ups---Q3?node-id=5404-14131&t=TZMMlaSkT983MfKM-4

[augustebaum]

With #1082 merged I believe a first iteration of this issue is done! Please review and close if you agree @MarieS-WiMLDS @sylvaincom

[sylvaincom]

Many thanks team! All good on my side, I'm letting @MarieS-WiMLDS give her approval as well

[MarieS-WiMLDS]

Hello!

Starting to play with the notes, I have a couple of questions.

I can't wait to show it to people who asked for it :)!

Q1

project.put("first_item 2", "some text here to change ", note="a note") # is ok
project.put("first_item 2", "some text here to change ", "a note") # is not ok

Why is the second option not ok? Also, why does it render this error, I don't understand why it tells me I give 4 arguments while I read only 3? Finally, the documentation of put doesn't seem to be updated, is it something you are planning to do later?

Q2

It was a bit difficult to me to understand how to save the note. I clicked on the screen outside of the note, but it didn't close the editing window. I'm not sure it should, be willing to hear your opinion about it.

Q3

When I write a simple note, like "blblbl", when I fetch it using:

item_v = project.get_item_versions("first_item 2")[0]
item_v.note
# outputs 'blblbl\n'. Where does \n comes from?

Capture.video.du.17-01-2025.09.38.57.webm

Q4

more a remark; it looks like we haven't been clear in the specs, sometimes we talk about a message, sometimes a note. everything is not consistant. --> let's harmonize everything on "note".

[augustebaum]

Great feedback @MarieS-WiMLDS

Re Q1: The second option is not ok because when you start adding a lot of arguments to a function, passing arguments by keyword is less ambiguous (otherwise the user might be confused as to which argument is the value and which is the note).

Re Q2: This was discussed with @rouk1 and I agree with you -- I thought it was something we could deal with later. Currently your options are all keyboard-based (Esc, Shift+Enter or Alt+Enter)

Re Q3: I can see in the video that you pressed Enter before saving the note, that would be why. Maybe we can strip those @rouk1 EDIT: When I press Shift+Enter, it adds a newline and then saves

Re Q4: You're right, I am only noticing it now. See #1143

[sylvaincom]

Re Q2: as in a markdown cell in Jupyter notebook, you do Shift+Enter

[rouk1]

It was a bit difficult to me to understand how to save the note. I clicked on the screen outside of the note, but it didn't close the editing window. I'm not sure it should, be willing to hear your opinion about it.

I agree that the question could be asked. Behind the scene your note is saved at each keystroke, hence no need to focus out or to click save (à la notion). I suppose this is fine.

I'll open a PR to handle "click outside" and trimming.

[MarieS-WiMLDS]

re Q1: ok, I understand why it's not a good idea! However I still don't understand the error: it tells me I gave 4 arguments, while I only gave 3. Is there something we can do about it? Also, the documentation of put is not updated yet, do you have a reminder somewhere to do it?

[auguste-probabl]

I still don't understand the error: it tells me I gave 4 arguments, while I only gave 3. Is there something we can do about it?

That's because it also counts self, as put is a method of project. That's something to do with how Python works, I don't thnk we can mitigate this... @thomass-dev do you agree?

the documentation is not updated yet

@thomass-dev #1052 should update the Project docs indeed. As for the public docs, they haven't been built in 1 week because OpenML is currently down, which means our examples don't run. We were hoping this would be resolved by now... @thomass-dev and I will start work on a fix shortly.

[MarieS-WiMLDS]

thanks for the answers, and for the "click outside" addition.

Our last element to tackle before closing this issue is the saving of the note. As @auguste-probabl said, When I press Shift+Enter, it adds a newline and then saves.

[rouk1]

thanks for the answers, and for the "click outside" addition.

Our last element to tackle before closing this issue is the saving of the note. As @auguste-probabl said, When I press Shift+Enter, it adds a newline and then saves.

Done in #1167