open/portfolio-optimiser
1
0
Fork 0
Code Issues Releases 3 Activity

docs(s31): --semantic-retrieval CLI surface + Embedder/Retriever extension points

Browse source
This commit is contained in:
Kjell Tore Guttormsen 2026-07-25 06:31:44 +02:00
commit 921a8daf71
3 changed files with 65 additions and 4 deletions
Download patch file Download diff file Expand all files Collapse all files

16
README.md
View file

@ -102,9 +102,10 @@ when the seam is detached, so the loop cannot silently degrade into theater.
cannot exercise every flag:
- **Single-project** — `PROJECT_ID --docs-dir <dir>`, plus optional `--bundle-dir`,
`--verdict-dir`, `--outbox-dir` (which requires `--run-id`), `--dimension-config`,
`--decision`/`--rationale`, and `--live-dry-run`.
- **Portfolio** — `--portfolio`, plus optional `--goals`, `--ledger`, `--dimension-config`;
it stops early and prints a `goal reached: …` line when the accumulated ledger meets a goal.
`--semantic-retrieval`, `--decision`/`--rationale`, and `--live-dry-run`.
- **Portfolio** — `--portfolio`, plus optional `--goals`, `--ledger`, `--dimension-config`,
`--semantic-retrieval`; it stops early and prints a `goal reached: …` line when the
accumulated ledger meets a goal.
- **Value report (S5.4, read-only)** — `--report --ledger <file>` rolls up the ledger's realized
savings to stdout: per-project totals, the portfolio total, flagged cross-dimension overlaps
(each counted once), and per-entry provenance. Add `--json` for deterministic JSON instead of
@ -121,6 +122,15 @@ when the seam is detached, so the loop cannot silently degrade into theater.
uv run python -m portfolio_optimiser.run --report --ledger ledger.json
```
`--semantic-retrieval` (S3.1) is an **opt-in** ranking change, valid in both run modes and
**off by default**. Off, prior verdicts are ranked exactly as before: a structural score over
the affected cost-code set, measure type and magnitude bucket, with surface text deliberately
excluded. On, that score is blended with brute-force cosine over embedded features, so a
semantically related prior verdict carrying a *different* code set can also reach the
hypothesis prompt. Since an embedder sees the proposal text, turning the flag on is a
deliberate, gated reversal of the text-excluded default — which is why it is a flag and not a
new default. Nothing about a flag-off run changes, and no savings claim depends on it.
The **prior-verdict fold — the learning step — happens only on the `--bundle-dir` path**; a
plain `--docs-dir`-only run is single-shot (no fold). `--decision`/`--rationale` apply to the
single-project path only and are inert in portfolio mode. **`--outbox-dir` must differ from