adachsoft / ai-integration-middleware
Middleware decorators for adachsoft/ai-integration tool-calling chat facade.
Package info
gitlab.com/a.adach/ai-integration-middleware
pkg:composer/adachsoft/ai-integration-middleware
Requires
- php: ^8.3
- adachsoft/ai-conversation-model: ^0.2
- adachsoft/ai-integration: ^0.10
- adachsoft/collection: ^3.0
Requires (Dev)
- adachsoft/php-code-style: ^0.7
- friendsofphp/php-cs-fixer: ^3.95
- phpstan/phpstan: ^2.2
- phpunit/phpunit: ^12.5
- rector/rector: ^2.6
- symplify/phpstan-rules: ^14.13
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
Middleware decorators for tool-calling chat facades from adachsoft/ai-integration.
Requirements
- PHP
^8.3 adachsoft/ai-integration^0.10adachsoft/ai-conversation-model^0.2adachsoft/collection^3.0
Problem
AI providers may reject a conversation when an assistant message contains a tool call without a matching tool result. This package provides an opt-in facade decorator that repairs pending tool calls in the terminal assistant message immediately before sending the conversation to the provider.
For each missing result in that terminal message, the decorator appends a synthetic tool message. The synthetic result is not evidence that the tool ran successfully; the default message tells the assistant not to assume success and to call the tool again if needed.
Installation
composer require adachsoft/ai-integration-middleware
Usage
Wrap the facade at the composition root and pass the decorated facade wherever a ToolCallingChatFacadeInterface is required:
use AdachSoft\AiIntegrationMiddleware\OrphanedToolCall\OrphanedToolCallRepairingFacadeFactory;
$toolCallingChatFacade = (new OrphanedToolCallRepairingFacadeFactory())
->wrap($toolCallingChatFacade);
A custom synthetic result message can be configured through the factory constructor:
$toolCallingChatFacade = (new OrphanedToolCallRepairingFacadeFactory(
'The previous tool execution was interrupted. Run the tool again if needed.',
))->wrap($toolCallingChatFacade);
Behavior and limitations
- The middleware is disabled unless the facade is explicitly wrapped.
- Complete histories are passed through unchanged. Existing tool results are not replaced; when only some terminal tool calls have results, synthetic results are added only for the missing calls.
- The middleware does not persist or mutate the application's conversation history.
- Tool execution is outside the middleware's responsibility. A synthetic result must not be treated as a real tool output.
- A middle orphan—an assistant tool call with missing results followed by later conversation messages—is not repaired here. The shared conversation model rejects such a history while constructing
ChatMessageDtoCollection, before the decorated facade receives it. The code that builds the history must handle this case (for example,adachsoft/ai-agent). - The package does not depend on
adachsoft/ai-agent.
The public composition API is OrphanedToolCallRepairingFacadeFactory::wrap(). The decorator and repair service are internal implementation details.
See the middleware design rules for the package conventions used by future decorators.
Breaking changes
This release targets adachsoft/ai-integration ^0.10 and the shared adachsoft/ai-conversation-model ^0.2 DTOs, replacing the conversation types used with adachsoft/ai-integration 0.8. Code that directly constructs or type-hints the old 0.8 types must migrate its imports, DTO construction, and related method signatures to the shared model. Histories must satisfy the shared model's validation rules when ChatMessageDtoCollection is constructed.
Tests
Run the default unit test suite with:
vendor/bin/phpunit
The default PHPUnit suite excludes the production group so that tests requiring paid provider APIs are not run by default.
License
MIT