README

The Assistant Engine for Filament makes it easy to add conversational AI capabilities directly into Laravel Filament projects. It includes a chat sidebar, a chat modal, and interactive buttons that enhance user interaction by offering AI support within the Filament panel.

Requirements

PHP 8.2 or higher
Composer
Filament (See Filament Installation Guide)
Filament Custom Theme (See Installation Guide)
OpenAI API Key (See OpenAI Documentation)
Assistant Engine API Key (See Assistant Engine Documentation)

Important Notice: Both an OpenAI API key and an Assistant Engine API key are required to use this package. Ensure these keys are configured correctly by following the respective documentation linked above.

Documentation

The official documentation for the Assistant Engine can be found here. Learn more about assistants, tasks, tools, and how to connect other third-party APIs.

Installation

You can install the Assistant Engine for Filament via Composer:

composer require assistant-engine/filament-assistant

Then, publish the configuration file using the command below:

php artisan filament-assistant:publish-config

After you installed the Plugin follow the instructions to create a custom theme and add the following lines to your new theme tailwind.config.js:

// resources/css/filament/admin(theme name)/tailwind.config.js
export default {
    content: [
        './vendor/assistant-engine/filament-assistant/resources/**/*.blade.php',
        './vendor/assistant-engine/laravel-assistant/resources/**/*.blade.php',
    ]
};

Run the following command for development:

npm run dev

Configuration

After publishing the configuration, you can find it in config/assistant-engine.php. Customize it to set your API keys and other settings.

return [
    'api-url' => env('ASSISTANT_ENGINE_API', 'https://api.assistant-engine.com/v1/'),
    'api-key' => env('ASSISTANT_ENGINE_TOKEN'),
    'llm-provider-key' => env('OPENAI_API_KEY'),

    "chat" => [
        "render-assistant-message-as-markdown" => true,

        "disable-assistant-icon" => false,
        "disable-user-input" => false,

        "open-ai-recorder" => [
            "activate" => true,
            "open-ai-key" => env('OPENAI_API_KEY'),
            "language" => "en"
        ]
    ],
    'filament' => [
        'assistant-button' => [
            'show' => true,
            'trigger' => \AssistantEngine\Filament\Components\AssistantButton::ASSISTANT_BUTTON_TRIGGER_MODAL,
            'options' => [
                'label' => 'Call Assistant',
                'size' => \Filament\Support\Enums\ActionSize::ExtraLarge,
                'color' => \Filament\Support\Colors\Color::Sky,
                'icon' => 'heroicon-o-academic-cap'
            ]
        ],

        'assistant-sidebar' => [
            'render' => false,
            'show-without-trigger' => false
        ],

        'assistant-modal' => [
            'show-tabs' => false,
            'max-visible-tabs' => 7,
            'show-page-component' => false,
            'auto-height' => true,
            'slide-over' => true,
            'heading' => 'Your AI Assistant',
            'max-width' => \Filament\Support\Enums\MaxWidth::ExtraLarge
        ]
    ]

];

Configuration Fields Description

chat
- render-assistant-message-as-markdown: Set to true to automatically format assistant messages as markdown.
- disable-assistant-icon: Defines if the assistant icon should be shown or not.
- disable-user-input: Set to true to only display the conversation history without allowing user input.
- open-ai-recorder: If activated, the transcribe button will be available to record and transcribe audio directly with OpenAI, requiring an OpenAI key.
filament
- assistant-button
  - show: Defines whether the assistant button should be displayed.
  - trigger: Sets the trigger mechanism for the assistant button (e.g., opening a sidebar).
  - options: Configurable options for the assistant button, such as label, size, color, and icon.
    - label: The text displayed on the button.
    - size: The size of the button, e.g., 'md', 'lg'.
    - color: The color of the button.
    - icon: The icon used for the button.
- assistant-sidebar
  - render: Whether the assistant sidebar should be rendered.
  - show-without-trigger: Defines if the sidebar should be displayed without the need for a trigger.
- assistant-modal
  - show-tabs: Enables or disables tab display in the assistant modal.
  - max-visible-tabs: Sets the maximum number of tabs visible in the modal.
  - show-page-component: Determines whether the page component should be displayed within the modal.
  - auto-height: Automatically adjusts the modal height based on content.
  - slide-over: Sets whether the modal should slide over the current page.
  - heading: The heading text for the modal.
  - max-width: The maximum width of the modal.

Example `.env` File

Add the following environment variables to your .env file to configure the Assistant Engine:

ASSISTANT_ENGINE_API=https://api.assistant-engine.com/v1/
ASSISTANT_ENGINE_TOKEN=your_assistant_engine_api_key
OPENAI_API_KEY=your_openai_api_key

Usage

When you successfully install the plugin and configure it to show the assistant button, you may notice that the assistant button does not appear. This is because additional configuration is needed to connect your resources and pages with an assistant.

To achieve this, two traits are provided to help you: AssistedResource and HasAssistant. These traits are used to establish the link between your resources or pages and the Assistant Engine. We will now dive into these traits in more detail.

