Skip to content

Architecture

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

Entities

The module defines three 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.

  • Bundle entity: ai_context_item_type (config entity, default bundle: default)
  • Base table: ai_context_item
  • Data table: ai_context_item_field_data
  • Revision tables: ai_context_item_revision, ai_context_item_field_revision

ai_context_item_type (config entity)

Bundle definition for context items. Carries Scheduler third-party settings.

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.

AiFunctionCall plugin

The module provides one function call plugin (ai_context:get_relevant_ai_context_items) that agents can invoke as a tool. 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.

Event subscribers

Two event subscribers integrate with the AI Agents module:

  • AiContextSystemPromptSubscriber -- appends selected context to agent system prompts
  • AiContextAgentToolSubscriber -- tracks entity modifications by agent tools

See Events.

Hooks

The module implements several hooks and provides one alter hook for extending 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
  4. AiContextScopeResolver applies hard context filters and scores items against the request's scope subscriptions
  5. AiContextSubcontextResolver resolves child items for selected parents
  6. AiContextRenderer renders items within the token limit
  7. 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()
  4. Returns rendered text or the full AiContextResult

Subcontext integrity

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, 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