Context Scope

The Context Scope system describes where context items apply and how consumers rank them. Agents and other consumers can subscribe to scope values to prioritize relevant context, but a matching subscription does not guarantee that an item reaches the final prompt.

How scopes work

Each scope defines a set of values that can be assigned to Context Items. For example, the Use Case scope has values such as Working with Text and Working with Canvas. The Language scope has values for each language configured on your site.

When editing a context item, you select which scope values apply. When configuring an agent, you select which scope values the agent should prioritize. The scope resolver then scores each context item based on how well its scope values align with the agent's subscriptions.

Selection has several stages:

Published, accessible items become candidates.
Explicit exclusions and contextual mismatches remove items.
Global, situational-match, and explicitly included items receive their existing priority.
Remaining applicable items are scored against subscriptions.
Global-item and token limits determine the final rendered result.

Scope matching

The AiContextScopeResolver service scores context items against scope subscriptions and applies hard context filters. Items that match more subscribed scope values receive higher scores and are more likely to be selected.

Scopes have two independent weights: a display weight that controls their order in forms and tabs (lower = first), and a scoring weight that controls how much influence each scope has over subscription scores. The built-in display order is Global, Use Cases, Context Tags, Roles, Languages, Site Sections, Entity Types, Taxonomy Terms, and Specific Entities: agent categorization first, then the Roles audience gate, then page-derived scopes from broadest to narrowest. Global, Roles, Languages, and Specific Entities do not participate in subscription scoring. Custom scopes appear according to their declared display_weight. Scoring weights below 1 are treated as 1.

These are separate operations. Site Sections, Entity Types, and Taxonomy Terms can all filter by the request context, contribute to subscription scoring, and -- in Relevant selection mode and above -- qualify a positive request-context match as situational-match on their own, without requiring a subscription (a scope plugin capability that custom scopes can also declare). Languages filters by the request context and situationally matches in Relevant+, but does not support subscriptions: a language tag is a restriction, not an affinity. Use Cases and Context Tags contribute only to subscription scoring. Roles is a hard filter only: a matching role never auto-includes the item. Specific Entities filters and qualifies exact matches as exact-match but does not support subscriptions. One matching scope does not override another scope that rejects an item.

Some scopes also support contextual detection -- they can automatically determine the detected value from the request context. For example:

Language scope uses the shared content-language detector (path prefix, same-site Referer, then Drupal content-language negotiation)
Site Section scope matches the request URL path against configured patterns
Entity Types scope detects the request entity's type and bundle
Taxonomy Terms scope reads taxonomy references on the request entity
Specific Entities scope identifies the entity being worked on
Roles scope checks the acting user's Drupal roles. A match does not auto-include the item; it only avoids excluding it.

Leaving a scope blank on a Context Item means that the scope does not restrict the item for hard filtering. During subscription scoring, though, a blank scope earns no credit for that dimension -- it needs a different subscribed scope to match, Relevant-mode situational-match, or Broad mode to be selected without an override.

See Context Selection for the complete pipeline, priority order, scoring rules, selection modes, and limits.

Scope settings

Manage scopes at /admin/config/ai/context/settings/scope. Each scope can be individually enabled or disabled. Some scopes have additional settings (e.g., Site Section has configurable URL patterns).

Disabled and unavailable scopes are ignored at runtime. They do not appear on item or consumer forms, listing pills, subscription summaries, or the scope field formatter. They do not filter or score items. Saving those forms does not delete stored item values or consumer subscriptions. When the scope is enabled again, or becomes available, the stored values apply without a re-save.

This keep-on-save rule does not override two existing item rules. Saving an item as Global still clears its other scopes. A subcontext that inherits parent scope still stores no scope of its own.

Language is unavailable when the site has only one language. The Languages row on the scope settings page shows as Unavailable, and Language settings cannot be changed until a second language exists. Recipes that ship language: en no-op on a single-language site and start applying when another language is added.

For custom scope plugins, see Custom scopes.

Built-in scopes

The AI Context module ships with nine scope types. Each can be enabled or disabled at /admin/config/ai/context/settings/scope.

Global

Mark context items as global to give them priority for every consumer. Global items bypass scope matching and do not require consumer subscriptions.

