Download the PHP package bycerfrance/llm-api-lib without Composer

LLM API Library

PHP 8.3+ library for interacting with multiple LLM providers (Google, Mistral, OpenAI, OVH and any OpenAI-compatible endpoint) with failover, retry, guard validation, tool calling, MCP client, and OpenAPI integration support.

Installation

You can install library with Composer, it's the recommended installation.

Providers

Built-in providers

• Google -- Google Generative Language API
• Mistral -- Mistral AI API
• OpenAI -- OpenAI API
• OVH -- OVH AI Endpoints

Generic (OpenAI-compatible)

The Generic provider connects to any OpenAI-compatible endpoint (local servers, proxies, third-party providers):

Model metadata

Use ModelInfo to attach rich metadata to a provider (capabilities, quality/cost tiers, pricing, context window, output limit):

Models without sampling parameters

Some recent models (e.g. GPT-5, OpenAI o1/o3/o4 reasoning models, Anthropic Claude Opus 4.x) reject sampling parameters such as temperature, top_p, seed, etc. Declare these models with tunable: false so the library automatically strips the offending fields from the outgoing payload:

When tunable is false, the following parameters are stripped from the request body: temperature, top_p, n, logprobs, top_logprobs, presence_penalty, frequency_penalty, seed (see ModelInfo::TUNING_PARAMETERS).

For atypical restrictions (custom endpoints, beta features, vendor-specific quirks), use stripFields to remove any payload path — dot-notation is supported for nested values:

If a LoggerInterface is provided to the provider constructor, each effectively stripped field emits a warning-level log entry with the field path and the model name, making the behaviour observable in production.

Chat

Basic usage

With instructions

Message types

The library provides typed message classes for convenience:

Completion parameters

Fine-tune the LLM behavior with immutable with*() methods:

Service tier

Control the processing priority and pricing tier with ServiceTier:

Each value defines a fallback() method for provider compatibility: PRIORITY → AUTO → DEFAULT, FLEX → AUTO → DEFAULT. Providers that do not support service_tier (e.g., Mistral) automatically strip it from the payload.

Reasoning effort

Control how much reasoning the model performs before generating a response with ReasoningEffort:

Each value defines a fallback() method: XHIGH → HIGH → MEDIUM → LOW → NONE. Provider-specific builders use this chain to map unsupported values to the closest supported one. For example, Mistral only supports HIGH and NONE, so MEDIUM falls back through LOW → NONE.

Setting reasoningEffort automatically adds Capability::REASONING to the completion's required capabilities, ensuring only providers that support reasoning are selected during failover.

Content Types

ArrayContent

Allows combining multiple contents (ContentInterface or strings) into a single object. Useful for sending multiple elements in a single message.

Example:

DocumentUrlContent

Represents a document accessible via a URL. Supports capabilities document and ocr.

Example:

Creates a DocumentUrlContent instance from a local file path or stream. The file is automatically converted to a base64-encoded data URL.

Example:

Parameters:

• $file: Path to the file as a string or a stream resource.
• $name: Optional custom name for the document.
• $detail: Optional detail level for processing (e.g., 'auto', 'low', 'high').

ImageUrlContent

Represents an image accessible via a URL. Supports capabilities image and ocr.

Example:

Creates an ImageUrlContent instance from a GD image resource. The image is automatically converted to a base64-encoded data URL.

Example:

Parameters:

• $image: A GD image resource.
• $detail: Optional detail level for processing (e.g., 'auto', 'low', 'high').
• $maxSize: Optional maximum size for resizing the image.
• $format: Optional image format ('jpeg', 'png', 'gif', 'webp').
• $quality: Optional quality setting for JPEG/PNG/WebP formats.

Creates an ImageUrlContent instance from a local file path or stream. The file is automatically converted to a base64-encoded data URL.

Example:

Parameters:

• $file: Path to the file as a string or a stream resource.
• $detail: Optional detail level for processing (e.g., 'auto', 'low', 'high').

InputAudioContent

Represents audio content encoded in base64 with a specified format. Supports capability audio.

Example:

TextContent & JsonContent

TextContent represents plain text or text read from a file. It supports the text capability.

JsonContent represents structured data in JSON format. It also supports the text capability.

Examples:

When creating a TextContent instance, you can pass an associative array of placeholders that will be applied to the content using str_replace. This allows dynamic content generation based on placeholders in the text.

Example:

The placeholders are applied using the format {key} where key corresponds to the keys in the placeholder array.

Creates a TextContent instance from a local file path or stream. The file content is automatically loaded and can be processed with optional placeholders.

Example:

