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

BootstrapConfig

Reproducible percentile-bootstrap controls for IPS estimates.

BootstrapInterval

Percentile interval for one bootstrap statistic.

BuildConfig

Tuning knobs for crate::build::build_prior_book.

BuildOutput

Result of a streaming or incremental build.

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.

ContextOrderSummary

Static support diagnostics for one context order in a prior book. num_prefixes counts distinct action prefixes, while num_states counts distinct (prefix, state) pairs. total_count is the sum of the stored raw observation counts and is therefore a support signal, not a quality or causal claim.

ContextQueryResult

Result of PriorBook::query_with_context: which depth of context backoff actually landed on candidates, alongside the candidates themselves – the same “how much evidence backs this” transparency confidence already gives per-action, but at the query level. 0 means the order-0 (plain state) rung, identical to what PriorBook::query alone would have returned.

DoublyRobustReport

Report from doubly robust evaluation using caller-supplied reward-model values.

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.

GateAcquisition

Expected improvement per unit expected gate cost. This is a prioritization score, not a probability of success and not a causal claim.

GateAcquisitionConfig

Controls for expected-improvement acquisition. baseline_elo is the incumbent delta against which improvement is measured.

GateAcquisitionQuery

Inputs to the cost-aware gate acquisition function.

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.

GateVerdictConfig

Elo thresholds defining the three verdict regions. The interval between fail_threshold and pass_threshold is intentionally inconclusive.

GateVerdictPrediction

Posterior probabilities for PASS/FAIL/INCONCLUSIVE under a fitted model.

IncrementalPriorBuilder

Incrementally builds a PriorBook from typed observations.

MacroAction

A reusable contiguous action sequence starting at a state.

MacroActionConfig

Configuration for extracting contiguous action windows from histories.

Observation

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

OffPolicyBootstrapReport

Reproducible uncertainty report for IPS and self-normalized IPS.

OffPolicyConfig

Safety limits for importance sampling.

OffPolicyObservation

One logged decision used by IPS and doubly robust evaluation.

OffPolicyReport

Report from self-normalized inverse propensity scoring.

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.

PriorBookSource

One independently-built book and its reliability multiplier.

PriorEntry

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

PriorTrie

Deterministic prefix-tree representation of context priors.

SequencePriorScore

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

SimilarState

One caller-provided state considered as a neighbor of a query state.

SimilarityCandidate

An observed action aggregated from one or more similar states.

SimilarityConfig

Controls the conservative weighting of caller-provided neighbors.

SimilarityEvidence

Evidence showing which caller-supplied neighbor supported an action.

SimilarityQueryResult

Result of an opt-in similarity lookup.

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 score::confidence and score::wilson_lower_bound for the underlying formulas.

Error

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

GateStatus

Real-gate PASS/FAIL/INCONCLUSIVE verdict, carried on a GateObservation purely for audit (e.g. eventually checking a predicted PASS probability against what actually happened historically). Deliberately never fed into features or the regression – a categorical id, not a quantity where “more” or “less” means anything to a linear model, same reasoning as this struct’s existing training_seed exclusion.

GateVerdict

The three-way verdict used when a gate result can be positive, negative, or too close to call.

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.

MonotonicDirection

Direction constraint for a named GateModel feature. The sign is applied in standardized space; because standard deviations are positive, it has the same meaning in the caller’s original feature units.

OffPolicyError

Errors for malformed propensity/reward data or invalid safety limits.

Outcome

Result of taking action from state.

PredictionStatus

Whether a query falls within the range GateModel::fit was actually trained on. See GateModelConfig::ood_leverage_ratio_threshold/ ood_missing_fraction_threshold for the classification rule. Reported, not enforced – expected_elo/probability_positive are still computed and returned regardless of status, same “report rather than refuse” convention as missing_features; a caller that wants to abstain on Extrapolation/Unsupported decides that for itself.

ScoringStrategy

Strategy used to turn per-action evidence into a prior ranking.

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

bootstrap_self_normalized_ips

Estimate percentile-bootstrap intervals for the two IPS statistics.

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_macro_actions

Extracts macro-actions from ordered histories. This is deliberately eager: callers must provide a bounded slice because sequence windows require retaining each sequence, unlike the streaming single-step builder.

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.

evaluate_doubly_robust

Evaluate a policy with the doubly robust estimator.

evaluate_self_normalized_ips

Evaluate an explicitly supplied policy with ordinary and self-normalized IPS.

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_binary

Reads LPB v1 with allocation caps; trailing bytes are rejected for corruption detection.

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.

macro_action_candidates

Converts macro-action suggestions to the same candidate shape used by a normal prior query. The joined action is explicit and never invented.

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.”

merge_prior_books

Merges independently-built books. Weights affect evidence and ranking; source names remain caller provenance and never create actions.

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 – the CLI’s grid loop filters those out before objective_value sees them.

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_binary

Writes deterministic compact binary format LPB v1, including context entries.

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