When you save a context item with global enabled, previous scope settings on that item are cleared, including Roles. Leave global disabled to configure scope filters and categories instead. Global plus Roles cannot coexist on the same item.

When more published global items exist than the configured global item limit, the selector includes higher Priority values first. When priority ties, shorter content is preferred. The highest item ID breaks remaining ties for deterministic selection.

Global items remain subject to publication, view access, Never include, global-item, and token limits. Global items are considered before per-consumer Always include overrides during merge. Global and Always include settings give items priority; neither guarantees that complete content reaches the prompt. Do not use them as the only delivery control for compliance-critical instructions.

Consumer subscriptions: Not applicable (global items apply to every consumer)
Contextual detection: Not applicable
Multiple values: No (global is a boolean toggle)

Roles

Limit a context item to one or more Drupal user roles. When any roles are selected, the item is available only if the acting user has at least one of those roles. When no roles are selected, this scope does not restrict the item.

Roles is a hard filter only. A matching role does not auto-include the item and does not raise its subscription score. Consumers cannot subscribe to Roles.

This is not a security or access-control boundary for viewing or editing the item. It only controls whose AI interactions can receive the item. These are Drupal user roles (the Roles page under People), not LLM message roles such as system, user, or assistant.

Roles is also different from Specific Entities. Choosing a user entity there means "include this item when someone is working on that user's profile." Roles means "include this item only when the person running the AI interaction has one of these roles," regardless of the content being edited.

Available values come from the site's role list, including Anonymous user and Authenticated user. Deleting a role removes it from context items and the scope index. A leftover stale role ID never matches.

If the acting account cannot be determined, an item with role values is excluded.

Roles cannot be combined with Global. Saving with Global enabled clears other scope values, so there is no "always include this for editors" toggle. Use a non-global item plus another inclusion reason (subscription, situation, or Always include) when the item should appear for that audience.

Always include on an agent bypasses hard filters, including Roles. An agent that always includes a role-gated item injects it regardless of who is asking. Do not always-include the item if the audience gate must hold for that agent.

Roles matching example

Assume these Context Items:

E is scoped to Editor.
A is scoped to Authenticated user.
U has no Roles values.

An Editor request considers E, A, and U. A Contributor request considers A and U. An anonymous request considers only U, unless an item is scoped to Anonymous user.

