1. Qué es y qué problema resuelve

Bienvenido. En los próximos minutos vas a conocer el módulo AI Context de Drupal. También se conoce como Context Control Center, o C C C. Los tres nombres se refieren al mismo proyecto y pueden aparecer mezclados en el código, la documentación y las incidencias.

Empecemos por el problema. Cuando un sitio Drupal usa inteligencia artificial, puede hacerlo de muchas formas: con un agente que redacta contenido, un botón de ayuda en el editor o un proceso que traduce páginas. El modelo de lenguaje sabe mucho sobre el mundo en general, pero no conoce tu sitio. No sabe cuál es el tono de tu marca, qué términos están prohibidos, cuáles son tus requisitos legales ni cuáles son los datos exactos de tu empresa.

AI Context resuelve este problema. Permite que los editores creen pequeñas piezas de conocimiento en formato Markdown, llamadas context items o elementos de contexto. Cada vez que una inteligencia artificial del sitio recibe una petición, el módulo selecciona las piezas relevantes y las añade al prompt del sistema.

Piensa en el módulo como una guía de estilo viva, gobernada y versionada, con un flujo editorial. Los agentes consultan esa guía antes de responder.

Hay un detalle importante: la selección es determinista y se basa en reglas. El módulo no le pregunta a una inteligencia artificial qué contexto debe usar. Aplica filtros, puntuaciones y prioridades. Así, el resultado es predecible y más fácil de depurar.

2. Estado del proyecto

El proyecto está alojado en GitLab, en Drupal punto org. Su rama principal se llama uno punto cero punto equis. El repositorio ya está clonado por SSH en la carpeta de proyectos de Drupal contrib.

El proyecto está en fase de candidata a lanzamiento. La etiqueta más reciente es uno punto cero punto cero, erre ce uno, después de cinco versiones beta. Esto significa que la API está cerca de estabilizarse, aunque todavía puede cambiar.

Es compatible con Drupal diez punto cinco y con Drupal once punto dos en adelante. Depende de los módulos AI y AI Agents, además de varios módulos del núcleo de Drupal: Content Moderation, Workflows, Taxonomy, Views, Options y Text.

Es un proyecto muy activo. Tiene alrededor de trescientos commits, y casi cien se han realizado durante los últimos tres meses. La mantenedora más activa es Kristen Pol, junto con Kurt Foster, Aidan Foster y Emma Horrell. También cuenta con más de doscientos archivos de pruebas unitarias, de kernel, funcionales y de JavaScript.

3. Las dos entidades

El módulo define dos tipos de entidad.

Context item

La entidad principal es context item, o elemento de contexto. Es una entidad de contenido con revisiones y traducciones, pero sin tipos o paquetes —bundles—. Guarda el texto en Markdown, los valores de alcance que veremos enseguida, referencias a entidades del sitio, una prioridad y relaciones de padre e hijo con otros elementos.

Como aprovecha las funciones editoriales de Drupal, admite moderación de contenido completa, por ejemplo, los estados de borrador y publicado. También permite la programación opcional con el módulo Scheduler. Así, podrías publicar el contexto de una campaña navideña el quince de noviembre y retirarlo automáticamente el veintiséis de diciembre.

Usage

La segunda entidad se llama usage, o uso. Es un registro de seguimiento que indica qué elementos se seleccionaron, para qué consumidor y en qué ruta, además de qué herramientas o entidades estuvieron involucradas. Sirve para saber qué contexto se utiliza realmente y cuál no.

4. Los scopes o alcances

Este es el concepto central del módulo, así que conviene entenderlo bien.

Cada elemento de contexto puede tener varios scopes, o alcances. Un alcance es una dimensión que indica en qué situación se aplica ese conocimiento. Los alcances son plugins de Drupal, por lo que se pueden ampliar. El módulo incluye los siguientes:

• Global: para elementos que se aplican siempre.
• Use Cases: casos de uso, como trabajar con texto o con Canvas.
• Context Tags: etiquetas libres.
• Languages: el idioma.
• Site Sections: secciones del sitio, determinadas por la ruta.
• Entity Types: el tipo de entidad y su paquete; por ejemplo, nodos de tipo artículo.
• Taxonomy Terms: términos de taxonomía.
• Specific Entities: una entidad concreta, como la página «Sobre nosotros».
• Roles: el rol de la persona usuaria.

