Issue #3586376: Add context item priority field and selection tie-breakers.

Kristen Polrequested to merge
issue/ai_context-3586376:3586376-ranking-field into 1.0.x

Description

Adds a Priority field (High / Medium / Low) on context items and uses it for deterministic selection ordering instead of the changed timestamp.

What changed

  • AiContextItemPriority — constants for High (10), Medium (5), Low (0); Medium is the default.

  • priority base field on ai_context_item, with getPriority() on the entity.

  • Context item form — Priority control in Context Scope (above Global); hidden on the default form display config.

  • ai_context_update_10020() — installs field storage on existing sites and removes priority from the default form display so the custom Context Scope widget can expose it.

  • AiContextSelector — shared compareSelectionPreference() ordering:

    1. Priority descending
    2. Shorter content length
    3. Higher item ID (final tie-break)

    Applied within each group:

    • Global — bounded top-K via insertTopPreferenceCandidate()
    • Always-include — sorted by priority; lower-priority items drop first when capped
    • Auto-included — same bounded preference helper (replaces chunk scan order)
    • Scored — priority breaks subscription score ties
    • Match-all — sorted by priority

    Between-group order is unchanged: global → always-include → auto-included → scored.

  • Docs — context_items.md, context_selection.md, and scopes.md updated for Priority and tie-breaking behavior.

  • Tests — kernel selector tests updated/added; functional form test asserts the Priority field on add; kernel test covers update hook 10020.

Machine name is priority (not ranking) to avoid confusion with subscription scope scoring.

Closes #3586376 (closed)

Testing instructions

Automated

cd web/modules/contrib/ai_context
./lint.sh
ddev exec vendor/bin/phpunit web/modules/contrib/ai_context/tests/src/Kernel/AiContextSelectorAlgorithmTest.php
ddev exec vendor/bin/phpunit web/modules/contrib/ai_context/tests/src/Kernel/AiContextPriorityFieldUpdateTest.php
ddev exec vendor/bin/phpunit web/modules/contrib/ai_context/tests/src/Kernel/AiContextSelectorEventsTest.php
ddev exec vendor/bin/phpunit web/modules/contrib/ai_context/tests/src/Functional/AiContextScopeContextItemFormTest.php --filter testScopeFieldsetAppearsOnAddForm

Priority-specific kernel coverage includes:

  • testSelectorCapsGlobalItemsAfterPriority
  • testGlobalContextLoadingOrder (includes same-priority content-length tie-break)
  • testAutoIncludedItemsOrderedByPriority
  • testAlwaysIncludeItemsOrderedByPriority
  • testAlwaysIncludePrefersHigherPriorityWhenCapped
  • testUpdateInstallsPriorityFieldStorage (update 10020)

Manual

  1. Run drush updatedb on an existing site — update 10020 should install the priority field storage.
  2. Add or edit a context item at /admin/config/ai/context/items/add — confirm Priority appears in Context Scope above Global.
  3. Create several global items with different priorities and run selection with a low max_global_items — higher-priority items should appear first; lowest should be dropped.
  4. Add several items to an agent Always include list (mixed request order) with different priorities and a low max_items — confirm highest-priority items are kept and ordered first.
  5. Create non-global items with different priorities, subscribe an agent to a scope (e.g. Working with Text), and confirm scored items with equal subscription scores are ordered High → Medium → Low.
  6. With Dynamic Entity Reference enabled, create entity-item auto-included items with different priorities on the same entity context — confirm higher priority is ordered first and survives caps.

Manual testing completed for global cap, always-include ordering, and subscription-scored ordering (minimal selection mode). Entity-item auto-include and match_all were not manually re-tested; kernel tests cover those paths.

Post-merge steps

  • Run database updates on existing sites: drush updatedb
  • Cache rebuild: drush cr

No config import required beyond what updatedb applies.

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