Updates to make the library applicable for wider range of use cases, and more stable. #644

polina-c · 2025-12-24T02:16:34Z

Contributes to #607

Remove ChatMessageRole: this library should not enforce the set of roles, as it can vary from case to case. The role should be part of envelope in client's code.
Rename ChatMessage to Message, because this library can be used in chats and in other systems.
Use constants for repeating literals
Remove postfix 'Part' from part type literals, to reduce size of messages.
Extend test coverage for primitives.
Add test for example.
Follow Gemini's advises below
Replace dynamic with Object?
Refactor Part to make the class extendable.
Update equality to match Flutter codestyle and to use package collection for deep collection comparison

polina-c · 2025-12-24T06:06:07Z

/gemini review

polina-c · 2025-12-24T06:09:54Z

@csells , how does it look?

gemini-code-assist

Code Review

This pull request introduces several significant and beneficial changes to make the library more flexible and robust. Key changes include removing the enforced ChatMessageRole, renaming ChatMessage to Message, and using constants for JSON keys to reduce message size. The test coverage has been significantly improved, including a new test for the example, which is excellent. My review focuses on some opportunities to improve code clarity and leverage more modern Dart features, such as using const constructors for immutable classes and refactoring switch statements/expressions for better readability. Overall, this is a solid pull request that improves the library's design and usability.

packages/genai_primitives/example/main.dart

packages/genai_primitives/lib/src/message.dart

packages/genai_primitives/lib/src/message_parts.dart

packages/genai_primitives/test/genai_primitives_test.dart

polina-c · 2025-12-30T04:17:34Z

Options for name for the class ChatMessage:

Message (I used it for now, but I am open)
MessageBody
MessageContent
Content

csells · 2025-12-30T05:44:14Z

I think you left one option:

ChatMessage

Can I ask what problem is solved by renaming it?

polina-c · 2025-12-30T15:03:53Z

I think you left one option:

ChatMessage

Can I ask what problem is solved by renaming it?

Sure!

This library is intended to serve very wide range of client applications, interacting with AI.

'Chat' is implying type of interaction, where history is preserved, and UI looks as timeline.

But, there can be many other types. And, I am sure we do not know these types as they do not exist yet.

Does it help?

csells · 2025-12-30T15:31:17Z

That sounds abstract. My understanding of the goal of this package was to concretely provide base types for chat history, which would eliminate the need to provide mapping layers between GenUI, dartantic and other packages like the Flutter AI Toolkit.

What concrete scenarios do you have in mind?

polina-c · 2025-12-30T15:46:18Z

That sounds abstract. My understanding of the goal of this package was to concretely provide base types for chat history, which would eliminate the need to provide mapping layers between GenUI, dartantic and other packages like the Flutter AI Toolkit.

What concrete scenarios do you have in mind?

For example, interaction with some history-less agent without chat-like UI.
Like agent that is doing google search, without history, using google-search-tool and then selecting responses that are more educational than offering concrete products and services.

csells · 2025-12-30T17:48:43Z

To which agent are you referring that provides such a history-based API without it being conversational? I'm unfamiliar with any that work like that.

yjbanov · 2025-12-30T17:56:39Z

packages/genai_primitives/lib/src/message.dart

