Skip to content

Architecture

This section provides a developer-oriented overview of the AI Context module's architecture.

Entities

The module defines two entity types:

ai_context_item (content entity)

The primary entity. Stores context text (markdown), scope values, target entity references, parent-child relationships, and moderation state. Extends EditorialContentEntityBase with translation and revision support. The entity type is bundleless.

  • Base table: ai_context_item
  • Data table: ai_context_item_field_data
  • Revision tables: ai_context_item_revision, ai_context_item_field_revision

Publishing defaults (default_status, new_revision) are stored in ai_context.settings and edited via AiContextItemSettingsForm at /admin/config/ai/context/settings/items. Scheduler settings for the entity type use Scheduler's no-bundle settings form (scheduler.no_bundle_entity_type_settings.ai_context_item).

ai_context_usage (content entity)

Stores usage tracking records -- which context items were selected, by which agent, on which route, and which tools/entities were involved.

Plugin system

AiContextScope plugins

The scope system is built on Drupal's plugin API. Scope plugins define categories/dimensions for context items. See Scope API and Custom scopes.

AiFunctionCall plugins

The module provides three function call plugins in the Context Tools (context_tools) function group for discovery, loading, and relevance-based selection:

  • ai_context:list_ai_context_items
  • ai_context:load_ai_context_item_by_id
  • ai_context:get_relevant_ai_context_items

See Function calls.

Services

The module registers over 20 services covering scope management, context selection, rendering, usage tracking, event handling, and routing. The request factory also provides convenience methods for non-agent consumers. See Services for the full reference.

Before depending on a service or class from contrib code, check API stability, which defines the public surface (request factory, request/result models, selector pipeline events, scope plugins) versus the internal selector pipeline and supporting services.

Event subscribers

Three event subscribers integrate with the module:

  • AiContextSystemPromptSubscriber -- appends selected context to agent system prompts via the AI Agents module (respects per-agent loop-aware injection when enabled)
  • AiContextAgentToolSubscriber -- tracks entity modifications by agent tools via the AI Agents module
  • AiContextScopeConfigSubscriber -- cleans stale scope values when dynamic scope configuration changes

Contrib modules may also subscribe to selector pipeline events to alter or observe selection output.

See Events.

Hooks

The module implements several hooks and provides alter hooks for scope plugin definitions and scope values. See Hooks.

Key data flows

Context selection pipeline (agent path)

  1. AiContextSystemPromptSubscriber listens for BuildSystemPromptEvent
  2. Builds an AiContextRequest via AiContextRequestFactory::fromAgent()
  3. AiContextSelectorInterface::select() loads published items in chunks (prefiltered via AiContextScopeIndexService when subscriptions exist)
  4. AiContextScopeResolver applies hard context filters and scores items against the request's scope subscriptions
  5. AiContextSubcontextResolver resolves child items for selected parents (skipped when subcontext_enabled is FALSE in ai_context.settings)
  6. AiContextSelectionEvents::ITEMS_SELECTED fires; subscribers may filter or replace the final item list (see Events)
  7. AiContextRenderer renders items within the token limit
  8. AiContextSelectionEvents::TEXT_RENDERED fires; subscribers may alter rendered text or merge cache metadata before the result is built
  9. Final text is appended to the agent's system prompt

Context access (non-agent path)

Non-agent modules can use the convenience methods on ai_context.request_factory:

  1. Caller invokes getRenderedContext() or getResult() on the factory
  2. Factory internally builds an AiContextRequest via fromParameters()
  3. Delegates to AiContextSelectorInterface::select() (including selector pipeline events documented in Events)
  4. Returns rendered text or the full AiContextResult

Subcontext integrity

Subcontext is gated by the Enable subcontext hierarchy setting in ai_context.settings (subcontext_enabled). When disabled, parent/type fields are cleared on save and AiContextSubcontextResolver is not invoked during selection.

Subcontext relationships are enforced as a persistence contract on ai_context_item entities, not only during context selection. The entity validation layer prevents self-parenting, nested subcontexts, and converting items with children into subcontexts. It also requires subcontext_type when a parent is selected. Parent deletion clears child parent and subcontext_type references.

See Services for the validator and hierarchy services, Subcontext for site-builder guidance, and Hooks for constraint registration and delete cleanup.

Usage tracking pipeline

  1. AiContextSystemPromptSubscriber captures the runner ID on AgentStartedExecutionEvent
  2. After context selection, records usage via AiContextUsageTracker
  3. AiContextAgentToolSubscriber listens for AgentToolFinishedExecutionEvent and records tool usage and entity modifications