librosys

Generic Rust framework for editorial and educational document pipelines. Provides reusable crates consumed via path dependency by implementation projects.

Architecture

librosys enforces a consumer-inversion constraint: framework crates contain zero references to any consumer project. Consumers implement the public traits and inject their logic via Arc<dyn Trait>.

Consumer project
    └── implements: ContentLoader, PedagogyEngine, ChapterConfig
    └── depends on: librosys-mcp, librosys-rag, librosys-suggestions
                         ↓                   ↓
                 librosys-rag-core     librosys-processor
                 (trait interfaces)    (ODT/DOCX/typst)

Crates

Crate	Type	Responsibility
librosys-rag-core	lib	EmbeddingProvider, VectorStore, Retriever trait interfaces
librosys-rag	lib	RAG implementation: fastembed (ONNX) + instant-distance vector index
librosys-mcp	lib + bin	MCP server framework; ContentLoader, PedagogyEngine, ChapterConfig public traits; Cedar authorization
librosys-processor	lib + bin	ODT/DOCX extraction, text corrections, typst generation, bookmarks, textboxes
librosys-suggestions	lib + bin	AI suggestion generation and merge: LanguageTool, Claude, OpenAI, n8n webhooks
librosys-watcher	lib + bin	File watcher; debounced git commits to author-edits; writes .watcher/status.json

Public API (stable traits)

These traits are the framework's public contract. Breaking changes require updating all consumers.

librosys-mcp

• ContentLoader — load/query structured document sections
• PedagogyEngine — pedagogy-aware content enrichment
• ChapterConfig — chapter-level configuration injection

librosys-rag-core

• EmbeddingProvider — text → Vec<f32>, with embed_batch support
• VectorStore — insert, search, persist, load
• Retriever — query interface over a VectorStore

Implementations live in the consuming project. The framework ships Mock* implementations for use in framework-level tests only.

Content Type Taxonomy

SectionContent carries six typed arrays that consumers populate and the framework indexes for RAG retrieval:

Type	Key fields	RAG use
concept	term, definition, related_terms	vocabulary lookup
exercise	instruction, difficulty	practice retrieval
reflection	question, topic	metacognitive prompts
example	text, context	illustrative retrieval
guideline	behavior, indicator	authoring rules
glossary-entry	term, definition, chapter_origin	cross-chapter glossary

Schemas live in reflection/schemas/. Adding a new type requires a schema file there and a new match arm in ingest.rs chunk routing. See ADR 0001.

Build

# Debug / release
cargo build --workspace
cargo build --workspace --release

# Tests (372+ tests, 6 pre-existing ignored)
cargo test --workspace
cargo test -p librosys-processor

# Quality gate
cargo clippy --workspace -- -D warnings
cargo fmt --all

# License and advisory check
cargo deny check

# Full CI gate (fmt-check + clippy + test + deny)
just ci

Shorthand aliases: just b (release build), just t (test), just c (clippy), just f (fmt).

Just recipes are organized into modules under justfiles/: build.just, ci.just, dev.just, test.just. The root justfile imports them all.

Features

librosys-suggestions exposes optional features to avoid pulling in unused HTTP clients:

librosys-suggestions = { path = "...", features = ["languagetool", "claude"] }

Feature	Enables
core (default)	Base suggestion types + reqwest
languagetool	LanguageTool HTTP analyzer
claude	Claude semantic analyzer
openai	OpenAI analyzer
n8n	n8n webhook dispatcher (HMAC signing)
all	All of the above

RAG cache

The first run using librosys-rag downloads the ONNX model to fastembed_cache/. This directory is git-ignored and requires internet access on first use only.

Adding a consumer

1. Add path dependencies in consumer Cargo.toml:

   librosys-mcp = { path = "../librosys/crates/librosys-mcp" }
   librosys-rag = { path = "../librosys/crates/librosys-rag" }
   

2. Implement ContentLoader and PedagogyEngine in the consumer crate.
3. Verify consumer still compiles after framework changes:

   cd ../your-consumer && cargo build --workspace 2>&1 | grep "^error"
   

License

MIT — see Cargo.toml workspace metadata.