apie/ai-instructor

Use a LLM to create an object in PHP similar to Instructor in Python

1.0.0-RC2 2025-05-03 15:41 UTC

Requires

• php: >=8.3
• apie/core: 1.0.0-RC2
• apie/schema-generator: 1.0.0-RC2
• apie/serializer: 1.0.0-RC2
• devizzent/cebe-php-openapi: ^1.1.2
• symfony/http-client: ^7.2

Requires (Dev)

• illuminate/support: *
• phpspec/prophecy-phpunit: ^2.2
• phpunit/phpunit: ^11.5.2

MIT

• Pieter Jordaan

README

ai-instructor

This package is part of the Apie library. The code is maintained in a monorepo, so PR's need to be sent to the monorepo

Documentation

Instructor is a library for Python that works with LLM's to force a specific structure. Wouldn't it be nice if we have the same functionality in PHP? That's what apie/ai-instructor does. Like you have some class in PHP and ask AI to fill it in for you from a chat prompt given by the user:

class MovieReview {
    public function __construct(
        public string $name,
        public string $description,
        public int $rating
    ) {
    }
}

Requirements

You need a OpenAI key or a valid ollama service running (in Docker or locally).

Setup

The simplest standalone setup is using any of the static methods in AiInstructor:

use Apie\AiInstructor\AiInstructor;
// ollama
$instructor = AiInstructor::createForOllama('http://localhost:11434');
// openAI
$instructor = AiInstructor::createForOpenAi('api-key');
// custom:
$instructor = AiInstructor::createForCustomConfig(
    'api-key',
    'http://localhost:11434/'
);
$result = $instructor->instruct(
    MovieReview::class,
    'tinyllama',
    'You are an AI bot that comes up with a movie review for a movie made from the description given by the user. It should follow the format given. If you can not come up with a movie review of the description given by the user, then make a review of a random Hollywood movie.',
    'I think the Lord of the Rings movie has dated terrible'
);
var_dump($result); // dumps a MovieReview instance.

It would give a response like this:

object(MovieReview)#160 (3) {
  ["name"]=>
  string(21) "The Lord of the Rings"
  ["description"]=>
  string(472) "Once a groundbreaking epic, The Lord of the Rings now feels surprisingly outdated. The ambitious scope and Howard Shore’s majestic score still impress, but the early-2000s CGI and practical-effects limitations often pull you out of Middle-earth. Pacing issues and theatrical dialogue that once felt grand now come across as heavy-handed. While die-hard fans may forgive its age, newcomers might struggle to stay immersed in a story weighed down by its own technical era."
  ["rating"]=>
  int(4)
}

Setup with Apie

You can also set it up with the Apie library. In This case you would need to require apie/apie-bundle for Symfony or apie/laravel-apie for Laravel to setup the key and url in the Laravel/Symfony configuration:

apie:
  ai:
    base_url: http://localhost:11434
    api_key: 'ignored-for-ollama'

It is recommended to use environment variables for the api key: Symfony:

apie:
  ai:
    api_key: '%env(AI_API_KEY)%'

Laravel:

// config/apie.php
return [
    'ai' => [
        'api_key' => env('AI_API_KEY'),
    ]
];