adaptergate 0.5.1__tar.gz

adaptergate-0.5.1/LICENSE

@@ -0,0 +1,189 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for describing the origin of the Work and
+      reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Support. While redistributing the Work or
+      Derivative Works thereof, You may accept support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or support.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 Kazdov
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+   implied. See the License for the specific language governing permissions
+   and limitations under the License.

adaptergate-0.5.1/NOTICE

@@ -0,0 +1,53 @@
+adaptergate
+Copyright (c) 2026
+Licensed under the Apache License, Version 2.0.
+
+This product builds upon the following research and software. All upstream
+work is credited to its authors; this project's contribution is its
+original implementation, integration, and the regression-gating system.
+
+============================================================================
+PAPERS (algorithmic foundations)
+============================================================================
+
+ProCL — arXiv 2605.13162
+  "Continual Fine-Tuning of LLMs via Program Memory"
+  Used in: src/adaptergate/core/procl.py
+  Our contribution: independent re-implementation from the paper, bug fixes
+  (composition cross-terms, dtype handling, autograd reset), production
+  integration. The algorithm is credited to the paper authors.
+
+Silent Collapse — arXiv 2605.14588
+  "Silent Collapse in Recursive Learning Systems"
+  Used in: src/adaptergate/observability/silent_collapse.py
+  Our contribution: independent re-implementation of the MTR framework.
+  The drift signature (H_g/H_0 < 0.5 with PPL_g/PPL_0 ≈ 1) is credited
+  to the paper authors.
+
+Online-LoRA — arXiv 2411.05663
+  "Online-LoRA: Task-free Online Continual Learning via LoRA"
+  Concepts of online distribution-shift detection informed our
+  regression-gating design.
+
+PreFT — arXiv 2605.14217
+  "Prefill-only Finetuning for Efficient Inference"
+  Referenced as a future integration once code is publicly released
+  by the authors. Not currently integrated.
+
+N-LoRA / O-LoRA — arXiv 2408.06133, arXiv 2310.14152
+  Orthogonal LoRA subspace work, referenced in the regression-gating
+  literature review.
+
+============================================================================
+SOFTWARE
+============================================================================
+
+vLLM — https://github.com/vllm-project/vllm — Apache License 2.0
+  Used as serving backbone via its public Python API.
+  No source modifications are distributed in this repository.
+
+bitsandbytes — Apache License 2.0
+  Used for 4-bit quantization.
+
+transformers, peft, accelerate (HuggingFace) — Apache License 2.0
+torch — BSD-3-Clause

adaptergate-0.5.1/PKG-INFO

