Issue #3586237: Add multi-vocabulary taxonomy scope plugin.

Kristen Polrequested to merge
issue/ai_context-3586237:3586237-taxonomy-scope-plugin into 1.0.x

Description

Adds a Taxonomy Terms scope plugin so context items can be associated with taxonomy terms from site vocabularies and matched against terms referenced on the current content entity.

Also renames the existing Tags scope label to Context Tags to avoid confusing it with entity-based taxonomy matching, per #3586237.

Scope behavior

  • Taxonomy Terms (taxonomy, weight 20):

    • Context item form shows one entity_autocomplete field per vocabulary.
    • Excludes the module-owned AI Context Tags vocabulary (ai_context_tags), which remains with the Context Tags scope.
    • Performs contextual detection by reading taxonomy reference fields on the current entity.
    • Supports agent subscriptions and hard context filtering.
    • getValues() returns an empty array; terms are selected through the per-vocabulary autocomplete widgets so large vocabularies are not loaded on every form build.

  • Context Tags (tag):

    • Label updated from Tags to Context Tags.
    • Manage link label updated to Manage Context Tags.
    • Still subscription-only; no contextual detection from content entities.

Supporting changes

  • AiContextEntityTargetResolver::loadCurrentContentEntity() loads the current content entity only when the user has view access, with request-level memoization. Taxonomy Terms uses this so untrusted request hints cannot leak field values from inaccessible entities.
  • Default config: ai_context.scope_settings.taxonomy (install + update 10015 for existing sites).
  • Scope icon, schema, CSS, and docs/features/scopes.md updated, including a note explaining why AI Context Tags is excluded from Taxonomy Terms.

Closes #3586237

Testing instructions

Prerequisites

  • Check out this branch and run drush updatedb -y (enables the Taxonomy Terms scope via update 10015).
  • Enable ai_agents_debugger and confirm you can access /admin/config/ai/agents/debug.
  • Confirm Taxonomy Terms is enabled at /admin/config/ai/context/settings/scope.
  • Configure a working AI provider/model for the debugger.

Automated

From the project root:

cd web/modules/contrib/ai_context
./lint.sh
# From Drupal site root
vendor/bin/phpunit web/modules/contrib/ai_context/tests/src/Kernel/AiContextScopeTaxonomyTest.php
vendor/bin/phpunit --filter testTaxonomyScope web/modules/contrib/ai_context/tests/src/Functional/AiContextScopeContextItemFormTest.php
vendor/bin/phpunit web/modules/contrib/ai_context/tests/src/Kernel/AiContextScopeManagerTest.php
vendor/bin/phpunit web/modules/contrib/ai_context/tests/src/Kernel/AiContextScopeTagTest.php

Locally verified: PHPCS, PHPStan, Stylelint, ESLint pass; kernel and functional taxonomy tests pass.

Manual

1. Create test taxonomy and content

  1. Create a vocabulary Topics with terms Climate and Sports.
  2. Create an Article content type (or reuse one) with a taxonomy reference field targeting Topics (for example field_topics).
  3. Create four published nodes:
    • Climate article — tagged Climate only. Note the node ID (NID).
    • Sports article — tagged Sports only. Note the node ID (NID).
    • Climate and Sports article — tagged both Climate and Sports. Note the node ID (NID).
    • Generic article — No topics. Note the node ID (NID).

2. Create distinctive context items

Create four published context items at /admin/config/ai/context/items/add. Use unique content strings so they are easy to spot in the system prompt.

Label Taxonomy Terms scope Content snippet (example)
Climate context Topics: Climate, Use Case: "Working with Text" When responding to the user, include information about climate and weather and related topics
Sports context Topics: Sports, Use Case: "Working with Text" When responding to the user, include information about sports and exercise classes and related topics
Climate and Sports context Topics: Climate and Sports, Use Case: "Working with Text" When responding to the user, include information about climate, weather, sports, exercise classes, and related topics
Generic context (leave Taxonomy Terms empty), Use Case: "Working with Text" When responding to the user, include information about Drupal related topics

Publish all four items.

3. Configure the Content Type Agent

  1. Go to /admin/config/ai/context/settings/agents and open Edit context settings for the agent you will run in the debugger.
  2. Confirm Allow context injection is enabled.
  3. Subscribe to scopes each test run based on the table in section 5 below.
  4. Save.

4. Spoof the current node in AI Agents Debugger

For each article node, we'll use the debugger with the node page spoofed.

The debugger runs on an admin route, not a node page. Spoof the entity context so Taxonomy Terms can read the node's taxonomy references.

  1. Open /admin/config/ai/agents/debug.
  2. Select your test agent and model.
  3. Expand Advanced.
  4. In Spoof Tokens, enter (replace NID with the appropriate article node ID):
[entity_type]=node
[entity_id]=NID
  1. Enter a simple chat message (for example Show context types [add unique text here to avoid getting cached response]) and click Run Agent.

5. Verify selection in the debugger monitor

In the right-hand monitor panel:

  1. Open the AI Input / System Prompt entry for the run.
  2. Confirm the injected context block (between the --- lines) includes the expected context items only.

6. Try different combinations

Minimum test combinations:

Run Spoof Subscribe Must see Must not see
1 Climate node Climate C, CS, G S
2 Sports node Sports S, CS, G C
3 Climate+Sports node Climate + Sports all four —
4 Generic node Climate G only C, S, CS

7. Optional: confirm usage tracking

After a debugger run, open /admin/config/ai/context/usage and confirm usage records were created for the injected context items, with the spoofed node as the target entity.

8. Optional: subscription-based selection (without Match all)

To test agent subscriptions instead of Match all:

  1. Reset the agent Selection mode to Use default (minimal).
  2. On the agent context form, subscribe to Taxonomy Terms → Climate.
  3. Spoof the Climate article again and run the agent.
  4. Confirm CLIMATE-ONLY-CONTEXT-12345 appears even in minimal mode.
  5. Spoof the Sports article — Climate-scoped items should not appear unless the Sports term is also subscribed.

UI checks (from earlier steps in this MR)

  • Context item add form shows Taxonomy Terms with one autocomplete per vocabulary; AI Context Tags does not appear there.
  • Context Tags still appears as a separate scope (renamed from Tags).
  • Saved taxonomy scope values persist after reload on the edit form.

Post-merge steps

  • Existing sites: run drush updatedb -y so update 10015 enables the taxonomy scope config.
  • New installs: config is provided via config/install.
  • Cache rebuild if scope settings UI does not show the new scope immediately.

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