Download the PHP package tivins/llm-lib without Composer

llm-lib

PHP library for building LLM agents and calling OpenAI-compatible HTTP APIs — chat completions, embeddings, rerank, and tokenize (OpenAI, Ollama, vLLM, llama.cpp, LiteLLM, etc.).

Namespace: Tivins\LlmLib
Package: tivins/llm-lib
PHP: ^8.3
Current version: see CHANGELOG.md

Table of contents

1. What this library does
2. Architecture
3. Quick start
4. Core concepts
5. Agent lifecycle hooks
6. Behavioral contracts
7. Examples
8. Backend compatibility
9. Project layout
10. Development

What this library does

Not included: streaming, model management endpoints (stubs exist as comments in LLM.php), multi-agent orchestration, vector indexing, or a built-in chat UI.

Architecture

Agent turn

One agent turn (Agent::runTurn()):

1. Dispatch BeforeTurn.
2. Call the LLM with the current conversation.
3. If the assistant message contains tool_calls, execute each tool, append tool messages, and call the LLM again.
4. Repeat until the model stops with finish_reason: stop (or length without tool calls — see behavioral contracts).
5. Store the final assistant message in the conversation.
6. Dispatch AfterTurn and return AgentTurnResult.

RAG pipeline (typical use of embeddings + rerank)

Embeddings and rerank are standalone LLM calls — they do not go through Agent. A common retrieval pipeline looks like:

Quick start

Install

Minimal agent (text response)

Agent with tools

Handlers receive the raw JSON arguments string from the model and must return a string (usually JSON) used as the tool message content.

Embeddings

Rerank

Use a reranker model on a server started with --reranking — do not call /v1/embeddings with a reranker (scores will be meaningless).

Conversation logging

Core concepts

Message

A chat message with role, content, optional reasoningContent, toolCalls, toolCallId, and meta.

Two serialization methods exist on purpose:

Conversation

Ordered list of Message objects. toChatCompletionArray() maps every message through Message::toChatCompletionArray().

ChatCompletionOptions

Per-request settings: model, temperature, topP, n, tools, toolChoice, responseFormat.

Important: Agent::runTurn() injects $options->tools = $this->tools (mutates the object in place). Passing a different ToolRegistry in options throws InvalidArgumentException.

AgentTurnResult

LLM

Shared HTTP client. Endpoint is the base URL without trailing /v1; paths are appended per method.

Common behaviour:

• Optional apiKey → Authorization: Bearer header.
• Configurable timeoutSeconds (default 120).
• Throws Exception on cURL failure, HTTP ≥ 400, or malformed JSON.
• Returns duration in milliseconds on response objects.

Chat-specific: chatCompletion() normalizes GPT-OSS / Harmony <|channel|> markers in assistant responses and can recover usable text from llama.cpp Harmony parse errors (HTTP 500).

Embeddings-specific: vectors are returned as float[]. When the API returns base64-encoded vectors (encoding_format: base64), they are decoded automatically.

Rerank-specific: RerankResponse::sortedResults() returns results by descending score; rankedDocuments($documents) maps scores back to the original document strings.

EmbeddingOptions / EmbeddingResponse

• EmbeddingOptions: model, encodingFormat (float or base64), dimensions (OpenAI embedding v3).
• EmbeddingResponse: model, usage, embeddings[], first(), vectors(), raw().
• Each Embedding has index and vector (list<float>).

RerankOptions / RerankResponse

• RerankOptions: model, topN (sent as top_n; limits how many results the server returns).
• RerankResponse: model, usage, results[], sortedResults(), rankedDocuments(), raw().
• Each RerankResult has index (position in the input documents array) and relevanceScore.

ToolRegistry

• registerTools() adds or overwrites tools by name (last registration wins).
• execute() runs the handler or returns a tool message with {"error":"No handler for tool: …"} (no exception).

Agent lifecycle hooks

Register listeners on AgentHooks (fluent API). Events are defined in AgentHookEvent:

See also todo_tool_approval.md for tool-approval patterns in a code harness.

Behavioral contracts

These behaviors are intentional and covered by unit tests. Open questions live in TODO.md.

Empty content

• Stored as '' in Message::$content and toArray().
• Sent to the API as null in toChatCompletionArray() (OpenAI format).

reasoning_content

• Parsed from API responses and kept in Message::$reasoningContent.
• Included in toArray() for logging.
• Never sent back in subsequent requests via toChatCompletionArray().

Unknown tool

No handler → tool message with JSON error content; conversation continues (model may recover).

Duplicate tool name

registerTools() silently overwrites the previous handler for the same name.

finish_reason: length

If the model stops due to token limit without pending tool calls, the turn is treated as success (truncated content is stored). Check message->meta['finish_reason'] if you need to detect truncation.

Assistant message metadata

Stored assistant messages include meta with at least created_at, time_ms, model, usage, finish_reason, and temperature (from options).

Examples

Runnable scripts in examples/. Numbering leaves gaps (ex011, …) for future additions.

Backend compatibility

Notes:

• Embeddings follow the OpenAI Embeddings API (input, model, optional encoding_format, dimensions).
• Rerank follows the llama.cpp / Jina-style API (query, documents, optional top_n). Requires a dedicated reranker model with --reranking --embedding --pooling rank.
• Multiple servers: point each LLM instance at a different endpoint / defaultModel (chat on :8080, embeddings on :8081, rerank on :8082, etc.).

Project layout

Development

Extending LLM

The library uses a concrete LLM class (not an interface). For tests or custom transports:

• Subclass and override protected function request(...) — see tests/LLMTest.php (CapturingLLM).
• Substitute a test double with compatible methods — see tests/Support/StubLLM.php (chatCompletion, embeddings, rerank, tokenize).

Contributing

1. Add or update tests for behavior changes.
2. Run composer analyse and composer test.
3. Document intentional behavior in this README or TODO.md.
4. Update CHANGELOG.md under [Unreleased].

License

MIT — see composer.json.