adachsoft / ai-agent-context-window
Context window strategy for adachsoft/ai-agent: sliding window with tool-call aware trimming for AI conversation history.
Package info
gitlab.com/a.adach/ai-agent-context-window
pkg:composer/adachsoft/ai-agent-context-window
Requires
- php: ^8.3
- adachsoft/ai-agent: ^0.13
Requires (Dev)
- adachsoft/php-code-style: ^0.7.2
- friendsofphp/php-cs-fixer: ^3.95
- phpstan/phpstan: ^2.2
- phpunit/phpunit: ^12.5
- rector/rector: ^2.6
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
Library extending adachsoft/ai-agent with a context window conversation trimming strategy.
Installation
composer require adachsoft/ai-agent-context-window
This package requires adachsoft/ai-agent ^0.13 and uses the shared
adachsoft/ai-conversation-model message types.
context_window Strategy
The library provides an SPI implementation:
AdachSoft\AiAgent\Spi\Conversation\ConversationContextStrategyInterface
Strategy ID: context_window.
The strategy accepts and returns a shared-model
AdachSoft\AiConversationModel\Message\Collection\ChatMessageDtoCollection.
Each item is an AdachSoft\AiConversationModel\Message\ChatMessageDto, with
its message ID represented by ChatMessageIdVo, role by ChatRoleEnum, content
by ContentPartCollection, tool calls by ToolCallDtoCollection, and tool
results by ToolResultDtoCollection.
The strategy:
- trims history to a window of N last messages (
max_messages), - preserves tool-calling consistency in the returned context:
- if tool results (
toolResults) are present in the window, the strategy automatically extends the window backwards to include their corresponding calls (toolCalls), - when needed, the limit is treated as a soft limit (more messages than
max_messagesare returned).
- if tool results (
ChatMessageDtoCollection validates conversation integrity when a collection is
created. The strategy creates a new validated collection after trimming.
Usage with AiAgentBuilder
use AdachSoft\AiAgent\PublicApi\Builder\AiAgentBuilder;
use AdachSoft\AiAgent\PublicApi\Dto\AgentConfigDto;
use AdachSoft\AiAgentContextWindow\Conversation\Strategy\ContextWindowConversationContextStrategy;
$strategy = new ContextWindowConversationContextStrategy();
$builder = new AiAgentBuilder();
$facade = $builder
->withPorts($ports) // PortsConfigDto
->withAgentConfig(new AgentConfigDto(
name: 'MyAgent',
description: 'Demo agent with context window',
providerId: 'deepseek',
modelId: 'deepseek-chat',
conversationContextStrategyId: 'context_window',
conversationContextStrategyParams: [
'max_messages' => 30,
],
))
->withPolicies($policies) // PoliciesConfigDto
->withSpiConversationContextStrategy($strategy)
->build();
Configuration
Configuration is provided via the conversationContextStrategyParams bag on
AgentConfigDto and read by ContextWindowConversationContextStrategy.
Supported parameters:
max_messages(int, required for trimming)- soft limit for the number of recent messages kept in the context window,
- must be an integer greater than or equal to 1.
Example:
use AdachSoft\AiAgent\PublicApi\Dto\AgentConfigDto;
$agentConfig = new AgentConfigDto(
name: 'MyAgent',
description: 'Demo agent with context window',
providerId: 'deepseek',
modelId: 'deepseek-chat',
conversationContextStrategyId: 'context_window',
conversationContextStrategyParams: [
'max_messages' => 50,
],
);
If max_messages is not provided, the strategy returns the full conversation
without trimming.
Exceptions
InvalidContextWindowConfigExceptionwhen themax_messagesparameter has an invalid type or is less than 1.
Static Analysis
Running PHPStan:
composer install
composer run phpstan
License
MIT