initial port of dartantic_interface types #619

csells · 2025-12-18T14:41:39Z

Description

fixes #626

Adds the following types ported from dartantic_interface and migrated to json_schema_builder:

Part (base class)
TextPart
DataPart (for images/binary data)
LinkPart (for URLs)
ToolPart (for tool calls and results)
ToolPartKind (enum: call, result)
ChatMessage
ChatMessageRole (enum: system, user, model)
ToolDefinition (name, description, inputSchema but no call implementation)

Pre-launch Checklist

I read the [Flutter Style Guide] recently, and have followed its advice.
I signed the [CLA].
I read the [Contributors Guide].
[n/a] I have added sample code updates to the [changelog].
I updated/added relevant documentation (doc comments with ///).

csells · 2025-12-18T14:42:50Z

fyi: @gspencergoog @polina-c @sethladd

gemini-code-assist

Code Review

This pull request introduces a new package genai_primitives by porting several types from dartantic_interface. The changes include new data models for chat messages, message parts (text, data, links, tools), and tool definitions, along with a comprehensive example and unit tests. The overall structure is good, but I've found several critical issues with equality checks and hashCode implementations that could lead to incorrect behavior, particularly when using these objects in hash-based collections. Additionally, there are some concerns with JSON serialization and a dependency on a private API. My review comments provide specific suggestions to address these points.

packages/genai_primitives/lib/src/chat_message.dart

packages/genai_primitives/lib/src/message_parts.dart

packages/genai_primitives/lib/src/chat_message.dart

gemini-code-assist · 2025-12-18T14:44:33Z

packages/genai_primitives/lib/src/message_parts.dart

+  /// Gets the extension for a MIME type.
+  static String? extensionFromMimeType(String mimeType) {
+    final String ext = defaultExtensionMap.entries
+        .firstWhere(
+          (e) => e.value == mimeType,
+          orElse: () => const MapEntry('', ''),
+        )
+        .key;
+    return ext.isNotEmpty ? ext : null;
+  }


This method relies on default_extension_map from package:mime/src/default_extension_map.dart, which is a private implementation detail of the mime package (as indicated by the src directory and the // ignore: implementation_imports). Relying on private APIs is risky as they can change without notice in minor or patch versions, potentially breaking your code. Since the mime package doesn't seem to offer a public reverse lookup API, a safer approach would be to define a local map of the common MIME types to extensions that your package needs to support.

it's worse to duplicate a half-assed version of the list of extensions that isn't properly maintained

Agreed. Really the mime package should be fixed to export a reverse lookup.

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

polina-c · 2025-12-18T20:25:22Z

packages/genai_primitives/lib/src/chat_message.dart

+}
+
+/// The role of a message author.
+enum ChatMessageRole {


Can you add more details to doc strings for enum and its items?

I can represent a confused user here:

doc for enum is saying that each item is a role of a message author, while doc for each item is describing type of message, not author

can you elaborate what is 'system'?

documentation is saying 'from', but not 'to'. Is it correct that system always send messages to model? If yes, should we specify it here? And the same about model: is it correct that model's messages are intended to be handled by system and then system will show to the user whatever is intended for user?

or my assumptions above are completely wrong and the enum relates to difference between 'user prompt' and 'system prompt' somehow?

Maybe in this library instead of ChatMessage having field ChatMessageRole role, it make sense for it to have the field 'String type', so that every dependent can define their set of message types.

Another option:

class ChatMessage<T>{ ... final T type; ... }

Then users will be able to pass their enums for the message type. Maybe some of them will have more than one model and more than one system.

Or, we can remove type completely, so that users just derive from ChatMessage and add whatever fields they want to add. Or users can compose ChatMessage into another object, that contains envelope information.

This seems to be cleanest option for me.

polina-c · 2025-12-18T20:32:41Z

packages/genai_primitives/lib/src/message_parts.dart

+  final ToolPartKind kind;
+
+  /// The unique identifier for this tool interaction.
+  final String id;


How about renaming it to interactionId, to avoid confusion and make it clear how to name this id, when it is copied outside of this class?
Is it correct that id of tool call is expected to be equal to id of tool call result? If yes, should it be documented here?

polina-c · 2025-12-18T20:38:07Z

packages/genai_primitives/lib/src/message_parts.dart

+      : '';
+
+  @override
+  bool operator ==(Object other) =>


Would you mind updating it to use this boilerplate, so that readers do not have to detect if it is identical to what is recommended in style guide:

https://github.com/flutter/flutter/blob/master/docs/contributing/Style-guide-for-Flutter-repo.md#common-boilerplates-for-operator--and-hashcode

polina-c · 2025-12-18T20:42:27Z

Thank you! It looks good. Left some naming and documentation related comments.

polina-c · 2025-12-18T20:45:53Z

packages/genai_primitives/lib/src/message_parts.dart

+  final String id;
+
+  /// The name of the tool.
+  final String name;


Should it be named 'toolName'? Unlike other properties 'name', this 'name' is not name of the enclosing object (ToolCall or ToolResult).

csells · 2025-12-18T20:46:23Z

Yes you're correct about the tool result id matching the tool can id. I like the idea of updating the name and the docs to reflect that, although I don't know what that name should be. I'll provide an update ASAP.

polina-c · 2025-12-18T20:47:15Z

packages/genai_primitives/lib/src/message_parts.dart

+  final Map<String, dynamic>? arguments;
+
+  /// The result of a tool execution (null for calls).
+  final dynamic result;


Should we use Object? instead of dynamic everywhere?

I second that. Dynamic turns off type checking.

polina-c · 2025-12-18T20:51:17Z

Yes you're correct about the tool result id matching the tool can id. I like the idea of updating the name and the docs to reflect that, although I don't know what that name should be. I'll provide an update ASAP.

I suggest interactionId.

polina-c · 2025-12-18T22:44:26Z

@csells, I raised many questions about minor details.

There are options how to proceed:

I can just merge your PR, then figure out the details in the follow up PRs, then publish the package.
We can figure out the details on this PR.

If you want to actively participate in discussion, let's go with (2).
Otherwise, let's proceed with (1), where you will be optional reviewer for the follow up PRs.

polina-c · 2025-12-19T03:58:28Z

Yes you're correct about the tool result id matching the tool can id. I like the idea of updating the name and the docs to reflect that, although I don't know what that name should be. I'll provide an update ASAP.

I suggest interactionId.

Or 'requestId'?

csells added 7 commits December 18, 2025 06:13

initial port

4ad0ecd

port to json_schema_builder

86b9f84

updated tests

2033059

changelog, pubspec

9a41d31

pubspec

dbeae4a

pana feedback

f301f5d

pana feedback

48b1401

gemini-code-assist bot reviewed Dec 18, 2025

View reviewed changes

csells and others added 7 commits December 18, 2025 06:45

copyrights

ae9bf1b

Update packages/genai_primitives/lib/src/chat_message.dart

c7cdf9a

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

Update packages/genai_primitives/lib/src/message_parts.dart

4c6c8e2

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

formatting

a95f613

Update packages/genai_primitives/lib/src/message_parts.dart

d2007d5

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

Update packages/genai_primitives/lib/src/chat_message.dart

4f3b62f

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

double quotes

3f1169d

polina-c reviewed Dec 18, 2025

View reviewed changes

polina-c requested a review from gspencergoog December 18, 2025 20:47

initial port of dartantic_interface types #619

Are you sure you want to change the base?

initial port of dartantic_interface types #619

Uh oh!

Conversation

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

Uh oh!

Description

Pre-launch Checklist

Uh oh!

csells commented Dec 18, 2025

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!

gemini-code-assist bot Dec 18, 2025

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 Dec 18, 2025 • 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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

polina-c Dec 18, 2025 • 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!

polina-c Dec 18, 2025 • 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!

Choose a reason for hiding this comment

Uh oh!

polina-c commented Dec 18, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

csells commented Dec 18, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

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

Uh oh!

Uh oh!

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

Uh oh!

Uh oh!

polina-c commented Dec 19, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

csells commented Dec 18, 2025 •

edited by polina-c

Loading

polina-c Dec 18, 2025 •

edited

Loading

polina-c Dec 18, 2025 •

edited

Loading

polina-c Dec 18, 2025 •

edited

Loading

polina-c commented Dec 18, 2025 •

edited

Loading

polina-c commented Dec 18, 2025 •

edited

Loading