Crate lineprior 

lineprior: domain-agnostic action priors built from historical action sequences. Given a state, it answers “what actions have historically worked well from here?” – as a prior for another system to weigh, not as an oracle. See AGENTS.md for the full design rationale.

This library never writes to stdout/stderr and never panics on malformed user input; all failure paths return Error.

Structs

BuildConfig

Tuning knobs for crate::build::build_prior_book.

BuildOutput

Result of build_prior_book_from_reader: the built book plus any non-fatal warnings collected along the way. book may legitimately be empty (no observations, or everything got filtered out) – callers that want “empty means an error” should check book.entries.is_empty() themselves, the same way crate::report::summarize’s callers do.

BuildStats

What a build actually did to the input, independent of the resulting PriorBook – lets a caller check whether their own pre-filtering (e.g. a domain-specific ply/depth cutoff) combined with BuildConfig’s thresholds behaved as expected, without re-deriving these numbers by hand from the input.

CalibrationBin

Ranking quality for one equal-width confidence bin of the #1 candidate, among evaluated test observations whose top1 confidence fell in [min_confidence, max_confidence) (the last bin is closed on both ends). Always exactly EvalConfig::calibration_bins entries, in ascending bin order, regardless of whether a given bin saw any observations.

EvalConfig

Tuning knobs for evaluate.

EvalOutput

Result of evaluate: the report plus warnings from the train pass. Warnings are collected from the train pass only – when both readers point at the same file (the only way the CLI uses this), a malformed line is malformed identically in both passes, so a second collection would just duplicate the first. The test pass still skips (non-strict) or aborts (strict) on invalid records; it just doesn’t re-report them.

EvalReport

Ranking-quality report produced by evaluate.

GateCalibrationBin

Ranking quality for one equal-width probability_positive bin, over out-of-fold predictions collected during GateModel::fit’s nested cross-validation pass (see its doc comment) – not the single-level CV used to pick the deployed model’s lambda, which would be optimistically biased if reused here directly. Mirrors eval.rs’s CalibrationBin shape: a well-calibrated model should show empirical_positive_rate tracking bin probability roughly 1:1.

GateFitOutput

Result of GateModel::fit: the fitted model plus its own diagnostics.

GateFitReport

Diagnostics from a GateModel::fit call, for deciding whether the fitted model is trustworthy enough to act on before any acquisition logic is layered on top (deferred to a later round).

GateModel

A fitted gate-outcome surrogate. Opaque by design – GateModel::fit and GateModel::predict are the API; the standardized-space coefficients are an implementation detail, not something callers should need to read directly.

GateModelConfig

Tuning knobs for GateModel::fit.

GateObservation

One historical training candidate that has already been through a real gate run, used as training data for GateModel::fit.

GateOofPrediction

One nested-CV out-of-fold audit row: predicted_elo/probability_positive were produced by a model that never saw this candidate’s own row or its group_id during fitting or lambda selection (see GateModel::fit_with_validation’s doc comment) – exactly the population GateFitReport::weighted_rmse/calibration are computed from, exposed per-candidate for real-data validation (comparing against an external baseline, auditing calibration and interval coverage by hand) before building anything on top of Round A. Not deduplicated by candidate_id: a caller whose data happens to repeat one is still owed every row, not a silently-collapsed one.

GatePrediction

GateModel::predict’s output for one GateQuery.

GateQuery

A not-yet-gated candidate to score with GateModel::predict.

GateValidationOutput

Result of GateModel::fit_with_validation: everything GateFitOutput carries, plus the nested-CV out-of-fold audit table and the confidence level its intervals represent. A superset, not a fork – report is the exact same GateFitReport fit returns, so the two functions can never disagree about the aggregate metrics.

Observation

One recorded step: from state, action was taken, with outcome.

ParetoEntry

One point on the coverage/MRR tradeoff curve.

ParseOutcome

Everything produced by a parse pass: the valid observations plus any non-fatal issues collected in non-strict mode.

PriorAction

One candidate action ranked for a given state.

