Artemis UI Plugin

artemis_ui_plugin is a Flutter plugin for adding a configurable AI agent chat experience to iOS and Android applications.

What this plugin contains

The plugin provides:

A full-screen chat screen and the AgentChatUI.open integration API.
Connection status, message history, typing indicators, and offline connectivity handling.
Markdown and rich-content rendering, including forms, tables, carousels, images, audio, video, files, quick replies, KPI cards, and feedback actions.
YAML-based and programmatic configuration.
Environment-specific configuration overrides.
Custom chat headers, footers, fonts, themes, and rich-content templates.

The plugin manages the chat connection internally. An application only needs to add artemis_ui_plugin; it does not need to add or configure the underlying transport dependency separately.

Requirements

Flutter 3.41.6 or later
Dart 3.11.4 or later
iOS 13 or later
An Android project supported by the installed Flutter toolchain

Installation

Add the dependency to the application pubspec.yaml:
```
dependencies:
  artemis_ui_plugin: ^1.0.0
```
Install the dependency:
```
flutter pub get
```

Import the plugin in the Dart file that opens the chat:

import 'package:artemis_ui_plugin/artemis_ui_plugin.dart';

Integration with inline configuration

Use SDKConfigurationLoader.createDefault when the application supplies configuration in code:

import 'package:artemis_ui_plugin/artemis_ui_plugin.dart';
import 'package:flutter/material.dart';

class OpenChatButton extends StatelessWidget {
  const OpenChatButton({super.key});

  @override
  Widget build(BuildContext context) {
    return ElevatedButton(
      onPressed: () {
        AgentChatUI.open(
          context,
          configuration: SDKConfigurationLoader.createDefault(
            projectId: 'your-project-id',
            endpoint: 'https://your-runtime-endpoint.example.com',
            apiKey: 'your-api-key',
            channelId: 'your-channel-id',
          ),
          title: 'Agent Chat',
        );
      },
      child: const Text('Open chat'),
    );
  }
}

AgentChatUI.open must be called with a BuildContext below a MaterialApp or another application-level Navigator.

Integration with YAML configuration

Use YAML when configuration should be separated from the Dart integration code.

Create assets/sdk_configurations.yaml in the host application:

artemis_ui_plugin:
  environment: dev
  connection:
    project_id: "your-project-id"
    api_key: "your-api-key"
    endpoint: "https://your-runtime-endpoint.example.com"
  channel:
    channel_id: "your-channel-id"
    channel_name: "Your channel"

flutter:
  assets:
    - assets/sdk_configurations.yaml

Run flutter pub get and open the chat without passing a configuration:
```
AgentChatUI.open(
  context,
  title: 'Agent Chat',
);
```

The loader supports sdk_configurations.dev.yaml, sdk_configurations.staging.yaml, and sdk_configurations.prod.yaml override files. Select an environment with AgentChatUI.open(context, environment: 'staging').

Configuration fields

The following fields are used under artemis_ui_plugin. The loader requires the project ID, endpoint, and either an API key or a bootstrap token. The channel ID should be supplied when required by the configured agent runtime:

Field	Description
`connection.project_id`	The AI agent project identifier.
`connection.endpoint`	The runtime HTTP or HTTPS endpoint. Production configurations should use HTTPS.
`connection.api_key`	The API key, unless a bootstrap token is used instead.
`connection.bootstrap_token`	An alternative to `connection.api_key` for verified-user flows.
`channel.channel_id`	The channel identifier used by the agent runtime.

Do not configure both connection.api_key and connection.bootstrap_token in the same configuration.

The complete set of optional connection, chat, voice, storage, theme, accessibility, feature, and security settings is shown in example/assets/sdk_configurations.yaml.

Customization

The chat UI accepts optional builders, templates, and fonts:

AgentChatUI.open(
  context,
  configuration: configuration,
  title: 'Support',
  headerBuilder: buildCustomChatHeader(),
  footerBuilder: buildCustomChatFooter(),
  templateRegistry: buildCustomTemplateRegistry(),
  fonts: const ChatFonts(family: 'YourFont'),
);

The plugin also exports AgentChatScreen, theme classes, rich-content models, and template helpers for applications that need more control over the UI.

Example application

The package includes a complete example application in the example directory.

Run it with:

cd example
flutter pub get
flutter run

Before connecting, replace the placeholder values in example/lib/main.dart or example/assets/sdk_configurations.yaml with valid project configuration.

Security

Do not commit production API keys or bootstrap tokens to source control. Use a secure runtime configuration mechanism for production applications. The credentials in the example application are placeholders.

License

MIT. See LICENSE.