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. tivins/llm-lib

ActiveLibrary

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

0.1.3(yesterday)01↑2900%MITPHPPHP ^8.3

Since Jun 8Pushed yesterdayCompare

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

READMEChangelogDependencies (3)Versions (2)Used By (0)

llm-lib
=======

[](#llm-lib)

PHP library for building **LLM agents** against **OpenAI-compatible** chat completion APIs (OpenAI, Ollama, vLLM, 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. [Project layout](#project-layout)
8. [Development](#development)

---

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

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

ResponsibilityClassFileHTTP client for `/v1/chat/completions``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`, …Request parameters`ChatCompletionOptions``src/ChatCompletionOptions.php`Turn outcome`AgentTurnResult``src/AgentTurnResult.php`Optional JSON persistence`Logger``src/Logger.php`Observability / extension points`AgentHooks``src/AgentHooks.php`**Not included:** streaming, embeddings, model management endpoints (stubs exist as comments in `LLM.php`), multi-agent orchestration, or a built-in chat UI.

---

Architecture
------------

[](#architecture)

 ```
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`.

---

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

[](#quick-start)

### Install

[](#install)

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

### Minimal agent (text response)

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

```