PHPackages                             tivins/llm-lib - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. tivins/llm-lib

ActiveLibrary[Utility & Helpers](/categories/utility)

tivins/llm-lib
==============

0.5.0(1mo ago)015↓85.7%1MITPHPPHP ^8.3

Since Jun 8Pushed 1mo agoCompare

[ Source](https://github.com/tivins/llm-lib)[ Packagist](https://packagist.org/packages/tivins/llm-lib)[ RSS](/packages/tivins-llm-lib/feed)WikiDiscussions main Synced 1w ago

READMEChangelogDependencies (6)Versions (7)Used By (1)

llm-lib
=======

[](#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 [`composer.json`](composer.json) and [`CHANGELOG.md`](CHANGELOG.md)

---

Table of contents
-----------------

[](#table-of-contents)

1. [What this library does](#what-this-library-does)
2. [Architecture](#architecture)
3. [Quick start](#quick-start)
4. [Core concepts](#core-concepts)
5. [Agent lifecycle hooks](#agent-lifecycle-hooks)
6. [Behavioral contracts](#behavioral-contracts)
7. [Examples](#examples)
8. [Backend compatibility](#backend-compatibility)
9. [Project layout](#project-layout)
10. [Development](#development)

---

What this library does
----------------------

[](#what-this-library-does)

ResponsibilityClassFileHTTP client (`/v1/chat/completions`, `/v1/embeddings`, `/v1/rerank`, `/tokenize`)`LLM``src/LLM.php`Message history`Conversation``src/Conversation.php`Single turn: LLM ↔ tools loop`Agent``src/Agent.php`Tool definitions + handlers`ToolRegistry`, `Tool`, `ToolSchema``src/ToolRegistry.php`, …Skipped tool call payloads`ToolCallRejection``src/ToolCallRejection.php`Request parameters (chat)`ChatCompletionOptions``src/ChatCompletionOptions.php`Request parameters (embeddings)`EmbeddingOptions``src/EmbeddingOptions.php`Request parameters (rerank)`RerankOptions``src/RerankOptions.php`Chat response`ChatCompletionResponse``src/ChatCompletionResponse.php`Embeddings response`EmbeddingResponse`, `Embedding``src/EmbeddingResponse.php`, …Rerank response`RerankResponse`, `RerankResult``src/RerankResponse.php`, …Turn outcome`AgentTurnResult``src/AgentTurnResult.php`Optional JSON persistence`Logger``src/Logger.php`Observability / extension points`AgentHooks``src/AgentHooks.php`**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
------------

[](#architecture)

### Agent turn

[](#agent-turn)

 ```
flowchart LR
    Caller --> Agent
    Agent --> Conversation
    Agent --> ToolRegistry
    Agent --> LLM
    LLM --> API["OpenAI-compatible API"]
    ToolRegistry --> Handlers["callable handlers"]
    Conversation --> Logger
    Agent --> Hooks["AgentHooks"]
```

      Loading **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](#behavioral-contracts)).
5. Store the final assistant message in the conversation.
6. Dispatch `AfterTurn` and return `AgentTurnResult`.

### RAG pipeline (typical use of embeddings + rerank)

[](#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:

 ```
flowchart LR
    Docs["Documents"] --> Embed["LLM::embeddings()"]
    Embed --> Index["Vector index (your code)"]
    Query["User query"] --> Search["Similarity search (your code)"]
    Index --> Search
    Search --> Rerank["LLM::rerank()"]
    Rerank --> Context["Top-K passages"]
    Context --> Agent["Agent::runTurn()"]
    Agent --> Answer["Assistant reply"]
```

      Loading ---

Quick start
-----------

[](#quick-start)

### Install

[](#install)

```
composer require tivins/llm-lib
```

### Minimal agent (text response)

[](#minimal-agent-text-response)

```