README

Unified AI tool-calling abstraction for PHP 8.3 with a clean Public API and an extensible SPI for custom tools.

• Public API to list and call tools via a simple facade.
• SPI to implement your own tools (factories) in a framework-agnostic way.
• Zero framework assumptions, manual wiring via a small Builder.
• Uses adachsoft/collection for strict, immutable collections.

Requirements

• PHP ^8.3
• adachsoft/collection ^3.0

Installation

composer require adachsoft/ai-tool-call

Quick Start (SPI with factories)

use AdachSoft\AiToolCall\PublicApi\Builder\AiToolCallFacadeBuilder;
use AdachSoft\AiToolCall\PublicApi\Dto\ToolCallRequestDto;
use AdachSoft\AiToolCall\SPI\Collection\ConfigMap;
use AdachSoft\AiToolCall\SPI\Collection\KeyValueMap;
use AdachSoft\AiToolCall\SPI\Collection\TagsCollection;
use AdachSoft\AiToolCall\SPI\Dto\ToolCallRequestDto as SpiRequestDto;
use AdachSoft\AiToolCall\SPI\Dto\ToolCallResultDto as SpiResultDto;
use AdachSoft\AiToolCall\SPI\Dto\ToolDefinitionDto;
use AdachSoft\AiToolCall\SPI\Exception\ToolConfigurationException;
use AdachSoft\AiToolCall\SPI\Factory\ToolFactoryInterface;
use AdachSoft\AiToolCall\SPI\ToolInterface;

final class EchoTool implements ToolInterface
{
 public static function getDefinition(): ToolDefinitionDto
 {
 return new ToolDefinitionDto(
 name: 'echo',
 description: 'Returns input as output',
 parametersSchema: [
 'type' => 'object',
 'properties' => [
 'text' => ['type' => 'string'],
 ],
 ],
 tags: new TagsCollection(['demo']),
 enabled: true,
 );
 }

 public function callTool(SpiRequestDto $request): SpiResultDto
 {
 return new SpiResultDto(
 'echo',
 new KeyValueMap(['text' => $request->parameters->get('text')])
 );
 }
}

final class EchoToolFactory implements ToolFactoryInterface
{
 public function getToolClass(): string
 {
 return EchoTool::class;
 }

 public function create(ConfigMap $config): ToolInterface
 {
 if ($config->has('invalid')) {
 throw new ToolConfigurationException('Invalid configuration for EchoTool.');
 }

 return new EchoTool();
 }
}

$facade = AiToolCallFacadeBuilder::new()
 ->withSpiFactories([new EchoToolFactory()])
 ->withToolConfigs([
 'echo' => new ConfigMap([]),
 ])
 ->build();

// List available tools (includes built-in current_datetime and your SPI tools)
$tools = $facade->listAvailableTools();
foreach ($tools as $tool) {
 echo $tool->name . PHP_EOL;
}

// Call a SPI tool
$result = $facade->callTool(new ToolCallRequestDto(
 toolName: 'echo',
 parameters: ['text' => 'hello'],
));

var_dump($result->result);

// Call the built-in current_datetime tool
$currentDateTimeResult = $facade->callTool(new ToolCallRequestDto(
 toolName: 'current_datetime',
 parameters: [],
));

var_dump($currentDateTimeResult->result);

Public API

• Facade: AdachSoft\AiToolCall\PublicApi\AiToolCallFacadeInterface
  • callTool(ToolCallRequestDto): ToolCallResultDto
  • listAvailableTools(): AvailableToolCollection
  • listAvailableToolsByTags(array $tags): AvailableToolCollection

DTOs

• ToolCallRequestDto(string $toolName, array $parameters)
• ToolCallResultDto(string $toolName, mixed $result)
• AvailableToolDto(string $name, string $description, array $parametersSchema, array $tags)
• AvailableToolCollection

SPI (Service Provider Interface)

Implement custom tools by fulfilling the SPI contracts.

• AdachSoft\AiToolCall\SPI\ToolInterface

  • callTool(ToolCallRequestDto): ToolCallResultDto
  • static getDefinition(): ToolDefinitionDto

• AdachSoft\AiToolCall\SPI\Factory\ToolFactoryInterface

  • getToolClass(): string
  • create(ConfigMap $config): ToolInterface

• ToolDefinitionDto

  • name: string
  • description: string
  • parametersSchema: array<string, mixed>
  • tags: TagsCollection
  • enabled: bool

• Collections used in SPI:

  • TagsCollection (immutable list of strings)
  • KeyValueMap (immutable map string->mixed)
  • ConfigMap (immutable map string->mixed)
  • ToolCollection (immutable collection of SPI tools)
  • ToolFactoryCollection (immutable collection of SPI tool factories)

Minimal tool example (SPI-only)

use AdachSoft\AiToolCall\SPI\ToolInterface;
use AdachSoft\AiToolCall\SPI\Collection\ToolCollection as SpiToolCollection;
use AdachSoft\AiToolCall\SPI\Dto\ToolDefinitionDto;
use AdachSoft\AiToolCall\SPI\Dto\ToolCallRequestDto as SpiRequest;
use AdachSoft\AiToolCall\SPI\Dto\ToolCallResultDto as SpiResult;
use AdachSoft\AiToolCall\SPI\Collection\TagsCollection;
use AdachSoft\AiToolCall\SPI\Collection\KeyValueMap;

final class EchoTool implements ToolInterface
{
 public static function getDefinition(): ToolDefinitionDto
 {
 return new ToolDefinitionDto(
 name: 'echo',
 description: 'Returns input as output',
 parametersSchema: ['type' => 'object', 'properties' => ['text' => ['type' => 'string']]],
 tags: new TagsCollection(['demo']),
 enabled: true,
 );
 }

 public function callTool(SpiRequest $request): SpiResult
 {
 return new SpiResult('echo', new KeyValueMap(['text' => $request->parameters->get('text')]));
 }
}

$tools = new SpiToolCollection([new EchoTool()]);

Tool discovery & registration

• No autoscan. The builder does not scan directories.
• Register tools via:
  • SPI factories using withSpiFactories() and optional withToolConfigs() for configuration maps, or
  • Direct SPI tools using withSpiTools() when tools are already fully configured.
• The builder always registers CurrentDateTimeToolCaller as a built-in domain tool by default.

Error handling

• Public API throws PublicApi\Exception\ToolCallFailedException on errors during tool execution.
• Public API throws PublicApi\Exception\ToolRegistrationException when tool registration or configuration fails while building the facade (e.g. duplicate tool names or invalid factory/config types).
• SPI exceptions:
  • SPI\Exception\InvalidToolCallException
  • SPI\Exception\ToolExecutionException
  • SPI\Exception\ToolConfigurationException These are mapped through the adapter when calling SPI tools through the Domain.

Versioning

• Semantic Versioning.
• Package version is controlled by Git tags (do not set version in composer.json).

License

MIT