docs(dart): align package with Dart documentation best practices

- Add comprehensive CHANGELOG.md following Keep a Changelog format
- Restructure README.md with improved sections and formatting
  - Add badges for GitHub, Dart SDK, and protocol
  - Simplify section headers and streamline content
  - Remove duplicate content between sections
- Enhance pubspec.yaml metadata
  - Add repository, issue tracker, and documentation links
  - Add topics for better package discoverability
  - Update minimum SDK version to 3.3.0
- Add dartdoc comments to all public APIs
  - Document main library with features and examples
  - Add class-level documentation for client, config, and types
  - Include method documentation with parameters and return values
  - Add usage examples in documentation comments

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

Author: mattsp1290

sdks/community/dart/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+All notable changes to the AG-UI Dart SDK will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2025-01-21
+
+### Added
+- Initial release of the AG-UI Dart SDK
+- Core protocol implementation with full event type support
+- HTTP client with Server-Sent Events (SSE) streaming
+- Strongly-typed models for all AG-UI protocol entities
+- Support for tool interactions and generative UI
+- State management with snapshots and JSON Patch deltas (RFC 6902)
+- Message history tracking across multiple runs
+- Comprehensive error handling with typed exceptions
+- Cancel token support for aborting long-running operations
+- Environment variable configuration support
+- Example CLI application demonstrating key features
+- Integration tests validating protocol compliance
+
+### Features
+- `AgUiClient` - Main client for AG-UI server interactions
+- `SimpleRunAgentInput` - Simplified input structure for common use cases
+- Event streaming with backpressure handling
+- Tool call processing and result handling
+- State synchronization across agent runs
+- Message accumulation and conversation context
+
+### Known Limitations
+- WebSocket transport not yet implemented
+- Binary protocol encoding/decoding not yet supported
+- Advanced retry strategies planned for future release
+- Event caching and offline support planned for future release
+
+[0.1.0]: https://github.com/mattsp1290/ag-ui/releases/tag/dart-v0.1.0

sdks/community/dart/README.md

@@ -2,6 +2,10 @@
 
 A strongly-typed Dart implementation of the AG-UI protocol for standardizing agent-user interactions through event-based communication.
 
