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

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

@@ -5,6 +5,40 @@ the project is pre-release, so everything sits under 0.1.0 until the first tag.
 
 ## [Unreleased]
 
+## [0.1.2] — 2026-09-07
+
+A fresh-eyes usability round, every finding verified in a clean venv:
+
+- The hero quickstart runs verbatim: bare engagement names resolve
+  (`fde ask acme` finds `engagements/acme`), and `fde start` reads its
+  own statement through the prose reader, so the first minute shows
+  typed facts instead of "no facts recorded yet".
+- `fde --version`; interview questions show their legal values with the
+  question; gate remedies name their clearing commands; the baseline
+  refusal names the exact keys that satisfy it.
+- `fde implement` without an agent on PATH is a sentence with the fix,
+  never a traceback; `fde cost --price-per-seat` works without fleet
+  flags.
+- kb subcommands take `--registry` (with `--root` kept as an alias).
+- Every emitted project gets a front-door README; images are PNG so
+  they render on PyPI and mobile; the README gains a copy-paste full
+  lifecycle with the baseline YAML inline, and a Python API section
+  backed by the public `fde.registry.default_root()`.
+
+## [0.1.1] — 2026-09-06
+
+- README images render everywhere: absolute URLs, because PyPI does not
+  serve a repository's relative paths — and each release's page is frozen,
+  so the fix required this patch.
+- A terminal demo card on the front page, rendered from real output,
+  refusal included on purpose.
+- Social-preview image shipped in assets/.
+
+## [0.1.0] — 2026-09-06
+
+First public release on PyPI: `pip install fde-framework`. The registry
+rides inside the wheel; a bare install knows everything the corpus knows.
+
 ### Added
 - End-to-end pipeline: prose/document/sample/interview/hardware-scan intake →
   append-only fact log with dimension-dependent provenance → permutation

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: fde-framework
-Version: 0.1.0
+Version: 0.1.2
 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
@@ -36,17 +36,28 @@ Requires-Dist: anthropic>=0.40; extra == 'llm'
 Description-Content-Type: text/markdown
 
 <picture>
-  <source media="(prefers-color-scheme: dark)" srcset="assets/banner-dark.svg">
-  <img src="assets/banner-light.svg" alt="fde — a framework for Forward Deployed Engineers" width="760">
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/atulkapoor/fde-framework/main/assets/banner-dark.png">
+  <img src="https://raw.githubusercontent.com/atulkapoor/fde-framework/main/assets/banner-light.png" alt="fde — a framework for Forward Deployed Engineers" width="760">
 </picture>
 
 # fde — a framework for Forward Deployed Engineers
 
