Metadata-Version: 2.4
Name: sheldon-context
Version: 0.1.0
Summary: Local-first, source-grounded context management for small language models.
Author: Om Bhojane
License-Expression: MIT
Project-URL: Homepage, https://sheldon.omisaur.app
Project-URL: Documentation, https://github.com/ombhojane/sheldon/tree/main/context-engine
Project-URL: Repository, https://github.com/ombhojane/sheldon
Project-URL: Issues, https://github.com/ombhojane/sheldon/issues
Keywords: context engineering,local ai,rag,small language models,source grounding
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: markdown-it-py<5,>=4.0
Provides-Extra: lsa
Requires-Dist: numpy>=1.24; extra == "lsa"
Provides-Extra: embeddings
Requires-Dist: sentence-transformers>=3.0; extra == "embeddings"
Provides-Extra: pdf
Requires-Dist: pypdf>=4.0; extra == "pdf"
Provides-Extra: mlx
Requires-Dist: mlx>=0.29; extra == "mlx"
Requires-Dist: mlx-lm>=0.31; extra == "mlx"
Requires-Dist: huggingface-hub>=0.30; extra == "mlx"
Provides-Extra: research
Requires-Dist: markdown-it-py==4.2.0; extra == "research"
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: tomli>=2; python_version < "3.11" and extra == "dev"
Requires-Dist: twine>=6; extra == "dev"
Dynamic: license-file

# 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

```bash
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:

```text
# Release state

Current release: 2.4.

The 2.3 line is supported for security fixes only.
```

Then compile it:

```bash
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

```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

```text
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

```bash
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:

```bash
sheldon research --help
```

## Optional local backends

```bash
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](https://github.com/ombhojane/sheldon)
- [Project site](https://sheldon.omisaur.app)
- [Issue tracker](https://github.com/ombhojane/sheldon/issues)

MIT licensed. Built by Om Bhojane.