+[![GitHub](https://img.shields.io/badge/GitHub-ag--ui-blue)](https://github.com/mattsp1290/ag-ui)
+[![Dart SDK](https://img.shields.io/badge/dart-%3E%3D3.0.0-blue)](https://dart.dev)
+[![Protocol](https://img.shields.io/badge/protocol-AG--UI-green)](https://github.com/mattsp1290/ag-ui/blob/main/docs/specification.md)
+
 ## Features
 
 ### ✅ Implemented
@@ -54,8 +58,7 @@ Then run:
 dart pub get
 ```
 
-## Quickstart
-### Basic Usage
+## Quick Start
 
 ```dart
 import 'package:ag_ui/ag_ui.dart';
@@ -99,9 +102,9 @@ void main() async {
 }
 ```
 
-## Usage Examples
+## Usage
 
-### 1. Initialize Client
+### Initialize Client
 
 ```dart
 import 'package:ag_ui/ag_ui.dart';
@@ -136,7 +139,7 @@ final customClient = AgUiClient(
 );
 ```
 
-### 2. Send User Message and Stream Response
+### Send User Message and Stream Response
 
 ```dart
 import 'dart:io';
@@ -182,7 +185,7 @@ Future<void> sendMessage(String userInput) async {
 }
 ```
 
-### 3. Handle Tool Calls
+### Handle Tool Calls
 
 ```dart
 import 'package:ag_ui/ag_ui.dart';
@@ -264,7 +267,7 @@ String processToolCall(ToolCall toolCall) {
 }
 ```
 
-### 4. Manage Conversation State
+### Manage Conversation State
 
 ```dart
 import 'dart:io';
@@ -342,7 +345,7 @@ class ConversationManager {
 }
 ```
 
-### 5. Error Handling and Cancellation
+### Error Handling and Cancellation
 
 ```dart
 import 'dart:async';
@@ -413,7 +416,7 @@ bool shouldCancel(BaseEvent event) {
 }
 ```
 
-### 6. Custom Event Processing
+### Custom Event Processing
 
 ```dart
 import 'dart:io';
@@ -485,7 +488,7 @@ void main() async {
 }
 ```
 
-### 7. Using Environment Variables
+### Using Environment Variables
 
 ```dart
 import 'dart:io';
@@ -515,7 +518,7 @@ AgUiClient createClientFromEnv() {
 // AGUI_BASE_URL=https://api.example.com AGUI_API_KEY=sk-xxx dart run main.dart
 ```
 
-### 8. Complete End-to-End Example
+### Complete End-to-End Example
 
 ```dart
 import 'dart:io';
@@ -649,92 +652,6 @@ Future<void> main() async {
 }
 ```
 
-### Handling Tool Calls
-
-```dart
-import 'package:ag_ui/ag_ui.dart';
-import 'dart:convert';
-
-Future<void> handleToolCalls() async {
-  final client = AgUiClient(
-    config: AgUiConfig(baseUrl: 'http://localhost:20203'),
-  );
-
-  final messages = <Message>[];
-  
-  // Initial user message
-  messages.add(UserMessage(
-    id: 'msg_1',
-    content: 'What\'s the weather in San Francisco?',
-  ));
-
-  final input = RunAgentInput(
-    threadId: 'thread_${DateTime.now().millisecondsSinceEpoch}',
-    runId: 'run_${DateTime.now().millisecondsSinceEpoch}',
-    messages: messages,
-    state: {},
-    tools: [],
-    context: [],
-    forwardedProps: {},
-  );
-
-  await for (final event in client.streamEvents('/agent', input)) {
-    if (event is MessagesSnapshotEvent) {
-      // Check for tool calls in assistant messages
-      for (final message in event.messages) {
-        if (message is AssistantMessage && message.toolCalls != null) {
-          for (final toolCall in message.toolCalls!) {
-            print('Tool called: ${toolCall.function.name}');
-            print('Arguments: ${toolCall.function.arguments}');
-            
-            // Provide tool result
-            final toolResult = ToolMessage(
-              id: 'tool_msg_${DateTime.now().millisecondsSinceEpoch}',
-              content: json.encode({'temperature': 72, 'condition': 'sunny'}),
-              toolCallId: toolCall.id,
-            );
-            
-            messages.add(toolResult);
-            
-            // Continue conversation with tool result
-            final continuedInput = RunAgentInput(
-              threadId: input.threadId,
-              runId: 'run_${DateTime.now().millisecondsSinceEpoch}',
-              messages: messages,
-              state: {},
-              tools: [],
-              context: [],
-              forwardedProps: {},
-            );
-            
-            // Stream the continuation
-            await for (final nextEvent in client.streamEvents('/agent', continuedInput)) {
-              // Handle continuation events...
-              if (nextEvent is RunFinishedEvent) break;
-            }
-          }
-        }
-      }
-    }
-  }
-}
-```
-
-### Environment Variables
-
-Configure the client using environment variables:
-
-```bash
-export AGUI_BASE_URL=http://your-server:20203
-export AGUI_API_KEY=your-api-key-here
-
-dart run your_app.dart
-```
-
-```dart
-// Client will automatically use environment variables
-final client = AgUiClient.fromEnvironment();
-```
 
 ## API Overview
 
@@ -807,7 +724,7 @@ dart pub get
 dart run ag_ui_example --help
 ```
 
-## Integration Testing
+## Testing
 
 The SDK includes comprehensive integration tests that validate compatibility with AG-UI servers. To run tests locally:
 
@@ -881,9 +798,6 @@ Contributions are welcome! Please:
 
 This SDK is part of the AG-UI Protocol project. See the [main repository](https://github.com/mattsp1290/ag-ui) for license information.
 
-## Versioning
-
-This SDK follows semantic versioning. Version history will be tracked in future releases.
 
 ## Support
 

sdks/community/dart/lib/ag_ui.dart

@@ -2,6 +2,40 @@
 ///
 /// This library provides strongly-typed Dart models for the AG-UI protocol,
 /// enabling agent-user interaction through a standardized event-based system.
+///
+/// ## Features
+///
+/// - **Core Protocol Support**: Full implementation of AG-UI event types
+/// - **HTTP Client**: Production-ready client with SSE streaming support
+/// - **Event Streaming**: Real-time event processing with backpressure handling
+/// - **Tool Interactions**: Support for tool calls with generative UI
+/// - **State Management**: Handle snapshots and deltas (JSON Patch RFC 6902)
+/// - **Type Safety**: Strongly-typed models for all protocol entities
+///
+/// ## Getting Started
+///
+/// ```dart
+/// import 'package:ag_ui/ag_ui.dart';
+///
+/// final client = AgUiClient(
+///   config: AgUiClientConfig(
+///     baseUrl: 'http://localhost:8000',
+///   ),
+/// );
+///
+/// final input = SimpleRunAgentInput(
+///   messages: [
+///     UserMessage(
+///       id: 'msg_1',
+///       content: 'Hello, world!',
+///     ),
+///   ],
+/// );
+///
+/// await for (final event in client.runAgent('agent', input)) {
+///   print('Event: ${event.type}');
+/// }
+/// ```
 library ag_ui;
 
 // Core types