Metadata-Version: 2.4
Name: rlat
Version: 2.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.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.12
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
Provides-Extra: build
Requires-Dist: transformers>=4.48; extra == "build"
Requires-Dist: torch>=2.0; extra == "build"
Requires-Dist: onnxscript>=0.1; extra == "build"
Provides-Extra: optimise
Requires-Dist: anthropic>=0.25; extra == "optimise"
Requires-Dist: torch>=2.0; extra == "optimise"
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"
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,optimise]; extra == "all"
Dynamic: license-file

# Resonance Lattice (`rlat`)

> **Give your AI assistant a local, citeable, drift-checked knowledge model of your docs, code, and notes.** One file you own. Every passage cited. No hosted index, no LLM in the retrieval loop.

`rlat` packages a corpus — your codebase, your documentation, your research notes — into a single `.rlat` file. Where a semantic data model captures the meaning of a database, a knowledge model captures the semantic shape of unstructured text plus every coordinate needed to find, cite, and verify the underlying source. You query it with a CLI command and feed the results to whichever AI assistant you're already using (Claude Code, Cursor, Aider, Continue, your own agent).

## What it does

- **One `.rlat` file you own.** Embeddings + source coordinates + content hashes — all in one ZIP. Open it with `unzip`, inspect the registry with `jq`. No hosted index, no proprietary binary, no vendor lock-in.
- **Every passage carries provenance.** Each result is `(text, source_file, char_offset, char_length, content_hash, drift_status)`. Citation is free. Drift detection is free. Refusal on stale evidence is one flag away.
- **No LLM in the retrieval loop.** `rlat search`, `rlat profile`, `rlat compare`, `rlat summary`, `rlat refresh`, `rlat skill-context`, `rlat memory`, and the entire RQL surface need no API key and no model call. After a one-time `rlat install-encoder` (downloads the 768d encoder), local-mode build/search workflows run offline. Remote-mode `rlat sync` and `rlat freshness` are network-backed by design (HTTP + SHA-pin verify); `rlat optimise` and the `rlat deep-search` CLI verb are the two opt-in commands that need an Anthropic API key — see [docs/user/API_KEYS.md](docs/user/API_KEYS.md).
- **A grounding directive your LLM sees.** `rlat search --format context` and `rlat skill-context` stamp an explicit instruction at the top of the markdown they emit (`augment` / `knowledge` / `constrain`) telling the consumer LLM how to weight the passages vs its training. The directive is non-negotiable — every consumer of the corpus sees the same rule.
- **Three storage modes, switchable in place.** `bundled` (zstd-framed source inside the file, fully self-contained), `local` (default — source on disk, reconcile via `rlat refresh`), `remote` (HTTP-pinned, SHA-verified, reconcile via `rlat sync`). Switch with `rlat convert` — no rebuild, embeddings preserved.
- **Multi-hop research, free with your Claude subscription.** A `deep-research` skill ships in `.claude/skills/` that drives a plan → retrieve → refine → synthesize loop natively in your Claude Code session — same loop and prompts as the `rlat deep-search` CLI verb, but no API key required because the LLM hops run through your existing Claude subscription. The CLI verb is the same loop exposed for non-Claude-Code agents / CI / batch consumers (Anthropic API key required).

## Quickstart (~2 min)

```bash
pip install rlat[build]                 # base + transformers/torch for first build
rlat install-encoder                    # one-time, ~2 min on CPU
rlat init-project                       # auto-detects docs/ + src/, builds + writes a primer
rlat search myproject.rlat "how does auth work?"
```

Once you have a `.rlat`, query-time only needs the base install — `pip install rlat` (no extras) on a different machine is enough to search a knowledge model someone else built. Full walkthrough: [docs/user/GETTING_STARTED.md](docs/user/GETTING_STARTED.md). Full CLI reference: [docs/user/CLI.md](docs/user/CLI.md).

## A real query, end-to-end

```bash
rlat build ./docs ./src -o resonance-lattice.rlat
rlat search resonance-lattice.rlat "How does verified retrieval work?" \
  --top-k 2 --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.

<!-- docs/internal/STORE.md:10094+56 score=0.832 verified -->
## Verified retrieval (`store.verified` — WS3 #292 port)

<!-- docs/user/GLOSSARY.md:10864+279 score=0.758 verified -->
**Verified retrieval** — the contract that every passage in every `.rlat` carries
source provenance + content hash, so query-time results can be cited back to
source and drift can be detected. `rlat`'s single biggest architectural
advantage vs. opaque-embedding-store retrievers.
```

Zero LLM calls, zero network round-trip, all local. That block drops straight into a Claude / Cursor / agent prompt. Each comment line is a stable citation anchor your assistant can preserve in its answer; the `verified` tag is its drift contract; the grounding-mode header is the rule the LLM is being asked to follow.

## Use it with your AI assistant

`rlat` is assistant-neutral — every result is portable markdown your assistant of choice can read.

### Claude Code

A `deep-research` skill ships in `.claude/skills/`. For cross-file synthesis questions ("why did we pick X over Y?", "what are the trade-offs across Y?"), it drives a plan → retrieve → refine → synthesize loop natively in your Claude Code session. No API key required — your Claude subscription covers the LLM hops. For one-shot fact lookups, use `rlat search`. See [docs/user/SKILLS.md](docs/user/SKILLS.md) for skill `!command` integration with citations + drift status pre-baked.