Consumer subscriptions: No
Contextual detection: Yes (acting user's roles)
Multiple values: Yes

Use case

Categorize context items by the type of task they support. Default values (ordered alphabetically in the UI):

Working with Canvas (working_with_canvas) -- for agents that operate in a visual canvas editor. Requires Canvas 1.8.0 or later on Canvas-enabled sites; see Canvas sites.
Working with Media (working_with_media) -- for agents that work with images, video, or other media
Working with People (working_with_people) -- for agents that help with people-related tasks such as profiles or team content
Working with Text (working_with_text) -- for agents that help create or edit text content

Additional values can be added via hook_ai_context_scope_values_alter().

Use Case matching example

Assume these Context Items:

TC has Working with Text and Working with Canvas.
T has only Working with Text.
C has only Working with Canvas.
U has no Use Case values.

When Use Case is the only subscription, a Text subscription considers TC and T; a Canvas subscription considers TC and C. A subscription to both values ranks TC highest; T and C receive half of the available Use Case credit.

Use Case does not inspect the request page or the user's task, and U (no Use Case values) no longer earns automatic credit for a Use Case subscription: it scores zero on that dimension and needs a different subscribed scope to match, or Broad mode, to be selected.

Consumer subscriptions: Yes
Contextual detection: No
Multiple values: Yes

Language

Scope context items to specific languages configured on your site. The available values are automatically populated from Drupal's language configuration.

Language scope requires more than one language. On a single-language site it is hidden from the context item form, does not filter items, and does not remove stored language values when you save. Languages never appears on consumer subscription forms, at any language count. Add a second language to make it available; existing stored item values then apply without editing the item again. Uninstalling a language removes that language from context items, consumer subscriptions, and the scope index.

Language scope is separate from the Context Item entity's language and translations. Scope values determine eligibility and situational inclusion in Relevant mode and above, not ranking. Entity translations determine which text is injected after an item is selected.

Language matching example

Assume these Context Items:

T has English and Spanish translations and English + Spanish scope.
E has English scope.
S has Spanish scope.
U has no Language scope.

On an English request, T and E pass the Language hard filter (U is neutral and always passes too); on a Spanish request the filter removes E, leaving T and U.

Languages does not participate in subscription scoring. In Relevant mode and above, T and E are situationally included on an English request because they match the detected language. U is language-universal: it is not excluded, and Language does not lift it. A Use Case subscription still scores independently, and Language still acts as a hard filter -- removing E on a Spanish request -- even though it contributes no score. If the detected language cannot be determined, Language scope does not remove the item.

After selection, T uses its English translation for an English content language and its Spanish translation for a Spanish content language. U uses its original translation when it has no translation for the detected content language.

The Language scope plugin uses the same content-language detection as translation selection: request path prefix, same-site Referer, then Drupal content-language negotiation.

In Relevant selection mode and above, a positive Language match also qualifies the item as situational-match on its own, even without a subscription -- see Situational-match.

Consumer subscriptions: No
Contextual detection: Yes (shared content-language detector)
Multiple values: Yes
Management link: /admin/config/regional/language

See the Multilingual documentation for more on languages.

Context Tags

Organize context items using tags from the AI Context Tags taxonomy vocabulary (ai_context_tags, installed with the module). Context Tags provide free-form categorization of context items beyond the structured scope types.

Context Tags work through consumer subscriptions, not contextual detection. The typical workflow is:

Add terms to the AI Context Tags vocabulary at /admin/structure/taxonomy/manage/ai_context_tags/overview.
Edit a context item and select one or more tags in the Context Tags scope field.
Configure a consumer and subscribe it to the same tags in its context settings.
When that consumer runs, context items tagged with its subscribed tags score higher and are more likely to be selected.

Context Tag scope does not read tags from the entity a consumer is working on. There is no automatic matching against a taxonomy reference field on the request entity. To prioritize context based on taxonomy terms referenced by the entity being processed, use the Taxonomy Terms scope instead. (A custom module can supply a tag value at runtime with hook_ai_context_scope_values_alter(), but the module ships no such behavior for Context Tags.)

Context Tags matching example

Assume BL has Brand and Legal, B has only Brand, L has only Legal, and U has no Context Tags scope. When Context Tags are the only subscription, a Brand subscription scores BL and B; a Legal subscription scores BL and L. A subscription to both tags ranks BL highest; B and L receive half of the available Context Tag credit. U scores zero on the Context Tags dimension -- it no longer receives automatic credit as generic context -- so it needs a different subscribed scope, or Broad mode, to be selected.

Matching uses taxonomy term IDs, not labels. Context Tags do not inspect the request entity or user task. Deleting a tag term removes it from context items, consumer subscriptions, and the scope index.

Consumer subscriptions: Yes
Contextual detection: No
Multiple values: Yes
Management link: /admin/structure/taxonomy/manage/ai_context_tags/overview

Taxonomy Terms

Associate context items with taxonomy terms from your site's vocabularies. When the request content entity references matching terms, those context items pass the hard context filter and can also be prioritized through agent subscriptions.

The context item form lists each site vocabulary (except AI Context Tags) with its own autocomplete field. Stored values are taxonomy term IDs. Values are not preloaded into checkbox options because large vocabularies would be too expensive to load on every form build.

Supported term reference fields

Matching reads the term reference fields on the request content entity. Two field types are inspected:

Entity reference (core entity_reference) fields whose target type is Taxonomy term. This is how most sites store terms, and it always works.
Dynamic entity reference fields, when the Dynamic Entity Reference module is installed. DER records the target type per value rather than once for the whole field, so a mixed field contributes only the values that point at taxonomy terms; nodes, users, and other targets in the same field are ignored. Taxonomy Terms works normally when DER is not installed -- the module is never required to use this scope.

Other reference field types are not inspected, including Entity Reference Hierarchy (entity_reference_hierarchy) and Entity Reference Revisions. Terms stored only in those fields will not make a context item match. If you need them, write a custom scope plugin.

Note: The AI Context Tags vocabulary (ai_context_tags) is excluded because it is reserved for the Context Tags scope. Context Tags categorize context items for consumer subscriptions and do not inspect taxonomy references on the request content entity. Use Context Tags when you want tag-based consumer subscriptions; use Taxonomy Terms when context should match site vocabularies referenced by the entity being processed, such as Topics or Categories.

Taxonomy Terms matching example

Assume C is scoped to Climate, CS to Climate and Sports, and U has no Taxonomy Terms values.

While viewing an Article tagged Climate, Sports, and Events, C, CS, and U pass the hard filter.
While viewing a Blog post tagged only Climate, C, CS, and U pass the hard filter.
While viewing content tagged only Sports, CS and U pass the hard filter.
If no request entity can be resolved, C and CS fail the hard filter; U still passes. Chatbots and AI Assistants must supply that entity; see Page and entity context.

Any matching term is enough for a scoped item to pass. Matching uses taxonomy term IDs, not labels. Deleting a term removes it from context items, agent subscriptions, and the scope index.

In Relevant selection mode and above, a positive Taxonomy Terms match also qualifies the item as situational-match on its own, even without a subscription -- see Situational-match.

Consumer subscriptions: Yes
Contextual detection: Yes (reads core entity reference and, when the module is installed, dynamic entity reference term fields on the request entity)
Multiple values: Yes
Management link: /admin/structure/taxonomy

Site section

Scope context items to URL path patterns. This allows context to be associated with specific sections of your site based on URL structure.

Patterns support wildcards:

/blog/* -- matches any path under /blog/
/products/* -- matches any path under /products/
/about -- matches the exact /about path

Site sections can include both predefined patterns (configured in settings) and custom patterns added per context item. Each custom pattern is stored as custom: plus the path. The stored value is limited to 255 characters, and custom: uses 7 of those, so each custom pattern can be at most 248 characters. For longer URL structures, add a named section in Site Section settings; the item then stores only the short section ID.

If there is no request path, items with Site Section values are rejected. Items without Site Section values remain unrestricted by this scope.

On API-proxy routes such as /api/deepchat, the HTTP path is the proxy endpoint, not the page the visitor is viewing. Callers can supply the effective page path on the request (attribute ai_context_path, or a POST/JSON path value). Site Sections prefers that hint over getPathInfo(). The hint is used only for path-pattern matching. See Page and entity context and request info resolver.

Site Section matching example

Assume B uses a predefined Blog section with /blog/*, P uses the custom pattern /products/*, BP uses both, and U has no Site Section values.

On /blog/post-1, B, BP, and U pass the hard filter.
On /products/widget, P, BP, and U pass the hard filter.
On /contact, only U passes the hard filter.
Without a request path, only U passes the hard filter.

Any matching value is enough for a scoped item to pass. Patterns match the complete path, with * as a wildcard.

Consumer subscriptions score surviving items by overlap with their stored section values. Custom patterns in subscriptions are compared as literal stored values; subscription scoring does not independently evaluate those patterns against the request path.

In Relevant selection mode and above, a positive Site Section match also qualifies the item as situational-match on its own, even without a subscription -- see Situational-match.

Consumer subscriptions: Yes
Contextual detection: Yes (matches the effective page path against configured patterns, including a caller-supplied path on API-proxy requests)
Multiple values: Yes
Settings form: /admin/config/ai/context/settings/scope/site_section

Entity Types

Scope context items to entity type and bundle combinations (for example, node:article). Active whenever the request entity is an entity of a matching bundle — on the frontend (viewing a blog post) or in the admin UI (editing or revising that post).

Unlike Specific Entities, which matches individual entities, the Entity Types scope applies to every entity in the configured bundle.

Values are built dynamically from the entity types enabled in scope settings at /admin/config/ai/context/settings/scope/entity-type.

Deleting a bundle removes that type:bundle value from items, agent subscriptions, and the scope index. A type-level All value (node:_all) is kept, because All still means every current and future bundle. Removing a type from Entity Types settings clears every stored value for that type, including All.

Entity Types matching example

Assume A is scoped to Content: Article, P to Content: Basic page, AP to both bundles, and U has no Entity Types values.

While working with an Article, A, AP, and U pass the hard filter.
While working with a Basic page, P, AP, and U pass the hard filter.
If no request entity can be resolved, only U passes the hard filter.

Consumer subscriptions then score the surviving items by Entity Types overlap. A specific bundle matches that bundle. A type-level All value (node:_all) matches every current and future bundle of that type, in either direction. In Relevant selection mode and above, a positive Entity Types match also qualifies the item as situational-match on its own, even without a subscription -- see Situational-match.

If no request entity type can be resolved, items with Entity Types values are rejected. Items without Entity Types values remain unrestricted by this scope. Chatbots and AI Assistants must supply that entity; see Page and entity context.

Consumer subscriptions: Yes
Contextual detection: Yes (resolves entity type and bundle from the request entity or request context)
Multiple values: Yes
Settings form: /admin/config/ai/context/settings/scope/entity-type

Specific Entities

Associate context items with specific content entities (nodes, media, taxonomy terms, etc.) using dynamic entity references. This is a hard filter, not a ranking boost. When a consumer operates on one of the targeted entities, the associated Context Items enter the exact-match group in every selection mode, including Minimal -- a different, unconditional tier from the Relevant-and-above situational-match that Languages, Site Sections, Entity Types, and Taxonomy Terms use. If the consumer is working on different content, or no request entity can be resolved, the targeted items are left out. They still respect publication, access, exclusion, and token limits.

The scope restricts this item to the targeted content. Other items (Global, Always include, subscription matches, Relevant or Broad fill) can still be selected alongside it.

Specific entities are set directly on the context item form using the entity reference field within this scope, rather than through the scope checkboxes.

Specific Entities requires the Dynamic Entity Reference module, which supplies the entity_items field. Without it the scope is listed as Unavailable on the scope overview, exactly like Languages on a single-language site: it is hidden from the context item form, it does not filter or match, and stored values are kept rather than deleted. Installing the module makes it available without re-saving items.

Specific Entities matching example

Assume 123 targets Article #123, 456 targets Article #456, and U has no specific entities.

While working with Article #123, 123 is an exact-match, 456 is removed, and U remains an ordinary candidate.
While working with Article #456, 456 is an exact-match, 123 is removed, and U remains an ordinary candidate.
Without a request entity, both targeted items are removed and U remains.

An item with multiple targets matches when any target matches. Specific Entities matches an exact entity instance; use Entity Types to apply context to every entity in a bundle.

Consumer subscriptions: Not applicable (context is applied based on the entity being worked on, not consumer configuration)
Contextual detection: Yes (resolves the request entity from the route, agent token contexts, or explicit tool parameters -- see Page and entity context)
Multiple values: Yes (can target multiple entities)
Requires: dynamic_entity_reference; otherwise Unavailable

For subcontext items with inherit_parent_scope enabled, entity item matching uses the parent's entity items, not values stored on the child. See Parent scope.

Worked examples

Subscription match does not guarantee selection

An item tagged Editorial matches a consumer's Tag subscription. That match improves the item's score, but another item may still be selected first when the token budget is reached or when other applicable items score higher.

Contextual mismatch excludes an item

An item has Use Case = Working with Text and Language = French. The consumer subscribes to Working with Text, but the request context is English. The use-case match improves ranking only after hard filters pass; the language mismatch makes the item inapplicable for that request.

Entity Types is applicability, not a guarantee

An Article editorial standards item is scoped to node:article. When the consumer works with an article, the item is applicable and can be scored against Entity Types subscriptions. It is not guaranteed to survive ranking and the token budget.

Specific Entities differs from Entity Types

An item that targets Article #123 is considered only when the consumer is working with Article #123. On any other page it is left out. A match is an exact-match: it is collected in every selection mode, including Minimal. Other items can still appear in the same prompt.

Entity Types such as node:article apply more broadly to every article. A positive Entity Types match is a situational-match (Relevant and above) and can also earn subscription-scoring credit. It is not an exact-match.

Explicit override

A consumer's Always include override gives an item priority independently of ordinary subscription scoring and hard context filters. The item must still be published and accessible, and the rendered content can still be shortened or omitted by the token limit. Never include wins over Always include.

Global context

A Global item does not require a subscription. The item must still be published and accessible. If more published global items exist than the configured global-item limit, the selector uses Priority, then shorter content, then the highest item ID to choose which global items enter the selection set. The token budget still controls what is rendered.