@@ -0,0 +1,437 @@
+Metadata-Version: 2.4
+Name: adaptergate
+Version: 0.5.1
+Summary: CI gate for per-tenant LoRA adapters that update online. Slice-level reject explain. Serving-stack agnostic.
+Author: Kazdov
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/OriginalKazdov/adaptergate
+Project-URL: Repository, https://github.com/OriginalKazdov/adaptergate
+Keywords: llm,lora,regression,continual-learning,fine-tuning,evaluation
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: typer>=0.12
+Requires-Dist: pydantic>=2.9.0
+Requires-Dist: rich
+Provides-Extra: ml
+Requires-Dist: torch>=2.5.0; extra == "ml"
+Requires-Dist: transformers>=4.45.0; extra == "ml"
+Requires-Dist: peft>=0.13.0; extra == "ml"
+Requires-Dist: accelerate>=1.0.0; extra == "ml"
+Requires-Dist: bitsandbytes; extra == "ml"
+Requires-Dist: sentencepiece; extra == "ml"
+Requires-Dist: protobuf; extra == "ml"
+Requires-Dist: numpy; extra == "ml"
+Requires-Dist: pandas; extra == "ml"
+Requires-Dist: tqdm; extra == "ml"
+Provides-Extra: serve
+Requires-Dist: vllm; extra == "serve"
+Provides-Extra: sql-example
+Requires-Dist: sqlglot>=25.0.0; extra == "sql-example"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: ipython; extra == "dev"
+Dynamic: license-file
+
+# adaptergate
+
+**CI gate for per-tenant LoRA adapters that update online.**
+
+When a customer-specific LoRA adapter is about to be promoted to production,
+`adaptergate gate` evaluates the candidate against a per-tenant held-out set
+and refuses to promote it if aggregate quality drops more than ε. Rejected
+adapters go to a replay buffer for later analysis. CI-friendly exit codes.
+Serving-stack agnostic: you supply a scorer callable, we supply the gate.
+
+When your held-out queries carry slice tags (intent, language, difficulty,
+whatever) and natural-language text, adaptergate doesn't just say "score
+dropped." It tells you **which behavioral slice broke**, **shows you the
+failing query IDs**, and **describes what the failing queries have in
+common** — the line your on-call PM screenshots into Slack at 2am.
+
+```
+$ adaptergate gate \
+    --tenant acme \
+    --candidate adapter_v19 \
+    --baseline adapter_v18 \
+    --holdout data/acme_holdout.jsonl \
+    --scorer my_eval:score
+─────────────────────────────────── REJECTED ───────────────────────────────────
+Tenant:    acme
+Candidate: adapter_v19
+Baseline:  adapter_v18
+Score:     0.924 → 0.353  (Δ=-0.571, ε=0.02)
+Held-out:  n=25
+Reason:    REJECTED: aggregate 0.924 → 0.353 (Δ=-0.571) over n=25.
+           Drop exceeds ε=0.02.
+
+DRIVER SLICE: intent=billing_dispute   0.946 → 0.113  (Δ=-0.834, 10/10 regressed)
+  Pattern: all 10 failing queries contain: "order_id", "refund"
+  Failing query IDs: billing_1, billing_2, billing_3, billing_4, billing_5 + 5 more
+
+Slice breakdown (most-regressed first):
+  -0.834   10/10 regressed   intent=billing_dispute
+  -0.396   15/15 regressed   intent=order_status
+
+25 unique queries regressed (slice n_regressed values may sum higher when
+queries belong to multiple slices)
+$ echo $?
+1
+```
+
+That `Pattern: ...` line is N-gram frequency analysis — no LLM, no extra
+dependencies, no cloud calls. Just the common words across failing queries.
+Slack-paste-friendly by design.
+
+---
+
+## Why it exists
+
+> *91% of production LLMs experience silent behavioral drift within 90 days.
+> Detection lag from onset to first user complaint: 14-18 days.*
+> — InsightFinder, 2026
+
+The dominant failure mode for teams serving per-customer fine-tuned LLMs is
+**silent regression on online updates**: a sub-skill (e.g. `JOIN-with-aggregate`
+accuracy) collapses from 91% to 64% while the aggregate eval stays green at
+87%, and you only find out when a customer Slacks support two weeks later.
+
+### Where adaptergate sits in the landscape
+
+Generic LLM eval CIs ([Braintrust](https://www.braintrust.dev/),
+[DeepEval](https://deepeval.com/), [LangSmith](https://www.langchain.com/langsmith),
+[Promptfoo](https://www.promptfoo.dev/), [W&B Registry](https://wandb.ai/site/automations/))
+all support pre-deploy CI gating with non-zero exit on regression. They're
+built for the case where the artifact under test is a **prompt or chain
+commit**, scored against a single fixed dataset.
+
+Runtime guardrails ([Galileo Luna-2](https://galileo.ai/luna-2),
+[Arize](https://arize.com/), [Langfuse](https://langfuse.com/)) catch failures
+after the model has shipped.
+
+adaptergate is for the workflow those tools aren't built for:
+
+- **Per-tenant scoping** — each customer has its own held-out set; regression
+  is measured against that customer's queries, not a shared benchmark.
+- **Online update cadence** — every accepted user query may trigger a new
+  adapter version, not a quarterly retrain.
+- **LoRA-adapter aware** — the artifact under test is a binary adapter, not
+  a prompt commit.
+- **Replay buffer for rejected updates** — rejects don't disappear; they're
+  preserved with the full gate decision for later analysis or downstream
+  repair logic.
+
+Closest neighbors:
+
+- [Predibase / LoRAX](https://github.com/predibase/lorax) — per-tenant LoRA
+  *serving* and continuous fine-tuning, no CI gate primitive.
+- [Baseten rank-1 LoRA continual learning](https://www.baseten.co/research/write-small-learn-forever/)
+  — same problem shape (shadow replica, ring buffer for rollback) but it's
+  research infrastructure, not a product, and has no per-tenant eval gate.
+
+### What we measured
+
+Reference run on Qwen 2.5 Coder 14B (4-bit, RTX 4090) with ProCL multi-LoRA
+slots on BIRD-SQL `student_club`:
+
+| | Before update | After update | Δ |
+|---|---|---|---|
+| `student_club` memorize set | 55.7% | 82.3% | **+26.6pp** |
+| Held-out other DBs (forgetting check) | 45.0% | 55.0% | **+10.0pp** |
+
+Zero catastrophic forgetting. The gate fires when this property breaks —
+the moment a candidate update would have damaged the held-out other-DBs
+score, it gets blocked.
+
+---
+
+## Install
+
+```bash
+pip install adaptergate
+```
+
+Core install is lightweight (typer + pydantic + rich). The gate doesn't
+require torch, transformers, or any specific serving stack.
+
+For the BIRD-SQL example or ProCL/Silent Collapse reference implementations:
+
+```bash
+pip install "adaptergate[ml]"        # adds torch/transformers/peft/bitsandbytes
+pip install "adaptergate[sql-example]"  # adds sqlglot for the BIRD-SQL demo
+```
+
+---
+
+## Quickstart
+
+### 1. Write a scorer
+
+A scorer is any Python callable `(adapter_id: str, query: dict) -> float`
+returning a score in `[0.0, 1.0]`. You almost certainly already have one
+for your eval suite — wire it up.
+
+```python
+# my_eval.py
+def score(adapter_id: str, query: dict) -> float:
+    output = run_adapter(adapter_id, query["prompt"])
+    return float(matches_gold(output, query["gold"]))
+```
+
+### 2. Seed a held-out set
+
+```bash
+adaptergate holdout add \
+    --tenant acme \
+    --holdout data/acme_holdout.jsonl \
+    '{"question_id": "q1", "prompt": "...", "gold": "..."}'
+# ... add at least 20 queries (configurable)
+```
+
+### 3. Run the gate
+
+```bash
+adaptergate gate \
+    --tenant acme \
+    --candidate adapter_v18 \
+    --baseline adapter_v17 \
+    --holdout data/acme_holdout.jsonl \
+    --scorer my_eval:score \
+    --epsilon 0.02 \
+    --audit-log data/audit.jsonl \
+    --replay-path data/rejected.jsonl
+```
+
+Exit code 0 = accepted (safe to promote). 1 = rejected. Use this in your
+deploy script.
+
+### 4. Try without writing any code
+
+```bash
+# 30 fake queries
+for i in $(seq 1 30); do
+  adaptergate holdout add --tenant demo --holdout demo.jsonl \
+    "{\"question_id\": \"q$i\"}"
+done
+
+adaptergate gate \
+    --tenant demo \
+    --candidate adapter_good_v18 \
+    --baseline adapter_bad_v17 \
+    --holdout demo.jsonl \
+    --scorer adaptergate.examples.mock_scorer:score
+```
+
+---
+
+## How the gate decides
+
+```
+accepted = (score_candidate - score_baseline) >= -epsilon
+```
+
+That's the headline rule. The gate runs the scorer against the held-out set
+for both the candidate and the baseline, takes the average delta, and
+compares to `epsilon` (default `0.02` = 2pp tolerance).
+
+### Modes
+
+- **Default (aggregate):** Reject if average drop > ε.
+- **`--strict`:** Also reject if any single query that scored 1.0 on baseline
+  now scores less. Catches regression-via-averaging.
+- **`--no-require-calibration`:** Allow promotion of a first adapter when no
+  baseline exists. Useful for bootstrapping a new tenant.
+
+### Per-query breakdown
+
+Every `GateDecision` includes `per_query`: a list of
+`{query_id, score_baseline, score_candidate, delta}` records. Use it to
+surface *which* queries regressed, not just *how much*.
+
+```python
+decision = gate.evaluate(...)
+for q in decision.regressions:
+    print(q["query_id"], q["delta"])
+```
+
+---
+
+## Recipe library — the answer to "what now?"
+
+When the gate rejects with a driver slice, adaptergate can recommend
+paper-derived intervention recipes ranked by **empirical efficacy across
+prior applications**. Generic eval frameworks tell you *what* failed;
+adaptergate v0.5+ tells you *what to do*, citing the paper each recipe
+came from.
+
+```bash
+# Seed your recipe library from the bundled 7-recipe starter
+adaptergate recipes seed --recipes data/recipes.jsonl
+
+# After a gate rejects (audit log captures the decision)
+adaptergate recommend-cmd \
+    --decision data/audit.jsonl \
+    --recipes data/recipes.jsonl \
+    --top-k 3
+```
+
+```
+Recipes for driver slice: intent=billing_dispute
+
+1. ProCL slot rebalance for the driver slice   [no prior applications]
+   id: procl_slot_rebalance_v1
+   intervention: slot_rebalance
+   source: arXiv 2605.13162
+   Allocate a new ProCL program slot dedicated to the driver-slice queries...
+
+2. Online-LoRA learning rate decay              [no prior applications]
+   id: online_lora_lr_decay_v1
+   source: arXiv 2411.05663
+   Reduce the LoRA learning rate and re-run training...
+```
+
+The compounding mechanic, scope-honest:
+
+- **Within a single store**: every recipe application you log via
+  ``RecipeStore.add_application()`` strengthens the recommender's ranking
+  for that store. Recipes with positive empirical efficacy outrank fresh
+  entries. This works today.
+- **Across tenants in a single store**: applications carry an anonymized
+  ``tenant_hash``; queries that aggregate across tenants ("recipe X has
+  worked for N other tenants on this slice signature") will land in v0.6.
+- **Across organizations** (your store vs. some other team's store): NOT
+  shipped. There is no centralized recipe-application service. Your
+  ``applications.jsonl`` stays on your disk.
+
+Seven seed recipes ship with the package: ProCL slot rebalance,
+Online-LoRA LR decay, N-LoRA orthogonalization, Silent Collapse
+trust-throttle, StableEdit localized patch (all paper-cited), plus
+two heuristic recipes (replay-buffer prune, LoRA rank reduction —
+explicitly tagged in the seed file as ``"(heuristic)"`` since they're
+common practice rather than paper-cited). Load via
+``adaptergate recipes seed --recipes data/recipes.jsonl``.
+
+---
+
+## CI integration & output formats
+
+```bash
+# Human-readable CLI output (default)
+adaptergate gate --tenant acme --candidate v19 --baseline v18 \
+    --holdout data/acme.jsonl --scorer my_eval:score
+
+# Structured JSON for piping into your own tooling
+adaptergate gate ... --format json
+
+# GitHub-flavored Markdown for PR comments
+adaptergate gate ... --format pr-comment | gh pr comment "$PR" --body-file -
+
+# Configurable failing-ID preview
+adaptergate gate ... --show-failures 20
+
+# Detect stale held-out sets
+adaptergate gate ... --staleness-threshold-days 14
+```
+
+The CLI surfaces three kinds of warnings on stderr (so they survive
+``--format json`` piping):
+
+- **Malformed slices** — when a query's ``slices`` field is a string
+  instead of a list (common typo).
+- **Suspected duplicate slice tags** — when two slice tags look alike
+  (e.g. ``"billing_dispute"`` and ``"intent=billing_dispute"``), reported
+  via ``GateDecision.suspected_duplicate_slices``.
+- **Held-out staleness** — when your held-out set hasn't been refreshed
+  in N days. Stops you from misreading eval-set drift as adapter drift.
+
+---
+
+## What's in the box (v0.5)
+
+```
+adaptergate/
+├── gating/
+│   ├── regression_gate.py   # RegressionGate + GateConfig + GateDecision + SliceAttribution
+│   ├── holdout_eval.py      # HoldoutSet — per-tenant queries, JSONL-backed, staleness check
+│   ├── replay_buffer.py     # ReplayBuffer — rejected updates with full decision
+│   └── cluster.py           # find_pattern() — N-gram failure pattern detection
+├── recipes/
+│   ├── models.py            # Recipe + RecipeApplication + RecipeRecommendation
+│   ├── store.py             # RecipeStore — JSONL-backed library + application log
+│   └── recommend.py         # recommend(decision, store) — efficacy-ranked picks
+├── data/
+│   └── seed_recipes.jsonl   # 7 seed recipes derived from May-2026 CL literature
+├── cli.py                   # `adaptergate` entry point
+└── examples/
+    └── mock_scorer.py       # deterministic mock for trying things out
+```
+
+Tests: 92 unit tests across the gating subsystem, cluster, robustness,
+recipes, and BIRD-SQL eval primitives. Run with `pytest`. Ruff-clean.
+
+### Scope
+
+**In:** per-tenant gate, slice-level attribution, driver slice, failing
+query IDs, N-gram pattern of failing queries, replay buffer, audit log,
+CI exit codes.
+
+**NOT in (yet):** LLM-generated cause hypothesis, automatic counterfactual
+training data, recipe library for repairs, multi-base-model orchestration,
+hosted dashboard. See **Roadmap** below — these are deliberate omissions.
+
+### Built on (cited, not invented)
+
+adaptergate implements ideas from published research. See [NOTICE](./NOTICE)
+for full attribution.
+
+- **ProCL** — arXiv 2605.13162 — program-memory LoRA slot architecture
+- **Silent Collapse / MTR** — arXiv 2605.14588 — drift detection framework
+- **Online-LoRA** — arXiv 2411.05663 — task-free online LoRA updates
+- **N-LoRA / O-LoRA** — arXiv 2408.06133, arXiv 2310.14152 — orthogonal subspaces
+
+Our contribution: independent production implementations + the per-tenant
+gating layer + slice-level attribution + N-gram failure-pattern detection +
+audit log + replay buffer + CLI.
+
+---
+
+## Roadmap
+
+**v0.1** — basic regression gate (✅ shipped)
+**v0.2** — slice-level attribution + driver slice + failing IDs (✅ shipped)
+**v0.3** — N-gram failure pattern + robustness fixes (✅ shipped)
+**v0.4** — `--format json/pr-comment`, `--show-failures N`, duplicate-slice
+detection, holdout staleness check (✅ shipped)
+**v0.5** — **recipe library** + `observed_efficacy` + `recommend()` API +
+7 seeded paper-derived recipes (✅ this release — the moat substrate)
+
+**v0.5.x / v0.6**:
+- Automated radar.db → recipe ingestion (LLM-extracted typed recipes from
+  newly-published CL papers, with manual review queue)
+- Cross-tenant pattern matching ("this regression style failed at N other
+  tenants") — emerges naturally as the application corpus grows
+- Diff view (`adaptergate review --query X`) — needs scorer-contract change
+- Baseline drift handling — gate currently assumes baseline is ground
+  truth, wrong for online-updating adapters
+- GitHub PR comment action (wrap `--format pr-comment` in a reusable action)
+
+---
+
+## Status
+
+**v0.5 — early but production-tested.** 92 tests, ruff clean, wheel built
+clean. API may change before v1.0; the gate decision schema carries a
+`schema_version` field so audit-log consumers can handle older records.
+Issues and PRs welcome.
+
+---
+
+## License
+
+Apache 2.0. See [LICENSE](./LICENSE) and [NOTICE](./NOTICE).