Artemis Flutter SDK

A production-ready Flutter plugin for integrating Artemis's AI agent capabilities into iOS and Android applications.

Features

✅ Text Chat: Real-time messaging with AI agents
✅ Configuration-First: All settings loaded from YAML configuration
✅ Event Streaming: Listen to SDK and chat events
✅ Message History: Full conversation management
✅ Environment Support: Dev/staging/prod configurations
✅ Type-Safe: Strongly typed Dart API
✅ Platform Native: Supports iOS and Android

Installation

Add this to your package's pubspec.yaml:

dependencies:
  artemis_socket_plugin: ^1.0.0

Then run:

flutter pub get

Quick Start

1. Create Configuration File

Create assets/sdk_configurations.yaml in your Flutter app:

artemis_sdk:
  environment: dev
  connection:
    project_id: "your-project-id"
    api_key: "pk_your_api_key"
    endpoint: "https://runtime.example.com"
  # ... see example/assets/sdk_configurations.yaml for all options

2. Add Assets to pubspec.yaml

flutter:
  assets:
    - assets/sdk_configurations.yaml

3. Initialize SDK

import 'package:artemis_socket_plugin/artemis_socket_plugin.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  
  // Initialize SDK with configuration from assets
  final sdk = await AgentSDK.initialize();
  
  // Connect to platform
  await sdk.connect();
  
  runApp(MyApp(sdk: sdk));
}

4. Use SDK in Your App

class ChatScreen extends StatefulWidget {
  final AgentSDK sdk;
  
  const ChatScreen({required this.sdk});
  
  @override
  State<ChatScreen> createState() => _ChatScreenState();
}

class _ChatScreenState extends State<ChatScreen> {
  @override
  void initState() {
    super.initState();
    
    // Listen to chat events
    widget.sdk.chatEvents.listen((event) {
      if (event is MessageReceivedEvent) {
        setState(() {
          // Update UI with new message
        });
      }
    });
  }
  
  Future<void> _sendMessage(String text) async {
    await widget.sdk.sendMessage(text);
  }
  
  @override
  Widget build(BuildContext context) {
    final messages = widget.sdk.getMessages();
    // Build your UI with messages
  }
}

Configuration

The SDK uses a YAML configuration file to control all behavior. This makes it easy to switch between environments without code changes.

Required Fields

artemis_sdk:
  connection:
    project_id: "your-project-id"      # REQUIRED
    api_key: "pk_your_api_key"         # REQUIRED (or bootstrap_token)
    endpoint: "https://runtime.example.com"  # REQUIRED

Environment-Specific Overrides

Create environment-specific files that override base configuration:

assets/
  ├── sdk_configurations.yaml         # Base configuration
  ├── sdk_configurations.dev.yaml     # Development overrides
  ├── sdk_configurations.staging.yaml # Staging overrides
  └── sdk_configurations.prod.yaml    # Production overrides

Load specific environment:

final sdk = await AgentSDK.initialize(
  environment: 'prod',  // Loads sdk_configurations.prod.yaml
);

Configuration Sections

Section	Description
`connection`	Project ID, API key, endpoint
`websocket`	Reconnection settings, idle disconnect
`voice`	Voice mode, barge-in, sample rate
`chat`	File upload, typing indicators, history
`storage`	Message cache, offline queue
`theme`	Colors, fonts, border radius
`debug`	Logging levels, request logging
`features`	Feature flags for all capabilities
`security`	TLS enforcement, certificate pinning

See example/assets/sdk_configurations.yaml for complete configuration.

API Reference

AgentSDK

Main SDK entry point.

// Initialize
final sdk = await AgentSDK.initialize();

// Connect
await sdk.connect();

// Send message
await sdk.sendMessage('Hello!');

// Get messages
final messages = sdk.getMessages();

// Clear history
sdk.clearHistory();

// Check connection
final isConnected = sdk.isConnected();

// Get session ID
final sessionId = sdk.getSessionId();

// Disconnect
sdk.disconnect();

// Dispose
await sdk.dispose();

Events

Listen to SDK and chat events:

// SDK events
sdk.events.listen((event) {
  if (event is SDKConnectedEvent) {
    print('Connected: ${event.sessionId}');
  } else if (event is SDKDisconnectedEvent) {
    print('Disconnected: ${event.reason}');
  } else if (event is SDKErrorEvent) {
    print('Error: ${event.error}');
  }
});

// Chat events
sdk.chatEvents.listen((event) {
  if (event is MessageReceivedEvent) {
    print('Message: ${event.message.content}');
  } else if (event is TypingIndicatorEvent) {
    print('Typing: ${event.isTyping}');
  }
});

Configuration Access

Access loaded configuration:

final config = sdk.config;

print('Environment: ${config.environment}');
print('Endpoint: ${config.connection.endpoint}');
print('Voice enabled: ${config.features.enableVoice}');
print('Debug mode: ${config.debug.enabled}');

Example App

Run the example app to see the SDK in action:

cd example
flutter run

The example demonstrates:

SDK initialization and connection
Sending and receiving messages
Event handling
Configuration display
UI integration

Architecture

The SDK follows a three-layer architecture:

┌─────────────────────────────────────┐
│  Host Application                    │
│  ├─ assets/sdk_configurations.yaml  │
│  └─ main.dart (SDK initialization)  │
└──────────────┬──────────────────────┘
               │
    ┌──────────┴──────────┐
    │ Artemis Flutter SDK  │
    │                      │
    │  Configuration Layer │
    │  ├─ sdk_configuration.dart
    │  └─ sdk_configuration_loader.dart
    │                      │
    │  Core SDK Layer      │
    │  ├─ agent_sdk.dart   │
    │  ├─ models/          │
    │  ├─ events/          │
    │  └─ utils/           │
    │                      │
    │  Platform Layer      │
    │  ├─ iOS (Swift)      │
    │  └─ Android (Kotlin) │
    └──────────────────────┘

Development

Setup

# Get dependencies
flutter pub get

# Run analysis
flutter analyze

# Run tests
flutter test

# Generate documentation
dart doc .

Adding Features

Add configuration options to sdk_configuration.dart
Update sdk_configuration_loader.dart validation
Implement feature logic in appropriate module
Add events if needed
Update example app to demonstrate feature
Add tests

Testing

# Run all tests
flutter test

# Run with coverage
flutter test --coverage

# Run example app tests
cd example
flutter test

Platform Support

Platform	Version
iOS	12.0+
Android	API 21+ (Android 5.0)

Requirements

Dart SDK: >=3.11.4 <4.0.0
Flutter: >=3.41.6

Documentation

CLAUDE.md - Development guide for AI assistants
example/ - Full working example
API Documentation - Generated docs

Troubleshooting

Configuration not loading

Verify file exists in assets/ folder
Check it's added to pubspec.yaml under flutter.assets
Run flutter clean and rebuild
Validate YAML syntax

Connection fails

Verify endpoint is reachable
Check project_id and api_key are correct
Enable debug logging: debug.enabled: true
Check SDK logs for detailed errors

Build errors

Run flutter clean
Run flutter pub get
Check Flutter version matches requirements

License

Add your license here

Support

For issues and questions:

GitHub Issues: your-repo-url
Documentation: your-docs-url
Email: your-email

Roadmap

Voice interaction support
Rich content rendering
File upload support
Offline message queue
Push notifications
WebRTC audio
Multi-session management

Contributing

Contributions are welcome! Please read CONTRIBUTING.md for details.

Acknowledgments

Built for the Artemis by Your Team