README

A provider-agnostic PHP 8.3+ library for representing AI conversations, including messages, multimodal content, tool calls and results, response formats, token usage, and cost.

The package contains immutable data-transfer objects, value objects, enums, and typed collections. It does not send HTTP requests, execute tools, or translate data into a specific provider's API format.

Installation

composer require adachsoft/ai-conversation-model

Quick start

<?php

use AdachSoft\AiConversationModel\Content\Collection\ContentPartCollection;
use AdachSoft\AiConversationModel\Content\TextContentPartDto;
use AdachSoft\AiConversationModel\Message\ChatMessageDto;
use AdachSoft\AiConversationModel\Message\ChatMessageIdVo;
use AdachSoft\AiConversationModel\Message\Collection\ChatMessageDtoCollection;
use AdachSoft\AiConversationModel\Normalizer\ConversationArrayNormalizer;
use DateTimeImmutable;

$userMessage = ChatMessageDto::user(
    new ChatMessageIdVo('message-1'),
    new DateTimeImmutable('2026-10-15T04:00:00.123456+00:00'),
    new ContentPartCollection([
        new TextContentPartDto('Explain immutable value objects.'),
    ]),
);

$messages = new ChatMessageDtoCollection([$userMessage]);
$serializedMessages = (new ConversationArrayNormalizer())->toArray($messages);

Provider adapters map these model objects to and from a provider's API format. Provider-specific request options belong to the application or adapter, not to this library.

Multimodal messages and tool results

A user message can contain multiple images without text, and a tool result can contain image content. The model stores the media references; applications and adapters handle retrieval and provider-specific conversion.

<?php

use AdachSoft\AiConversationModel\Content\Collection\ContentPartCollection;
use AdachSoft\AiConversationModel\Content\MediaContentPartDto;
use AdachSoft\AiConversationModel\Content\MediaSourceEnum;
use AdachSoft\AiConversationModel\Content\MimeTypeVo;
use AdachSoft\AiConversationModel\Message\ChatMessageDto;
use AdachSoft\AiConversationModel\Message\ChatMessageIdVo;
use AdachSoft\AiConversationModel\Tool\ToolCallIdVo;
use AdachSoft\AiConversationModel\Tool\ToolNameVo;
use AdachSoft\AiConversationModel\Tool\ToolResultDto;
use DateTimeImmutable;

$firstImage = new MediaContentPartDto(
    new MimeTypeVo('image/png'),
    MediaSourceEnum::Url,
    'https://example.com/first.png',
);
$secondImage = new MediaContentPartDto(
    new MimeTypeVo('image/jpeg'),
    MediaSourceEnum::Url,
    'https://example.com/second.jpg',
);

$imageOnlyMessage = ChatMessageDto::user(
    new ChatMessageIdVo('message-images'),
    new DateTimeImmutable('2026-10-15T04:00:00+00:00'),
    new ContentPartCollection([$firstImage, $secondImage]),
);

$imageToolResult = new ToolResultDto(
    new ToolCallIdVo('call-chart'),
    new ToolNameVo('render_chart'),
    new ContentPartCollection([$firstImage]),
);

The application is responsible for choosing which history to retain. When trimming, preserve required system or developer instructions and keep every tool result corresponding to a retained assistant tool call. Construct a new ChatMessageDtoCollection after trimming so its conversation invariants are checked.

See the usage guide for exhaustive role matching and additional examples.

Core types

ChatMessageDto represents a system, developer, user, assistant, or tool message, including its creation time.
ChatMessageDtoCollection holds chronologically ordered messages and validates conversation-wide invariants.
TextContentPartDto and MediaContentPartDto represent ordered text and media content.
ToolDefinitionDto, ToolCallDto, and ToolResultDto represent tool schemas and the call/result exchange. The application executes tools.
ConversationArrayNormalizer converts a message collection to and from the documented lossless array format.
TokenUsageDto and CostDto hold provider-reported token usage and optional cost.

An assistant conversation may end while tool calls are still pending. If more messages follow, all open calls must receive matching results before any non-tool message continues the conversation. Use an exhaustive match over ChatRoleEnum cases without a default arm when handling roles, so new role cases cannot be silently ignored.

Documentation

Usage guide: messages, tools, media, response formats, and usage data.
Provider integration: responsibilities and mapping boundaries for provider adapters.
Conversation serialization: canonical array shape and strict hydration.

Requirements

PHP 8.3 or newer
Composer

adachsoft / ai-conversation-model

Package info

Security

Statistics