Skip to content

feat: explain supplier scoring decisions deterministically - #9

Merged
yigitcan-ozturk merged 5 commits into
mainfrom
feature/decision-explanations
Aug 28, 2026
Merged

yigitcan-ozturk merged 5 commits into
mainfrom
feature/decision-explanations

Conversation

@yigitcan-ozturk

Copy link
Copy Markdown
Owner

What changed

  • add criterion-level score_breakdown to every scored supplier
  • identify the runner-up and score margin in decision_summary
  • add structured decision_explanation with winner component scores and criterion leaders
  • show runner-up, margin and winner score contributions in the console report
  • export price, lead-time and payment-term score contributions in CSV/XLSX reports
  • add runner-up and score margin to the Excel Summary sheet
  • add dedicated decision-explanation tests and update report coverage
  • mark the original v0.2 roadmap as implemented in the README

Compatibility

  • the existing final score and recommendation semantics are unchanged
  • default and custom weight profiles use the same scoring formula as before
  • new explanation fields are additive to the v0.2 machine-readable payload
  • provenance and upstream metadata continue to pass through supplier objects

Decision boundary

The explanation layer is deterministic and derived directly from the scoring model. It does not generate opaque narrative rationale or introduce additional hidden criteria.

Why

A recommendation is more useful when reviewers can see exactly how much each commercial criterion contributed and how far the winner finished ahead of the next supplier.

@yigitcan-ozturk
yigitcan-ozturk merged commit fe35f81 into main Aug 28, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant