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

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

@@ -5,6 +5,22 @@ the project is pre-release, so everything sits under 0.1.0 until the first tag.
 
 ## [Unreleased]
 
+## [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.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: fde-framework
-Version: 0.1.2
+Version: 0.1.3
 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
@@ -94,6 +96,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 +273,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 +282,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 +510,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 +525,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.3}/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
@@ -57,6 +58,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 +235,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 +244,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 +472,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 +487,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.3}/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.3/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.3/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.2 → fde_framework-0.1.3}/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.3/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.3/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.3}/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.3/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.

fde_framework-0.1.3/framework/templates/retrieval/hybrid-search.plain.py.j2

@@ -0,0 +1,43 @@
+"""{{ component }}: {{ approach }}, via {{ stack }}.
+
+{{ rationale }}
+
+Keyword and semantic results fused by reciprocal rank -- never by score,
+because BM25 scores and cosine similarities do not share a scale, and
+mixing them rewards whichever index is having a loud day.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from app.contract import RefusedInput
+
+interface = "{{ interface }}"
+approach = "{{ approach }}"
+stack = "{{ stack }}"
+
+TOP_K = 8
+CANDIDATES_PER_SIDE = 25
+RRF_K = 60  # the standard damping constant; rank 1 vs 2 matters, 40 vs 41 does not
+
+# Injected at wiring time: each callable(query, k) -> ordered list of
+# {"id": ..., ...} results. Two indexes, one contract.
+keyword_search: Callable | None = None
+semantic_search: Callable | None = None
+
+
+class {{ class_name }}:
+    def run(self, query: str, top_k: int = TOP_K) -> list[dict]:
+        if keyword_search is None or semantic_search is None:
+            raise RefusedInput(
+                "both retrievers must be wired -- hybrid over one index is "
+                "the single index wearing a costume"
+            )
+        fused: dict[str, dict] = {}
+        for results in (keyword_search(query, CANDIDATES_PER_SIDE),
+                        semantic_search(query, CANDIDATES_PER_SIDE)):
+            for rank, item in enumerate(results):
+                entry = fused.setdefault(item["id"], {**item, "rrf": 0.0})
+                entry["rrf"] += 1.0 / (RRF_K + rank + 1)
+        return sorted(fused.values(), key=lambda e: -e["rrf"])[:top_k]

fde_framework-0.1.3/framework/templates/retrieval/reranked-retrieval.plain.py.j2

@@ -0,0 +1,41 @@
+"""{{ component }}: {{ approach }}, via {{ stack }}.
+
+{{ rationale }}
+
+Wide first pass, careful second pass. The first-stage contract is recall --
+do not miss -- and the cross-encoder buys precision on the shortlist.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from app.contract import RefusedInput
+
+interface = "{{ interface }}"
+approach = "{{ approach }}"
+stack = "{{ stack }}"
+
+TOP_K = 8
+CANDIDATES = 50  # recall-at-fifty is the first stage's whole job
+
+# Injected at wiring time: retrieve(query, k) -> candidates;
+# rerank(query, text) -> relevance score, higher is better.
+retrieve: Callable | None = None
+rerank: Callable | None = None
+
+
+class {{ class_name }}:
+    def run(self, query: str, top_k: int = TOP_K) -> list[dict]:
+        if retrieve is None or rerank is None:
+            raise RefusedInput(
+                "wire retrieve(query, k) and rerank(query, text) -- an "
+                "unreranked shortlist returned from here would wear a "
+                "precision it does not have"
+            )
+        candidates = retrieve(query, CANDIDATES)
+        scored = [
+            {**c, "rerank_score": rerank(query, c.get("text", ""))}
+            for c in candidates
+        ]
+        return sorted(scored, key=lambda c: -c["rerank_score"])[:top_k]

fde_framework-0.1.3/framework/templates/retrieval/vector-search.llamaindex.py.j2

