Ollama PHP Client Library

To use this library, you must have PHP 8.1+ and Ollama installed on your system.

1. Install the package via Composer:

composer require ardagnsrn/ollama-php

2. Initialize the client. You can use the default base URL or provide a custom one (e.g., if Ollama is running on a different host or port):

// Using default base URL
$client = \ArdaGnsrn\Ollama\Ollama::client();

// Using a custom base URL
$client = \ArdaGnsrn\Ollama\Ollama::client('http://localhost:11434');

To interact with the Ollama API, instantiate the OllamaClient class. You can specify the host address, an optional API key for authentication, and a connection timeout.

By default, it connects to http://localhost:11434 with a 10-second timeout.

use ArdaGnsrn\
Ollama\OllamaClient;

$client = new OllamaClient(
    host: 'http://localhost:11434',
    apiKey: 'your-api-key',
    timeout: 30
);

The Blobs resource allows you to interact with the underlying data blobs used by Ollama models.

// Check if a blob exists
$exists = $client->blobs()->exists('blobname');

// Create a new blob
$success = $client->blobs()->create('blobname');

Use the Embed resource to generate vector embeddings for input text using a specified model.

$response = $client->embed()->create([
    'model' => 'llama3.1',
    'input' => [
        "Why is the sky blue?",
    ]
]);

$embedding = $response->embedding; // Array of floats

The Models resource provides full lifecycle management for LLMs within Ollama.

Available Methods:

• list(): Returns all available models.
• show($name): Shows details (modelfile, parameters, template) of a specific model.
• create([...]): Creates a new model from a modelfile.
• copy($source, $target): Copies an existing model.
• delete($name): Deletes a model.
• pull($name): Downloads a model from the Ollama server.
• push($name): Uploads a model to the Ollama server.
• runningList(): Lists models currently running in memory.

// List models
$response = $client->models()->list();

// Pull a model
$response = $client->models()->pull('llama3.1');

// Create a custom model
$client->models()->create([
    'name' => 'mario',
    'modelfile' => "FROM llama3.1\nSYSTEM You are mario from Super Mario Bros."
]);

The Completions resource allows you to generate a single response for a given prompt using a specific model.

Use create() for a standard blocking request, or createStreamed() to iterate over chunks of the response as they are generated.

// Standard completion
$completions = $client->completions()->create([
    'model' => 'llama3.1',
    'prompt' => 'Once upon a time',
]);
echo $completions->response;

// Streamed completion
$completions = $client->completions()->createStreamed([
    'model' => 'llama3.1',
    'prompt' => 'Once upon a time',
]);

foreach ($completions as $completion) {
    echo $completion->response;
}

Use the isRunning() method to verify if the Ollama service is active and reachable. It returns true if the service responds with 'Ollama is running', and false otherwise (including on connection errors).

if ($client->isRunning()) {
    echo 'Ollama is ready!';
}

The ListModelsResponse object is returned when requesting a list of available models from the Ollama API. It contains a collection of ListModelsModelResponse objects. You can access the list of models via the $models property or convert the entire response back into a plain associative array using the toArray() method.

// Assuming $response is an instance of ListModelsResponse
foreach ($response->models as $model) {
    // $model is an instance of ListModelsModelResponse
    echo $model->name;
}

// Convert back to array
$array = $response->toArray();

The ChatMessageResponse class represents an individual message within a chat response. You can instantiate it from an associative array (typically parsed from an Ollama API response) using the from() static method.

The method expects the following keys in the $attributes array:

• role (string): The role of the message (e.g., 'assistant', 'user', 'system').
• content (string): The text content of the message.
• tool_calls (array, optional): An array of tool call data. If provided, these are automatically converted into ChatMessageToolCallResponse objects.

$message = ChatMessageResponse::from([
    'role' => 'assistant',
    'content' => 'Hello! How can I help you today?',
    'tool_calls' => []
]);

echo $message->role;    // 'assistant'
echo $message->content; // 'Hello! How can I help you today?'

To convert a ChatMessageResponse instance back into a plain associative array, use the toArray() method. This is useful for serialization or passing data back to other systems. The resulting array includes the role, content, and tool_calls keys.

$array = $chatMessageResponse->toArray();
// Returns:
// [
//   'role' => '...',
//   'content' => '...',
//   'tool_calls' => [...]
// ]