### Cursor, Aider, Continue, CLI-only, CI

```bash
# Pipe the markdown straight into your assistant's prompt
rlat search myproject.rlat "how does auth work?" --format context > context.md

# Or for compliance / audit work where wrong-but-confident is unacceptable:
rlat search myproject.rlat "what's our SOX retention policy?" \
  --format context --mode constrain --strict-names --verified-only
```

The output is plain markdown with citation anchors and a grounding-mode directive header. Paste it into your assistant's system prompt or include it via your IDE's context-injection mechanism. For programmatic multi-hop research outside Claude Code, `rlat deep-search` runs the same loop as the skill but as a CLI command (Anthropic API key required, ~$0.009-0.025 per question — see [API_KEYS.md](docs/user/API_KEYS.md)).

## What's measured

Every claim against named alternatives on committed test sets — methodology and reproducibility recipes in [docs/user/BENCHMARKS.md](docs/user/BENCHMARKS.md).

| Bench | Result |
|---|---|
| **Hallucination** (Microsoft Fabric, 63 hand-written questions, Sonnet 4.6, relaxed rubric) | `rlat deep-search` (default `--mode augment`): **92.2% accuracy / 2.0% answerable hallucination** at $0.009/q, vs LLM-only **56.9% / 19.6%**. `--mode knowledge` variant drops to **0% answerable hallucination** at the same accuracy; `--mode constrain` hits **91.7% distractor refusal** — pick for compliance / audit. Full 11-lane matrix in [BENCHMARKS.md](docs/user/BENCHMARKS.md#hallucination-reduction). The `--strict-names` namecheck gate catches the failure mode where the encoder surfaces a similarly-named real entity for a fake-product-name distractor and the LLM confidently answers about the wrong entity. |
| **Token spend** (rlat repo, 20 questions, **single-shot** retrieval — note: predates `deep-search`) | `rlat skill-context --mode constrain` $0.012 per correct answer vs grep+read $0.044 (3.7× cheaper) vs full-corpus dump $0.796 (67× cheaper). Absolute accuracy is lower (35% vs 85%) — single-shot trades accuracy for cost. Deep-search lanes pending v2.0.1. |
| **Session-start primer** (`resonance-lattice.rlat`, 25 scenarios × 5 lanes, Sonnet 4.6) | Code primer (`rlat summary`) wins **3/5 orientation**; memory primer (`rlat memory primer`) wins **5/5 memory recall**; `both_primers` loaded carries **48% turn-1 correct** vs cold's **0%**. Code primer ~1,708 tok/call, memory primer ~746 tok/call, both ~2,454 tok/call (~1,400× smaller than a full-corpus dump). [BENCHMARKS.md § Session-start primer](docs/user/BENCHMARKS.md#session-start-primer). |
| **Query latency + on-disk size** (1K-passage corpus, Intel CPU + OpenVINO) | Warm query p50 **17 ms** vs Chroma **145 ms** (8.5× faster); **2.7 MB** on disk vs Chroma **8.6 MB** (3.2× smaller). |
| **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 (apples-to-apples). [BENCHMARK_GATE.md](docs/internal/BENCHMARK_GATE.md). |

## How it's built

Three layers: a **field** (`gte-modernbert-base` 768d CLS+L2, dense cosine, FAISS HNSW) routes the query to ranked passage IDs; a **store** (the `.rlat` archive) resolves IDs back to source bytes and verifies drift; **no reader** — `rlat` returns passages, your assistant composes synthesis. Single recipe — no rerank, no lexical sidecar, no query-prefix tuning, no auto-mode router. Empirically validated to match or beat tuned alternatives. Deep dive: [docs/internal/ARCHITECTURE.md](docs/internal/ARCHITECTURE.md).

## Documentation

- [docs/user/GETTING_STARTED.md](docs/user/GETTING_STARTED.md) — first knowledge model in 15 minutes
- [docs/user/CLI.md](docs/user/CLI.md) — every command, every flag
- [docs/user/CORE_FEATURES.md](docs/user/CORE_FEATURES.md) — seven things `rlat` enables
- [docs/user/BENCHMARKS.md](docs/user/BENCHMARKS.md) — measured numbers vs named baselines
- [docs/user/SKILLS.md](docs/user/SKILLS.md) — Anthropic-skill `!command` integration
- [docs/user/STORAGE_MODES.md](docs/user/STORAGE_MODES.md) — bundled / local / remote decision guide
- [docs/user/API_KEYS.md](docs/user/API_KEYS.md) — when an Anthropic API key is needed (and the free alternatives)
- [docs/user/FAQ.md](docs/user/FAQ.md) — common questions, including licence
- [docs/user/GLOSSARY.md](docs/user/GLOSSARY.md) — terminology
- [docs/internal/ARCHITECTURE.md](docs/internal/ARCHITECTURE.md) — three-layer thesis + module map
- [docs/internal/KNOWLEDGE_MODEL_FORMAT.md](docs/internal/KNOWLEDGE_MODEL_FORMAT.md) — `.rlat` v4.1 ZIP format spec (open it with `unzip` and `jq`; nothing proprietary)
- [docs/internal/HONEST_CLAIMS.md](docs/internal/HONEST_CLAIMS.md) — calibrated claims, known limits
- [docs/internal/BENCHMARK_GATE.md](docs/internal/BENCHMARK_GATE.md) — locked floor + reproduction recipe
- [docs/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](docs/user/FAQ.md) 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).