+[![PyPI](https://img.shields.io/pypi/v/fde-framework?color=3775A9&logo=pypi&logoColor=white)](https://pypi.org/project/fde-framework/)
 [![CI](https://github.com/atulkapoor/fde-framework/actions/workflows/ci.yml/badge.svg)](https://github.com/atulkapoor/fde-framework/actions/workflows/ci.yml)
-![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12-blue)
+![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)
 
+<p>
+  <a href="#install">Install</a> ·
+  <a href="#try-it-in-two-minutes">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>
+</p>
+
 **fde** is an open-source framework for Forward Deployed Engineers: it takes a
 client engagement from a problem statement to a runnable, deployable AI
 project — with every decision traced to a fact, and every fact traced to a
@@ -59,12 +70,18 @@ evidence, and code generation that ends in something you can actually deploy —
 including on-premise, inside a customer VPC, or fully air-gapped.
 
 ```bash
+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     # code + evals + deploy assets + runbook
 ```
 
+<img src="https://raw.githubusercontent.com/atulkapoor/fde-framework/main/assets/demo.png" alt="fde in a terminal: a paragraph becomes typed facts, an architecture with a fingerprint, and a build that refuses until the hard gate passes" width="780">
+
+*That refusal at the end is the product working: no baseline, no verified data
+access — no build. The remedies ship with every gate.*
+
 ## What it does
 
 | | |
@@ -179,13 +196,23 @@ modules that raise with the reason attached, never as silent gaps.
 
 ## Install
 
-Prerequisites: Python 3.11+ and git. Not yet on PyPI — install from source:
+Prerequisites: Python 3.11+.
+
+```bash
+pip install fde-framework          # the registry ships inside the wheel
+fde start acme --statement "..."   # works from any directory
+```
+
+Extras: `pip install "fde-framework[documents]"` for PDF/docx intake, `[llm]`
+for the hosted-model reader path.
+
+Or from source (contributors — a local ./framework outranks the packaged copy):
 
 ```bash
 git clone https://github.com/atulkapoor/fde-framework.git
 cd fde-framework
 python3 --version   # must say 3.11+; an older python3 makes pip backtrack for ages instead of failing fast
-python3 -m venv .venv && .venv/bin/pip install -e ".[dev,documents]"  # add ,llm for the hosted-model reader path
+python3 -m venv .venv && .venv/bin/pip install -e ".[dev,documents]"
 ```
 
 Or with [uv](https://docs.astral.sh/uv/): `uv venv && uv pip install -e ".[dev,documents]"`
@@ -214,18 +241,18 @@ refuses by name and says exactly what to install.
 ## Try it
 
 ```bash
-.venv/bin/fde start acme --statement "Extract fields from supplier invoices."
-.venv/bin/fde ask engagements/acme --role admin      # role-scoped interview
-.venv/bin/fde status engagements/acme                # gates, gaps, disagreements
-.venv/bin/fde architect engagements/acme             # the design, with rationale
-.venv/bin/fde build engagements/acme --out project   # refuses until gates clear
-
-.venv/bin/fde scan engagements/acme                  # what this hardware runs
-.venv/bin/fde cost --requests-per-day 500000 --model-b 70   # dated fleet sizing
-
-.venv/bin/fde kb validate --root framework   # parse and cross-link the registry
-.venv/bin/fde kb gaps     --root framework   # what the corpus is missing
-.venv/bin/fde kb sweep    --root framework   # profiles no approach can serve
+fde start acme --statement "Extract fields from supplier invoices."
+fde ask engagements/acme --role admin      # role-scoped interview
+fde status engagements/acme                # gates, gaps, disagreements
+fde architect engagements/acme             # the design, with rationale
+fde build engagements/acme --out project   # refuses until gates clear
+
+fde scan engagements/acme                  # what this hardware runs
+fde cost --requests-per-day 500000 --model-b 70   # dated fleet sizing
+
+fde kb validate   # parse and cross-link the registry
+fde kb gaps     --root framework   # what the corpus is missing
+fde kb sweep    --root framework   # profiles no approach can serve
 .venv/bin/pytest -q
 ```
 
@@ -258,6 +285,66 @@ project/
 └── COMPLIANCE.md         # jurisdiction obligations, when a locale pack was applied
 ```
 
+## The full lifecycle, copy-paste
+
+Everything below runs from an empty directory after `pip install fde-framework`:
+
+```bash
+fde start acme --statement "Extract fields from scanned supplier invoices; \
+data cannot leave; 200,000 documents, 8,000 verified; a person is waiting."
+# plays back the typed facts it read, and the three questions worth asking next
+
+fde ask acme --role eval_owner       # answer what discovery still needs
+fde status acme                      # facts by scope, gates, % settled
+
+cat > baseline.yaml <<'YAML'
+volume: {value: 20000, unit: docs/month, definition: invoices received by AP}
+cycle_time_per_unit_seconds: {value: 300, unit: s, definition: arrival to posted}
+labour_hours_per_week: {value: 35, unit: h/week, definition: AP team keying time}
+rework_rate: {value: 0.1, unit: ratio, definition: entries corrected after post}
+exception_rate: {value: 0.07, unit: ratio, definition: routed to a human queue}
+error_rate: {value: 0.04, unit: ratio, definition: wrong amount or vendor posted}
+business_metric: {value: 9, unit: days, definition: mean days payable outstanding}
+sampled: {n: 40, method: random invoices across two months}
+YAML
+fde baseline acme --file baseline.yaml
+fde data-access acme --note "read replica returned 14 real rows"
+fde security-review acme --note "client infosec walked the data paths"
+fde ask acme --role eval_owner       # or: fde waive acme client_readiness --reason "..."
+
+fde build acme --out project         # refuses until the gates truly pass
+python project/evals/harness.py      # red until implemented -- that's the exam
+fde implement project                # drive a coding agent until it's green
+```
+
+## Python API
+
+The CLI is a thin layer; everything is importable. The registry loads from the
+installed wheel, so this runs anywhere:
+
+```python
+from fde.architect import architect
+from fde.intake.prose import parse_prose
+from fde.models.profile import Profile
+from fde.registry import default_root, load_registry
+
+registry = load_registry(default_root())
+
+profile = Profile()
+profile.ingest(parse_prose(
+    "500,000 scanned invoices; data cannot leave; 10,000 verified; "
+    "a person is waiting; structured records out.", registry))
+
+design = architect(profile, registry)
+print(design.topology)                    # customer-vpc
+for component, decision in sorted(design.decisions.items()):
+    if decision.approach:
+        print(component, decision.approach, decision.rationale)
+```
+
+Every decision object carries its rationale and its rejected alternatives —
+the same receipts the emitted `ARCHITECTURE.md` prints.
+
 ## Common commands
 
 | | |
@@ -410,9 +497,8 @@ The registry is the shared asset; engagements are private working state.
 - **Rule revision from outcomes** — capture is wired end to end; revision
   deliberately waits for a corpus of measured retrospectives rather than
   pretending a handful is evidence.
-- **PyPI release** — after the first tagged version.
 - **More locale packs and stacks** — both are data; contributions enter
-  against [CONTRIBUTING.md](CONTRIBUTING.md)'s contract.
+  against [CONTRIBUTING.md](CONTRIBUTING.md)'s contract (and the [code of conduct](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,

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

@@ -1,15 +1,26 @@
 <picture>
-  <source media="(prefers-color-scheme: dark)" srcset="assets/banner-dark.svg">
-  <img src="assets/banner-light.svg" alt="fde — a framework for Forward Deployed Engineers" width="760">
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/atulkapoor/fde-framework/main/assets/banner-dark.png">
+  <img src="https://raw.githubusercontent.com/atulkapoor/fde-framework/main/assets/banner-light.png" alt="fde — a framework for Forward Deployed Engineers" width="760">
 </picture>
 
 # fde — a framework for Forward Deployed Engineers
 
+[![PyPI](https://img.shields.io/pypi/v/fde-framework?color=3775A9&logo=pypi&logoColor=white)](https://pypi.org/project/fde-framework/)
 [![CI](https://github.com/atulkapoor/fde-framework/actions/workflows/ci.yml/badge.svg)](https://github.com/atulkapoor/fde-framework/actions/workflows/ci.yml)
-![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12-blue)
+![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)
 
+<p>
+  <a href="#install">Install</a> ·
+  <a href="#try-it-in-two-minutes">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>
+</p>
+
 **fde** is an open-source framework for Forward Deployed Engineers: it takes a
 client engagement from a problem statement to a runnable, deployable AI
 project — with every decision traced to a fact, and every fact traced to a
@@ -22,12 +33,18 @@ evidence, and code generation that ends in something you can actually deploy —
 including on-premise, inside a customer VPC, or fully air-gapped.
 
 ```bash
+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     # code + evals + deploy assets + runbook
 ```
 
+<img src="https://raw.githubusercontent.com/atulkapoor/fde-framework/main/assets/demo.png" alt="fde in a terminal: a paragraph becomes typed facts, an architecture with a fingerprint, and a build that refuses until the hard gate passes" width="780">
+
+*That refusal at the end is the product working: no baseline, no verified data
+access — no build. The remedies ship with every gate.*
+
 ## What it does
 
 | | |
@@ -142,13 +159,23 @@ modules that raise with the reason attached, never as silent gaps.
 
 ## Install
 
-Prerequisites: Python 3.11+ and git. Not yet on PyPI — install from source:
+Prerequisites: Python 3.11+.
+
+```bash
+pip install fde-framework          # the registry ships inside the wheel
+fde start acme --statement "..."   # works from any directory
+```
+
+Extras: `pip install "fde-framework[documents]"` for PDF/docx intake, `[llm]`
+for the hosted-model reader path.
+
+Or from source (contributors — a local ./framework outranks the packaged copy):
 
 ```bash
 git clone https://github.com/atulkapoor/fde-framework.git
 cd fde-framework
 python3 --version   # must say 3.11+; an older python3 makes pip backtrack for ages instead of failing fast
-python3 -m venv .venv && .venv/bin/pip install -e ".[dev,documents]"  # add ,llm for the hosted-model reader path
+python3 -m venv .venv && .venv/bin/pip install -e ".[dev,documents]"
 ```
 
 Or with [uv](https://docs.astral.sh/uv/): `uv venv && uv pip install -e ".[dev,documents]"`
@@ -177,18 +204,18 @@ refuses by name and says exactly what to install.
 ## Try it
 
 ```bash
-.venv/bin/fde start acme --statement "Extract fields from supplier invoices."
-.venv/bin/fde ask engagements/acme --role admin      # role-scoped interview
-.venv/bin/fde status engagements/acme                # gates, gaps, disagreements
-.venv/bin/fde architect engagements/acme             # the design, with rationale
-.venv/bin/fde build engagements/acme --out project   # refuses until gates clear
-
-.venv/bin/fde scan engagements/acme                  # what this hardware runs
-.venv/bin/fde cost --requests-per-day 500000 --model-b 70   # dated fleet sizing
-
-.venv/bin/fde kb validate --root framework   # parse and cross-link the registry
-.venv/bin/fde kb gaps     --root framework   # what the corpus is missing
-.venv/bin/fde kb sweep    --root framework   # profiles no approach can serve
+fde start acme --statement "Extract fields from supplier invoices."
+fde ask engagements/acme --role admin      # role-scoped interview
+fde status engagements/acme                # gates, gaps, disagreements
+fde architect engagements/acme             # the design, with rationale
+fde build engagements/acme --out project   # refuses until gates clear
+
+fde scan engagements/acme                  # what this hardware runs
+fde cost --requests-per-day 500000 --model-b 70   # dated fleet sizing
+
+fde kb validate   # parse and cross-link the registry
+fde kb gaps     --root framework   # what the corpus is missing
+fde kb sweep    --root framework   # profiles no approach can serve
 .venv/bin/pytest -q
 ```
 
@@ -221,6 +248,66 @@ project/
 └── COMPLIANCE.md         # jurisdiction obligations, when a locale pack was applied
 ```
 
+## The full lifecycle, copy-paste
+
+Everything below runs from an empty directory after `pip install fde-framework`:
+
+```bash
+fde start acme --statement "Extract fields from scanned supplier invoices; \
+data cannot leave; 200,000 documents, 8,000 verified; a person is waiting."
+# plays back the typed facts it read, and the three questions worth asking next
+
+fde ask acme --role eval_owner       # answer what discovery still needs
+fde status acme                      # facts by scope, gates, % settled
+
+cat > baseline.yaml <<'YAML'
+volume: {value: 20000, unit: docs/month, definition: invoices received by AP}
+cycle_time_per_unit_seconds: {value: 300, unit: s, definition: arrival to posted}
+labour_hours_per_week: {value: 35, unit: h/week, definition: AP team keying time}
+rework_rate: {value: 0.1, unit: ratio, definition: entries corrected after post}
+exception_rate: {value: 0.07, unit: ratio, definition: routed to a human queue}
+error_rate: {value: 0.04, unit: ratio, definition: wrong amount or vendor posted}
+business_metric: {value: 9, unit: days, definition: mean days payable outstanding}
+sampled: {n: 40, method: random invoices across two months}
+YAML
+fde baseline acme --file baseline.yaml
+fde data-access acme --note "read replica returned 14 real rows"
+fde security-review acme --note "client infosec walked the data paths"
+fde ask acme --role eval_owner       # or: fde waive acme client_readiness --reason "..."
+
+fde build acme --out project         # refuses until the gates truly pass
+python project/evals/harness.py      # red until implemented -- that's the exam
+fde implement project                # drive a coding agent until it's green
+```
+
+## Python API
+
+The CLI is a thin layer; everything is importable. The registry loads from the
+installed wheel, so this runs anywhere:
+
+```python
+from fde.architect import architect
+from fde.intake.prose import parse_prose
+from fde.models.profile import Profile
+from fde.registry import default_root, load_registry
+
+registry = load_registry(default_root())
+
+profile = Profile()
+profile.ingest(parse_prose(
+    "500,000 scanned invoices; data cannot leave; 10,000 verified; "
+    "a person is waiting; structured records out.", registry))
+
+design = architect(profile, registry)
+print(design.topology)                    # customer-vpc
+for component, decision in sorted(design.decisions.items()):
+    if decision.approach:
+        print(component, decision.approach, decision.rationale)
+```
+
+Every decision object carries its rationale and its rejected alternatives —
+the same receipts the emitted `ARCHITECTURE.md` prints.
+
 ## Common commands
 
 | | |
@@ -373,9 +460,8 @@ The registry is the shared asset; engagements are private working state.
 - **Rule revision from outcomes** — capture is wired end to end; revision
   deliberately waits for a corpus of measured retrospectives rather than
   pretending a handful is evidence.
-- **PyPI release** — after the first tagged version.
 - **More locale packs and stacks** — both are data; contributions enter
-  against [CONTRIBUTING.md](CONTRIBUTING.md)'s contract.
+  against [CONTRIBUTING.md](CONTRIBUTING.md)'s contract (and the [code of conduct](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,

{fde_framework-0.1.0 → fde_framework-0.1.2}/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.0"
+version = "0.1.2"
 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"}