Sheldon

Local evidence in. Source-grounded context out.

Sheldon is a local-first context compiler for small language models. It turns Markdown, text, LaTeX, PDF, and structured records into compact context packets with visible citations, temporal state, conflict warnings, and a generation gate.

Sheldon does not hide a hosted model behind the package. Core ingestion, retrieval, state resolution, packet compilation, bundle verification, and the HTTP API run locally. Model calls are explicit and optional.

Install

python -m pip install sheldon-context

The distribution is named sheldon-context because the older sheldon name on PyPI belongs to an unrelated project. The command is simply sheldon, and the Python import is sheldon_context.

Five-minute path

Create a note:

# Release state

Current release: 2.4.

The 2.3 line is supported for security fixes only.

Then compile it:

sheldon --db /tmp/sheldon.db ingest release.md
sheldon --db /tmp/sheldon.db query "Which release is current?"

The packet includes the selected evidence and citations. With --json, inspect generation_gate.status before calling a model:

• ready: the cited sources and packet fingerprint are current.
• caution: generation is allowed, but a warning must be preserved.
• blocked: source drift or an unresolved integrity issue must be repaired.

Python

from pathlib import Path
from sheldon_context import LocalContextEngine

engine = LocalContextEngine(Path(".sheldon-context/context.db"))
try:
    engine.ingest_text(
        "Current release: 2.4. The 2.3 line gets security fixes only.",
        source="release-note",
        title="Release state",
    )
    result = engine.query("Which release is current?", token_budget=600)
    print(result["packet"])
    print(result["generation_gate"])
finally:
    engine.close()

What the compiler owns

local sources
    -> typed evidence and temporal state
    -> retrieval and conflict resolution
    -> budgeted, cited context packet
    -> generation gate and replayable bundle
    -> your local or self-hosted model

This boundary matters. Evidence can be present while a model still omits, misreads, or mixes it. Sheldon makes the pre-generation evidence path explicit and keeps generated answers separate from deterministic context artifacts.

Useful commands

sheldon --help
sheldon ingest --help
sheldon query --help
sheldon compile-context --help
sheldon bundle --help
sheldon verify-bundle --help
sheldon serve --help

The complete research and evaluation surface remains available under:

sheldon research --help

Optional local backends

python -m pip install "sheldon-context[lsa]"
python -m pip install "sheldon-context[embeddings]"
python -m pip install "sheldon-context[pdf]"
python -m pip install "sheldon-context[mlx]"

The dependency-free hashed and TF-IDF retrieval paths remain available without those extras. Sentence-transformer and MLX weights are never bundled into this package.

Research boundary

Sheldon is alpha research software. The repository includes frozen positive, mixed, and negative studies. Package verification proves artifact integrity and installability; it does not turn every experimental method into a confirmed accuracy improvement.

The current supported mechanism claim is narrow: reader adaptation and fixed demonstrations can improve how a local model uses supplied evidence. A universal context-rendering advantage, robust multi-source execution, and reliable abstention have not been established.

Links

• Source and full documentation
• Project site
• Issue tracker

MIT licensed. Built by Om Bhojane.