PriorBook

In-memory prior book: state -> ranked candidate actions.

PriorEntry

One line of prior-book output: a state and its ranked actions.

SequencePriorScore

Result of PriorBook::score_sequence: an aggregate read on how much historical precedent supports a whole caller-supplied candidate path.

StateEntropy

Entropy of one state’s prior distribution, in bits. Low entropy means one action dominates and the prior is likely useful; high entropy means many actions compete and a fallback search may be safer.

StepScore

Per-step result of PriorBook::score_sequence: whether/how well this step of a caller-supplied candidate path is backed by historical data.

SummaryReport

Aggregate statistics over an entire prior book, for the CLI summary command.

ThresholdSweepEntry

Selective-prediction metrics at one confidence threshold: if the caller only acted when the #1 candidate’s confidence was >= min_confidence, how often would they have predicted at all, and how good were those predictions? Always exactly EvalConfig::thresholds.len() entries, in the requested order.

TopKHitRate

Hit rate for one requested k. A Vec (not a map) so JSON output has a deterministic order matching the order top_k was requested in.

TuneCandidateResult

One evaluated grid candidate’s outcome. Note the field is objective_value (a number), not objective – that name is reserved at the TuneOutput level for which TuneObjective was chosen.

TuneConstraints

Candidates failing a constraint stay in TuneOutput::all_results (so the caller can see why they were excluded) but are never select_best- eligible. None on any field means “no floor/ceiling on this metric.”

TuneMetrics

The subset of EvalReport that matters for comparing candidates.

TuneOutput

Full result of a tune run.

Warning

A non-fatal issue skipped in non-strict mode. Carries enough detail to report to the user without aborting the whole run.

Enums

ConfidenceMode

How PriorAction::confidence is computed. See [crate::score::confidence] and [crate::score::wilson_lower_bound] for the underlying formulas.

Error

Errors produced while parsing, validating, or building a prior book.

MissingTimestampPolicy

What to do with an observation that has no observed_at_unix_seconds when BuildConfig::time_decay_half_life_days is set. Inert when time decay is disabled.

Outcome

Result of taking action from state.

TuneObjective

Which held-out metric tune ranks candidates by. See each variant’s doc comment; CoveredMrr is the recommended default – optimizing Mrr alone tends to pick configs that abstain (report no candidate) except when very confident, while optimizing coverage alone tolerates a sloppy prior. CoveredMrr penalizes both.

TuneParam

One --param key=v1,v2,... sweep. Each variant already carries its values pre-parsed to the right type, so applying it to a BuildConfig can never mismatch a key against the wrong value type – unlike a generic (key, values: Vec<AnyValue>) pair, this is checked by the compiler, not at grid-expansion time.

Constants

DEFAULT_CONFIDENCE_K

We use k=20 so confidence grows slowly for low-sample actions. This prevents one-off successes from dominating the prior.

DEFAULT_CONFIDENCE_Z

z=1.96 is the two-sided-95% value conventionally used (Evan Miller / Reddit-ranking style) as a one-sided Wilson lower bound – slightly more conservative than a strict one-sided 95% bound (which would use ~1.64), which is the right direction for a “how much should I trust this” score.

DEFAULT_DRAW_VALUE

A draw is a genuine partial outcome in adversarial games (chess, shogi), not a loss – we default to crediting it as half a win rather than scoring it identically to a failure.

DEFAULT_SOURCE_WEIGHT

Multiplier applied to an observation whose source is None or not a key in BuildConfig::source_weights. 1.0 means “trust unlabeled/unknown sources same as any other” – the backward-compatible default.

Functions

build_candidate_result

Builds one TuneCandidateResult from an already-evaluated candidate. Does not call evaluate() itself – callers (e.g. the CLI’s grid loop) own opening/parsing the input and only reach this on Ok.

build_config_fingerprint

Deterministic fingerprint of a BuildConfig, stable within a given lineprior version (it hashes a JSON encoding, and serde_json’s exact byte layout for floats is not itself guaranteed forever-stable across serde_json versions – unlike eval’s sequence-id hash, which only ever hashes raw string bytes and so carries a stronger cross-version guarantee). Good enough to detect a stale cached prior book within one project’s lifetime; not meant as a long-term archival checksum.

build_prior_book

Aggregates observations into a PriorBook, applying filters, smoothing, normalization, and ranking per AGENTS.md’s scoring model.

build_prior_book_from_reader

Parses and aggregates a JSONL observation stream in one pass, without ever collecting a Vec<Observation> – peak memory stays bounded by the number of unique (state, action) pairs, not the number of lines read. Prefer this over parse_jsonl + build_prior_book for anything beyond small, already-in-memory inputs.

covered_fraction

Observation-weighted fraction of test observations whose state had at least one candidate. 1.0 - fallback_rate, not EvalReport::coverage (that field is state-weighted and deliberately doesn’t complement to 1 with fallback_rate – see its doc comment). Defaults to 0.0 (no coverage) on the degenerate fallback_rate: None case (zero test observations), matching the “can’t confirm coverage” reading.

default_gate_lambda_grid

1e-4 through 100.0, log-spaced-ish, chosen to bias toward strong regularization for a p-approx-n regime – see GateModelConfig::lambda_grid.

evaluate

Builds a prior from a sequence-held-out train split and reports how well it ranks the actual action taken on the held-out test split.

expand_grid

Deterministic Cartesian product over params, in the given param and value order, applied on top of base. config_ids are "cfg_001", "cfg_002", … in generation order. No params -> a single candidate (base itself, as "cfg_001").

load_prior_book

Reads a prior book back from the JSONL format emitted by build. Querying itself is PriorBook::query – an unseen state returns no candidates rather than an error or an invented action.

load_prior_book_with_config

Like load_prior_book, but also checks the file’s embedded BuildConfig fingerprint (if any) against expected_config’s fingerprint. Returns Error::BuildConfigMismatch if the file has a header and it doesn’t match – otherwise a stale cached book could silently be reused as if its confidence/prior values were computed under the caller’s current config. A file with no header (saved by plain save_prior_book, or by a version of lineprior that predates this) is accepted unconditionally – there’s nothing to compare against.

meets_constraints

Whether report clears every floor/ceiling set in constraints. A missing metric (None) is treated as failing a floor and failing a ceiling check is skipped only when the ceiling itself is unset – i.e. “no data” never counts as “constraint satisfied.”

objective_value

The value tune ranks a candidate by. A metric field of None (valid config, but its book covers nothing to measure – e.g. min_confidence filtered every candidate away) scores 0.0 here rather than being treated as an error; only a config evaluate() itself rejects (an Err) is excluded before this is ever called (see [crate::tune]’s module doc).

pareto_front

Non-dominated set over (mrr, covered_fraction), both maximized: a candidate is excluded if another candidate is at least as good on both dimensions and strictly better on at least one. Unlike select_best, this ignores meets_constraints – it shows the whole tradeoff space so a caller can override “best” with their own pick. O(n^2); fine at the grid sizes tune targets (tens to low hundreds of candidates).

parse_jsonl

Streams JSONL observations from reader, one line at a time so memory stays bounded regardless of input size.

save_prior_book

Writes a prior book as JSONL: order-0 entries in the same deterministic order as PriorBook::entries_sorted, followed by any context entries in PriorBook::context_entries_sorted’s order. The inverse of load_prior_book.

save_prior_book_with_config

Like save_prior_book, but also writes a leading header line with config’s fingerprint, so a later load_prior_book_with_config call can detect whether the book was built under different config values than the caller currently expects.

select_best

Highest objective_value among meets_constraints == true entries in results, ties broken by earliest config_id (grid generation order). None if results is empty or nothing satisfies its constraints.

state_entropy

Per-state entropy, sorted lexicographically by state for determinism.

summarize

Summarizes a whole prior book: how many states/actions it covers and how confident/decisive it tends to be.

Type Aliases

Result