In this tutorial we are going to build a Laravel application using the new OpenAI Assistants API.
The goal of the application is to build a tool which answers questions about the Pest Testing framework based on the current state of the Pest documentation.
One of the benefits of using the Assistants API is that you can provide data which is then used by the AI. This way we can provide the latest version of the documentation instead of only using the outdated knowledge of the base model.
To achieve our goal we are going to use the OpenAI PHP Client for Laravel developed by me and Nuno Maduro.
If you are using any other PHP framework you can use the underlying OpenAI PHP Client directly.
All the source for this tutorial is available at GitHub.
API overview / what to do
If you are not familiar with the Assistants API yet, here is a brief overview of the API and what we need to do in order to achieve our goal.
The basic structur of the Assistants API is as follows:
- Assistants are the main resource. There we can attach files and tools the AI can use to answer questions. In our case we are going to attach the Pest docs.
- Threads contain the actual questions and answers. We can create multiple threads for the same assistant. You can think of a thread as a conversation between a user and the AI.
- Messages are either a user input / question or an answer from the AI.
- Runs are the requests to start the AI work after a thread has been created and optionally a user message has been added. Unlike the Chat API, we do not get the answer directly. Instead, we get a run id which we can use to get the result later on.
- Steps represent the progress of the AI. We can use them to get the current state of the AI. This is useful if we want to show the progress to the user or for debugging purposes. We are not going to use them in this tutorial.
For more in-depth information visit the OpenAI documentation.
Prerequisites
If you want to follow along you need to have an OpenAI account and an API key. You can create an account at https://openai.com/.
Create a new Laravel application and install the OpenAI PHP Client
We start by creating a new application using the Laravel installer.
laravel new pest-docs-bot
Next we install the OpenAI PHP Client for Laravel.
Note: You need to install the latest (beta) version of the package.
composer require openai-php/laravel:^0.8.0-beta.2`
Prepare the Pest docs
Before we can upload the documents to OpenAI, we have to prepare them, as the documentation consists of several files and OpenAI has a limit of 20 files per assistant.
Therefore, we will merge all doc files into a single file. Furthermore, we are going to exclude some files as they do not contain any useful information for our goal.
First we create a new command.
php artisan make:command PrepareDocs
We are fetching a list of all the files in the PestDoc repository using the GitHub REST API.
Then we are looping through all the files and filter out files which do not have a download url or the ones we want to exclude.
Finally, we retrieve the contents of the individual files and merge them into a single file. Then we save the file locally.
<?php
namespace App\Console\Commands;
use Illuminate\Console\Command;
use Illuminate\Support\Facades\Http;
use Illuminate\Support\Facades\Storage;
class PrepareDocs extends Command
{
private static array $FILES_TO_IGNORE = [
'LICENSE.md',
'README.md',
'announcing-pest2.md',
'documentation.md',
'pest-spicy-summer-release.md',
'video-resources.md',
'why-pest.md',
];
protected $signature = 'app:prepare-docs';
protected $description = 'Create one file containing the full Pest documentation';
public function handle()
{
$files = Http::get('https://api.github.com/repos/pestphp/docs/contents')->collect();
$fullDocs = $files->filter(fn (array $file) => $file['download_url'] !== null)
->filter(fn (array $file) => ! in_array($file['name'], self::$FILES_TO_IGNORE))
->map(fn (array $file) => Http::get($file['download_url'])->body())
->implode(PHP_EOL.PHP_EOL);
Storage::disk('local')->put('full-pest-docs.md', $fullDocs);
}
}
Upload the docs to OpenAI
Now we are ready to upload the docs to OpenAI. We are going to use the upload()
method of the Files
resource in a new UploadDocs
command.
The file to upload has to be a resource stream. Therefore, we are using the readStream()
method of the Storage
facade.
As purpose
we are using assistants
as we want to use the file for an assistant.
As a result we get a File
object which contains the id
of the uploaded file. We are going to use this id later on when we create the assistant.
I would suggest to store this id
somewhere in your application, for example in a AssistantFile
model to keep track of your uploaded files.
For simplicity we are here just going to output the id
to the console.
<?php
namespace App\Console\Commands;
use Illuminate\Console\Command;
use Illuminate\Support\Facades\Storage;
use OpenAI\Laravel\Facades\OpenAI;
class UploadDocs extends Command
{
protected $signature = 'upload-docs';
protected $description = 'Uploads the docs to OpenAI';
public function handle()
{
$uploadedFile = OpenAI::files()->upload([
'file' => Storage::disk('local')->readStream('full-pest-docs.md'),
'purpose' => 'assistants',
]);
$this->info('File ID: '.$uploadedFile->id);
}
}
Then we run the command:
Create the assistant
Now we need to create the assistant. We are going to use the create()
method of the Assistants
resource in a new CreateAssistant
command.
We are giving the assistant a name
, pass the id of the uploaded
file from before and add the retrieval
tool.
The Knowledge Retrieval tool is used to extract information from the uploaded file. For more information about the tool visit the OpenAI documentation.
Next we instruct
the AI to use the uploaded file to answer questions. And set the model to gpt-4-1106-preview
.
Note: The regular gpt-4
model does not work with the retrieval
tool.
Finally, we output the id
of the created assistant
to use it later.
namespace App\Console\Commands;
use Illuminate\Console\Command;
use OpenAI\Laravel\Facades\OpenAI;
class CreateAssistant extends Command
{
protected $signature = 'create-assistant {file_id}';
protected $description = 'Creates the PestDocs assistant.';
public function handle()
{
$assistant = OpenAI::assistants()->create([
'name' => 'Pest Chat Bot',
'file_ids' => [
$this->argument('file_id'),
],
'tools' => [
[
'type' => 'retrieval',
],
],
'instructions' => 'Your are a helpful bot supporting developers using the Pest Testing Framework.
You can answer questions about the framework, and help them find the right documentation.
Use the uploaded files to answer questions.',
'model' => 'gpt-4-1106-preview',
]);
$this->info('Assistant ID: '.$assistant->id);
}
}
Then we run the command:
Create the interface
Now we are ready to create the interface. We are going to use the Livewire package to create a simple interface.
First we install livewire.
composer require livewire/livewire
Then we create a new Livewire component and a layout file.
php artisan make:livewire DocBot
php artisan livewire:layout
In our routes file routes/web.php
we are registering the home route to the DocBot
component.
Route::get('/', \App\Livewire\DocBot::class);
To style the component we are using Tailwind CSS with the Forms and Typography plugins.
All installation instructions can be found in the docs.
We are going to create a simple interface where the user can enter a question and the AI will answer it.
Because this tutorial isn’t about Livewire, here a brief list of the relevant parts:
-
wire:model
directive to bind the input field to the $question
property.
-
wire:submit.prevent
directive to call the ask()
method on form submit.
-
wire:loading
directive to show a spinner while the AI is working.
- When the AI has finished its work, we render the answer which comes as markdown with Spatie’s
spatie/laravel-markdown
library.
This is what the blade part of the component does look like. All the classes have been removed to keep it simple. You can find the full code at GitHub.
<div>
<div>
<h3>PEST Documentation Assistant</h3>
<div>
<p>Enter you question, and I will try to find an answer in the current Pest documentation.</p>
</div>
<form wire:submit.prevent="ask">
<div>
<label for="question">Question</label>
<input type="text"
name="question"
wire:model="question"
placeholder="How to run a single test?"
>
</div>
<button type="submit">
<span wire:loading.class="invisible">Ask</span>
<x-spinner class="absolute invisible" wire:loading.class.remove="invisible" />
</button>
</form>
@if($answer)
<h3 class="mt-8 mb-1 text-base font-semibold leading-6 text-gray-900">My answer</h3>
<div class="mb-2 prose">
<x-markdown>{!! $answer !!}</x-markdown>
</div>
@endif
</div>
</div>
This gives us the following interface:
Ask the AI
In the class part of the Livewire component we have two properties to store the user question
and the AI answer
and one more to store the error
if necessary.
The ask()
function is executed when the user submits the form. For now, it is empty. We are going to fill it in the next step.
<?php
namespace App\Livewire;
use Livewire\Component;
use OpenAI\Laravel\Facades\OpenAI;
use OpenAI\Responses\Threads\Runs\ThreadRunResponse;
class DocBot extends Component
{
public string $question = '';
public ?string $answer = null;
public ?string $erro = null;
public function ask()
{
// ...
}
public function render()
{
return view('livewire.doc-bot');
}
}
When the user submits a question the ask()
function does two things.
First it creates a new Thread and runs it, and then it loads the answer from the given run.
public function ask()
{
$threadRun = $this->createAndRunThread();
$this->loadAnswer($threadRun);
}
Create a new Thread and run it
Let’s start with the createAndRunThread()
function. We are going to use the createAndRun()
method of the Threads
resource.
This endpoint allows us to create a new thread and run it in a single request. As an alternative we could also create a thread first and then run it in a next step. This is handy you want to prepare the thread synchronously but execute the run asynchronously.
We are passing the id
of the assistant we created before and the question
the user entered as the only message
in the thread.
private function createAndRunThread(): ThreadRunResponse
{
return OpenAI::threads()->createAndRun([
'assistant_id' => 'asst_6VzQhp0uC0ZouIRJlxhfxI0a',
'thread' => [
'messages' => [
[
'role' => 'user',
'content' => $this->question,
],
],
],
]);
}
As a result we get a ThreadRunResponse
object which contains the ids
of the thread
and the run
. Besides that it has other properties like the status
of the run
.
At this point the status
is always queued
as the AI has not processed the thread
yet.
Currently, there is no way yet to get the answer directly. Additionally, it is not possible to stream the request unlike the Chat API.
The only thing we can do is to periodically check the status of the run and wait until it is done.
OpenAI already announced that they are working on a streaming and notification options. So, this will change in the future.
Load the answer
Now we are going to implement the loadAnswer()
function. We are going to use the retrieve()
method of the ThreadsRuns
resource to get the updated status of the run
.
In a while loop we are fetching the run
until the status
is not queued
or in_progress
anymore.
Then we check if the run
has terminated successfully. If not, we set the error
message, which by the way is not handled in the GUI for simplicity.
When the run
has completed successfully we are going to fetch the messages
of the thread
. The AI has added the result of the run
as a new message.
Because new messages are added at the beginning of the list, we can access the answer
at index 0
.
Each message
contains an array of content
objects. These are either text
or image
objects. In our case there is always only one text object
.
This text object
has a text
property which has a property value
containing the actual answer
we are interested in.
So, we are going to store this value in the $answer
property of the component.
private function loadAnswer(ThreadRunResponse $threadRun)
{
while(in_array($threadRun->status, ['queued', 'in_progress'])) {
$threadRun = OpenAI::threads()->runs()->retrieve(
threadId: $threadRun->threadId,
runId: $threadRun->id,
);
}
if ($threadRun->status !== 'completed') {
$this->error = 'Request failed, please try again';
}
$messageList = OpenAI::threads()->messages()->list(
threadId: $threadRun->threadId,
);
$this->answer = $messageList->data[0]->content[0]->text->value;
}
Using the bot
That’s all we have to do. Now we can ask the AI questions about the Pest documentation and see the result.
Regular ChatGTP models are currently not able to answer this question correctly because throwsUnless
has been added to Pest after the models have been trained.
Conclusion
In this tutorial we have seen how to use the new OpenAI Assistants API in a Laravel application.
We have seen how to upload files, create an assistant, create a thread and run it, and how to get the result.
Of course there is a lot more you can do with the Assistants API. For example, you can use the AI to analyse your data and draw a graph or extend the capabilities of the AI by giving it access to your software through tools
.
If you want to learn more about the Assistants API visit the OpenAI documentation.
Additionally, we did not cover topics like error handling or testing. You can learn more about this in the PHP Client documentation.
I would love to hear your feedback. You can reach me on X / Twitter or by using the contact form.
If you like this tutorial I wouldn’t mind if you share it with your friends and colleagues. Thank you!