Usage
Basic usage
This is a simple example demonstrating how Instructor retrieves structured information from provided text (or chat message sequence).
Response model class is a plain PHP class with typehints specifying the types of fields of the object.
NOTE: By default, Instructor looks for OPENAI_API_KEY environment variable to get your API key. You can also provide the API key explicitly when creating the Instructor instance.
<?php
use Cognesy\Instructor\Instructor;
// Step 0: Create .env file in your project root:
// OPENAI_API_KEY=your_api_key
// Step 1: Define target data structure(s)
class Person {
public string $name;
public int $age;
}
// Step 2: Provide content to process
$text = "His name is Jason and he is 28 years old.";
// Step 3: Use Instructor to run LLM inference
$person = (new Instructor)->respond(
messages: [['role' => 'user', 'content' => $text]],
responseModel: Person::class,
);
// Step 4: Work with structured response data
assert($person instanceof Person); // true
assert($person->name === 'Jason'); // true
assert($person->age === 28); // true
echo $person->name; // Jason
echo $person->age; // 28
var_dump($person);
// Person {
// name: "Jason",
// age: 28
// }
?>
!!! note
Currently, Instructor for PHP only supports classes / objects as response models. In case you want to extract simple types or arrays, you need to wrap them in a class (or use Scalar
helper class).
String as Input
You can provide a string instead of an array of messages. This is useful when you want to extract data from a single block of text and want to keep your code simple.
<?php
use Cognesy\Instructor\Instructor;
$value = (new Instructor)->respond(
messages: "His name is Jason, he is 28 years old.",
responseModel: Person::class,
);
?>
Alternative way to get results
You can call request()
method to initiate Instructor with request data
and then call get()
to get the response.
<?php
use Cognesy\Instructor\Instructor;
$instructor = (new Instructor)->request(
messages: "His name is Jason, he is 28 years old.",
responseModel: Person::class,
);
$person = $instructor->get();
?>
Structured-to-structured data processing
Instructor offers a way to use structured data as an input. This is useful when you want to use object data as input and get another object with a result of LLM inference.
The input
field of Instructor’s respond()
and request()
methods
can be an object, but also an array or just a string.
<?php
use Cognesy\Instructor\Instructor;
class Email {
public function __construct(
public string $address = '',
public string $subject = '',
public string $body = '',
) {}
}
$email = new Email(
address: 'joe@gmail',
subject: 'Status update',
body: 'Your account has been updated.'
);
$translation = (new Instructor)->respond(
input: $email,
responseModel: Email::class,
prompt: 'Translate the text fields of email to Spanish. Keep other fields unchanged.',
);
?>
Streaming support
Instructor supports streaming of partial results, allowing you to start processing the data as soon as it is available.
<?php
use Cognesy\Instructor\Instructor;
$stream = (new Instructor)->request(
messages: "His name is Jason, he is 28 years old.",
responseModel: Person::class,
options: ['stream' => true]
)->stream();
foreach ($stream->partials() as $partialPerson) {
// process partial person data
echo "Name: " $partialPerson->name ?? '...';
echo "Age: " $partialPerson->age ?? '...';
}
// after streaming is done you can get the final, fully processed person object...
$person = $stream->getLastUpdate()
// ...to, for example, save it to the database
$db->save($person);
?>
Scalar responses
See Scalar responses for more information on how to generate scalar responses with Scalar
adapter class.
Partial responses and streaming
See Streaming and partial updates for more information on how to work with partial updates and streaming.
Extracting arguments for function call
See FunctionCall helper class for more information on how to extract arguments for callable objects.