Crate context_weaver 

ContextWeaver

A lorebook engine for LLM role-playing applications, built on weaver-lang. ContextWeaver manages a collection of entries that are selectively activated based on conversation context and assembled into the final prompt sent to the model.

Architecture

┌─────────────────────────────────────────────────────┐
│  Host Application (LLM frontend)                    │
│                                                     │
│  Provides: chat history, character data, user prefs │
│  Receives: assembled context blocks for the prompt  │
└────────────────────────┬────────────────────────────┘
                         │
┌────────────────────────▼────────────────────────────┐
│  ContextWeaver                                      │
│                                                     │
│  ┌─────────────┐  ┌────────────┐  ┌─────────────┐   │
│  │  Lorebook   │  │ Activation │  │  Assembler  │   │
│  │  (entries)  │──│  Engine    │──│  (ordering, │   │
│  │             │  │            │  │   budgeting)│   │
│  └─────────────┘  └────────────┘  └──────┬──────┘   │
│                                          │          │
│  ┌───────────────────────────────────────▼──────┐   │
│  │  WeaverHost (EvalContext impl)               │   │
│  │  - namespace management                      │   │
│  │  - read-only enforcement                     │   │
│  │  - trigger collection (no output)            │   │
│  │  - document → recursive entry evaluation     │   │
│  └──────────────────────────────────────────────┘   │
│                                                     │
│  ┌──────────────────────────────────────────────┐   │
│  │  Plugin Interface                            │   │
│  │  - custom processors & commands              │   │
│  │  - activation hooks                          │   │
│  └──────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────┘
                         │
┌────────────────────────▼────────────────────────────┐
│  weaver-lang (template evaluation)                  │
└─────────────────────────────────────────────────────┘

Quick start

use context_weaver::{ContextWeaver, Lorebook, ChatMessage, Slot};

// Load a lorebook from disk
let book = Lorebook::load_from_directory("./my_character/lorebook")?;

// Configure the engine
let mut weaver = ContextWeaver::new(book);
weaver.set_variable("char", "name", "Aria");
weaver.set_variable("char", "class", "Mage");
weaver.set_variable("user", "name", "Player");

// Provide conversation context
let messages = vec![
    ChatMessage::user("I walk into the dark forest"),
    ChatMessage::assistant("The trees close in around you..."),
];

// Assemble activated entries into context blocks
let blocks = weaver.assemble(&messages)?;
for block in &blocks {
    println!("[{}] {}", block.slot, block.content);
}

Re-exports

pub use activation::ActivationEngine;

pub use activation::ActivationReason;

pub use activation::ActivationResult;

pub use activation::ActivationState;

pub use assembler::AssembledBlock;

pub use assembler::ContextAssembler;

pub use assembler::GuesstimationTokenizer;

pub use assembler::Slot;

pub use assembler::TokenBudget;

pub use assembler::Tokenizer;

pub use entry::Entry;

pub use entry::EntryMeta;

pub use host::NamespaceAccess;

pub use host::NamespaceConfig;

pub use host::WeaverHost;

pub use lifecycle::FnLifecycle;

pub use lifecycle::HookError;

pub use lifecycle::LifecyclePlugin;

pub use lifecycle::PostActivationCtx;

pub use lifecycle::PostAssembleCtx;

pub use lifecycle::PostEvaluateCtx;

pub use lifecycle::PreActivationCtx;

pub use lifecycle::PreEvaluateCtx;

pub use lifecycle::TriggerCtx;

pub use lifecycle::TurnAdvanceCtx;

pub use lorebook::Lorebook;

pub use lorebook::LorebookConfig;

pub use plugin::Plugin;

Modules

activation

Activation engine for entry matching.

assembler

Context assembler: orders evaluated entries and applies token budgets.

entry

Entry parsing and representation.

host

Host context implementation for ContextWeaver.

lifecycle

Lifecycle plugin system: hooks into the assembly pipeline.

lorebook

Lorebook: a collection of entries with shared configuration.

plugin

Plugin interface for extending ContextWeaver.

stdlib

Standard library of commands and processors for ContextWeaver.

Structs

ChatMessage

A chat message provided by the host application for activation scanning.

ContextWeaver

The main entry point for ContextWeaver.

EngineConfig

Top-level engine configuration.

EvaluatedEntry

An entry that has been evaluated to its final string content.

Enums

ChatRole

ContextWeaverError