Los alcances pueden influir de dos maneras distintas. Esta diferencia es clave.

Como filtro obligatorio

El alcance evalúa la petición actual y responde de una de estas tres formas: coincide, no coincide o es neutral. Si cualquier alcance indica que no hay coincidencia, el elemento queda descartado, sin importar el resultado de los demás. Por ejemplo, un elemento limitado al español nunca se incluirá en una petición en inglés.

Como puntuación por suscripción

Cada consumidor —por ejemplo, un agente— puede suscribirse a determinados valores, como un caso de uso o una etiqueta. Los elementos que comparten más valores con esa suscripción reciben más puntos. Si un elemento no obtiene puntos en ningún alcance al que el consumidor esté suscrito, su puntuación es cero y se descarta.

No todos los alcances tienen el mismo peso: los casos de uso valen el doble que los demás alcances temáticos.

5. El proceso de selección

Veamos el recorrido completo. Cuando llega una petición de inteligencia artificial, el selector sigue estos pasos:

1. Descarta los elementos no publicados, aquellos que la persona usuaria no puede ver y los marcados como «no incluir nunca».
2. Carga los elementos marcados como «incluir siempre».
3. Aplica los filtros obligatorios.
4. Recoge los elementos globales, hasta alcanzar el límite configurable.
5. Recoge las coincidencias exactas, como la entidad específica que se está editando.
6. Puntúa los elementos restantes según las suscripciones.
7. Según el modo de selección, añade coincidencias situacionales o completa la selección con el catálogo general.
8. Añade los subcontextos hijos.
9. Prepara el resultado respetando el límite de tokens.

El orden de prioridad al combinar los resultados es fijo: primero los elementos globales; después, los de inclusión forzada; luego, las coincidencias exactas; a continuación, los elementos puntuados; después, las coincidencias situacionales; y, por último, los elementos de relleno.

Hay tres modos de selección. Forman una progresión: cada modo incluye lo que ofrece el anterior.

Minimal

Es el modo más estricto. Incluye los elementos globales, los añadidos a la fuerza, las coincidencias exactas y las suscripciones explícitas. Se recomienda para catálogos grandes.

Relevant

Es el modo predeterminado. Incluye todo lo de Minimal y, además, los elementos que coinciden positivamente con la situación actual, como el idioma o el tipo de contenido, aunque el agente no esté suscrito a ese alcance.

Broad

Es el modo más amplio. Incluye todo lo anterior y también cualquier elemento publicado que supere los filtros. Los ordena por prioridad hasta completar el presupuesto de tokens.

La documentación repite una advertencia importante: «incluir siempre» da prioridad, pero no garantiza que el texto completo llegue al prompt. El límite de tokens siempre prevalece.

6. Cómo llega el contexto a la inteligencia artificial

El contexto puede llegar por tres vías.

La vía de los agentes

Un suscriptor de eventos escucha el evento de construcción del prompt del sistema de AI Agents. Ejecuta el proceso de selección, añade el contexto al final del prompt del agente y registra el uso.

La vía del chat genérico

Otro suscriptor escucha el evento que ocurre antes de generar una respuesta de AI, con prioridad menos cien. Si la operación es un chat y algún tipo de consumidor reconoce la petición por sus etiquetas, toma el mensaje más reciente de la persona usuaria como tarea y añade el contexto al prompt del sistema. Por esta vía entran, por ejemplo, los automators.

La vía de las herramientas

El módulo ofrece tres llamadas a funciones, agrupadas bajo el nombre Context Tools. Un agente puede invocarlas directamente para:

• listar elementos de contexto;
• cargar un elemento por su identificador;
• obtener los elementos relevantes para una tarea, ejecutando el proceso completo en un solo paso.

Además, cualquier otro módulo puede solicitar contexto directamente al servicio Selection Factory, sin pasar por eventos.

7. Los consumidores

Un consumidor es cualquier sistema que recibe contexto. Los tipos de consumidor también son plugins. El módulo incluye dos:

• Agent: para los agentes de AI Agents.
• Automator: para los AI Automators.

Otros proyectos, como AI CKEditor, pueden aportar sus propios tipos de consumidor.

Cada instancia de consumidor tiene su propia configuración: a qué alcances se suscribe, qué elementos debe incluir siempre o nunca, qué modo de selección utiliza y cuál es su límite de tokens.

