Metadata-Version: 2.4
Name: rlat
Version: 3.0.0
Summary: Knowledge-model retrieval for AI assistants — base-first, dense-only, three storage modes
Author: Kane Snyder
License: # Business Source License 1.1
        
        ## Parameters
        
        - **Licensor**: Kane Snyder
        - **Licensed Work**: Resonance Lattice, including each version first publicly released by Licensor.
        - **Change Date**: Four years from the date each version of the Licensed Work is first publicly released.
        - **Change License**: Mozilla Public License 2.0
        
        ## Additional Use Grant
        
        You may make production use of the Licensed Work for your own internal business purposes, including as part of software development workflows, CI/CD pipelines, build systems, developer tools, coding assistants, automation, evaluation, testing, retrieval pipelines, context assembly, orchestration, and other internal engineering systems.
        
        You may use the Licensed Work as a dependency, tool, or input within your own projects and services, and you may use, distribute, and commercialise the outputs produced through your permitted use of the Licensed Work, provided that your use does not involve offering the Licensed Work itself, or a modified version of it, to third parties on a hosted, managed, embedded, or redistributed basis as a Competitive Offering.
        
        Without a separate commercial licence from Licensor, you may not:
        
        1. offer the Licensed Work, or a modified version of it, to third parties as a hosted or managed service;
        2. embed, bundle, redistribute, or sublicense the Licensed Work, or a modified version of it, in a commercial product or service where the Licensed Work provides a substantial part of the core functionality;
        3. offer a paid product or service to third parties that substantially overlaps with the core functionality of the Licensed Work, including query, retrieval, routing, orchestration, or context-assembly functionality for LLM assistants, coding assistants, or developer workflow tools;
        4. sell support, services, or access for a product whose core commercial value is substantially derived from the Licensed Work in a manner that competes with Licensor's commercial offering.
        
        ### Definitions
        
        "Internal Use" means use within your own organisation and its affiliates for your own business operations, and not for providing the Licensed Work itself to third parties as a product or service.
        
        "Hosted or Managed Service" means making the Licensed Work available to third parties as a service, including SaaS, API, platform, or managed offering, where third parties access or benefit from a substantial set of the Licensed Work's functionality.
        
        "Embedded" means including the Licensed Work's source code, object code, executable binaries, or required packaged components within a product or service offered to third parties.
        
        "Competitive Offering" means a paid product or service offered to third parties that substantially overlaps with the core functionality of the Licensed Work. A product is not a Competitive Offering merely because it was developed using the Licensed Work internally.
        
        ### For the avoidance of doubt
        
        - internal organisational use is permitted;
        - use of the Licensed Work in internal developer workflows is permitted;
        - creating software with the help of the Licensed Work is permitted;
        - ownership of your own code, prompts, data, and outputs remains yours;
        - this licence governs the Licensed Work itself, not independent software you create that does not include, embed, redistribute, or offer the Licensed Work or a modified version of it in violation of this licence.
        
        ## Notice
        
        The Business Source License (this document, or the "License") is not an Open Source license. However, the Licensed Work will eventually be made available under an Open Source License, as stated in this License.
        
        ## Terms
        
        The Licensor hereby grants you the right to copy, modify, create derivative works, redistribute, and make non-production use of the Licensed Work. The Licensor may make an Additional Use Grant, above, permitting limited production use.
        
        Effective on the Change Date, or the fourth anniversary of the first publicly available distribution of a specific version of the Licensed Work under this License, whichever comes first, the Licensor hereby grants you rights under the terms of the Change License, and the rights granted in the paragraph above terminate.
        
        If your use of the Licensed Work does not comply with the requirements currently in effect as described in this License, you must purchase a commercial license from the Licensor, its affiliated entities, or authorized resellers, or you must refrain from using the Licensed Work.
        
        All copies of the original and modified Licensed Work, and derivative works of the Licensed Work, are subject to this License. This License applies separately for each version of the Licensed Work, and the Change Date may vary for each version of the Licensed Work released by Licensor.
        
        You must conspicuously display this License on each original or modified copy of the Licensed Work. If you receive the Licensed Work in original or modified form from a third party, the terms and conditions set forth in this License apply to your use of that work.
        
        Any use of the Licensed Work in violation of this License will automatically terminate your rights under this License for the current and all other versions of the Licensed Work.
        
        This License does not grant you any right in any trademark or logo of Licensor or its affiliates (provided that you may use a trademark or logo of Licensor as expressly required by this License).
        
        TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS, EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND TITLE.
        
        MariaDB hereby grants you permission to use this License's text to license your works, and to refer to it using the trademark "Business Source License", as long as you comply with the Covenants of Licensor below.
        
        ## Covenants of Licensor
        
        In consideration of the right to use this License's text and the "Business Source License" name and trademark, Licensor covenants to MariaDB, and to all other recipients of the licensed work to be provided by Licensor:
        
        1. To specify as the Change License the GPL Version 2.0 or any later version, or a license that is compatible with GPL Version 2.0 or a later version, where "compatible" means that software provided under the Change License can be included in a program with software provided under GPL Version 2.0 or a later version. Licensor may specify additional Change Licenses without limitation.
        
        2. To either: (a) specify an additional grant of rights to use that does not impose any additional restriction on the right granted in this License, as the Additional Use Grant; or (b) insert the text "None".
        
        3. To specify a Change Date.
        
        4. Not to modify this License in any other way.
        
