Flutter Agent Pupau #

A Flutter plugin that integrates a Pupau agent in your application.

Features #

• AI-Powered Chat Interface - Full-featured chat UI with streaming responses
• Multiple Widget Modes - Full screen, sized container, or floating overlay
• Flexible Authentication - API key or bearer token authentication
• Event Streaming - Real-time events for conversation lifecycle
• Multi-language Support - Built-in support for 14 languages
• Programmatic Control - Open, reset, and load conversations via code

Installation #

Add this to your package's pubspec.yaml file:

dependencies:
  flutter_agent_pupau:
    git:
      url: https://github.com/gluelabs/flutter_agent_pupau.git

Then run:

flutter pub get

Usage #

1. Import the Package #

import 'package:flutter_agent_pupau/flutter_agent_pupau.dart';

Configuration #

Create a configuration using one of two authentication methods:

Option A: API Key Authentication #

The assistant ID is automatically extracted from the API key.

final config = PupauConfig.createWithApiKey(
  apiKey: 'your-api-key',
  // Optional parameters
  conversationId: 'existing-conversation-id',  // Load specific conversation
  isAnonymous: false,                          // Anonymous chat mode
  language: 'en',                              // UI language (en, es, fr, de, etc.)
  googleMapsApiKey: 'your-maps-key',           // For location features
  hideInputBox: false,                         // Hide the input field
  widgetMode: WidgetMode.full,                 // Display mode
  showNerdStats: false,                        // Show token/credit stats
  conversationStarters: [                      // Predefined starter messages
    'Tell me about your features',
    'How can you help me?',
  ],
  customProperties: {                          // Custom metadata
    'userId': '123',
    'source': 'mobile_app',
  },
);

Option B: Bearer Token Authentication #

Requires explicit assistant ID.

final config = PupauConfig.createWithToken(
  bearerToken: 'your-bearer-token',
  assistantId: 'your-assistant-id',
  isMarketplace: false,                        // Set to true if it's a Pupau marketplace agent
  // ... same optional parameters as above
);

Widget Avatar #

The PupauAgentAvatar widget is the main UI component that displays an avatar and handles chat interactions. It supports three display modes:

Full Screen Mode (Default) #

On tap it navigates to a full page that displays the chat.

PupauAgentAvatar(
  config: PupauConfig.createWithApiKey(
    apiKey: 'your-api-key',
    widgetMode: WidgetMode.full,
  ),
)

Sized Mode #

The avatar expands in-place to a specified width and height.

PupauAgentAvatar(
  config: PupauConfig.createWithApiKey(
    apiKey: 'your-api-key',
    widgetMode: WidgetMode.sized,
    sizedConfig: SizedConfig(
      width: 400,
      height: 600,
      initiallyExpanded: false, // Start collapsed
    ),
  ),
)

Floating Overlay Mode #

The chat appears as a floating overlay anchored to the avatar.

PupauAgentAvatar(
  config: PupauConfig.createWithApiKey(
    apiKey: 'your-api-key',
    widgetMode: WidgetMode.floating,
    floatingConfig: FloatingConfig(
      width: 400,
      height: 600,
      anchor: FloatingAnchor.bottomRight, // bottomRight, bottomLeft, topRight, topLeft
    ),
  ),
)

Initially Expanded Chat** #

If you want the chat to be already expanded when the widget first loads, use the sized mode with initiallyExpanded: true:

PupauAgentAvatar(
  config: PupauConfig.createWithApiKey(
    apiKey: 'your-api-key',
    widgetMode: WidgetMode.sized,
    sizedConfig: SizedConfig(
      width: 400,
      height: 600,
      initiallyExpanded: true, //Chat starts expanded!
    ),
  ),
)

Programmatic Control with PupauChatUtils #

Control the chat programmatically from anywhere in your app:

Open Chat from Code #

// Open chat with a button press
ElevatedButton(
  onPressed: () {
    PupauChatUtils.openChat(
      context,
      PupauConfig.createWithApiKey(apiKey: 'your-api-key'),
    );
  },
  child: Text('Open Chat'),
)

Reset Current Chat #

// Clear the current conversation and start fresh
await PupauChatUtils.resetChat();

Load Specific Conversation #

// Load a conversation by ID
await PupauChatUtils.loadConversation('conversation-id');

Event Streaming with PupauEventService #

Listen to real-time events from the chat interface:

Basic Event Listening #

import 'package:flutter_agent_pupau/flutter_agent_pupau.dart';

// Listen to all chat events
PupauEventService.pupauStream.listen((event) {
  print('Event Type: ${event.type}');
  print('Event Payload: ${event.payload}');
  
  switch (event.type) {
    case UpdateConversationType.newConversation:
      print('New conversation created: ${event.payload}');
      break;
    case UpdateConversationType.messageSent:
      print('Message sent: ${event.payload}');
      break;
    case UpdateConversationType.messageReceived:
      print('Message received: ${event.payload}');
      break;
    case UpdateConversationType.conversationChanged:
      print('Conversation changed to: ${event.payload}');
      break;
    case UpdateConversationType.error:
      print('Error occurred: ${event.payload}');
      break;
    // ... handle other events
  }
});

Event Types #

## Supported Languages

The plugin supports the following language codes for the `language` parameter:

- `en` - English (default)
- `de` - German
- `es` - Spanish
- `fr` - French
- `hi` - Hindi
- `it` - Italian
- `ko` - Korean
- `nl` - Dutch
- `pl` - Polish
- `pt` - Portuguese
- `sq` - Albanian
- `sv` - Swedish
- `tr` - Turkish
- `zh` - Chinese

## License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.