Las instancias se identifican con este formato: tipo, dos puntos, identificador. Por ejemplo: «agent, dos puntos, mi agente».

8. El mapa del código

Al abrir el repositorio, puedes orientarte de esta manera.

En la raíz están los archivos del módulo y de instalación. Son grandes: el archivo de instalación supera los ciento cuarenta kilobytes porque acumula muchas funciones de actualización de las versiones beta. También hay un archivo de actualizaciones posteriores a la instalación.

Dentro de la carpeta src, estas son las áreas más importantes:

• Entity: contiene las dos entidades y sus controles de acceso.
• Service: es el corazón del módulo. Incluye Selector, que ejecuta el proceso de selección; Selection Factory, el punto de entrada público; Scope Resolver, que aplica filtros y puntuaciones; Subcontext Resolver; Renderer, que respeta el presupuesto de tokens; Token Estimator; Usage Tracker; y Consumer Router, que decide qué consumidor atiende una petición.
• Plugin: contiene los alcances, los tipos de consumidor, las llamadas a funciones y los plugins de Views, campos y validación.
• Event Subscriber: integra el módulo con AI y AI Agents.
• Model: contiene objetos de valor como Selection, Selection Params y Selection Result.
• Event: contiene dos eventos propios del proceso. El primero se dispara después de elegir los elementos y permite filtrarlos o reemplazarlos. El segundo se dispara después de generar el texto y permite modificarlo.

La carpeta docs contiene documentación completa, publicada con MkDocs y organizada en funcionalidades, desarrollo y contribución. Antes de modificar el código, conviene leer la documentación sobre arquitectura y selección de contexto. También hay que revisar el documento de estabilidad de la API, que indica qué clases son públicas y cuáles son internas.

El repositorio incluye, además, un submódulo llamado Document Loader, para importar archivos y páginas web al editor Markdown, y una receta de ejemplo con el contexto de una universidad ficticia. La receta es ideal para hacer pruebas.

9. Cómo contribuir

El flujo de contribución de Drupal punto org tiene algunos pasos particulares.

1. Busca o crea una incidencia en la cola del proyecto.
2. Desde la página de la incidencia, pulsa el botón para crear un issue fork.
3. Añade ese fork como un remoto por SSH en tu clon local.
4. Empuja una rama cuyo nombre incluya el número de la incidencia.
5. Abre una solicitud de integración, o merge request.

La regla del proyecto es que otra persona, distinta de quien hizo el trabajo, revise la solicitud. Si miras el historial, verás que casi todos los commits empiezan con «Issue», seguido del signo de número y el número de la incidencia.

En cuanto a calidad, el proyecto utiliza cinco herramientas: PHP CodeSniffer con los estándares de Drupal, PHPStan, CSpell para la ortografía, ESLint para JavaScript y Stylelint para CSS. Todas son obligatorias en el proceso de integración continua de GitLab. Si una falla, falla el proceso completo. Puedes ejecutarlas en local con Composer Lint o con el script lint punto sh.

Las pruebas usan PHPUnit, y la guía de pruebas está preparada para DDEV, el entorno recomendado. El proceso de integración continua prueba Drupal diez y Drupal once, además de las versiones mínima y máxima de PHP. La suite es tan grande que se ejecuta en paralelo. Toda funcionalidad nueva debe incluir pruebas.

Para empezar a contribuir, sigue este recorrido:

1. Levanta un sitio Drupal once con DDEV.
2. Instala el módulo con la receta de la universidad.
3. Crea un agente.
4. Activa el registro de depuración para observar qué contexto se selecciona y por qué.
5. Cuando entiendas el proceso en acción, busca en la cola una incidencia marcada como novice o relacionada con documentación y prepara tu primera solicitud de integración.

Resumen final

AI Context es una biblioteca de conocimiento gobernada para la inteligencia artificial de un sitio Drupal. Los editores escriben elementos de contexto en Markdown. Los alcances describen cuándo se aplica cada elemento. Los consumidores se suscriben a lo que necesitan. Y un proceso determinista filtra, puntúa, ordena y recorta los elementos dentro de un presupuesto de tokens, antes de añadirlos al prompt.

Si solo recuerdas tres cosas, que sean estas:

1. La diferencia entre los filtros obligatorios y la puntuación por suscripción.
2. La progresión de los modos Minimal, Relevant y Broad.
3. El límite de tokens siempre tiene la última palabra.

Fin del guion.