README

adachsoft/ai-tool-runtime is a runtime layer for adachsoft/ai-tool-call. It loads tool configuration, resolves placeholders, normalizes tool results for JSON serialization, extracts tool names from SPI factories, and flattens exception chains.

Usage

Use JsonFileToolConfigResolverFactory as the recommended entry point:

use AdachSoft\AiToolRuntime\Config\Dto\ToolConfigContextDto;
use AdachSoft\AiToolRuntime\Config\Dto\ToolConfigLayerContextDto;
use AdachSoft\AiToolRuntime\Factory\JsonFileToolConfigResolverFactory;

$factory = new JsonFileToolConfigResolverFactory();
$resolver = $factory->create(['/etc/my-tools']);

$configs = $resolver->buildToolConfigs(
    registeredToolNames: ['example_tool'],
    toolConfigContextDto: new ToolConfigContextDto(['api_key' => $apiKey]),
    toolConfigLayerContextDto: new ToolConfigLayerContextDto(),
);

$facadeBuilder->withToolConfigs($configs);

JSON configuration

Each tool configuration is stored in <tool_name>.json. The filename must exactly match the name returned by the tool's getDefinition() method. The JSON root must be an object. Configuration keys must satisfy the ConfigMap rules: a non-empty string of at most 32 characters containing lowercase letters, digits, underscores, and optional dot-separated segments.

Placeholders use the {{name}} syntax. Whitespace inside the braces is accepted, and dotted names are supported. Values are taken exclusively from the ToolConfigContextDto supplied by the caller.

This package never reads environment variables, .env files, $_ENV, $_SERVER, or getenv(). The host application decides where context values come from. Exception messages do not contain environment variable names.

Public API and internal implementation

Public API	Purpose
`ToolConfigResolverInterface`	Builds final tool configurations.
`ToolConfigPlaceholderResolverInterface`	Resolves configuration placeholders.
`ToolConfigRepositoryInterface`	Extension point for configuration sources.
`ToolConfigLayerInterface`	Extension point for configuration layers.
`SpiToolNameExtractorInterface`	Extracts registered tool names from SPI factories.
`ToolCallResultNormalizerInterface`	Converts tool results into JSON-safe values.
`ToolConfigContextDto`, `ToolConfigLayerContextDto`	Input context DTOs.
Classes in `Exception/`	Exceptions exposed to consumers.
`ExceptionChainFlattener`	Public exception-chain formatting helper.
`JsonFileToolConfigResolverFactory`	Recommended resolver factory.
`RepositoryToolConfigLayer`	Reusable repository-backed layer.
`InMemoryToolConfigRepository`	In-memory repository for tests and custom integrations.

ToolConfigResolver, ToolConfigPlaceholderResolver, JsonFileToolConfigRepository, SpiToolNameExtractor, and ToolCallResultNormalizer are internal implementations created or used by the factory.

Configuration for a tool that is not registered causes the build to fail fast with ToolConfigUnknownToolException.

Testing

vendor/bin/phpunit -c packages/ai-tool-runtime/phpunit.xml.dist
vendor/bin/phpstan analyse packages/ai-tool-runtime/src packages/ai-tool-runtime/tests
vendor/bin/rector process packages/ai-tool-runtime/src packages/ai-tool-runtime/tests
vendor/bin/php-cs-fixer fix packages/ai-tool-runtime/src packages/ai-tool-runtime/tests

First release

Version 0.1.0 is the first release of adachsoft/ai-tool-runtime. It provides the runtime services required to load tool configuration, resolve caller-provided placeholders, normalize tool results for JSON serialization, extract registered SPI tool names, and flatten exception chains.

Install the package with Composer:

composer require adachsoft/ai-tool-runtime:^0.1

See CHANGELOG.md for the complete release history.

adachsoft / ai-tool-runtime

Package info

Security

Statistics