fde-framework 0.1.2__tar.gz → 0.1.4__tar.gz

{fde_framework-0.1.2 → fde_framework-0.1.4}/CHANGELOG.md

@@ -5,6 +5,49 @@ the project is pre-release, so everything sits under 0.1.0 until the first tag.
 
 ## [Unreleased]
 
+## [0.1.4] — 2026-09-09
+
+The measurement release: claims the framework already made, turned into
+numbers and walks.
+
+- Projects with a retrieval component ship `evals/retrieval.py`: recall@10
+  and recall@50 against golden queries in `retrieval_cases.jsonl`, gated in
+  CI, refusing an empty case set. The embedding and index choices set a
+  ceiling nothing downstream recovers; this measures the ceiling by itself,
+  no model in the loop. The diagnosis walk's evidence step now ends at this
+  number, and both embedding approaches record the doctrine: chosen by
+  measured recall on the engagement's own queries, never by leaderboard.
+- Emitted projects ship `ops/diagnosis.md`: the walk that finds which layer
+  a failure lives in -- definitions, evidence, tools, loop, model -- ordered
+  cheapest-to-check first, sections adapted to the components actually in
+  the system. An unclear definition can look like a model error; the
+  expensive habit is re-prompting before finding out.
+- Retrieval corpus: `corpus_churn` dimension (static/periodic/continuous —
+  how fast the document stock turns over, distinct from corpus size and
+  query arrival) and a graph-expanded-retrieval approach: vector entry,
+  entity expansion, rerank exit, for multi-hop questions on a corpus that
+  keeps changing. Full graph-retrieval now steps aside on continuous churn,
+  by name, with the reason on the record. Realizations for plain-python,
+  pgvector and qdrant.
+- README quickstart shows the gate refusal before the passing build, so the
+  first run's refusal is announced rather than a surprise.
+
+## [0.1.3] — 2026-09-08
+
+A post-launch funnel audit replayed every public transcript against the
+shipped package; everything it caught, in one release:
+
+- `fde start` with a statement now also offers the three questions worth
+  asking next (the follow-ups hint names the actual engagement path).
+- Seat economics dates its figures; `fde scan` on unified-memory machines
+  no longer prints a contradictory "0GB total".
+- Retrieval corpus: hybrid-search and reranked-retrieval (adopted by
+  measurement, like finetune); LlamaIndex stack with a realization;
+  invoices/complaints/claims join the corpus-size vocabulary.
+- The worked example's transcript is now a replay test: an output change
+  that would strand it fails in the same commit.
+- CI tests 3.11/3.12/3.13; doc links absolute so PyPI renders them.
+
 ## [0.1.2] — 2026-09-07
 
 A fresh-eyes usability round, every finding verified in a clean venv:

{fde_framework-0.1.2 → fde_framework-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: fde-framework
-Version: 0.1.2
+Version: 0.1.4
 Summary: A framework for Forward Deployed Engineers: from problem statement to a deployable AI project, every decision traced to a fact.
 Project-URL: Homepage, https://github.com/atulkapoor/fde-framework
 Project-URL: Repository, https://github.com/atulkapoor/fde-framework
@@ -14,6 +14,7 @@ Classifier: Intended Audience :: Developers
 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
 Classifier: Topic :: Software Development :: Code Generators
 Requires-Python: >=3.11
 Requires-Dist: jinja2>=3.1
@@ -47,15 +48,16 @@ Description-Content-Type: text/markdown
 ![Python](https://img.shields.io/pypi/pyversions/fde-framework?logo=python&logoColor=white)
 [![Downloads](https://img.shields.io/pypi/dm/fde-framework?color=blueviolet)](https://pypistats.org/packages/fde-framework)
 ![Status](https://img.shields.io/badge/status-alpha-orange)
-[![License](https://img.shields.io/badge/license-Apache--2.0-green)](LICENSE)
+[![License](https://img.shields.io/badge/license-Apache--2.0-green)](https://github.com/atulkapoor/fde-framework/blob/main/LICENSE)
 
 <p>
   <a href="#install">Install</a> ·
-  <a href="#try-it-in-two-minutes">Quickstart</a> ·
+  <a href="#try-it">Quickstart</a> ·
   <a href="ARCHITECTURE.md">Architecture</a> ·
   <a href="examples/invoice-extraction/">Worked example</a> ·
   <a href="CONTRIBUTING.md">Contributing</a> ·
-  <a href="https://pypi.org/project/fde-framework/">PyPI</a>
+  <a href="https://pypi.org/project/fde-framework/">PyPI</a> ·
+  <a href="https://atulkapoor.github.io/fde-framework/">Website</a>
 </p>
 
 **fde** is an open-source framework for Forward Deployed Engineers: it takes a
@@ -74,6 +76,8 @@ pip install fde-framework
 fde start acme --statement "Extract fields from supplier invoices."
 fde ask acme --role admin        # role-scoped discovery interview
 fde architect acme               # the design, with cited rationale
+fde build acme --out project     # refuses: seven gates guard the build
+# ...verify data access, capture the baseline (each gate prints its remedy), then:
 fde build acme --out project     # code + evals + deploy assets + runbook
 ```
 
@@ -94,6 +98,16 @@ access — no build. The remedies ship with every gate.*
 | **Jurisdiction as data** | Locale packs preset answers at the weakest provenance and attach dated compliance obligations to the build; they can never change how decisions are made |
 | **Self-evolution, honestly** | Overrides, trigger calibration and anonymised cases are captured per engagement; the corpus grows only through human-reviewed ingestion |
 
+
+## How it fits together
+
+<img src="https://raw.githubusercontent.com/atulkapoor/fde-framework/main/assets/how-it-fits.png" alt="statement to typed facts to answer space to seven gates, then decide, architect, emit, implement — registry as data, deterministic builds" width="800">
+
+Discovery narrows an answer space; gates decide whether building is honest
+yet; the decision engine picks the simplest applicable approach per component
+and cites why; emit writes a project whose exam fails until it is truly
+implemented. The full design is in [ARCHITECTURE.md](https://github.com/atulkapoor/fde-framework/blob/main/ARCHITECTURE.md).
+
 ---
 
 ## Who this is for
@@ -261,7 +275,7 @@ check. `--lenient` exists for the hour when you are mid-way through authoring
 content and the links do not resolve yet.
 
 A complete worked engagement — real transcript, synthetic client — lives in
-[examples/invoice-extraction](examples/invoice-extraction/).
+[examples/invoice-extraction](https://github.com/atulkapoor/fde-framework/tree/main/examples/invoice-extraction).
 
 ## What a build emits
 
@@ -270,10 +284,10 @@ project/
 ├── app/                  # components, pipeline, controls, boundary check
 │   ├── components/       #   implementations or honest scaffolds — never silent gaps
 │   ├── pipeline.py       #   topological order; approval gates before anything mutative
-│   ├── controls.py       #   fail-closed: an unwired gate refuses, loudly
+│   ├── controls.py       #   fail-closed gates & critics — when anything mutative was decided
 │   ├── boundary.py       #   imported at startup when data may not leave
 │   ├── contract.py       #   RefusedInput: forbidden input is refused, never guessed at
-│   └── llm.py            #   the one model touchpoint, when a decision needs one (boundary-gated)
+│   └── llm.py            #   the one model touchpoint — when a decision needs a model (boundary-gated)
 ├── evals/                # golden / edge / adversarial sets from the client's own pairs
 │   ├── harness.py        #   fails CI until implemented; judge-based when the evaluation decided judged
 │   ├── acceptance.md     #   blind UAT protocol for the client's own judges
@@ -498,7 +512,7 @@ The registry is the shared asset; engagements are private working state.
   deliberately waits for a corpus of measured retrospectives rather than
   pretending a handful is evidence.
 - **More locale packs and stacks** — both are data; contributions enter
-  against [CONTRIBUTING.md](CONTRIBUTING.md)'s contract (and the [code of conduct](CODE_OF_CONDUCT.md)).
+  against [CONTRIBUTING.md](https://github.com/atulkapoor/fde-framework/blob/main/CONTRIBUTING.md)'s contract (and the [code of conduct](https://github.com/atulkapoor/fde-framework/blob/main/CODE_OF_CONDUCT.md)).
 - **Language, channel, and device axes** — six of twenty industry test
   statements named regional languages, low bandwidth, or basic devices;
   the honest wiring (per-language evaluation, SMS/IVR serving approaches,
@@ -513,22 +527,47 @@ The registry is the shared asset; engagements are private working state.
   `fde kb sweep` report what the corpus is missing and which profile shapes
   no approach can serve yet.
 
-## Learn more
+## Documentation
+
+| I want to… | Read |
+|---|---|
+| Run the whole lifecycle once | [The full lifecycle, copy-paste](#the-full-lifecycle-copy-paste) |
+| See a real transcript with expected output | [Worked example](https://github.com/atulkapoor/fde-framework/tree/main/examples/invoice-extraction) |
+| Understand the moving parts | [ARCHITECTURE.md](https://github.com/atulkapoor/fde-framework/blob/main/ARCHITECTURE.md) |
+| Understand a gate that just refused me | `fde status <eng>` — every gate names its remedy and its clearing command |
+| Add a dimension / approach / template | [CONTRIBUTING.md](https://github.com/atulkapoor/fde-framework/blob/main/CONTRIBUTING.md) — incl. the template context table |
+| Use it as a library | [Python API](#python-api) |
+| Report a vulnerability | [SECURITY.md](https://github.com/atulkapoor/fde-framework/blob/main/SECURITY.md) |
+| See what changed | [CHANGELOG.md](https://github.com/atulkapoor/fde-framework/blob/main/CHANGELOG.md) · [Releases](https://github.com/atulkapoor/fde-framework/releases) |
+
+
+## Development
+
+```bash
+git clone https://github.com/atulkapoor/fde-framework.git && cd fde-framework
+python3 -m venv .venv && .venv/bin/pip install -e ".[dev,documents]"
+.venv/bin/pytest -q          # ~850 tests, < 30s
+.venv/bin/ruff check src tests
+```
+
+The registry is data: most contributions are a markdown file in `framework/`
+plus a test that pins the behaviour. CI additionally runs a sanitisation sweep
+over the tree and history.
+
+## Community
 
-- [ARCHITECTURE.md](ARCHITECTURE.md) — module map, the data/mechanism boundary, how to extend the registry
-- [CHANGELOG.md](CHANGELOG.md) — what exists and how it was hardened
-- [examples/invoice-extraction](examples/invoice-extraction/) — a full engagement transcript
-- [SECURITY.md](SECURITY.md) — reporting, and what counts as security-grade here
-- [llms.txt](llms.txt) — the project summarised for AI assistants
+Questions and engagement war stories → [Discussions](https://github.com/atulkapoor/fde-framework/discussions).
+Bugs and corpus gaps → [issues](https://github.com/atulkapoor/fde-framework/issues/new/choose) (the forms ask for evidence, the way the framework does).
+Conduct → [CODE_OF_CONDUCT.md](https://github.com/atulkapoor/fde-framework/blob/main/CODE_OF_CONDUCT.md).
 
 ## License
 
-[Apache 2.0](LICENSE) — chosen for the explicit patent grant, because
+[Apache 2.0](https://github.com/atulkapoor/fde-framework/blob/main/LICENSE) — chosen for the explicit patent grant, because
 enterprise legal review is a real gate for the audience this is for.
 
 ## Contributing
 
-See [CONTRIBUTING.md](CONTRIBUTING.md). The short version: contributions enter
+See [CONTRIBUTING.md](https://github.com/atulkapoor/fde-framework/blob/main/CONTRIBUTING.md). The short version: contributions enter
 against a contract, and **client material never enters this repository** — only
 patterns re-expressed in the framework's own words. Sanitisation is enforced in
 CI: allowed paths only, history checked, credential and personal-data patterns,

{fde_framework-0.1.2 → fde_framework-0.1.4}/README.md

@@ -10,15 +10,16 @@
 ![Python](https://img.shields.io/pypi/pyversions/fde-framework?logo=python&logoColor=white)
 [![Downloads](https://img.shields.io/pypi/dm/fde-framework?color=blueviolet)](https://pypistats.org/packages/fde-framework)
 ![Status](https://img.shields.io/badge/status-alpha-orange)
-[![License](https://img.shields.io/badge/license-Apache--2.0-green)](LICENSE)
+[![License](https://img.shields.io/badge/license-Apache--2.0-green)](https://github.com/atulkapoor/fde-framework/blob/main/LICENSE)
 
 <p>
   <a href="#install">Install</a> ·
-  <a href="#try-it-in-two-minutes">Quickstart</a> ·
+  <a href="#try-it">Quickstart</a> ·
   <a href="ARCHITECTURE.md">Architecture</a> ·
   <a href="examples/invoice-extraction/">Worked example</a> ·
   <a href="CONTRIBUTING.md">Contributing</a> ·
-  <a href="https://pypi.org/project/fde-framework/">PyPI</a>
+  <a href="https://pypi.org/project/fde-framework/">PyPI</a> ·
+  <a href="https://atulkapoor.github.io/fde-framework/">Website</a>
 </p>
 
 **fde** is an open-source framework for Forward Deployed Engineers: it takes a
@@ -37,6 +38,8 @@ pip install fde-framework
 fde start acme --statement "Extract fields from supplier invoices."
 fde ask acme --role admin        # role-scoped discovery interview
 fde architect acme               # the design, with cited rationale
+fde build acme --out project     # refuses: seven gates guard the build
+# ...verify data access, capture the baseline (each gate prints its remedy), then:
 fde build acme --out project     # code + evals + deploy assets + runbook
 ```
 
@@ -57,6 +60,16 @@ access — no build. The remedies ship with every gate.*
 | **Jurisdiction as data** | Locale packs preset answers at the weakest provenance and attach dated compliance obligations to the build; they can never change how decisions are made |
 | **Self-evolution, honestly** | Overrides, trigger calibration and anonymised cases are captured per engagement; the corpus grows only through human-reviewed ingestion |
 
+
+## How it fits together
+
+<img src="https://raw.githubusercontent.com/atulkapoor/fde-framework/main/assets/how-it-fits.png" alt="statement to typed facts to answer space to seven gates, then decide, architect, emit, implement — registry as data, deterministic builds" width="800">
+
+Discovery narrows an answer space; gates decide whether building is honest
+yet; the decision engine picks the simplest applicable approach per component
+and cites why; emit writes a project whose exam fails until it is truly
+implemented. The full design is in [ARCHITECTURE.md](https://github.com/atulkapoor/fde-framework/blob/main/ARCHITECTURE.md).
+
 ---
 
 ## Who this is for
@@ -224,7 +237,7 @@ check. `--lenient` exists for the hour when you are mid-way through authoring
 content and the links do not resolve yet.
 
 A complete worked engagement — real transcript, synthetic client — lives in
-[examples/invoice-extraction](examples/invoice-extraction/).
+[examples/invoice-extraction](https://github.com/atulkapoor/fde-framework/tree/main/examples/invoice-extraction).
 
 ## What a build emits
 
@@ -233,10 +246,10 @@ project/
 ├── app/                  # components, pipeline, controls, boundary check
 │   ├── components/       #   implementations or honest scaffolds — never silent gaps
 │   ├── pipeline.py       #   topological order; approval gates before anything mutative
-│   ├── controls.py       #   fail-closed: an unwired gate refuses, loudly
+│   ├── controls.py       #   fail-closed gates & critics — when anything mutative was decided
 │   ├── boundary.py       #   imported at startup when data may not leave
 │   ├── contract.py       #   RefusedInput: forbidden input is refused, never guessed at
-│   └── llm.py            #   the one model touchpoint, when a decision needs one (boundary-gated)
+│   └── llm.py            #   the one model touchpoint — when a decision needs a model (boundary-gated)
 ├── evals/                # golden / edge / adversarial sets from the client's own pairs
 │   ├── harness.py        #   fails CI until implemented; judge-based when the evaluation decided judged
 │   ├── acceptance.md     #   blind UAT protocol for the client's own judges
@@ -461,7 +474,7 @@ The registry is the shared asset; engagements are private working state.
   deliberately waits for a corpus of measured retrospectives rather than
   pretending a handful is evidence.
 - **More locale packs and stacks** — both are data; contributions enter
-  against [CONTRIBUTING.md](CONTRIBUTING.md)'s contract (and the [code of conduct](CODE_OF_CONDUCT.md)).
+  against [CONTRIBUTING.md](https://github.com/atulkapoor/fde-framework/blob/main/CONTRIBUTING.md)'s contract (and the [code of conduct](https://github.com/atulkapoor/fde-framework/blob/main/CODE_OF_CONDUCT.md)).
 - **Language, channel, and device axes** — six of twenty industry test
   statements named regional languages, low bandwidth, or basic devices;
   the honest wiring (per-language evaluation, SMS/IVR serving approaches,
@@ -476,22 +489,47 @@ The registry is the shared asset; engagements are private working state.
   `fde kb sweep` report what the corpus is missing and which profile shapes
   no approach can serve yet.
 
-## Learn more
+## Documentation
+
+| I want to… | Read |
+|---|---|
+| Run the whole lifecycle once | [The full lifecycle, copy-paste](#the-full-lifecycle-copy-paste) |
+| See a real transcript with expected output | [Worked example](https://github.com/atulkapoor/fde-framework/tree/main/examples/invoice-extraction) |
+| Understand the moving parts | [ARCHITECTURE.md](https://github.com/atulkapoor/fde-framework/blob/main/ARCHITECTURE.md) |
+| Understand a gate that just refused me | `fde status <eng>` — every gate names its remedy and its clearing command |
+| Add a dimension / approach / template | [CONTRIBUTING.md](https://github.com/atulkapoor/fde-framework/blob/main/CONTRIBUTING.md) — incl. the template context table |
+| Use it as a library | [Python API](#python-api) |
+| Report a vulnerability | [SECURITY.md](https://github.com/atulkapoor/fde-framework/blob/main/SECURITY.md) |
+| See what changed | [CHANGELOG.md](https://github.com/atulkapoor/fde-framework/blob/main/CHANGELOG.md) · [Releases](https://github.com/atulkapoor/fde-framework/releases) |
+
+
+## Development
+
+```bash
+git clone https://github.com/atulkapoor/fde-framework.git && cd fde-framework
+python3 -m venv .venv && .venv/bin/pip install -e ".[dev,documents]"
+.venv/bin/pytest -q          # ~850 tests, < 30s
+.venv/bin/ruff check src tests
+```
+
+The registry is data: most contributions are a markdown file in `framework/`
+plus a test that pins the behaviour. CI additionally runs a sanitisation sweep
+over the tree and history.
+
+## Community
 
-- [ARCHITECTURE.md](ARCHITECTURE.md) — module map, the data/mechanism boundary, how to extend the registry
-- [CHANGELOG.md](CHANGELOG.md) — what exists and how it was hardened
-- [examples/invoice-extraction](examples/invoice-extraction/) — a full engagement transcript
-- [SECURITY.md](SECURITY.md) — reporting, and what counts as security-grade here
-- [llms.txt](llms.txt) — the project summarised for AI assistants
+Questions and engagement war stories → [Discussions](https://github.com/atulkapoor/fde-framework/discussions).
+Bugs and corpus gaps → [issues](https://github.com/atulkapoor/fde-framework/issues/new/choose) (the forms ask for evidence, the way the framework does).
+Conduct → [CODE_OF_CONDUCT.md](https://github.com/atulkapoor/fde-framework/blob/main/CODE_OF_CONDUCT.md).
 
 ## License
 
-[Apache 2.0](LICENSE) — chosen for the explicit patent grant, because
+[Apache 2.0](https://github.com/atulkapoor/fde-framework/blob/main/LICENSE) — chosen for the explicit patent grant, because
 enterprise legal review is a real gate for the audience this is for.
 
 ## Contributing
 
-See [CONTRIBUTING.md](CONTRIBUTING.md). The short version: contributions enter
+See [CONTRIBUTING.md](https://github.com/atulkapoor/fde-framework/blob/main/CONTRIBUTING.md). The short version: contributions enter
 against a contract, and **client material never enters this repository** — only
 patterns re-expressed in the framework's own words. Sanitisation is enforced in
 CI: allowed paths only, history checked, credential and personal-data patterns,

{fde_framework-0.1.2 → fde_framework-0.1.4}/examples/invoice-extraction/README.md

@@ -25,7 +25,7 @@ fde frame engagements/acme --file examples/invoice-extraction/brief.md
 #
 # Correct anything wrong before we go further.
 #
-# worth asking next (fde ask <eng> --role <who>):
+# worth asking next (fde ask engagements/acme --role <who>):
 #   - What accelerator does the machine this runs on have?   [admin]
 #   - Who may use this -- one operating team, distinct roles with different
 #     permissions, or anyone internal?   [admin/sponsor]

fde_framework-0.1.4/framework/approaches/graph-expanded-retrieval.md

@@ -0,0 +1,24 @@
+---
+id: graph-expanded-retrieval
+name: Graph-expanded retrieval
+complexity: 3
+components: [retrieval]
+applies_when: [query_pattern == multi_hop and corpus_churn == continuous]
+avoid_when: [query_pattern == lookup]
+evidence: {case_ids: [structured-extraction], confidence: low, last_verified: 2026-09-09}
+---
+Vector search finds the entry points, the entities they mention open the
+graph, a bounded expansion collects what connects, and a reranker orders the
+merged pool. Most of what a full graph buys on multi-hop questions -- without
+asking the graph to carry recall.
+
+That one reassignment is what survives churn. With vector search carrying
+recall, the graph keeps a lighter contract -- entities and first-class edges,
+rebuilt incrementally -- instead of the exhaustive index whose super-linear
+growth and drifting entity resolution turn a moving corpus's graph
+confidently wrong.
+
+Where the corpus holds still, the full graph still wins: richer edges, deeper
+traversal, no rerank pass to pay for. This exists for the corpus that will
+not hold still. And like the reranker, it is adopted on measurement rather
+than fashion: run the golden multi-hop queries and let the recall gap argue.

{fde_framework-0.1.2 → fde_framework-0.1.4}/framework/approaches/graph-retrieval.md

@@ -4,8 +4,8 @@ name: Graph retrieval
 complexity: 3
 components: [retrieval]
 applies_when: [query_pattern == multi_hop]
-avoid_when: [query_pattern == lookup, query_pattern == comparative]
-evidence: {case_ids: [structured-extraction], confidence: medium, last_verified: 2026-08-21}
+avoid_when: [query_pattern == lookup, query_pattern == comparative, corpus_churn == continuous]
+evidence: {case_ids: [structured-extraction], confidence: medium, last_verified: 2026-09-09}
 ---
 Explicit entities and edges, traversed at query time.
 
@@ -16,7 +16,10 @@ rather than an upgrade.
 
 The costs are real: multi-pass extraction to build it, two to three times the
 end-to-end latency to use it, and an index that grows super-linearly, which is
-what makes incremental updates painful on a corpus that changes.
+what makes incremental updates painful on a corpus that changes. Where the
+corpus changes continuously, that maintenance is the deciding cost --
+graph-expanded retrieval keeps the multi-hop benefit by letting vector search
+carry recall, so the graph can stay small enough to rebuild.
 
 Published gains also warrant scepticism -- judge position bias has been shown to
 swing reported win rates by tens of points. Measure on your own traffic.

fde_framework-0.1.4/framework/approaches/hybrid-search.md

@@ -0,0 +1,24 @@
+---
+id: hybrid-search
+name: Hybrid search
+complexity: 2
+components: [retrieval]
+applies_when: [query_pattern == comparative and corpus_size > 100000]
+avoid_when: [query_pattern == multi_hop, corpus_size < 10000]
+evidence: {case_ids: [structured-extraction], confidence: medium, last_verified: 2026-09-07}
+---
+Keyword and semantic retrieval fused, because each fails where the other
+holds: exact identifiers, part numbers and names that embeddings blur past
+are what BM25 was built for, and paraphrase is what it cannot see. Fusion
+(reciprocal rank, not score mixing -- scores from different retrievers do
+not share a scale) takes both.
+
+Earns its second index where the corpus is large enough that either
+retriever alone leaves recall on the table, and comparative queries mix
+named things with described things. Below ten thousand documents, one good
+retriever plus a rerank is less to operate than two indexes that must stay
+in sync -- the sync is the real cost, and it fails silently.
+
+Reached by override wherever the sample queries show identifier-plus-prose
+mixtures the chosen retriever measurably misses; the golden set is the
+evidence, never the hunch.

{fde_framework-0.1.2 → fde_framework-0.1.4}/framework/approaches/local-embedding.md

@@ -19,6 +19,11 @@ Ruled out where nobody is named to operate it. A model with no owner is a
 liability handed over with a bow on it, and an embedding model whose host dies
 takes the index with it.
 
+Whichever model, it sets the ceiling on retrieval: nothing downstream
+recovers a document that was never encoded well enough to surface. The
+choice is made by measured recall on the engagement's own golden queries --
+the emitted `evals/retrieval.py` is that measurement -- not by leaderboard.
+
 The handover concern is stated precisely rather than broadly: with nobody
 named to operate and data free to leave, the managed alternative is
 strictly simpler and wins. But where data cannot leave, the plain

{fde_framework-0.1.2 → fde_framework-0.1.4}/framework/approaches/managed-embedding.md

@@ -19,4 +19,7 @@ to their source, so this is not a way of anonymising anything on the way out.
 
 One-way, like any vendor call. And expensive to reverse for a second reason --
 changing embedding model means reindexing everything, so leaving is a
-reindexing project rather than a configuration change.
+reindexing project rather than a configuration change. Which is exactly why
+the model is chosen by measured recall on the engagement's own golden
+queries (the emitted `evals/retrieval.py`) rather than by leaderboard: the
+reindexing bill for a wrong guess arrives after the index is full.

fde_framework-0.1.4/framework/approaches/reranked-retrieval.md

@@ -0,0 +1,24 @@
+---
+id: reranked-retrieval
+name: Reranked retrieval
+complexity: 2
+components: [retrieval]
+applies_when: [query_pattern == lookup and corpus_size > 200000 and human_waiting == "no"]
+avoid_when: [latency_budget_ms < 500, query_pattern == multi_hop]
+evidence: {case_ids: [structured-extraction], confidence: medium, last_verified: 2026-09-07}
+---
+A cheap retriever casts wide, a cross-encoder reads the top candidates
+properly, and precision comes from the second pass. The first-stage
+retriever's job quietly changes from "rank correctly" to "do not miss" --
+recall at fifty, not precision at five -- which is a much easier contract to
+keep on a big corpus.
+
+The cost is a model call per query on the reranking pass, which is why the
+latency budget avoids it where somebody is waiting on a tight budget: a
+cross-encoder over fifty candidates is real milliseconds, and no fusion
+trick refunds them.
+
+Like the finetune rule, this is mostly reached by measurement rather than by
+default: run the golden queries, look at where the right answer ranked, and
+adopt the reranker when the gap between position one and position twenty is
+where your answers actually live.

fde_framework-0.1.4/framework/dimensions/corpus_churn.md

@@ -0,0 +1,24 @@
+---
+id: corpus_churn
+type: enum
+scope: data
+kind: requirement
+weight: 1.0
+asks: "How often does the document corpus itself change?"
+ask_role: [admin, user]
+values: [static, periodic, continuous]
+recognises:
+  static: [historical archive, frozen corpus, fixed set of documents, one-time snapshot, corpus is static, closed cases]
+  periodic: [refreshed monthly, monthly refresh, refreshed weekly, quarterly refresh, batch refresh, re-indexed every]
+  continuous: [updated continuously, constantly changing, changes daily, keeps changing, new documents arrive daily, updated throughout the day, live document feed]
+---
+`corpus_size` is stock and `arrival_rate` is the flow of questions; this is
+how fast the stock itself turns over. Nobody volunteers it, because no demo
+runs long enough to feel it.
+
+Any index that is expensive to rebuild pays this rate forever, and the
+expensive ones fail politely: retrieval keeps answering, fluently, from a
+corpus that is no longer the client's. An entity graph pays the rate worst --
+extraction is multi-pass, the index grows super-linearly, and entity
+resolution drifts as names and structures change, which is how a graph goes
+from wrong to confidently wrong without an error in any log.

{fde_framework-0.1.2 → fde_framework-0.1.4}/framework/dimensions/corpus_size.md

@@ -6,7 +6,7 @@ kind: requirement
 weight: 1.5
 asks: "How many items in total?"
 recognises_near:
-  [documents, docs, document, files, records, pages, rows, accounts, items, tickets, reports, corpus]
+  [documents, docs, document, files, records, pages, rows, accounts, items, tickets, reports, corpus, invoices, complaints, claims]
 ask_role: ['admin', 'eval_owner']
 ---
 Total volume. Distinct from how many are labelled, which is usually far smaller

fde_framework-0.1.4/framework/patterns/graph-expanded-retrieval.md

@@ -0,0 +1,15 @@
+---
+id: graph-expanded-retrieval
+component: retrieval
+approach: graph-expanded-retrieval
+realizations:
+  - {stack: plain-python, template: retrieval/graph-expanded-retrieval.plain.py.j2, provides: Retriever}
+  - {stack: pgvector, template: retrieval/graph-expanded-retrieval.pgvector.py.j2, provides: Retriever}
+  - {stack: qdrant, template: retrieval/graph-expanded-retrieval.qdrant.py.j2, provides: Retriever}
+evidence: {case_ids: [structured-extraction], confidence: low, last_verified: 2026-09-09}
+---
+Implements graph-expanded-retrieval for retrieval, satisfying Retriever.
+
+Vector entry, entity expansion, rerank exit. The graph is deliberately the
+junior partner: it contributes connections, never recall, which is what lets
+it stay small enough to rebuild as the corpus moves.

fde_framework-0.1.4/framework/patterns/hybrid-search.md

@@ -0,0 +1,9 @@
+---
+id: hybrid-search
+component: retrieval
+approach: hybrid-search
+realizations:
+  - {stack: plain-python, template: retrieval/hybrid-search.plain.py.j2, provides: Retriever}
+evidence: {case_ids: [structured-extraction], confidence: medium, last_verified: 2026-09-07}
+---
+Implements hybrid-search for retrieval, satisfying Retriever.

fde_framework-0.1.4/framework/patterns/reranked-retrieval.md

@@ -0,0 +1,9 @@
+---
+id: reranked-retrieval
+component: retrieval
+approach: reranked-retrieval
+realizations:
+  - {stack: plain-python, template: retrieval/reranked-retrieval.plain.py.j2, provides: Retriever}
+evidence: {case_ids: [structured-extraction], confidence: medium, last_verified: 2026-09-07}
+---
+Implements reranked-retrieval for retrieval, satisfying Retriever.

{fde_framework-0.1.2 → fde_framework-0.1.4}/framework/patterns/vector-search.md

@@ -6,6 +6,7 @@ realizations:
   - {stack: plain-python, template: retrieval/vector-search.plain.py.j2, provides: Retriever}
   - {stack: pgvector, template: retrieval/vector-search.pgvector.py.j2, provides: Retriever}
   - {stack: qdrant, template: retrieval/vector-search.qdrant.py.j2, provides: Retriever}
+  - {stack: llamaindex, template: retrieval/vector-search.llamaindex.py.j2, provides: Retriever}
 evidence: {case_ids: [structured-extraction], confidence: medium, last_verified: 2026-08-21}
 ---
 Implements vector-search for retrieval, satisfying Retriever.

fde_framework-0.1.4/framework/stacks/llamaindex.md

@@ -0,0 +1,20 @@
+---
+id: llamaindex
+name: LlamaIndex
+licence: MIT
+topologies: [public-saas, managed-api, customer-vpc, hybrid, on-prem]
+last_verified: 2026-09-07
+provides: {Retriever: stable}
+reversibility: moderate
+---
+The data layer of the LLM framework stack: ingestion, indexing, query
+engines, RAG plumbing. Earns its place where the client already runs it or
+where the retrieval surface is complex enough (many sources, many readers)
+that its connectors beat hand-rolled ingestion -- the published clinical-QA
+deployments are built exactly this way.
+
+Moderate reversibility on purpose: its index formats and query-engine
+abstractions weave into the retrieval path, and unwinding them is a
+re-embedding project, not a refactor. Where nothing justifies carrying the
+framework, the plain-python and pgvector realizations answer the same
+contract with less to own.