Issue #3586378: Remove max_items context limit and rely on token budget.

Kristen Polrequested to merge
issue/ai_context-3586378:3586378-remove-max-items into 1.0.x

Description

Removes the Max context items to inject (max_items) setting and all selection logic that depended on it. The token budget (max_tokens) is now the primary user-facing limit on how much context reaches an agent prompt. max_global_items is unchanged and still caps the Global group only.

The selector also applies an internal, non-configurable bound of 100 candidates per selection group (scored, match-all, and auto-included) as a performance safeguard on very large catalogs. It keeps the highest-scored (or most recently changed, for match all) candidates. Realistic token budgets are exhausted well before this bound is reached.

Code changes

  • Remove max_items from ai_context.settings schema/defaults, General settings, and per-agent Advanced overrides.
  • Remove maxItems from AiContextRequest, AiContextRequestParamsData, and AiContextRequestFactory.
  • Update AiContextSelector so merge/scoring/auto-include paths no longer slice by configurable item count; token truncation at render time remains the user-facing ceiling.
  • Add MAX_CANDIDATES_PER_GROUP (100) to bound scored, match-all, and auto-included candidate accumulation during chunked catalog scans.
  • Remove AiContextLimitsConstraint (global cap vs total item cap).
  • Remove max_items from the GetRelevantAiContextItems function-call plugin.
  • Remove getMaxItems() from AiContextSelectionItemsSelectedEvent.
  • Add ai_context_update_10020() to strip obsolete max_items from active config on existing sites.
  • Strip legacy max_items during config import via STORAGE_TRANSFORM_IMPORT (not validation-only) so older exports import cleanly.

Documentation

  • Update limit and selection docs (context_selection.md, agent_configuration.md, scopes.md, developer docs).
  • Document the internal candidate bound in context_selection.md.

Breaking API changes (documented)

  • max_items removed from settings and agent configuration.
  • AiContextRequest no longer accepts maxItems.
  • AiContextSelectionItemsSelectedEvent::getMaxItems() removed.
  • GetRelevantAiContextItems no longer accepts a max_items parameter.
  • AiContextLimitsConstraint and related validation removed.

Closes #3586378 (closed)

Testing instructions

  1. Run drush updatedb and confirm update 10020 removes max_items from ai_context.settings and any agent overrides.
  2. Open Configuration → AI → Context Control Center → General settings (/admin/config/ai/context/settings/general) and confirm Max context items to inject is no longer shown. Save the form with no errors.
  3. Open a per-agent edit form under Agent configuration and confirm the Max context items to inject override is gone; Max global context items and Max tokens still work.
  4. Configure an agent with subscriptions that would previously exceed max_items but stay within max_tokens. Confirm additional matching context is selected and rendered until the token budget applies.
  5. Export config from a site that previously had max_items, re-import on a checkout of this branch, and confirm import succeeds (legacy key stripped from active config).
  6. From the module directory, run ./lint.sh.
  7. Run targeted PHPUnit (example):
ddev exec bash -c 'SIMPLETEST_DB=sqlite://localhost/tmp.sqlite \
  /var/www/html/vendor/bin/phpunit --configuration /var/www/html/phpunit.xml \
  web/modules/contrib/ai_context/tests/src/Unit/AiContextLimitResolverTest.php \
  web/modules/contrib/ai_context/tests/src/Kernel/AiContextSettingsConfigValidationTest.php \
  web/modules/contrib/ai_context/tests/src/Kernel/AiContextAgentConfigValidationTest.php \
  web/modules/contrib/ai_context/tests/src/Kernel/AiContextRequestFactoryTest.php \
  web/modules/contrib/ai_context/tests/src/Kernel/AiContextSelectorAlgorithmTest.php \
  web/modules/contrib/ai_context/tests/src/Kernel/AiContextSelectorEventsTest.php \
  web/modules/contrib/ai_context/tests/src/Kernel/AiContextSettingsConfigImportValidationTest.php \
  web/modules/contrib/ai_context/tests/src/Kernel/AiContextAgentsConfigImportValidationTest.php \
  web/modules/contrib/ai_context/tests/src/Kernel/AiContextUpdate10020Test.php'

Post-merge

  • Existing sites: run drush updatedb once after deploy (update 10020).
  • No manual config edits required beyond the update hook.

Checklist

  • I have updated the MR title to use format: Issue #1234: My issue title.
  • I have updated the MR description to include: Closes #1234
  • I have performed a self-review of my own code
  • I have added or updated tests, or explained in the description why this change is not covered by tests
  • I have updated documentation for any new or changed functionality
  • I have written testing instructions and verified them locally
  • I have noted any required post-merge steps (config imports, cache rebuilds, manual changes)
  • This MR contains no breaking API or hook changes, or they are explicitly documented in the description

AI Compliance

Note

Check the one that best describes your usage, or leave all unchecked if AI was not significantly used.

  • AI Assisted Code — Mainly written by a human; AI used for autocomplete or partial generation under full human supervision.
  • AI Generated Code — Mainly generated by AI, reviewed and approved by a human before this MR was created.
  • Vibe Coded — Generated by AI and only functionally reviewed before this MR was created.
Edited by Kristen Pol

Merge request reports