README

Unified AI tool-calling chat abstraction for PHP 8.3 with pluggable providers and a clean, framework-agnostic Public API.

Public API: simple facade to send chat messages, define tools (function-calling), and receive results.
Built-in providers: OpenAI and Deepseek.
SPI: implement your own provider by fulfilling a tiny interface and DTO set.
HTTP logging: optional, via a small logger interface.
Zero-framework: no container required; everything is manually wired with a builder.

Requirements

PHP 8.3+
ext-json, ext-mbstring (standard in most PHP installations)

Installation

composer require adachsoft/ai-integration

Quick start (Public API)

use AdachSoft\AiIntegration\PublicApi\Builder\ToolCallingChatFacadeBuilder;
use AdachSoft\AiIntegration\PublicApi\ToolCalling\Dto\ChatMessageDto;
use AdachSoft\AiIntegration\PublicApi\ToolCalling\Dto\Collection\ChatMessageDtoCollection;
use AdachSoft\AiIntegration\PublicApi\ToolCalling\Dto\Collection\ToolDefinitionDtoCollection;
use AdachSoft\AiIntegration\PublicApi\ToolCalling\Dto\ToolCallingChatRequestDto;
use AdachSoft\AiIntegration\PublicApi\ToolCalling\Dto\ToolDefinitionDto;

$builder = ToolCallingChatFacadeBuilder::create()
    ->withOpenAi(apiKey: getenv('OPENAI_API_KEY'));

$messages = new ChatMessageDtoCollection([
    new ChatMessageDto(role: 'system', content: 'You are a helpful assistant.'),
    new ChatMessageDto(role: 'user', content: 'Add 2 and 3 using a tool and show the token.'),
]);

$tools = new ToolDefinitionDtoCollection([
    new ToolDefinitionDto(
        name: 'sum',
        description: 'Returns JSON {result: string, token: string}',
        parametersSchema: [
            'type' => 'object',
            'properties' => [ 'a' => ['type' => 'number'], 'b' => ['type' => 'number'] ],
            'required' => ['a','b'],
            'additionalProperties' => false,
        ]
    )
]);

$request = new ToolCallingChatRequestDto(
    messages: $messages,
    tools: $tools,
    providerId: 'openai',
    modelId: 'gpt-4o-mini',
    temperature: 0.0,
);

$facade = $builder->build();
$response = $facade->chat($request);

if ($response->result !== null) {
    echo $response->result; // final model answer (should include tool token if your prompt enforces it)
}

foreach ($response->toolCalls as $call) {
    // inspect tool calls if needed
}

Providers

OpenAI (provider id: openai)
- Endpoint: https://api.openai.com/v1/chat/completions
- Env: OPENAI_API_KEY
Deepseek (provider id: deepseek)
- Endpoint: https://api.deepseek.com/chat/completions
- Env: DEEPSEEK_API_KEY

If you pass modelId as null, each provider uses its default. For OpenAI, a safe starter is gpt-4o-mini; for Deepseek: deepseek-chat.

HTTP logging and CLI example

You can inject your own HTTP traffic logger via the builder. A convenient demonstration script is included:

php bin/test-ai-tool-chat.php --provider=openai --model=gpt-4o-mini --show-meta=on --log-http=1 --log-headers=0

The script runs 3 scenarios (smoke and two tool-calling flows) and optionally pretty-prints HTTP request/response payloads.

SPI (Service Provider Interface)

Do not depend on internals. External integrations should use only:

AdachSoft\AiIntegration\PublicApi – the facade and DTOs to call the model.
AdachSoft\AiIntegration\Spi – the small interface and DTOs to implement your own provider.

All other namespaces (Application, Domain, Infrastructure) are internal and may change at any time. Reading them brings no value and increases processing costs for AI agents.

For a complete SPI guide (interface, DTOs, exceptions, examples), see:

docs/SPI.md

Versioning and stability

Versioning via Git tags only. Suggested first release tag: v0.1.0.
SemVer: PublicApi and Spi are considered public surface and will follow semantic versioning rules. Internal namespaces may change without notice.

Testing

Run unit and integration tests:
```
composer test
```
Production checks (require API keys): see tests/Production and bin/test-ai-tool-chat.php.

adachsoft / ai-integration

Maintainers

Details