README

Composer plugin that discovers ai-tool-call tooling across installed packages and generates deterministic registry files used at runtime.

Requirements

PHP >= 8.3
Composer 2.x
composer-plugin-api ^2.0, psr/log ^3.0, adachsoft/collection ^3.0

ToolFactory autodiscovery (recommended)

From version 0.3.0 the main integration path is ToolFactory-based autodiscovery.

1) Enable plugin in your project composer.json

{
  "config": {
    "allow-plugins": {
      "adachsoft/ai-tool-call-plugin": true
    }
  }
}

2) Implement ToolFactory in your extension package

In your package that provides tools:

implement AdachSoft\AiToolCall\SPI\Factory\ToolFactoryInterface,
point to your package via normal Composer autoload (autoload.psr-4).

Example:

namespace Vendor\Pkg;

use AdachSoft\AiToolCall\SPI\Factory\ToolFactoryInterface;
use AdachSoft\AiToolCall\SPI\ToolInterface;
use AdachSoft\AiToolCall\SPI\Dto\ToolDefinitionDto;
use AdachSoft\AiToolCall\SPI\Collection\ConfigMap;

final class MyToolFactory implements ToolFactoryInterface
{
    public static function getToolClass(): string
    {
        return MyTool::class;
    }

    public static function createTool(object $serviceLocator): ToolInterface
    {
        // resolve dependencies from your container / service locator
        return new MyTool();
    }
}

final class MyTool implements ToolInterface
{
    public static function getDefinition(): ToolDefinitionDto
    {
        return new ToolDefinitionDto(
            name: 'my_tool',
            description: 'My tool description',
            parametersSchema: [],
            tags: new \AdachSoft\AiToolCall\SPI\Collection\TagsCollection([]),
            enabled: true,
        );
    }

    // ... implement callTool(...)
}

3) Build ToolFactory registry

The plugin can build the registry in two ways:

Automatically via Composer plugin hooks (post-install-cmd, post-update-cmd).
Manually via CLI:

$ ./vendor/bin/ai-tool-call-tool-factory-registry-build
[ai-tool-call-plugin] ToolFactory registry written to /path/to/project/.generated/ai-tool-call-registry.php

The generated file has the following shape:

<?php
// .generated/ai-tool-call-registry.php
return [
    'packages' => [
        'vendor/pkg-a' => [
            'Vendor\\Pkg\\MyToolFactory',
        ],
        'vendor/other' => [
            'Vendor\\Other\\AnotherFactory',
        ],
    ],
];

4) Runtime discovery

At runtime you use ToolFactoryRegistryReaderInterface + ToolFactoryDiscoveryInterface + DefaultToolingDiscovery to turn the registry into actual factories and tools.

Registry reader loads ToolFactoryRegistryDataDto from .generated/ai-tool-call-registry.php.
DefaultToolFactoryDiscovery turns factory FQCNs into ToolFactoryInterface instances using ToolFactoryInstantiator and an application ServiceLocatorInterface.
DefaultToolingDiscovery takes discovered factories plus ToolConfigProviderInterface and builds:
- configsByToolName (map toolName => ConfigMap),
- DiscoveryErrorCollection with all discovery/config errors.

You can choose failure mode via ToolFactoryAutodiscoveryOptionsDto:

FailureModeEnum::FAIL_FAST – stop on first error, return partial data.
FailureModeEnum::FAIL_SOFT – collect all errors and continue.

Legacy providers-based registry (backwards compatibility)

The original entry-file based mechanism is still supported for BC, but considered legacy.

1) In your extension package add entry-file and point it in composer.json:

extra.ai-tool-call.entry-file: "resources/ai-tool-call.php"
resources/ai-tool-call.php must return array like:

<?php
return [
    'providers' => [
        ['provider' => 'Vendor\\Pkg\\Provider\\MyToolProvider'],
    ],
];

2) Run composer update (or composer install) -> plugin generates .generated/ai-tool-call-registry.php in the legacy providers format.

3) At runtime use the legacy RegistryReader / RegistryWriter from Infrastructure\Registry if you still rely on the providers-based schema.

Debug helpers (bin)

ToolFactory registry debug

Use bin/ai-tool-call-registry-debug to quickly inspect the ToolFactory registry.

Prints absolute path to the registry.
Prints number of packages and number of factories per package.
Exits with non-zero when registry is missing/invalid.