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

packages/genai_primitives/lib/src/message_parts.dart

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.

I'll elaborate on what the enums mean, but across all of the LLM APIs (and I've built against most of them by now, certainly all of the major ones), it always boils down to role (user or system or model|assistant) and parts. Anything more than that is over engineering, imo.

I still think having roles itemized makes this library too opinionated.

I would remove role from the message completely, allowing clients to define the roles in their systems.

If you disagree let's merge this as is and have this discussion outside of this PR.

let's talk after the merge.

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?

yes. that's correct. I'll update the name and the docs.

packages/genai_primitives/lib/src/message_parts.dart

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

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

packages/genai_primitives/lib/src/message_parts.dart

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.

what kind of type checking do we get with Object? the standard JSON in/out in Dart is Map<String, dynamic> -- shouldn't we stick with that? I'm open to changing to Object? if I can understand the reason to vary from the Dart SOP.

There are debates in Dash team if Dart should change the standard.
It is verified that Map<String, Object?> does not break standard json serialization.

With Object you get some minimal static analysis, with dynamic you can invoke whatever field you want.

There are lints that restrict dynamic and we use them.

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'?

…oolName` for clarity, and enhance `ChatMessageRole` documentation."

…ble fields and new client properties. Also downstream updates required a new version of dartantic.

…into initial_primitives

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

…oolName` for clarity, and enhance `ChatMessageRole` documentation."

…ble fields and new client properties. Also downstream updates required a new version of dartantic.

polina-c · 2025-12-22T21:42:26Z

Landed!

Thanks to @andrewkolos for the fast fix!

Minor suggestion about this PR: how about using callId instead of interactionId to reduce number of terms in the package?

…into initial_primitives

…age parts and examples. interactionId=>callId.

csells · 2025-12-22T22:21:25Z

ok @polina-c . I rebased on main, got everything building again and replaced "interactionId" with "callId" as well as most of the other suggestions I well.

also, the latest dartantic_ai works with the latest mistral if that's of interest.

polina-c · 2025-12-23T01:54:21Z

Amazing! Thank you 🙏

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

packages/genai_primitives/lib/src/message_parts.dart Outdated Show resolved Hide resolved

polina-c reviewed Dec 18, 2025

View reviewed changes

packages/genai_primitives/lib/src/message_parts.dart Outdated Show resolved Hide resolved

polina-c reviewed Dec 18, 2025

View reviewed changes

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

csells and others added 3 commits December 20, 2025 13:19

PR feedback: rename ToolPart id to interactionId and name to `t…

457a3f5

…oolName` for clarity, and enhance `ChatMessageRole` documentation."

chore: Update SDK dependencies and enhance fake A2A client with nulla…

3c7057e

…ble fields and new client properties. Also downstream updates required a new version of dartantic.

Merge branch 'main' into initial_primitives

9947103

gspencergoog and others added 23 commits December 22, 2025 13:10

Switch to local A2A Dart client library (flutter#627)

8707e5f

revert changes in packages/genui_a2ui/pubspec.yaml

e6a840a

Merge branch 'initial_primitives' of https://github.com/csells/genui …

6a1f186

…into initial_primitives

Merge branch 'main' into initial_primitives

35d2f87

initial port

bc16a51

port to json_schema_builder

6836134

updated tests

73ae75d

changelog, pubspec

f9b9a9e

pubspec

165b7f7

pana feedback

106f6dd

pana feedback

3e88ed2

copyrights

179a79b

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

86b2c26

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

bd045bc

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

formatting

3b40f10

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

1f2b758

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

eeddae9

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

double quotes

70cb971

PR feedback: rename ToolPart id to interactionId and name to `t…

313a827

…oolName` for clarity, and enhance `ChatMessageRole` documentation."

chore: Update SDK dependencies and enhance fake A2A client with nulla…

891c3be

…ble fields and new client properties. Also downstream updates required a new version of dartantic.

revert changes in packages/genui_a2ui/pubspec.yaml

ea96b0e

Switch to local A2A Dart client library (flutter#627)

e23a58f

revert changes in packages/genui_a2ui/pubspec.yaml

68ce736

csells added 2 commits December 22, 2025 13:53

Merge branch 'initial_primitives' of https://github.com/csells/genui …

0b6a929

…into initial_primitives

chore: Update package dependencies and adjust genai_primitives mess…

8597a0a

…age parts and examples. interactionId=>callId.

polina-c approved these changes Dec 23, 2025

View reviewed changes

polina-c merged commit 3b98cd6 into flutter:main Dec 23, 2025
36 checks passed

initial port of dartantic_interface types #619

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!

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!

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!

Uh oh!

polina-c commented Dec 18, 2025

Uh oh!

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!

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!

polina-c commented Dec 22, 2025

Uh oh!

csells commented Dec 22, 2025

Uh oh!

polina-c commented Dec 23, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

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