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

docs(mandate): how a domain expert commissions a run — and one honesty fix the run itself exposed

Browse source 
`docs/bestille-en-kjoring.md` is the commissioning half of the expert-facing pair
(`ekspert-svar.md` is the judging half): the mandate file field by field, how to
run it, and — separated deliberately — what a commission does NOT do. It directs
what is evaluated, never what is approved.

Registered in _LIVE_DOCS, so it cannot silently fall behind the code.

The example output in it is COPIED FROM A REAL RUN, not composed, and running
that run is what found the defect fixed here: three approaches against the same
cost line each validated at 30000 NOK, and the settlement printed
"Validated total: 90000 NOK". Commissioned approaches are ALTERNATIVES — they
usually attack the same line — so summing them reports money the project cannot
realise. A domain expert reading that total would reasonably believe the run
found 90k.

The settlement now reports how many approaches held and which one the run
carries: a selection, not an arithmetic claim. That also removes the last money
addition from this module, which is the right place for it not to be.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ULCqjLF61rehj5cZmdUoR3
This commit is contained in:
Kjell Tore Guttormsen 2026-08-05 16:31:27 +02:00
commit 30bcdd3544
5 changed files with 174 additions and 10 deletions
Download patch file Download diff file Expand all files Collapse all files

20
src/portfolio_optimiser/mandate.py
View file

@ -194,10 +194,14 @@ def settle(
Empty coverage renders an EMPTY string — a run without a mandate has nothing to settle, and a
header over zero rows would imply a commission that never existed.
The ``Validated total`` is a DISPLAY figure, summed in float NOK exactly like
``PortfolioResult.sum_claimed_saving_nok``, and it decides nothing. The goal verdict is
**passed in**, never computed here: ``ledger.to_ore`` is the framework's one NOK->øre
conversion and the goal comparison already runs on quantised integers, but this module cannot
**Commissioned approaches are ALTERNATIVES and are never summed.** Several of them usually
attack the same cost line, so a total would report money the project cannot realise — measured
on a real run, three approaches against one line each validated at 30000 NOK and an earlier
version of this function claimed a 90000 total. What is honest is how many held and which one
the run carries: a selection, not an arithmetic claim.
The goal verdict is **passed in**, never computed here: ``ledger.to_ore`` is the framework's one
NOK->øre conversion and the goal comparison already runs on quantised integers, but this cannot
import it without pulling ``verdicts`` — and with it ``agent_framework`` — into a deliberately
framework-neutral file, while a private copy of a money conversion is precisely the ``(p)``
defect. So the caller decides and this renders. Both ``goal_nok`` and ``goal_reached`` must be
@ -216,8 +220,12 @@ def settle(
else:
lines.append(f" {row.id:<20} NOT EVALUATED {row.detail}")
total = sum(r.saving_nok or 0.0 for r in coverage if r.status == "validated")
lines.append(f" Validated total: {total:.0f} NOK")
held = [r for r in coverage if r.status == "validated"]
best = max((r.saving_nok or 0.0 for r in held), default=None)
tally = f" Validated: {len(held)} of {len(coverage)} approaches"
if best is not None:
tally += f" — best {best:.0f} NOK (the outcome this run carries)"
lines.append(tally)
if goal_nok is not None and goal_reached is not None:
lines.append(
f" Target: >= {goal_nok:.0f} NOK — "