Finite preference elicitation¶
solvi.experimental.experience.preferences implements a single author's finite
linear utility family. It does not interpret natural language or infer a
continuous weight polytope. Utility is the exact integer dot product of 3–5
integer attributes and declared integer weights. Larger utility is preferred;
encode costs as negative attributes/weights explicitly.
Create immutable Alternative(id, attributes) and
Requirement(id, attribute, minimum, hard=True) records, then pass concrete
lists/tuples to PreferenceSession(alternatives, weights, requirements=(),
budget=shared_budget, host_revision="v1"). Limits are 64 alternatives, 256
unique weight vectors, 16 requirements, 128 answer IDs and 512 historical events.
Boolean values are rejected wherever integers are required.
choose() returns a RegretCertificate containing a stable choice ID, exact
integer maximum regret, surviving weight indices, all candidate regrets, and a
fingerprint of the complete input/history. The comparator set consists of
alternatives satisfying all requirements. Minimax regret enumerates that
entire set for every surviving utility. Ties use lexicographic alternative IDs.
Empty feasibility is no_feasible_alternative; inconsistent preferences are
conflict, with no choice or numeric regret. These statuses do not prove the
original problem impossible beyond the declared finite family.
check_regret_certificate(session, certificate, budget=shared_budget) rebuilds
the utility table with independent enumeration and checks every certificate
field. It never calls choose() or the producer's regret routine. The host's
input and revision remain the trust boundary; the fingerprint is an integrity
check, not a signature or external outcome verification.
next_question(cost=0, criterion="worst_case") considers all feasible pairs.
Its three disjoint outcomes are strict left preference, tie, and strict right
preference. It chooses the greatest exact minimax-regret reduction minus the
declared integer question cost, returning None if no strictly positive value
remains. criterion="expected", probabilities=(...) instead requires declared
nonnegative integer masses over the original weight family and normalizes them
over survivors. Expectations use exact Fraction arithmetic. Query selection
work is charged separately; question cost is a decision penalty, not an
automatically purchased observation. Record an obtained answer through
answer(id, preferred, other, source=..., relation="strict", revision=None).
relation="weak" means greater-or-equal, "tie" means equal. For a tie, pass
both question IDs in either order. Strict answers match the query's two strict
branches; weak answers deliberately supply less information.
Answer IDs persist; another answer with that ID supersedes it with the next
revision. retract(id, source=...) appends an inactive revision. Sources must be
nonempty provenance strings. Contradictory answers remain in history and create
explicit conflicts; no automatic repair occurs. conflicts() returns all
minimal-by-inclusion inconsistent sets of active answer IDs and separately of
requirement IDs. relaxations() returns all minimal-by-inclusion sets of
negotiable requirement IDs whose removal would restore feasibility. It
returns ((),) when already feasible and () when hard requirements alone
prevent feasibility. These are proposals only: requirements are never mutated.
Every enumeration step debits the shared WorkBudget before work. Exhaustion
raises BudgetStop rather than emitting a partial certificate, conflict set or
question. Combinatorial conflict enumeration can exhaust a small budget even
when the declared domain is within bounds. Work units describe operations, not
wall time or dollars.
snapshot() includes the immutable problem, host revision, entire event history,
strict schema version, and digest. PreferenceSession.restore(snapshot,
budget=shared_budget, host_revision="v1", authority=session.authority) charges restoration and replays each
event through validation, rejecting corrupt schemas, invalid revisions and host
revision mismatches. Use the existing shared ledger: restoring preferences does
not reset prior spending. Provenance is retained but not authenticated.
Public records also include PreferenceAnswer (historical assertion) and
PreferenceQuestion (IDs, exact reduction, cost, net value and criterion).
See examples/38_preference_elicitation.py for a runnable interaction.
PreferenceAuthority is the host authentication capability. Keep it outside
untrusted snapshots; restore(..., authority=session.authority) requires it.
Snapshots carry an HMAC and monotonic session epoch, so recomputed plain hashes
cannot remove answers and old checkpoints cannot undo a later answer/retraction.
A mutation of one restored copy invalidates other copies sharing that authority.
export_trusted_state(budget=shared_budget) /
PreferenceAuthority.from_trusted_state(state, budget=shared_budget) enable
cross-process persistence of the secret and epoch registry. Store that state in
trusted host storage, atomically updating it after mutations. Restoring an old
trusted authority state also rolls back its protection; the payload alone is
never authority. The snapshot contains no spending permission: restoration uses
the supplied existing shared WorkBudget.
The public answers property returns an immutable tuple of frozen records;
mutating a detached copy cannot change the session or bypass its epoch. A signed
checkpoint also binds the current ledger. Restore requires the supplied ledger's
entry state to retain the same limit and at least every recorded category count
and total spending. For cross-process continuation, persist and restore the
trusted WorkBudget ledger alongside the separately trusted authority state;
a fresh empty or higher-limit budget is rejected. Replay costs are additional.