README

Ollama PHP Client Library

Documentation for version v0.6.0

About

Ollama PHP Client Library is a robust, well-designed PHP client for interacting with the Ollama API. This library allows PHP developers to easily integrate large language models (LLMs) into their applications using the Ollama server.

Features

Clean, domain-driven architecture with clear separation of concerns
Comprehensive Ollama API support including text generation and embeddings
Type-safe request and response handling with full DTO support
Text generation with advanced options (temperature, top-k, top-p, repetition penalty, and more)
Text embeddings for semantic search, similarity, and vector operations
Multimodal support for image inputs with base64-encoded images
Streaming support for real-time text generation
Flexible configuration with customizable timeouts and connection settings
PSR standards compliance with proper interfaces and abstractions
Comprehensive test coverage with 97+ unit tests for embeddings alone

Installation

You can install the package via composer:

composer require tenqz/ollama

Requirements

PHP 7.2 or higher (supports PHP 8.0+ features)
cURL extension for HTTP communication
JSON extension for data serialization
Ollama server running locally or remotely

Usage

Text Generation

use Tenqz\Ollama\Generation\Application\DTO\Request\GenerationRequest;
use Tenqz\Ollama\Generation\Application\DTO\Request\GenerationOptions;
use Tenqz\Ollama\Generation\Infrastructure\Client\OllamaGenerationClient;
use Tenqz\Ollama\Shared\Infrastructure\Config\OllamaServerConfig;
use Tenqz\Ollama\Transport\Infrastructure\Http\Client\CurlTransportClient;

// Configure the server connection
$config = new OllamaServerConfig('localhost', 11434);
$transportClient = new CurlTransportClient($config->getBaseUrl());

// Create the Generation API client
$client = new OllamaGenerationClient($transportClient);

// Create a generation request with options
$request = new GenerationRequest('llama3.2');
$request->setPrompt('Write a creative story about AI');
$request->setSystem('You are a creative writing assistant.');

// Configure generation options
$options = new GenerationOptions();
$options->setTemperature(0.8);      // More creative
$options->setTopK(40);              // Vocabulary diversity
$options->setNumPredict(500);       // Max tokens
$request->setOptions($options);

// Generate text
$response = $client->generate($request);
echo $response->getResponse();

Text Embeddings

use Tenqz\Ollama\Embedding\Application\DTO\Request\EmbeddingRequest;
use Tenqz\Ollama\Embedding\Infrastructure\Client\OllamaEmbeddingClient;
use Tenqz\Ollama\Shared\Infrastructure\Config\OllamaServerConfig;
use Tenqz\Ollama\Transport\Infrastructure\Http\Client\CurlTransportClient;

// Configure the server connection
$config = new OllamaServerConfig('localhost', 11434);
$transportClient = new CurlTransportClient($config->getBaseUrl());

// Create the Embedding API client
$client = new OllamaEmbeddingClient($transportClient);

// Create an embedding request
$request = new EmbeddingRequest('nomic-embed-text:latest', 'Hello world');

// Generate embedding vector
$response = $client->embed($request);

// Access the embedding vector
$embedding = $response->getEmbedding();        // First embedding (768-dimensional vector)
$dimension = $response->getDimension();        // Vector dimension (e.g., 768)

// Use embeddings for similarity search, clustering, etc.
echo "Embedding dimension: {$dimension}\n";
echo "First 5 values: " . implode(', ', array_slice($embedding, 0, 5));

Architecture

The library follows Domain-Driven Design principles with a clear separation of concerns across multiple layers:

Transport Layer

TransportClientInterface - Interface for HTTP clients with GET/POST methods
ResponseInterface - Interface for API responses with status and data access
CurlTransportClient - cURL implementation with configurable timeouts and headers
JsonResponse - JSON response implementation with data parsing

Generation Layer (Text Generation)

GenerationRequest - Request DTO with prompts, options, images, streaming, templates
GenerationOptions - Fine-grained control (temperature, top-k, top-p, repetition penalty, etc.)
GenerationResponse - Response DTO with generated text and metadata
GenerationClientInterface - Client interface for generation operations
OllamaGenerationClient - Implementation with error handling and response transformation
GenerationException - Domain-specific exception for generation errors

Embedding Layer (Text Embeddings)

EmbeddingRequest - Request DTO with model and input text
EmbeddingResponse - Response DTO with embedding vectors (supports batch processing)
EmbeddingClientInterface - Client interface for embedding operations
OllamaEmbeddingClient - Implementation with error handling and vector processing
EmbeddingException - Domain-specific exception for embedding errors

Shared Layer

OllamaServerConfig - Server configuration with host, port, and URL building
OllamaApiEndpoints - API endpoint constants (/api/generate, /api/embed)
Cross-cutting concerns and utilities used across domains

Advanced Features

Generation Options

The library supports comprehensive generation options for fine-tuning model behavior:

Sampling Parameters:

temperature (0.0-1.0) - Controls randomness (higher = more creative)
top_k (1-100) - Limits vocabulary diversity
top_p (0.0-1.0) - Nucleus sampling for focused responses
seed (integer) - Deterministic outputs for reproducible results

Generation Control:

num_predict (integer) - Maximum tokens to generate
repeat_penalty (float) - Penalty for repetition
stop (array) - Stop sequences to end generation

Advanced:

stream (boolean) - Real-time streaming responses
format (string) - Output format (e.g., 'json')
system (string) - System message for role definition
images (array) - Base64-encoded images for multimodal models
keep_alive (string/int) - Model persistence duration

Embedding Features

The Embedding layer supports:

Request Options:

model (string) - Embedding model name (e.g., nomic-embed-text:latest)
input (string) - Text to generate embeddings for
options (array) - Additional model parameters
keep_alive (string/int) - Model persistence duration

Response Data:

embeddings (array) - Array of embedding vectors (supports batch processing)
dimension (int) - Vector dimension (e.g., 768)
model (string) - Model name used
Performance metrics: total_duration, load_duration, prompt_eval_count

Methods:

getEmbedding() - Get first embedding vector (single text)
getEmbeddings() - Get all embedding vectors (batch processing)
getDimension() - Get vector dimension
getCount() - Get number of embeddings

Development

The library includes comprehensive development tools:

# Run tests
composer test

# Check code style
composer check-style

# Fix code style issues
composer fix-style

# Run static analysis
composer analyze

# Run all quality checks
composer check

License

The MIT License (MIT). Please see License File for more information.

tenqz / ollama

Maintainers

Details