Download the PHP package sentience/ai without Composer

Sentience AI

The AI connector for the Sentience framework.

Sentience AI is a small, opinionated PHP library for talking to large language models. It targets PHP 8.3 and wraps two underlying API shapes - the OpenAI chat completions API and the Anthropic messages API - behind one consistent interface. Anything that speaks OpenAI's protocol (OpenRouter, local inference servers, compatible gateways) works through the OpenAI driver by pointing it at a different base URI.

The goal is not to be a kitchen-sink SDK. It is to give a PHP application a clean way to:

• send a prompt to a model,
• attach images and files,
• expose tools the model can call,
• ask for a structured JSON response,
• enable streaming over a PHP Generator, reading SSE chunks incrementally,
• and have tool calls loop to completion without writing that loop yourself.

All of that is one fluent call chain on a Prompt object, returning a Generator that yields ResponseInterface values through each round of the conversation.

Installation

Requires PHP 8.3 or newer. The only runtime dependency is guzzlehttp/guzzle.

Providers

Three providers ship out of the box, defined on the Sentience\Ai\Api enum:

Both drivers share ApiAbstract, so the message-building, attachment formatting, and structured-output handling live in one place. The per-provider classes only deal with the wire format differences (message roles, tool call shapes, image content blocks, and SSE streaming events).

Usage

Connect

For OpenRouter, swap the enum and the base URI:

For Anthropic:

A basic prompt

Models can be passed as a plain string or as any backed enum; backed enums are resolved to their .value automatically, which is handy when models live in your own enum.

System prompt and conversation history

withPreviousMessages accepts an array of message objects (UserMessage, AssistantMessage, ToolMessage). These are the same message types the library produces internally, so you can round-trip a previous response through AssistantMessage::fromResponse($response) and feed it back in.

Attachments

Images (png, jpg, jpeg, gif, webp, bmp) are sent as image content blocks. Anything else is decoded and embedded as a fenced text block so the model sees the file contents directly. There are also withBase64Attachment and withRawAttachment entry points for when the bytes are already in memory.

Tools

Tools can be a closure, a callable, or any class implementing ToolInterface. The simplest form is a closure:

If you do not supply an explicit schema, the library reflects on the closure's parameters and builds one for you. Supported parameter types are bool, int, float, string, and array. Nullable types are honoured. This is enough for the vast majority of tools; for anything fancier, pass a Schemable schema explicitly.

When execute() is called, the library will:

1. send the prompt,
2. collect any tool calls in the response,
3. run them against the registered tools,
4. append the assistant message and each tool result to the conversation,
5. and re-send, repeating until the model stops calling tools.

The tool-call loop runs automatically inside the generator. Each round of the conversation yields a ResponseInterface that you can inspect or consume before the loop continues to the next round.

For class-based tools, implement ToolInterface and register with withToolInterface:

Structured output

Ask for a JSON object back by passing an ObjectType schema:

The schema is injected as a system message instructing the model to return minified JSON conforming to the schema. On the way back, getStructuredOutput parses the response, handling both raw JSON and json Ai // entry point, picks a driver -> ApiInterface (OpenAI|Anthropic) // translates to the wire format -> Prompt // fluent builder -> ResponseGenerator // owns the tool-call loop, yields responses -> ResponseInterface // content, reasoning, tool calls, finish reason

- `Sentience\Ai\Ai` - the facade. Connects, dispatches on the `Api` enum, and
  starts prompts.
- `Sentience\Ai\Apis\ApiAbstract` - shared behaviour: image detection, MIME
  handling, multipart content building, the structured-output system message,
  and the `/v1/models` listing.
- `Sentience\Ai\Apis\OpenAI\OpenAIApi` and `Sentience\Ai\Apis\Anthropic\AnthropicApi`
  - per-provider message and attachment formatting plus SSE stream parsing.
- `Sentience\Ai\Prompt` - the builder. Holds the prompt, system prompt,
  conversation history, attachments, tools, max tokens, structured output,
  and the stream flag. `execute()` returns a `Generator` via `ResponseGenerator`.
- `Sentience\Ai\Apis\ResponseGenerator` - an `IteratorAggregate` that wraps the
  tool-call loop. It yields `ResponseInterface` objects, re-sending with tool
  results until the model stops. In streaming mode, each yielded response
  can be consumed incrementally with `read()`.
- `Sentience\Ai\Apis\ResponseAbstract` - base class for provider responses.
  Handles both streaming and non-streaming HTTP bodies. Streaming reads SSE
  data via `read()` (with `Length` enum chunk sizes) and exposes `readAll()`
  for full consumption. Each provider subclass implements `handleSseData()`,
  `isStreamEnd()`, and `finalizeStream()`.
- `Sentience\Ai\Apis\Length` - an enum of chunk sizes (`ExtraSmall` through
  `ExtraLarge`) that controls how many bytes are read per `read()` call.
- `Sentience\Ai\Schema` - the schema factory and type hierarchy.
- `Sentience\Ai\Tools` - `Tool` (closure-backed, with reflection-driven schema
  generation) and `ToolInterface` for class-based tools.
- `Sentience\Ai\Messages` - `UserMessage`, `AssistantMessage`, `ToolMessage`,
  `SystemMessage`, and the `Role` enum.
- `Sentience\Ai\Attachments\Base64Attachment` - file and inline attachment
  helper.

Adding a provider means implementing `ApiInterface` (or extending
`ApiAbstract`) and adding a case to the `Api` enum plus a branch in `Ai`'s
constructor. Everything above the driver - prompt building, schemas, tools,
attachments, the loop - is shared.