Download the PHP package assistant-engine/filament-assistant without Composer

Assistant Engine for Filament

The Assistant Engine for Filament makes it easy to add conversational AI capabilities directly into Laravel Filament projects. It includes a chat sidebar, context resolver, connection to 3rd party tools and the possibility to create 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:

Then, publish the configuration file using the command below:

After installing the plugin, follow the instructions to create a custom theme and add the following lines to your new theme's tailwind.config.js:

As well as enabling the plugin within your panel:

Run the following command for development:

Configuration

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

The chat configuration section is identical to the description provided in the Laravel Assistant repository. Refer to it for more detailed information.

Configuration Fields Description

Filament Assistant Configuration

• button: Controls whether the assistant button is shown in the bottom right corner.

  • show: Boolean that determines if the assistant button is displayed.
  • options: Customization options for the button.
    • label: The label text displayed on the button.
    • size: The size of the button, e.g., ExtraLarge.
    • color: The color of the button, e.g., Sky.
    • icon: The icon displayed on the button.

• conversation-option: Configures conversation behavior.

  • assistant-key: The key for the assistant, which the user must create in the Assistant Engine.
  • conversation-resolver: Class responsible for resolving the conversation option based on defined rules.
  • context-resolver: Resolves context models automatically.
• sidebar: Configures the sidebar that displays the assistant conversation.
  • render: Boolean that controls whether the sidebar is rendered.
  • width: The width of the sidebar in pixels.
  • show-without-trigger: Boolean that controls whether the sidebar is automatically shown when a conversation option is available.

Example .env File

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

Usage

After you installed the plugin and logged into your filament panel you will have the assistant button available at the bottom of the page:

Conversation Option Resolver

The Conversation Option Resolver is used to determine which conversation option should be used when initializing the assistant. It allows you to implement custom logic based on the current page or other factors to control whether an assistant should be displayed and how it should behave.

You can create a custom conversation option resolver by implementing the ConversationOptionResolverInterface. This gives you complete control over the behavior, including the ability to determine whether to return a conversation option or not. If you return null, no conversation or assistant will be shown on the page.

Example of the built-in Conversation Option Resolver:

You can also customize the resolver logic to adapt to different pages or user roles, providing a tailored conversational experience by extending the built-in ConversationOptionResolver or implement the interface on your own.

ConversationOption Object

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

• assistant_key (required): Unique key identifying the assistant.
• user_id (optional): 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.

Context Resolver

The Context Resolver is responsible for resolving context models that are visible on the page and providing them to the assistant. This helps the assistant understand the context of the current page and allows it to access relevant information during the conversation.

The default Context Resolver (ContextResolver) tries to collect models related to the page, such as records or list items, and injects them into the context of the ConversationOption object.

Example of a Context Resolver:

The Context Resolver automatically gathers information about the page and its related models, enabling the assistant to leverage this information during a conversation.

Custom Context Resolvers

Sometimes you have pages which are fully custom, and where the standard Context Resolver doesn't get all the models visible to the customer. In this case, you can either implement your own Context Resolver based on the interface, or you can extend it, like in the example below, to add more context. You can extend the Context Resolver and, based on different pages, inject other contexts, like models or the description of the page, to give the LLM even more context about what the user is seeing right now.

Example of a Custom Context Resolver:

Custom Model Serialization

The standard resolving mechanism for models is to transform them to arrays. But sometimes you want to have a different model serialization. Maybe you want to hide properties or give the LLM a little bit more context regarding the models it sees. Therefore, another interface exists called Context Model Interface, which defines a static function resolveModels that you can implement and use to resolve a list of models of the same type.

There is also a trait implementing this interface called Context Model, where you can group models from the same class inside a data object and provide the LLM with metadata as well as exclude properties from the model itself. This ensures that sensitive data is not sent to the LLM directly, but you can adjust it to your needs.

This Trait you can implement in your Model Classes and overwrite the defined methods if needed:

Tool Calling

Of course, there's also the flow backwards from the chat to your application, so that the assistant can access your application. All you need to do is expose an API, which can be defined or described by an OpenAPI schema, and create within the Assistant Engine a new tool, and connect your assistant to the tool. Then, the assistant can perform operations on this API (eg. CRUD).

After the message is processed, the page component automatically refreshes so that you can see what the assistant updated for you. If you want, you can also manually listen to the event; just implement a listener on and then you can process your custom logic.

You can also connect your assistant to other APIs and let the assistant perform tasks for you in other systems or third-party systems, which are also connected to the assistant with the tool. You can learn more about tool usage in the official documentation. You can also connect your local APIs via a tunnel, such as ngrok, to the Assistant Engine and work locally without the need of deploying an api.

Creating Buttons to Trigger an AI Task

You can also trigger an AI task with a Filament action. For example, if you want to generate a suggestion within a form, you can inject the AssistantEngine object directly and then trigger a task. It could be something like provide a suggestion, rework a text, or make sth. more concise — whatever task you have in mind. A task can also leverage tools.

Example:

This example demonstrates how you can provide an action to trigger an AI task, which interacts directly with the assistant engine to perform an operation based on the form data and return the result for further processing or to suggest updates directly to the user.

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 [email protected].

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.