Parameters:

• $file: Path to the file as a string or a stream resource.
• $placeholders: Optional associative array of placeholders to apply to the content.

Response Formats

Control the output format of the LLM response using withResponseFormat().

Text (default)

JSON Object

Forces the LLM to return valid JSON. Requires a provider with JSON_OUTPUT capability.

JSON Schema

Forces the LLM to return JSON conforming to a specific schema. Requires a provider with JSON_SCHEMA capability.

Tools (Function Calling)

Tools allow the LLM to call external functions during inference. The library handles the tool execution loop automatically.

Defining a tool

Using tools in a completion

Multiple tools

Filtered tools

Use FilteredToolCollection to restrict which tools are visible to the LLM. Supports include patterns (whitelist) and exclude patterns (prefix with !):

Tool choice

Control whether and how the model should use tools with ToolChoice:

When null (default), tool_choice is not sent in the payload and the provider uses its own default (typically auto). Mistral uses any instead of required; the library remaps this automatically.

Parallel tool calls

Control whether the model can issue multiple tool calls in a single turn:

When null (default), parallel_tool_calls is not sent in the payload and the provider uses its own default (typically true). Set to false to force the model to call tools one at a time.

Tool execution loop

The library automatically:

• Sends tools definition to the LLM
• Detects when the LLM wants to call a tool
• Executes the callback with the provided arguments
• Sends the result back to the LLM
• Continues until the LLM provides a final response or max iterations is reached

MCP Client (Model Context Protocol)

The library includes a full MCP client that connects to remote MCP servers, discovers tools, and executes them. MCP servers implement ToolCollectionInterface and can be passed directly to withTools().

McpServer

The MCP client handles the full lifecycle: initialization handshake, tool discovery (with pagination), tool execution via JSON-RPC tools/call, and graceful shutdown.

OpenAPI integration

Connect to any REST API described by an OpenAPI 3.x specification. Each operation becomes a tool the LLM can call.

Requires the optional dependency: composer require devizzent/cebe-php-openapi

LlmTool (Agentic Sub-Model Delegation)

LlmTool allows the orchestrator LLM to delegate tasks to a different model via tool calling:

Model Selection

Selection strategy

When using multiple providers with Llm, control which provider is preferred:

Available strategies:

Scoring is based on the QualityTier (BASIC, GOOD, PREMIUM) and CostTier (LOW, MEDIUM, HIGH) defined in each provider's ModelInfo.

Response Handling

CompletionResponseInterface

The chat() method returns a CompletionResponseInterface which extends CompletionInterface with additional response data:

FinishReason

The FinishReason enum indicates why the LLM stopped generating:

Retry

The Retry decorator wraps any LlmInterface and retries on failure with configurable backoff:

Guard System

Guards validate LLM responses after each chat() call. If validation fails, a GuardException is thrown with the rejected response attached.

Custom guard

FinishReasonGuard

A built-in guard that rejects responses with specific finish reasons (defaults to LENGTH and CONTENT_FILTER):

Combining Guard + Retry

Guards and retries compose naturally as decorators:

Failover

The Llm class accepts multiple providers and implements automatic failover:

Capability-based filtering

Before attempting providers, Llm automatically filters them by required capabilities. If a message contains an image, only providers with the IMAGE capability are tried. If a JsonSchemaFormat is used, only providers with JSON_SCHEMA are tried.

Strategy-based ordering

When a SelectionStrategy is set on the completion, providers are sorted by their score (based on ModelInfo quality/cost tiers) before the failover sequence begins.

Logging

The chat() method accepts an optional PSR-3 logger for per-call logging:

The library logs:

• Provider selection and routing decisions
• Request initiation and completion metrics (tokens, cost, finish reason)
• Tool call counts and execution
• Retry attempts with wait times
• Failover transitions with error details

Usage & Cost Tracking

Token usage

Retrieve aggregated token usage across all calls:

Cost tracking

Calculate monetary cost based on ModelInfo pricing:

Cost is computed as: (promptTokens * inputCost / 1M) + (completionTokens * outputCost / 1M).

Context window & output limit

Query the model's maximum context window and output token limits:

When using multi-provider Llm, both methods return the minimum across all providers.

Capabilities

This library supports a wide range of LLM capabilities, allowing developers to leverage advanced features such as multimodal processing, structured output, and reasoning. The following table lists the supported capabilities along with their descriptions.

Each provider implementing the LlmInterface must declare its supported capabilities via the getCapabilities() method. The Llm class automatically filters providers based on compatibility with the requested capabilities, ensuring that only suitable providers are used for each request.