Saltar a contenido

Knowledge Cartridges

A knowledge cartridge is a distributable unit of domain knowledge. It packages a corpus of documents, extraction configuration, and pre-extracted graph nodes into a format that Rai can load and query.

Cartridges answer the question: "How does Rai know about X?" — where X is a methodology, a framework, a codebase, or any domain that benefits from structured knowledge.

How Cartridges Work

Corpus (docs)  →  Extract (LLM)  →  Reconcile  →  Curate (HITL)  →  Pack
    ↓                  ↓                ↓               ↓              ↓
 markdown         GraphNode[]    phantom/orphan    human review    instances/
  files            raw nodes       detection        + edits       ready to load
  1. Corpus — markdown documents that contain the knowledge. These are the source of truth.
  2. Extract — an LLM reads each document and produces structured GraphNode entities with types, relationships, and metadata.
  3. Reconcile — automated checks detect phantom targets (referenced but missing nodes), orphan nodes (no connections), and cross-category edges.
  4. Curate — a human reviews extracted nodes, accepting, rejecting, or editing them. Curation state persists so you can resume across sessions.
  5. Pack — curated nodes are written to instances/ as JSON, ready for Rai to load into the knowledge graph.

Cartridge Structure

.raise/cartridges/my-cartridge/
  CARTRIDGE.yaml          # manifest: name, version, corpus paths, schema
  extractors/
    config.yaml           # which extractors run on which corpus files
  instances/
    core-knowledge.json   # extracted + curated nodes (generated)

The corpus itself can live anywhere — inside the cartridge directory, in docs/, or at any relative path. The manifest's corpus: field points to it.

CARTRIDGE.yaml

name: my-methodology
display_name: "My Methodology"
version: "1.0.0"
author: "Your Org"
license: "Apache-2.0"
tier: open               # open | community | verified | enterprise
description: >
  What this cartridge teaches Rai.

schema:
  module: raise_core.graph.models
  class_name: GraphNode

corpus:
  - ../../docs/**/*.md    # relative paths to source documents

requires:
  llm: any                # extraction needs an LLM

Types of Cartridges

Methodology Cartridge

Teaches Rai how to work — values, workflows, skills, governance model. Repo-agnostic: works in any project.

RaiSE ships with raise-methodology, which teaches Rai the RaiSE methodology. It is extracted from this documentation site.

Repo Cartridge

Teaches Rai about this specific project — architecture, ADRs, conventions, guardrails. Generated per-project, typically during onboarding (rai init).

Domain Cartridge

Teaches Rai about a specific domain — a framework, a library, an industry standard. Created by domain experts, distributed via cartridge registries.

CLI Commands

rai cartridge list                          # list installed cartridges
rai cartridge extract my-cartridge          # run extraction on corpus
rai cartridge extract my-cartridge --dry-run # preview without writing
rai cartridge curate my-cartridge start     # begin HITL curation session
rai cartridge curate my-cartridge status    # check curation progress
rai cartridge validate my-cartridge         # verify cartridge structure
rai cartridge init my-cartridge             # scaffold a new cartridge
rai cartridge pack my-cartridge             # package for distribution
rai cartridge install my-cartridge.cartridge.tar.gz          # install a cartridge
rai cartridge query my-cartridge "term"     # query cartridge nodes

Key Concepts

  • GraphNode — the atomic unit of knowledge. Has an id, type, content, source_file, and metadata (including relationships and categories).
  • Extractor — transforms source documents into GraphNode arrays. The LLMExtractor uses any OpenAI-compatible LLM with JSON mode.
  • Reconciler — detects structural issues (phantom targets, orphans, cross-category edges) in extracted nodes.
  • CurationSession — HITL workflow for reviewing, accepting, rejecting, and editing extracted nodes.

Further Reading