Saltar a contenido

Conceptos de Cartuchos

Un cartucho de conocimiento es una unidad distribuible de conocimiento de dominio — un corpus empaquetado de documentos, configuración de extracción y nodos de grafo pre-extraídos. Los cartuchos le enseñan a Rai cosas que no ha encontrado en tu proyecto: una metodología, un framework externo, una arquitectura específica del proyecto.

Por Qué Existen los Cartuchos

El Knowledge Graph es potente, pero solo sabe lo que ha visto. Un proyecto nuevo no tiene patrones, ni principios, ni decisiones de arquitectura en el grafo. Sin priming, Rai empieza cada sesión con cero conocimiento institucional.

Los cartuchos resuelven esto empaquetando conocimiento que puede distribuirse, instalarse e importarse al grafo en cualquier máquina. El cartucho raise-methodology — incluido con cada instalación de RaiSE — le enseña a Rai la propia metodología RaiSE. Puedes crear cartuchos específicos de proyecto para enseñarle a Rai la arquitectura de tu codebase, o cartuchos de comunidad para compartir conocimiento de dominio entre equipos.

Estructura de un Cartucho

Un cartucho es un directorio con un manifiesto y tres áreas de contenido:

my-cartridge/
├── CARTRIDGE.yaml      ← manifest: name, version, description, schema
├── corpus/             ← source documents (Markdown, text, code)
│   ├── principles.md
│   └── architecture.md
├── extractors/         ← extraction rules (YAML or Python)
│   └── concepts.yaml
└── instances/          ← pre-extracted graph nodes (JSON)
    └── nodes.json

CARTRIDGE.yaml

El manifiesto declara la identidad del cartucho y el esquema de extracción:

name: raise-methodology
version: 1.0.0
description: "Core RaiSE methodology — principles, patterns, and workflow"
tier: community
schema:
  node_types: [principle, pattern, guardrail, requirement]
  edge_types: [governed_by, depends_on, learned_from]

corpus/

Documentos crudos que son la fuente de verdad. Estos son los textos que Rai lee cuando el cartucho está activo. Markdown, texto plano y archivos de código son todos válidos.

extractors/

Reglas para convertir documentos del corpus en nodos del grafo. Los extractores declaran qué buscar — headings, secciones etiquetadas, símbolos de código — y cómo mapearlos a tipos de nodo.

instances/

Nodos de grafo pre-extraídos en formato JSON. Son el resultado de ejecutar los extractores sobre el corpus. Incluir instancias pre-extraídas hace que la instalación sea rápida — no hace falta ejecutar la extracción salvo que modifiques el corpus.

Ciclo de Vida del Cartucho

init → extract → validate → pack → publish
                                  → install
Fase Comando Qué sucede
init rai cartridge init Genera el scaffold de CARTRIDGE.yaml y la estructura de directorios
extract rai cartridge extract Ejecuta los extractores sobre el corpus, produce instances/
validate rai cartridge validate Verifica el cumplimiento del esquema y la integridad de las instancias
pack rai cartridge pack Crea el archivo distribuible .cartridge
publish rai cartridge publish Publica a un registro de cartuchos (no disponible en la beta 3.1.0)
install rai cartridge install Importa el cartucho al grafo local

Tiers

En la beta 3.1.0 solo existen cartuchos community: incluidos con RaiSE o instalados desde una ruta local. El cartucho raise-methodology es de tier community. Un registro hospedado para distribución versionada en equipo está en el roadmap de la plataforma — no forma parte de esta beta.

El Cartucho raise-methodology

Este es el ejemplo canónico de un cartucho. Se distribuye pre-instalado con RaiSE y puebla el grafo con:

  • Principios RaiSE (Jidoka, Kaizen, Poka-yoke, etc.)
  • El modelo de coaching Shu-Ha-Ri
  • Guardrails incorporados (TDD, disciplina de commits, modelo de ramas)
  • Patrones de ciclo de vida de skills

Cuando ejecutas rai session start, los nodos de grafo de este cartucho están entre las primeras cosas que se cargan en el contexto.

Próximos Pasos