Transform Messages Capability

[WaelKarkoub]

Why are these changes needed?

When I think of transforming chat messages (truncating, compressing, summarizing, etc.), it sounded to me like it's a transformation matrix problem in robotics. For example:

$\textbf{P}_2 = \textbf{R}_x \textbf{R}_y \textbf{R}_z \textbf{P}_1$

Where $\textbf{R}$ is the rotation transformation matrix relative to an axis, and $\textbf{P}$ is the position vector.

So I thought, why not approach transforming chat messages the same way?

$\textbf{M}_2 = \textbf{R}_a \textbf{R}_b \textbf{R}_c \textbf{M}_1$

For example:

• $\textbf{R}_a$ can be max number of messages,
• $\textbf{R}_b$ can be token limit,
• $\textbf{R}_c$ LLM Lingua compression

So I refactored TransformChatHistory in context_handling.py to get the same behavior described above, cc @gagb. So the ability is now called TransformMessages, and it accepts a list of the transformations you would like to apply to the messages. MessageTransform defines the interface of how the transform, $\textbf{R}$, should look like. I also implemented a few transforms as early examples (MaxMessagesTransform, TruncateMessageTransform)

Why is this useful?

There are some text-based use cases like I mentioned above that can be very helpful in managing the number of tokens used, but they can also be useful for other modalities. Imagine a certain LLM can only accept a certain image size, but the chat history has all kinds of image sizes and resolutions. All you have to do is create a transform (e.g. ResizeImageTransfrom) and pass it to the ability.

NOTE: Need to add tests

Related issue number

Checks

• I've included any doc changes needed for https://microsoft.github.io/autogen/. See https://microsoft.github.io/autogen/docs/Contribute#documentation to build and test documentation locally.
• I've added tests (if relevant) corresponding to the changes introduced in this PR.
• I've made sure all auto checks have passed.

[codecov-commenter]

Codecov Report

Attention: Patch coverage is 68.42105% with 36 lines in your changes are missing coverage. Please review.

Project coverage is 48.97%. Comparing base (78aa0eb) to head (8b0e77a).

Files	Patch %	Lines
...togen/agentchat/contrib/capabilities/transforms.py	76.82%	11 Missing and 8 partials ⚠️
...entchat/contrib/capabilities/transform_messages.py	37.03%	17 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##             main    #1923       +/-   ##
===========================================
+ Coverage   37.36%   48.97%   +11.61%     
===========================================
  Files          74       76        +2     
  Lines        7481     7591      +110     
  Branches     1617     1774      +157     
===========================================
+ Hits         2795     3718      +923     
+ Misses       4445     3559      -886     
- Partials      241      314       +73     

Flag	Coverage Δ
unittest	13.84% <64.03%> (?)
unittests	47.88% <4.38%> (+10.53%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[gagb]

This is nice! I'll check @dkirsche might also be interested

[WaelKarkoub]

@sonichi @jackgerrits updated the PR, notebook should be renderable and formatted to follow the guidelines

[sonichi]

@gagb could you add the deprecation plan to the roadmap?