CrumbLLM 🥖🧠

Turn portable CRUMB memory into grounded summaries, risks, next actions, and better handoffs.

Looking for context routing and token optimization? CrumbContext now lives in its own standalone repository: XioAISolutions/CrumbContext.

CrumbLLM is the reasoning engine in the CRUMB ecosystem. It reads individual .crumb files or complete CRUMB packs and produces useful, inspectable work without silently trusting model output.

pip install crumb-llm
crumblm analyze examples/basic.crumb

What it does

• analyzes a single CRUMB or a directory of linked CRUMBs;
• summarizes project memory;
• identifies risks and unresolved constraints;
• proposes concrete next actions;
• improves handoffs for the next agent or human;
• exports CRUMB collections as training-ready JSONL;
• runs with cloud models, local model servers, or the built-in offline mock provider.

Every result passes quality gates for invalid JSON, hallucinated paths, empty output, and generic non-answers.

Pick a path

Analyze one CRUMB

crumblm analyze examples/basic.crumb

Analyze a complete project pack

crumblm analyze-pack examples/pack
crumblm risks examples/pack --format json
crumblm next examples/pack

Improve a handoff

crumblm improve examples/basic.crumb --out improved.txt

Use local AI without a cloud key

crumblm setup local --backend ollama --model <local-model>
# or
crumblm setup local --backend lmstudio --model <local-model>

crumblm status
crumblm analyze examples/basic.crumb

Export training data

crumblm export-dataset path/to/crumbs --out data/crumb_training.jsonl

Install

pip install crumb-llm

Optional extras:

pip install 'crumb-llm[openai]'
pip install 'crumb-llm[anthropic]'
pip install 'crumb-llm[scratch]'

CrumbLLM communicates with supported cloud and local-server providers through standard HTTP, so provider SDKs are optional rather than required.

Providers

Provider	Runs where	Key required?
mock	built into CrumbLLM	no
ollama	local server	no
lmstudio	local server	no
openai	cloud	yes
anthropic	cloud	yes
scratch	local experimental model	no

The default mock path makes the package runnable in tests and demonstrations without external services.

🔒 Provider keys are read from environment variables at call time. crumblm setup stores only non-secret routing configuration.

Commands

# Analyze one CRUMB
crumblm analyze examples/basic.crumb

# Analyze a pack
crumblm analyze-pack examples/pack

# Create a project summary
crumblm summarize examples/pack --out summary.md

# Classify risks
crumblm risks examples/basic.crumb --format text
crumblm risks examples/pack --format json

# Recommend next actions
crumblm next examples/pack

# Improve a handoff
crumblm improve examples/basic.crumb --out improved.txt

# Export a dataset
crumblm export-dataset path/to/crumbs --out data/crumb_training.jsonl

Every analysis command accepts either a .crumb file or a directory containing CRUMB files where applicable. Warnings are printed to stderr and included in JSON output.

Quality gates

CrumbLLM never treats model output as automatically trustworthy. Each AnalysisResult includes warnings generated by checks for:

• JSON validity — structured output must parse;
• hallucinated paths — file paths are compared with paths found in the source CRUMB;
• empty or generic output — boilerplate and unusably short answers are flagged.

from crumb_llm.crumb.loader import load_crumb
from crumb_llm.engine import CrumbEngine

result = CrumbEngine().analyze(load_crumb("examples/basic.crumb"))
print(result.text)
print(result.warnings)
print(result.ok)

How the CRUMB projects fit together

Crumb-Bob ──captures sessions──▶ .crumb files and packs
                                      │
crumb-format ──specifies + validates──┤
                                      ▼
CrumbContext ──routes + protects──▶ model-ready context
                                      │
                                      ▼
CrumbLLM ──summarizes · checks · plans · improves handoffs

Project	Responsibility
crumb-format	canonical format, parser, validator, linter, base CLI
Crumb-Bob	session capture and CRUMB generation
CrumbContext	safety-first context routing and exact-anchor protection
CrumbLLM	local/cloud reasoning over CRUMB files and packs

CrumbLLM bundles its own small CRUMB reader and does not require crumb-format at runtime. The projects remain independently installable with clean boundaries.

What CrumbLLM is not

• It is not the canonical CRUMB specification.
• It does not capture sessions.
• It does not automatically train models.
• Its experimental scratch model is not production-grade.
• It does not replace CrumbContext's routing and exactness layer.

Development

git clone https://github.com/XioAISolutions/CrumbLLM.git
cd CrumbLLM
python -m pip install -e '.[dev]'
pytest
crumblm analyze examples/basic.crumb

The CI suite tests Python 3.10–3.12, enforces independence from crumb-format, builds the distribution, verifies the zero-required-dependency wheel, installs it offline, and smoke-tests the CLI.

Experimental scratch model

The scratch provider is deliberately opt-in and requires PyTorch plus a compatible checkpoint.

pip install 'crumb-llm[scratch]'

Training never starts automatically and requires explicit confirmation. Treat this path as a research toy; use a supported cloud or local-server provider for serious work.

Contributing

Useful contributions include:

• stronger quality gates;
• additional provider adapters;
• adversarial CRUMB fixtures;
• better pack-level reasoning;
• improved structured-output validation;
• clearer local-model setup and diagnostics.

Keep CrumbLLM focused on reasoning over CRUMB artifacts. Context routing contributions belong in CrumbContext, while grammar and validation changes belong in crumb-format.

License

MIT © XIO AI Solutions