README

Ollaminator is an Ollama client for F4, a lightweight PHP/PostgreSQL-based web development framework.

It provides a small, typed wrapper around the Ollama HTTP API for chat, single-prompt generation, embeddings, and model listing — returning readonly response objects instead of raw arrays.

Requirements

PHP 8.3+ (uses typed class constants and named arguments)
A running Ollama instance (defaults to http://localhost:11434)
Guzzle 7 (installed as a dependency)

Installation

composer require f4php/ollaminator

Configuration

Ollaminator reads two F4-wide config constants for its defaults:

// somewhere in your F4 config
final class Config
{
    public const string OLLAMINATOR_URL   = 'http://localhost:11434'; // Ollama host
    public const string OLLAMINATOR_MODEL = 'llama3.2';               // default model
    // ...
}

Both are used as fall-through defaults, so in most applications you configure them once and never pass a host or model again.

Model is resolved per call in this order:

A model: argument passed to the individual call (chat/generate/embed).
The model: argument passed to the Client constructor.
F4\Config::OLLAMINATOR_MODEL.

Host comes from F4\Config::OLLAMINATOR_URL and is the default baseUrl of ApiClient. Construct an ApiClient with an explicit baseUrl: to override it for a given client.

You can still override the model per-client or per-call, and the host per-client, whenever you need to.

Quick start

By default the client talks to Ollama on Config::OLLAMINATOR_URL (e.g. http://localhost:11434). Make sure the model you want is pulled first (e.g. ollama pull llama3.2).

Chat

use F4\Ollaminator\Client;

$client = new Client();

// No model here — it comes from Config::OLLAMINATOR_MODEL
$response = $client->chat(
    messages: [
        ['role' => 'system', 'content' => 'You are a helpful assistant.'],
        ['role' => 'user',   'content' => 'Say hello in one sentence.'],
    ],
);

// ChatResponse is Stringable — casting yields the message content
echo $response;                     // "Hello! ..."
echo $response->message['content']; // same thing, explicitly

Generate (single prompt)

$response = $client->generate(
    prompt: 'Write a haiku about PHP.',
);

echo $response;           // GenerateResponse is Stringable
echo $response->response; // the generated text

Embeddings

$response = $client->embed(
    model: 'nomic-embed-text', // override the default just for this call
    input: ['The quick brown fox', 'jumps over the lazy dog'],
);

// float[][] — one vector per input
$vectors = $response->embeddings;

List local models

foreach ($client->listModels() as $model) {
    echo "{$model->name} ({$model->size} bytes)\n";
}

Connecting to a non-default host

To reach a host other than Config::OLLAMINATOR_URL, pass a configured ApiClient to the Client constructor. Use named arguments, since $model is the first constructor parameter:

use F4\Ollaminator\ApiClient;
use F4\Ollaminator\Client;

$client = new Client(
    apiClient: new ApiClient(baseUrl: 'http://ollama.internal:11434', timeout: 120),
);

// or pin both a default model and a custom host:
$client = new Client(
    model: 'llama3.2',
    apiClient: new ApiClient(baseUrl: 'http://ollama.internal:11434'),
);

JSON / structured output

Ask the model to return valid JSON, optionally constrained by a JSON schema:

$response = $client->chat(
    messages: [['role' => 'user', 'content' => 'Give me a person as JSON.']],
    format: [
        'type' => 'object',
        'properties' => [
            'name' => ['type' => 'string'],
            'age'  => ['type' => 'integer'],
        ],
        'required' => ['name', 'age'],
    ],
);

$person = json_decode((string) $response, associative: true);

Pass format: 'json' for unstructured JSON mode.

Error handling

All errors extend F4\Ollaminator\Exception\OllamaException:

use F4\Ollaminator\Exception\ConnectionException;
use F4\Ollaminator\Exception\ModelNotFoundException;
use F4\Ollaminator\Exception\OllamaException;

try {
    $response = $client->chat(messages: $messages);
} catch (ConnectionException $e) {
    // Ollama unreachable at the configured host
} catch (ModelNotFoundException $e) {
    // model isn't pulled locally (HTTP 404)
} catch (OllamaException $e) {
    // any other Ollama / transport error
}

Documentation

docs/AGENTS.md — complete API reference (every method, parameter, and response object) intended for AI agents and as a detailed developer reference.

f4php / ollaminator

Maintainers

Package info

Statistics

Security