Project-URL: Homepage, https://github.com/tenfingerseddy/resonance-lattice
Project-URL: Repository, https://github.com/tenfingerseddy/resonance-lattice
Keywords: retrieval,ai-assistants,context-injection,knowledge-model,semantic-search
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: Other/Proprietary License
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.11
Description-Content-Type: text/markdown
License-File: LICENSE.md
License-File: NOTICE
Requires-Dist: numpy>=1.24
Requires-Dist: scipy>=1.11
Requires-Dist: zstandard>=0.22
Requires-Dist: huggingface_hub>=0.20
Requires-Dist: tokenizers>=0.15
Requires-Dist: onnxruntime>=1.17
Requires-Dist: portalocker>=2.8
Provides-Extra: build
Requires-Dist: transformers<5,>=4.48; extra == "build"
Requires-Dist: torch<2.12,>=2.0; extra == "build"
Requires-Dist: onnxscript>=0.1; extra == "build"
Provides-Extra: llm
Requires-Dist: anthropic>=0.25; extra == "llm"
Provides-Extra: ann
Requires-Dist: faiss-cpu>=1.13; extra == "ann"
Provides-Extra: gpu
Requires-Dist: onnxruntime-gpu>=1.17; extra == "gpu"
Provides-Extra: bench
Requires-Dist: rank_bm25>=0.2; extra == "bench"
Requires-Dist: beir>=2.0; extra == "bench"
Requires-Dist: memory-profiler>=0.61; extra == "bench"
Requires-Dist: anthropic>=0.25; extra == "bench"
Requires-Dist: chromadb>=0.4; extra == "bench"
Requires-Dist: sentence-transformers>=2.5; extra == "bench"
Requires-Dist: psutil>=5.9; extra == "bench"
Requires-Dist: scikit-learn>=1.3; extra == "bench"
Provides-Extra: watch
Requires-Dist: rlat[build]; extra == "watch"
Requires-Dist: watchdog>=4.0; extra == "watch"
Provides-Extra: fabric
Requires-Dist: azure-identity>=1.15; extra == "fabric"
Requires-Dist: azure-storage-file-datalake>=12.14; extra == "fabric"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1; extra == "dev"
Requires-Dist: hypothesis>=6.90; extra == "dev"
Requires-Dist: ruff>=0.2; extra == "dev"
Requires-Dist: pyright>=1.1.400; extra == "dev"
Provides-Extra: all
Requires-Dist: rlat[ann,bench,build,llm,watch]; extra == "all"
Dynamic: license-file

<p align="center">
  <img src="docs/assets/lockup-horizontal.svg" alt="Resonance Lattice" width="640">
</p>

# Resonance Lattice (`rlat`)

