Search by

adachsoft / ai-integration-middleware

Arkadiusz Adach

Middleware decorators for adachsoft/ai-integration tool-calling chat facade.

Package info

gitlab.com/a.adach/ai-integration-middleware

Issues

pkg:composer/adachsoft/ai-integration-middleware

Statistics

Installs: 7

Dependents: 0

Suggesters: 0

Stars: 0

v0.2.0 2026-11-12 20:24 UTC

This package is auto-updated.

Last update: 2026-11-12 19:30:54 UTC


README

Middleware decorators for tool-calling chat facades from adachsoft/ai-integration.

Requirements

  • PHP ^8.3
  • adachsoft/ai-integration ^0.10
  • adachsoft/ai-conversation-model ^0.2
  • adachsoft/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