+
+/// A message in a conversation between a user and a model.
+@immutable
+class Message {


Is this class intended to be implemented? If not, let's mark it using the base modifier.

Made it final to avoid issues with backward compatibility. If we ever change our mind, it will be easy to remove it or replace final with base.

packages/genai_primitives/lib/src/message.dart

yjbanov · 2025-12-30T18:03:33Z

packages/genai_primitives/lib/src/message.dart

+  /// Creates a new message, taking a text string as separate parameter.
+  Message(
+    String text, {
+    List<Part> parts = const [],


What happens if one of the parts is a TextPart? Is it OK to have two text parts?

yes, added documentation

The documentation is on a different constructor. This constructor should explain what happens if one passes both text, and one or more TextParts.

packages/genai_primitives/lib/src/utils.dart

yjbanov · 2025-12-30T19:15:09Z

packages/genai_primitives/lib/src/message_parts.dart

 @immutable
 abstract class Part {
  /// Creates a new part.
  const Part();


Why do we need a constructor for creating an empty part?

Because we need parent constructor for all descendants, but implicit constructor is not constant. It is good to redefine it to make constant.

yjbanov · 2025-12-30T19:20:55Z

packages/genai_primitives/lib/src/message.dart

+  final Map<String, dynamic> metadata;
+
+  /// Gets the text content of the message by concatenating all text parts.
+  String get text => parts.whereType<TextPart>().map((p) => p.text).join();


If I have parts "happy", "new", "year", "world", will the concatenated text be "happynewyearworld"?

yes, but luckily the text parts include whitespace, so we're good.

Yes, these text parts are created to support streaming from LLM. And, LLM will produce the parts with spaces and paragraph marks:

"Happy", " new", " year,", " world!\n"

packages/genai_primitives/lib/src/message.dart

polina-c · 2026-01-07T20:50:28Z

To which agent are you referring that provides such a history-based API without it being conversational? I'm unfamiliar with any that work like that.

(yes, happy New Year!)

I said above not 'history-based' but 'history-less', but it is not very important.

As I said before, we want to cover wide range of stories, published and not published, past and future. It does not matter if such agent exist or no. The landscape of AI-related tools and patterns and practices changes every week. If a story is theoretically possible, and it may benefit from this library, I do not want naming to create confusion.

And yes, as you noticed, it sounds abstract, and it should be abstract, to allow as many concrete implementations, as possible.

A good side effect of this renaming is that now the name 'ChatMessage' is used in example, and it is good that this name is available for client applications to incapsulate whatever envelope information is needed.

Did I miss something?

csells · 2026-01-07T21:59:43Z

sounds like you're architecting for an unknown future. that's not something I'm a fan of in general. have you considered dynamic? : )

Yes, I am cutting off some opinions of this library that have big chances to be different in different use cases.

In particular I am separating message body and message envelope: the body should stay in the library (because body has the same structure in most cases), while envelope should be defined in the client application (because content of envelope has big chances to differ from case to case, and thus there is no point to have it in library).

Does it help?

…er#645)

Wraps the example data parsing and component creation in a try-catch block to capture and rethrow errors with additional context (the item name). This makes it easier to identify which catalog item has invalid example data.

yjbanov · 2026-01-09T18:21:34Z

packages/genai_primitives/lib/src/message.dart

+  ///
+  /// If `parts` or `metadata` is not provided, an empty collections are used.
+  ///
+  /// If there is no parts of type [TextPart], the [text] property


grammar: "are no parts"

yjbanov · 2026-01-09T18:23:02Z

packages/genai_primitives/lib/src/message.dart

+  /// If there is no parts of type [TextPart], the [text] property
+  /// will be empty.
+  ///
+  /// If there are many parts of type [TextPart], the [text] property


"many" sounds ambiguous. Let's say "more than one".

yjbanov · 2026-01-09T18:24:42Z

packages/genai_primitives/lib/src/message.dart

+  ///
+  /// If there are many parts of type [TextPart], the [text] property
+  /// will be a concatenation of all of them.
+  /// Many text parts is convenient to have to support


Separate paragraphs with one empty line.

grammar: "convenient to have to support" doesn't sound right. Suggestion: "Use multiple text parts to support..."

yjbanov · 2026-01-09T18:25:57Z

packages/genai_primitives/lib/src/message.dart

+  /// If there are many parts of type [TextPart], the [text] property
+  /// will be a concatenation of all of them.
+  /// Many text parts is convenient to have to support
+  /// streaming of the message.


What does "streaming of the message" mean? Standard Dart Streams are asynchronous constructs, but parts are provided as one synchronous List.

yjbanov · 2026-01-09T18:26:18Z

packages/genai_primitives/lib/src/message.dart

+  /// streaming of the message.
+  const Message({this.parts = const [], this.metadata = const {}});
+
+  /// Creates text message.


grammar: "Creates a text message"

yjbanov · 2026-01-09T18:48:22Z

packages/genai_primitives/lib/src/message_parts.dart

-        break;
+  @override
+  Part convert(
+    Map<String, Object?> input, {


nit: let's give input a proper name (all arguments are "inputs" 😄 ). Perhaps partJson?

yjbanov · 2026-01-09T18:51:36Z

packages/genai_primitives/lib/src/message_parts.dart

 /// Base class for message content parts.
 @immutable
-abstract class Part {
+abstract base class Part {


With a little more understanding of how this works, I think this needs substantially more documentation. In particular, if we want to support custom parts, we should document how to properly create them. The docs should explain about operator==, hashCode, and the JsonToPartConverter. The developer would want to know that all these things need to be covered in order to build a robust custom part implementation.

yjbanov · 2026-01-09T18:53:14Z

packages/genai_primitives/lib/src/message_parts.dart


-  /// The default MIME type for binary data.
-  static const defaultMimeType = 'application/octet-stream';
+  /// Converts the part to a JSON-compatible map.


The map needs more than JSON compatibility. The returned value must be a JSON object, containing certain keys, such as "type". Let's document that.

yjbanov · 2026-01-09T18:55:20Z

packages/genai_primitives/lib/src/message_parts.dart

 /// A text part of a message.
 @immutable
-class TextPart extends Part {
+base class TextPart extends Part {


It might be safer to make this final. Inheritance complicates equality, hash codes, and serialization. For example, it would be too easy to attempt to call super.toJson() from a subclass, and forget to overwrite the part "type". So a HeadingTextPart may accidentally end up getting deserialized as a plain TextPart.

There's not much code to reuse anyway. The developer could just copy this code and make the necessary changes.

This comment applies to other concrete Part classes below.

yjbanov · 2026-01-09T18:57:47Z

pubspec.lock

    description:
      name: characters
-      sha256: f71061c654a3380576a52b451dd5532377954cf9dbd272a78fc8479606670803
+      sha256: faf38497bda5ead2a8c7615f4f7939df04333478bf32e4173fcb06d428b5716b


Did you need to update pubspec.lock to make your code changes to work? Or was this by accident?

yjbanov · 2026-01-09T19:05:45Z

@csells @polina-c

My 2c on the ChatMessage => Message renaming. In the genUI context some messages coming from the LLM are UI updates/mutations to an existing genUI surface. It would be counterintuitive to think of such messages as "chat messages". So I think the renaming is the right choice. An application that uses this library for a chat application could wrap the Message object into a ChatMessage object that would contain additional chat-specific semantics. I can even imagine a "chat message" being one of or a composition of a text message, genui surface, and a data message (e.g. containing a generated image).

polina-c added 4 commits December 23, 2025 17:54

-

b49f458

-

62e769d

Update mesage.dart

5b70ebc

Update mesage.dart

47f4ef5

This comment was marked as outdated.

Sign in to view

polina-c changed the title - Some cleanups to make the library useable for wide range of use cases. Dec 24, 2025

polina-c added 10 commits December 23, 2025 18:27

-

ed024ad

Update genai_primitives.dart

0f37256

Update genai_primitives_test.dart

918e4d9

-

daaa464

-

0452bea

-

87cc5dd

-

724ba2b

-

2ea87b5

-

5887cc4

-

f6af083

polina-c changed the title ~~Some cleanups to make the library useable for wide range of use cases.~~ Updates to make the library applicable for wide range of use cases. Dec 24, 2025

polina-c changed the title ~~Updates to make the library applicable for wide range of use cases.~~ Updates to make the library applicable for wider range of use cases. Dec 24, 2025

polina-c added 2 commits December 23, 2025 21:54

Update genai_primitives_test.dart

f259308

-

5110939

This comment was marked as outdated.

Sign in to view

Update message_parts.dart

31e666a

polina-c marked this pull request as ready for review December 24, 2025 06:08

polina-c requested a review from gspencergoog December 24, 2025 06:08

polina-c changed the title ~~Updates to make the library applicable for wider range of use cases.~~ Updates to make the library applicable for wider range of use cases, and more stable. Dec 24, 2025

gemini-code-assist bot reviewed Dec 24, 2025

View reviewed changes

polina-c added 2 commits December 26, 2025 13:51

-

6a245e8

Update message_parts.dart

52eb3a7

polina-c removed the request for review from gspencergoog December 30, 2025 14:57

yjbanov reviewed Dec 30, 2025

View reviewed changes

mrtakao550-gif mentioned this pull request Dec 30, 2025

## Code Review #647

Closed

andrewkolos and others added 15 commits January 8, 2026 16:12

ci: add workflow_dispatch to enable manual CI triggers (flutter#633)

af0d06b

Add A2UI support section to README (flutter#648)

4ebab33

Update dartantic_ai dependency (flutter#649)

0d4e92d

Post publish commit to add sections to CHANGELOGs (flutter#650)

910f4c5

[docs] Suggest using flutter pub add for adding dependencies (flutt…

4bf48a4

…er#645)

-

c29fca4

Update message.dart

56e12a8

---

36593a0

--

167109f

-

dee7e6b

-

1eb2b23

Create custom_part_test.dart

b3c3014

Update custom_part_test.dart

aebee60

-

62a421d

polina-c requested review from csells and yjbanov January 9, 2026 04:20

yjbanov reviewed Jan 9, 2026

View reviewed changes

Updates to make the library applicable for wider range of use cases, and more stable. #644

Are you sure you want to change the base?

Updates to make the library applicable for wider range of use cases, and more stable. #644

Conversation

polina-c commented Dec 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment was marked as outdated.

Uh oh!

This comment was marked as outdated.

Uh oh!

polina-c commented Dec 24, 2025

Uh oh!

polina-c commented Dec 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

polina-c commented Dec 30, 2025

Uh oh!

csells commented Dec 30, 2025

Uh oh!

polina-c commented Dec 30, 2025

Uh oh!

csells commented Dec 30, 2025

Uh oh!

polina-c commented Dec 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

csells commented Dec 30, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

polina-c Jan 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

polina-c commented Jan 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

csells commented Jan 7, 2026 • edited by polina-c Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

polina-c commented Dec 24, 2025 •

edited

Loading

polina-c commented Dec 24, 2025 •

edited

Loading

polina-c commented Dec 30, 2025 •

edited

Loading

polina-c Jan 8, 2026 •

edited

Loading

polina-c commented Jan 7, 2026 •

edited

Loading

csells commented Jan 7, 2026 •

edited by polina-c

Loading