@@ -0,0 +1,44 @@
+"""{{ component }}: {{ approach }}, via {{ stack }}.
+
+{{ rationale }}
+
+LlamaIndex as the retrieval surface -- the right realization where the
+client already operates it, or where many sources feed one index and its
+connectors beat hand-rolled ingestion.
+
+**The same contract as the in-process implementation.** Swapping between
+realizations changes this file and nothing about the architecture -- which
+is the seam the registry exists to preserve, and the reason the index is
+injected rather than constructed here.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from app.contract import RefusedInput
+
+interface = "{{ interface }}"
+approach = "{{ approach }}"
+stack = "{{ stack }}"
+
+TOP_K = 8
+
+# Injected at wiring time: a llama_index VectorStoreIndex (or anything with
+# .as_retriever). Kept injectable so tests run without an index and the
+# boundary decides where the store lives.
+index: Any = None
+
+
+class {{ class_name }}:
+    def run(self, query: str, top_k: int = TOP_K) -> list[dict]:
+        if index is None:
+            raise RefusedInput(
+                "no index is wired -- an empty result from an unwired store "
+                "would read as 'no evidence'"
+            )
+        nodes = index.as_retriever(similarity_top_k=top_k).retrieve(query)
+        return [
+            {"id": n.node_id, "score": n.score, "text": n.get_content()}
+            for n in nodes
+        ]

{fde_framework-0.1.2 → fde_framework-0.1.3}/pyproject.toml

@@ -2,7 +2,7 @@
 # Distribution name matches the repository and stays unique on any index;
 # the import package and the CLI command remain the short `fde`.
 name = "fde-framework"
-version = "0.1.2"
+version = "0.1.3"
 description = "A framework for Forward Deployed Engineers: from problem statement to a deployable AI project, every decision traced to a fact."
 readme = "README.md"
 license = {text = "Apache-2.0"}
@@ -19,6 +19,7 @@ classifiers = [
     "License :: OSI Approved :: Apache Software License",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
     "Topic :: Software Development :: Code Generators",
 ]
 

{fde_framework-0.1.2 → fde_framework-0.1.3}/src/fde/cli.py

@@ -159,6 +159,15 @@ def start(
     if facts:
         typer.echo("")
         typer.echo(restate(facts, registry))
+        space_now = Space.from_registry(registry).apply(_with_all(Profile(), facts))
+        follow_ups = remaining_questions(
+            space_now, _with_all(Profile(), facts), registry
+        )[:3]
+        if follow_ups:
+            typer.echo(f"\nworth asking next (fde ask {name} --role <who>):")
+            for question in follow_ups:
+                roles = "/".join(question.roles) if question.roles else "anyone"
+                typer.echo(f"  - {question.asks}   [{roles}]")
         session_id = _next_session_id(engagement, "frame")
         briefs = engagement.artifacts_dir / "briefs"
         briefs.mkdir(parents=True, exist_ok=True)
@@ -367,7 +376,7 @@ def frame(
     space_now = Space.from_registry(registry).apply(with_new)
     follow_ups = remaining_questions(space_now, with_new, registry)[:3]
     if follow_ups:
-        typer.echo("\nworth asking next (fde ask <eng> --role <who>):")
+        typer.echo(f"\nworth asking next (fde ask {root} --role <who>):")
         for question in follow_ups:
             roles = "/".join(question.roles) if question.roles else "anyone"
             typer.echo(f"  - {question.asks}   [{roles}]")
@@ -1597,8 +1606,13 @@ def scan_cmd(
             typer.echo(f"  {gpu.model}  {gpu.vram_gb:.0f}GB  sm {gpu.sm}")
     elif measured:
         typer.echo("  no accelerator")
-    typer.echo(f"  {hardware.total_vram_gb:.0f}GB total"
-               f"{'' if vram is None else '  (stated, not measured)'}")
+    if hardware.gpus or hardware.total_vram_gb:
+        typer.echo(f"  {hardware.total_vram_gb:.0f}GB total"
+                   f"{'' if vram is None else '  (stated, not measured)'}")
+    elif hardware.ram_gb:
+        # Unified memory or CPU-only: "0GB total" beside "17GB of host
+        # memory" read as the tool contradicting itself.
+        typer.echo(f"  {hardware.ram_gb:.0f}GB host memory (shared)")
 
     fit = fits(hardware, params_b, precision=precision)
     if not hardware.gpus:
@@ -1897,7 +1911,7 @@ def cost_cmd(
         )
 
     if price_per_seat is not None:
-        from fde.costing import unit_economics
+        from fde.costing import COSTING_AS_OF, unit_economics
 
         coverage = None
         if root is not None:
@@ -1908,7 +1922,8 @@ def cost_cmd(
         )
         typer.echo(
             f"\nunit economics at ${price_per_seat:.2f}/seat, "
-            f"{workflows_per_day:g} workflows/day, {steps} step(s):"
+            f"{workflows_per_day:g} workflows/day, {steps} step(s) "
+            f"-- token pricing as of {COSTING_AS_OF}:"
         )
         typer.echo(f"  ${economics['cost_per_workflow']:.4f}/workflow -> "
                    f"${economics['cost_per_seat_month']:.2f}/seat-month in model spend")

{fde_framework-0.1.2 → fde_framework-0.1.3}/src/fde/costing.py

@@ -30,6 +30,7 @@ STALE_AFTER_DAYS = 270
 
 # Indicative. Re-derive against current pricing rather than quoting these.
 GPU_COST_PER_HOUR = 4.50
+COSTING_AS_OF = "2026-08"
 MANAGED_COST_PER_MILLION_TOKENS = 3.00
 TOKENS_PER_REQUEST = 1_500