papi-ai / papi-core
Core classes for PapiAI - A simple but powerful PHP library for building AI agents
Requires
- php: ^8.2
- composer-runtime-api: ^2.0
Requires (Dev)
- friendsofphp/php-cs-fixer: ^3.0
- mockery/mockery: ^1.6
- pestphp/pest: ^3.0
- psr/log: ^3.0
- psr/simple-cache: ^3.0
- vimeo/psalm: ^6.0
Suggests
- psr/log: Required for LoggingMiddleware (^3.0)
- psr/simple-cache: Required for CacheMiddleware (^3.0)
Provides
None
Conflicts
None
Replaces
None
README
A simple but powerful PHP library for building AI agents. Framework-agnostic, type-safe, and designed for real-world applications.
Features
- Framework-agnostic - Works standalone, with Laravel, Symfony, or any PHP project
- Multi-provider - Supports Anthropic Claude, Google Gemini, and more
- Tool calling - Define tools as functions or class methods with attributes
- Structured output - Zod-like schema validation for LLM responses
- Streaming - First-class streaming support with events
- Hooks - Observability hooks for logging, metrics, and error handling
- Type-safe - Full PHP 8.2+ type hints and strict types
Installation
composer require papi-ai/core
For providers, install the ones you need:
composer require papi-ai/anthropic # For Claude composer require papi-ai/google # For Gemini
Quick Start
use PapiAI\Core\Agent; use PapiAI\Anthropic\AnthropicProvider; $agent = new Agent( provider: new AnthropicProvider(apiKey: $_ENV['ANTHROPIC_API_KEY']), model: 'claude-sonnet-5-5', instructions: 'You are a helpful assistant.', ); $response = $agent->run('What is 2 + 2?'); echo $response->text; // "4"
Adding Tools
Tools let the agent perform actions and retrieve information.
Function-based Tools
use PapiAI\Core\Tool; $weatherTool = Tool::make( name: 'get_weather', description: 'Get current weather for a city', parameters: [ 'city' => ['type' => 'string', 'description' => 'City name'], ], handler: fn(array $args) => fetchWeather($args['city']), ); $agent = new Agent( provider: $provider, model: 'claude-sonnet-5-5', tools: [$weatherTool], ); $response = $agent->run('What is the weather in London?');
Class-based Tools with Attributes
use PapiAI\Core\Tool; use PapiAI\Core\Attributes\Tool as ToolAttr; use PapiAI\Core\Attributes\Description; class WebTools { #[ToolAttr('Fetch content from a URL')] public function fetchUrl( #[Description('The URL to fetch')] string $url, #[Description('Timeout in seconds')] int $timeout = 30, ): string { return file_get_contents($url); } #[ToolAttr('Search the web')] public function search(string $query, int $limit = 10): array { // Implementation } } $agent = new Agent( provider: $provider, model: 'claude-sonnet-5-5', tools: Tool::fromClass(WebTools::class), );
Structured Output
Use schemas to validate and parse LLM responses:
use PapiAI\Core\Schema\Schema; $schema = Schema::object([ 'sentiment' => Schema::enum(['positive', 'negative', 'neutral']), 'confidence' => Schema::number()->min(0)->max(1), 'keywords' => Schema::array(Schema::string()), ]); $response = $agent->run( prompt: 'Analyze: "Great product, highly recommend!"', options: ['outputSchema' => $schema], ); // $response->data is validated $response->data['sentiment']; // 'positive' $response->data['confidence']; // 0.95 $response->data['keywords']; // ['great', 'recommend']
Schema Types
Schema::string() // String values Schema::string()->min(1) // Min length Schema::string()->max(100) // Max length Schema::string()->pattern('/regex/') Schema::number() // Float values Schema::integer() // Integer values Schema::number()->min(0) // Minimum value Schema::number()->max(100) // Maximum value Schema::boolean() // Boolean values Schema::array(Schema::string()) // Array of strings Schema::array($itemSchema)->minItems(1)->maxItems(10) Schema::object([ // Object with properties 'name' => Schema::string(), 'age' => Schema::integer()->optional(), ]) Schema::enum(['a', 'b', 'c']) // Enum values // Modifiers ->nullable() // Allow null ->optional() // Not required in objects ->default('value') // Default value ->description('...') // Description for LLM
Streaming
Simple Text Streaming
foreach ($agent->stream('Tell me a story') as $chunk) { echo $chunk->text; flush(); }
Event Streaming
foreach ($agent->streamEvents('Use tools to help me') as $event) { match ($event->type) { 'text' => echo $event->text, 'tool_call' => echo "Calling: {$event->tool}\n", 'tool_result' => echo "Result: " . json_encode($event->result) . "\n", 'done' => echo "\nComplete!\n", 'error' => echo "Error: {$event->error}\n", }; }
Hooks
Add observability to your agent:
$agent = new Agent( provider: $provider, model: 'claude-sonnet-5-5', tools: $tools, hooks: [ 'beforeToolCall' => function (string $name, array $input) { Log::info("Calling tool: {$name}", $input); }, 'afterToolCall' => function (string $name, mixed $result, float $duration) { Metrics::timing("tool.{$name}", $duration); }, 'onError' => function (Throwable $error) { Sentry::captureException($error); }, ], );
Messages & Conversation
Build conversations manually:
use PapiAI\Core\Message; use PapiAI\Core\Conversation; // Individual messages $message = Message::user('Hello'); $message = Message::system('You are helpful'); $message = Message::assistant('Hi there!'); $message = Message::userWithImage('What is this?', $imageUrl); // Conversation helper $conversation = new Conversation(); $conversation->setSystem('You are a helpful assistant'); $conversation->addUser('Hello'); $conversation->addAssistant('Hi! How can I help?'); $conversation->addUser('Tell me a joke'); $messages = $conversation->getMessages();
If you keep the transcript yourself, continue it with $response->toMessage() rather than
Message::assistant($response->text, ...). Some providers leave state on the response that they
need back on the next request, such as reasoning signatures, and toMessage() carries it. It is
plain data under $message->replay, keyed by provider name, so toArray() and fromArray()
store and restore it with the rest of the message.
Why a Response Stopped
Every provider reports why the model stopped in the same words:
use PapiAI\Core\StopReason; $response = $agent->run('Summarise this repository'); if ($response->isTruncated()) { // The output ceiling cut the answer short: raise maxTokens and ask again. } match ($response->stoppedBecause) { StopReason::Stop => 'finished', StopReason::ToolCalls => 'wants tools run', StopReason::MaxTokens => 'cut short', StopReason::Refused => 'declined or filtered', StopReason::Other => 'something else', };
The provider's own string is still on $response->stopReason.
Configuration Options
$agent = new Agent( provider: $provider, model: 'claude-sonnet-5-5', instructions: 'System prompt here', tools: [...], hooks: [...], maxTokens: 4096, // Max response tokens temperature: 0.7, // Only on models that still take it; current Claude and Gemini refuse it maxTurns: 10, // Max tool-use loops before stopping );
Providers
Anthropic (Claude)
use PapiAI\Anthropic\AnthropicProvider; $provider = new AnthropicProvider( apiKey: $_ENV['ANTHROPIC_API_KEY'], defaultModel: 'claude-sonnet-5-5', );
Google (Gemini)
use PapiAI\Google\GoogleProvider; $provider = new GoogleProvider( apiKey: $_ENV['GOOGLE_API_KEY'], defaultModel: GoogleProvider::MODEL_3_8_FLASH, ); // Some of the available models GoogleProvider::MODEL_4_HYDROGEN // gemini-4-hydrogen GoogleProvider::MODEL_4_CARBON // gemini-4-carbon GoogleProvider::MODEL_3_8_FLASH // gemini-3.8-flash (default) GoogleProvider::MODEL_3_1_PRO // gemini-3.1-pro-preview GoogleProvider::MODEL_2_5_PRO // gemini-2.5-pro
Choosing a Provider by Name
An application that lets its users pick a provider in configuration does not need to know any
provider's class or constructor. Every provider package ships a factory, and ComposerDiscovery
finds the ones that are installed:
use PapiAI\Core\Factory\ComposerDiscovery; use PapiAI\Core\Factory\ProviderRegistry; $registry = new ProviderRegistry(new ComposerDiscovery()); $provider = $registry->create('google', ['api_key' => $_ENV['GOOGLE_API_KEY']]); foreach ($registry->installed() as $factory) { echo $factory->package(), ': ', $factory->name(), "\n"; foreach ($factory->settings() as $setting) { echo ' ', $setting->name, $setting->required ? ' (required)' : '', ': ', $setting->description, "\n"; } }
Setting names are snake_case (api_key, base_url, model, max_tokens, effort). A missing,
unknown or mistyped setting throws ConfigurationException, an InvalidArgumentException, before
any request is made. The registry accepts any list of factories, so tests can hand it their own.
Creating Custom Providers
Implement ProviderInterface:
use PapiAI\Core\Contracts\ProviderInterface; use PapiAI\Core\Response; class MyProvider implements ProviderInterface { public function chat(array $messages, array $options = []): Response { // Make API call and return Response } public function stream(array $messages, array $options = []): iterable { // Yield StreamChunk objects } public function supportsTool(): bool { return true; } public function supportsVision(): bool { return true; } public function supportsStructuredOutput(): bool { return false; } public function getName(): string { return 'my-provider'; } }
If your API needs opaque state back on the next request, return it as replay: ['my-provider' => $state]
on the Response, and read it from $message->replayFor('my-provider') when you convert the history.
To make it discoverable by name, ship a factory with it. Extend AbstractProviderFactory,
declare your settings, and build the provider from them:
use PapiAI\Core\Contracts\ProviderInterface; use PapiAI\Core\Factory\AbstractProviderFactory; use PapiAI\Core\Factory\Setting; use PapiAI\Core\Factory\SettingValues; final class MyProviderFactory extends AbstractProviderFactory { public function name(): string { return 'my-provider'; } public function package(): string { return 'acme/my-provider'; } public function settings(): array { return [new Setting('api_key', true, 'My API key')]; } protected function build(SettingValues $values): ProviderInterface { return new MyProvider($values->string('api_key')); } }
Then declare the package type and the factory in its composer.json:
{
"type": "papi-provider",
"extra": {"papi": {"factory": "Acme\\MyProviderFactory"}}
}
Testing
composer test
License
MIT