[![PyPI](https://img.shields.io/pypi/v/rlat?label=pypi%20rlat)](https://pypi.org/project/rlat/)
[![Python](https://img.shields.io/pypi/pyversions/rlat)](https://pypi.org/project/rlat/)
[![License: BSL 1.1](https://img.shields.io/badge/license-BSL%201.1-blue.svg)](LICENSE.md)
[![Hugging Face](https://img.shields.io/badge/%F0%9F%A4%97%20datasets-tenfingers-yellow)](https://huggingface.co/tenfingers)

> **A knowledge model that knows its own world.** One portable `.rlat` file carries your corpus — docs, code, notes — plus what's been learned about the world that corpus covers: stable facts, standing constraints, and what was tried and failed. Every learned item carries a receipt. Local, citeable, drift-checked. Proven in three unrelated worlds: a Fabric tenant, a garden, a law practice.

`rlat` is a semantic layer over unstructured data. It packages a corpus into a single `.rlat` file you own; where a semantic data model captures the meaning of a database, a knowledge model captures the meaning of unstructured text — plus every coordinate needed to find, cite, and verify the source. You query it with one CLI command and feed the results to whichever AI assistant you already use (Claude Code, Cursor, Aider, your own agent). No hosted index, no LLM in the retrieval loop, no API key to search.

## What you get

- **One file you own.** Embeddings + source coordinates + content hashes + learned facts, all in one ZIP. Open it with `unzip`, inspect it with `jq`. Three storage modes — `bundled` (source inside the file), `local` (source on disk, reconcile with `rlat refresh` or live with `rlat watch`), `remote` (HTTP-pinned, SHA-verified, reconcile with `rlat sync`) — switchable in place with `rlat convert`, no rebuild.
- **Every passage cited, drift-checked.** Each result is `(text, source_file, char_offset, char_length, content_hash, drift_status)`. If a source file changed since the build, the result says so instead of silently returning stale text. `--verified-only` refuses unverified evidence outright.
- **It knows its own world.** Three kinds of learned content, each proven to change answers for the better, each with a published receipt:
  - **World facts** — stable facts about your environment that no document states ("the tenant runs an F64 capacity", "watering is restricted to twice a week"). The capture path is validated: 0.86 precision, 1.00 recall, and zero personal facts captured across seven deliberate traps. [Receipt](https://github.com/tenfingerseddy/resonance-lattice/blob/main/benchmarks/attribute_gate_e2c/DESIGN.md)
  - **Standing constraints** — rules every answer must respect ("no synthetic fertiliser", "we don't take family-law matters"). Tested in three unrelated worlds — a Fabric tenant, a home garden, a law practice. Without the rules served, answers broke them most of the time (15 of 24 Fabric items; 23 of 24 garden and legal items). With them served, violations nearly disappeared (1 of 15; 3 of 23), and no unrelated question lost its answer. Receipts: [Fabric](https://github.com/tenfingerseddy/resonance-lattice/blob/main/benchmarks/constraint_band/VERDICT.md), [garden + law practice](https://github.com/tenfingerseddy/resonance-lattice/blob/main/benchmarks/constraint_band_xdomain/VERDICT.md)
  - **Tried-and-falsified findings** — "we tested X; it failed." Serving the verdict stopped every repeat recommendation of a falsified approach (0 of 7, against 6 of 7 when the same approach was described without its verdict — an 86-point gap). [Receipt](https://github.com/tenfingerseddy/resonance-lattice/blob/main/benchmarks/falsification_ledger/VERDICT.md)
- **Capture is low-friction and consent-gated.** Say "remember this" and the bundled `rlat-learn` skill captures it on your Claude subscription — you approve every fact, no API key. Explicit: `rlat capture-attribute km.rlat "..." --kind attribute|constraint|falsified` (or `rlat capture-env` to auto-read machine facts). Unattended: `rlat memory install-hooks --mine` opts a workspace into a four-gate session miner that learns world facts as you work. Every path drops facts about a *person* by design — that privacy gate held at zero leaks in validation.
- **A corpus that fills its own gaps — opt-in, gated.** The archive records what was asked and poorly covered. `rlat grow` fills the most-demanded, worst-covered gap; nothing lands without passing its gates. `--dry-run` shows the candidates first.
- **Nothing is forgotten silently.** Automatic cleanup of learned facts is **not** shipped: we built it, tested it live, and it failed its pre-registered safety bar — it suppressed a true fact and added no measurable value. The full failure record is published. [Receipt](https://github.com/tenfingerseddy/resonance-lattice/blob/main/benchmarks/r4_continuous_credit/DESIGN_CONFIRM.md) Corrections stay explicit: the newest value per subject wins, and `rlat lens` is the review/delete surface.
- **Trust surfaces throughout.** Verified retrieval, corpus self-audit (contradictions + demand gaps, stored at build), and a grounding directive at the top of every context block telling the consumer LLM how to weight the passages (`augment` / `knowledge` / `constrain`).
- **No API key required — bring your Claude subscription.** Retrieval never calls an LLM: `rlat search`, `profile`, `compare`, `summary`, `refresh`, `watch`, and `skill-context` run offline after a one-time `rlat install-encoder`. The LLM-driven loops run two ways, your choice. **Free on the subscription you already have**: bundled Claude Code skills drive deep research (`deep-research`), teach the file your world in-session with you approving every fact (`rlat-learn`), and run the whole curation loop (`rlat-gap-scan`, `rlat-contradictions`, `rlat-refresh-facts`, `rlat-curate`) — your assistant's own model does the reading and judging, which is typically a stronger model than a budget API call. **Or unattended with an API key** for automation and CI: `rlat deep-search` (~$0.009/question), `rlat grow`, the background capture hook. See [API keys](https://tenfingerseddy.github.io/resonance-lattice/api-keys.html).

## Install

```bash
pip install rlat[build]      # Python 3.11+; [build] adds the encoder deps for building
rlat install-encoder         # one-time, ~2 min on CPU
```

Query-only machines need just `pip install rlat` — no extras — to search a knowledge model someone else built.

## 60-second quickstart

```bash
cd my-project/
rlat init-project                       # auto-detects docs/ + src/, builds + writes a primer
rlat search my-project.rlat "how does auth work?" --format context
```

```markdown
<!-- rlat-mode: augment -->
> **Grounding mode: augment.** Use the passages below as primary context
> for this corpus's domain. Cite them when answering; prefer them over
> your training knowledge when the two conflict.

<!-- SOURCE docs/auth.md:1042+118 score=0.810 verified -->
Authentication is handled by ...
```

Now teach it a standing rule of your world, and see it served:

```bash
rlat capture-attribute my-project.rlat \
  "All schema changes go through the staging workspace first" --kind constraint

rlat search my-project.rlat "how do I deploy a schema change?" --format context
# → your standing constraints now render right after the grounding
#   directive, before any cited passage
```

`--format context` prints LLM-ready markdown — citations, drift status, the grounding directive, and the learned facts and rules of your world. Paste it into any assistant's prompt. Inputs are plain text (`.md`, `.txt`, source code, prose); convert PDF/DOCX to markdown first.

If your docs fit in your assistant's context window, `cat docs/*.md` is fine. `rlat` earns its keep when they don't — or when citations, drift checks, and a world that's learned over time matter. Full walkthrough: [Getting started](https://tenfingerseddy.github.io/resonance-lattice/getting-started.html).

### Don't want to build? Try a prebuilt `.rlat` first.

Five prebuilt knowledge models live on HuggingFace, ready to query in seconds — no encoder install, no build step. Remote-mode rlats pin to the source repo at a commit SHA and fetch source on demand (SHA-verified at query time); the bundled-mode rlat packs source inside the archive:

| Corpus | Source | Files | Passages | Filename | Mode |
|---|---|---:|---:|---|---|
| [`tenfingers/fabric-docs-rlat`](https://huggingface.co/datasets/tenfingers/fabric-docs-rlat) | [MicrosoftDocs/fabric-docs](https://github.com/MicrosoftDocs/fabric-docs) `docs` | 2,435 | 67,503 | `fabric-docs-bundled.rlat` | bundled |
| [`tenfingers/powerbi-developer-rlat`](https://huggingface.co/datasets/tenfingers/powerbi-developer-rlat) | [MicrosoftDocs/powerbi-docs](https://github.com/MicrosoftDocs/powerbi-docs) `powerbi-docs/developer` | 176 | 5,684 | `powerbi-developer.rlat` | remote |
| [`tenfingers/powershell-docs-rlat`](https://huggingface.co/datasets/tenfingers/powershell-docs-rlat) | [MicrosoftDocs/PowerShell-Docs](https://github.com/MicrosoftDocs/PowerShell-Docs) `reference` | 2,647 | 107,033 | `powershell-docs.rlat` | remote |
| [`tenfingers/python-stdlib-rlat`](https://huggingface.co/datasets/tenfingers/python-stdlib-rlat) | [python/cpython](https://github.com/python/cpython) `Doc` | 617 | 49,179 | `python-stdlib.rlat` | remote |
| [`tenfingers/tsql-docs-rlat`](https://huggingface.co/datasets/tenfingers/tsql-docs-rlat) | [MicrosoftDocs/sql-docs](https://github.com/MicrosoftDocs/sql-docs) `docs/t-sql` | 1,209 | 33,282 | `tsql-docs.rlat` | remote |

```bash
pip install rlat huggingface_hub
hf download tenfingers/python-stdlib-rlat python-stdlib.rlat --local-dir .
rlat search python-stdlib.rlat "asyncio Task cancellation" --top-k 5 --format context
```

All five are encoded with `gte-modernbert-base` 768d at the pinned revision documented in [`docs/internal/BENCHMARK_GATE.md`](docs/internal/BENCHMARK_GATE.md), so retrieval quality matches anything you build locally.

## Use it with your AI assistant

`rlat` is assistant-neutral — every result is portable markdown. Pipe `rlat search ... --format context` into any prompt, or use `rlat skill-context` for Anthropic-skill `!command` blocks ([Skills](https://tenfingerseddy.github.io/resonance-lattice/skills.html)). For compliance work where wrong-but-confident is unacceptable: `--mode constrain --strict-names --verified-only`.

In Claude Code, a bundled `deep-research` skill drives a plan → retrieve → refine → synthesize loop for cross-file questions — no API key, your subscription covers the LLM hops. The same loop runs as `rlat deep-search` for other agents and CI (Anthropic API key required — [API keys](https://tenfingerseddy.github.io/resonance-lattice/api-keys.html)).

## What's measured

Every claim against named alternatives on committed test sets, designs pre-registered before the runs — methodology and reproduction in [Benchmarks](https://tenfingerseddy.github.io/resonance-lattice/benchmarks.html). The world-learning receipts are linked inline above; headline retrieval numbers:

| Bench | Result |
|---|---|
| **Hallucination** (Microsoft Fabric, 63 hand-written questions, Sonnet 4.6, relaxed rubric) | `rlat deep-search`: **92.2% accuracy / 2.0% answerable hallucination** vs LLM-only **56.9% / 19.6%**. `--mode knowledge` drops to **0%** answerable hallucination at the same accuracy. [Full matrix](https://tenfingerseddy.github.io/resonance-lattice/benchmarks.html#hallucination). |
| **Query latency + on-disk size** (1K-passage corpus, Intel CPU + OpenVINO) | Warm query p50 **17 ms** vs Chroma **145 ms**; **2.7 MB** on disk vs Chroma **8.6 MB**. |
| **Retrieval quality** (BEIR-5 mean nDCG@10, gte-modernbert-base 768d) | **0.5144** locked floor — beats BGE-large by **+0.026** and E5-large by **+0.081** on the same `rlat` stack. [BENCHMARK_GATE.md](docs/internal/BENCHMARK_GATE.md). |

## Documentation

User docs — rendered — at **https://tenfingerseddy.github.io/resonance-lattice/**:

- [Getting started](https://tenfingerseddy.github.io/resonance-lattice/getting-started.html) — first knowledge model in 15 minutes
- [CLI reference](https://tenfingerseddy.github.io/resonance-lattice/cli.html) — every command, every flag
- [Core features](https://tenfingerseddy.github.io/resonance-lattice/core-features.html) — what `rlat` enables
- [Claims](https://tenfingerseddy.github.io/resonance-lattice/claim-system.html) — how learned facts are captured, trusted, served, and corrected
- [Benchmarks](https://tenfingerseddy.github.io/resonance-lattice/benchmarks.html) — measured numbers vs named baselines, with run artifacts
- [Skills](https://tenfingerseddy.github.io/resonance-lattice/skills.html) — Anthropic-skill `!command` integration
- [Storage modes](https://tenfingerseddy.github.io/resonance-lattice/storage-modes.html) — bundled / local / remote decision guide
- [API keys](https://tenfingerseddy.github.io/resonance-lattice/api-keys.html) — when a key is needed (and the free alternatives)
- [FAQ](https://tenfingerseddy.github.io/resonance-lattice/faq.html) — common questions, including licence
- [Glossary](https://tenfingerseddy.github.io/resonance-lattice/glossary.html) — terminology

Engineering reference (in-repo): [ARCHITECTURE.md](docs/internal/ARCHITECTURE.md) — three-layer thesis + module map · [STORE.md](docs/internal/STORE.md) — `.rlat` ZIP format spec (nothing proprietary) · [HONEST_CLAIMS.md](docs/internal/HONEST_CLAIMS.md) — calibrated claims, known limits · [VISION.md](docs/VISION.md) — the why.

## License

[BSL-1.1](LICENSE.md). Source-available, commercial-use restricted during the change-licence window. See the [licence FAQ](https://tenfingerseddy.github.io/resonance-lattice/faq.html) for the change date and what it means in practice.

Issues, contributions, and corrections welcome at [tenfingerseddy/resonance-lattice](https://github.com/tenfingerseddy/resonance-lattice).
