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.
fix case of null in nameFromMimeType
Follow Gemini's advises below

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.

yjbanov · 2025-12-30T17:57:58Z

packages/genai_primitives/lib/src/message.dart

+  static const metadata = 'metadata';
+}
+
+/// A message in a conversation between a user and a model.


It's not super-clear what "between" means. Does it mean that a Message can be sent by the user to the model, and by the model to the user? If so, consider spelling it out, if not in the intro paragraph, then in a second paragraph.

yjbanov · 2025-12-30T18:00:01Z

packages/genai_primitives/lib/src/message.dart

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


Document the arguments. Special cases, such as when parts and metadata are both empty, could be particularly important.

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

packages/genai_primitives/lib/src/message.dart

+
+  /// Creates a new message, taking a text string as separate parameter.
+  Message(
+    String text, {


Looks like this is a convenience constructor. Typically, the default constructor is the main constructor, and named constructors are conveniences. That is, I'd make fromParts the default, and this one named Message.fromText.

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?

yjbanov · 2025-12-30T19:11:13Z

packages/genai_primitives/lib/src/utils.dart

 }
+
+int mapHashCode(Map<dynamic, dynamic>? map) {
+  if (map == null) return 0;


Let's avoid redefining the hash code for null. null already has hashCode, and it is equal to 2011 on the Dart VM, and 0 on the web. Let's just return null.hashCode and let the language/compiler do its thing.

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?

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.

yjbanov · 2025-12-30T19:23:21Z

packages/genai_primitives/lib/src/message.dart

+  /// Gets the text content of the message by concatenating all text parts.
+  String get text => parts.whereType<TextPart>().map((p) => p.text).join();
+
+  /// Checks if this message contains any tool calls.


"Checks" is an unusual way to describe a getter. It's as if it fails if there are no tool calls. Typically we say, "Returns whether this message contains...", or "Returns true if this message contains...".

This comment applies to other getters in the library.

yjbanov · 2025-12-30T19:25:32Z

packages/genai_primitives/lib/src/message.dart

+      .where((p) => p.kind == ToolPartKind.result)
+      .toList();
+
+  /// Converts the message to a JSON-compatible map.


nit: consider "Serializes" instead of "Converts". The word "convert" implies that this same object transforms/mutates to something else, but what this method does is create a new object that represents this object in JSON format.

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

Open

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

Uh oh!

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!

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

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

polina-c commented Dec 24, 2025 •

edited

Loading

polina-c commented Dec 24, 2025 •

edited

Loading

polina-c commented Dec 30, 2025 •

edited

Loading