Assisted Resources and Pages with Assistants

AssistedResource Trait

The AssistedResource trait is designed for Filament resource classes, and it requires an implementation of an abstract method called assistant(). This method returns a ConversationOption object, which is used to configure the assistant chat.

Here's a simple example of how to use the AssistedResource trait in a Filament resource:

<?php

namespace App\Filament\Resources;

use AssistantEngine\Filament\Traits\AssistedResource;
use AssistantEngine\SDK\Models\Options\ConversationOption;
use Filament\Resources\Resource;
use Filament\Pages\Page;

class ExampleResource extends Resource
{
    use AssistedResource;

    public static function assistant(Page $page): ConversationOption
    {
        return new ConversationOption('example_assistant_key');
    }
}

In this example, the assistant() method simply creates a new ConversationOption instance with an assistant key. This option is then used by the system to configure the conversation.

ConversationOption Object

The ConversationOption object allows you to configure how a conversation is created or retrieved. The available fields include:

use AssistantEngine\SDK\Models\Options\ConversationOption;

// Create a new ConversationOption
$options = new ConversationOption('assistant_key', [
    'user_id' => 'user123',
    'subject_id' => 'subject456',
    'title' => 'New Conversation',
    'context' => ['topic' => 'tech support'],
    'additional_data' => ['foo' => 'bar'],
    'recreate' => true,
]);

assistant_key (required): Unique key identifying the assistant.
user_id (required): ID of the user associated with the conversation, allowing multiple users to have different conversations with the same assistant.
subject_id (optional): ID of a specific subject, enabling a user to have separate conversations with the assistant about different topics.
title (optional): Title of the conversation, used solely for client purposes.
context (optional): Arbitrary data to provide context to the conversation. This context is included with the conversation data sent to the LLM.
additional_data (optional): Data intended for the front-end or client application, allowing additional operations based on its content.
recreate (optional): If set to true, recreates the conversation, deactivating the previous one.

Note: The Assistant Engine will attempt to locate an existing conversation based on the combination of assistant_key, user_id, and subject_id. If a match is found, that conversation will be retrieved; otherwise, a new one will be created.

HasAssistant Trait

The HasAssistant trait is intended for Filament pages. This trait is responsible for caching the modal action and listening to the OpenModal event. If you have configured the plugin to use a modal, the HasAssistant trait is responsible for receiving the event and displaying the modal. It also provides methods to configure your pages and adapt the conversation based on page configuration.

Configuration Possibilities with `HasAssistant` Trait

getAssistantSubjectKey(): Retrieves the assistant subject key associated with this instance. By default, this method returns null, but you can override it in subclasses to provide a specific subject key. This key uniquely identifies the subject within the assistant context, allowing for more personalized interactions.
```
public function getAssistantSubjectKey(): ?string
{
    return 'unique_subject_key';
}
```
getAssistantPageDescription(): Adds a page description to the conversation context. By default, it returns null. You can override this method to provide additional descriptive information about the page that will be included in the assistant's context.
```
public function getAssistantPageDescription(): ?string
{
    return 'This is a description of the current page.';
}
```
getAdditionalAssistantContextModels(): Adds additional models to the assistant context for processing. Each model must use the AssistantContext trait. The input array should be structured as follows:
```
[
    'ClassName' => [$models],
    // ...
]
```
Where 'ClassName' is the fully qualified class name of the model, and [$models] is an array of model instances of that class.
```
public function getAdditionalAssistantContextModels()
{
    return [
        \App\Models\Order::class => [\App\Models\Order::find(1)],
    ];
}
```
This method allows you to provide additional context that the assistant can use to enhance the conversation.

One more thing

We’ve created more repositories to make working with the Assistant Engine even easier! Check them out:

PHP SDK: The PHP SDK provides a convenient way to interact with the Assistant Engine API, allowing developers to create and manage conversations, tasks, and messages.
Laravel Assistant: The Laravel integration for adding conversational AI capabilities in your Laravel applications.

We are a young startup aiming to make it easy for developers to add AI to their applications. We welcome feedback, questions, comments, and contributions. Feel free to contact us at contact@assistant-engine.com.

Contributing

We welcome contributions from the community! Feel free to submit pull requests, open issues, and help us improve the package.

License

This project is licensed under the MIT License. Please see License File for more information.

assistant-engine / filament-assistant

Maintainers

Details

README

Requirements

Documentation

Installation

Configuration

Configuration Fields Description

Example `.env` File

Usage

Assisted Resources and Pages with Assistants

AssistedResource Trait

ConversationOption Object

HasAssistant Trait

Configuration Possibilities with `HasAssistant` Trait

One more thing

Contributing

License

assistant-engine / filament-assistant

Maintainers

Details

README

Requirements

Documentation

Installation

Configuration

Configuration Fields Description

Example .env File

Usage

Assisted Resources and Pages with Assistants

AssistedResource Trait

ConversationOption Object

HasAssistant Trait

Configuration Possibilities with HasAssistant Trait

One more thing

Contributing

License

Example `.env` File

Configuration Possibilities with `HasAssistant` Trait