Skip to main content

firstpass_core/
lib.rs

1//! # firstpass-core
2//!
3//! The Firstpass domain contract — pure, with **no I/O** (no filesystem, network, clock, or
4//! env access). Everything here is deterministic so the audit hash chain and feature
5//! extraction are reproducible and testable in isolation; all I/O lives in `firstpass-proxy`.
6//!
7//! This crate is the versioned thing every other component (gates, bandit, CLI, auditors)
8//! depends on. The serde field names on [`Trace`], [`Config`], [`Verdict`], and friends are
9//! the wire/audit contract — see each module for the "don't rename silently" rule.
10//!
11//! ## Modules
12//! - [`verdict`] — [`Verdict`], validated [`Score`], [`GateResult`] (the unit of ground truth).
13//! - [`features`] — the versioned, privacy-preserving request [`Features`] vector.
14//! - [`trace`] — the [`Trace`] audit record (SPEC §9.1).
15//! - [`hashchain`] — tamper-evident, auditor-re-derivable hashing.
16//! - [`config`] — declarative routing [`Config`] (SPEC §8.4).
17//! - [`cost`] — model pricing and the counterfactual baseline.
18//! - [`conformal`] — split-conformal risk control on the gate threshold (SPEC §10.1).
19//! - [`ltt`] — Learn-then-Test threshold calibration (RCPS, Angelopoulos et al. 2021).
20//! - [`prior`] — verified predictive routing: maps a decision-model's per-rung answer to a
21//!   cumulative gate-pass prior over the ladder.
22//! - [`eprocess`] — anytime-valid risk control: a bound that holds at *every* round, for the
23//!   continuously-recalibrated regime where the fixed-sample guarantees above do not compose.
24//! - [`error`] — the crate [`Error`] type.
25
26#![cfg_attr(test, allow(clippy::unwrap_used, clippy::expect_used))]
27#![doc(html_root_url = "https://docs.rs/firstpass-core")]
28
29pub mod config;
30pub mod conformal;
31pub mod cost;
32pub mod eprocess;
33pub mod error;
34pub mod features;
35pub mod guardrail;
36pub mod hashchain;
37pub mod ltt;
38pub mod predictor;
39pub mod prior;
40pub mod rollout;
41pub mod select;
42pub mod trace;
43pub mod verdict;
44
45pub use config::{
46    AbstainPolicy, AuthScheme, BanditAlgorithm, BanditConfig, Budget, Config, ConsistencyDef,
47    DecisionDef, Dialect, Escalation, GateDef, JudgeDef, Mode, ModePreset, ModelRef, OnExhausted,
48    PredictorConfig, PriceDef, PriorConfig, ProbeConfig, ProviderDef, Route, RoutingMode,
49    SessionPromotion,
50};
51pub use conformal::{ConformalResult, calibrate, served_failure_rate};
52pub use cost::{ModelPrice, PriceTable};
53pub use error::{Error, Result};
54pub use features::{FEATURE_VERSION, Features, TaskKind};
55pub use guardrail::{Guardrail, GuardrailAction, GuardrailVerdict};
56pub use hashchain::{Chained, GENESIS_HASH, canonical_json, record_hash, verify_chain};
57pub use ltt::{LttDiagnostic, LttResult};
58pub use predictor::PassPredictor;
59pub use prior::cumulative_pass;
60pub use rollout::{Challenger, Rollout, RolloutDecision, RolloutKey};
61pub use select::{Arm, Experiment, Report as ExperimentReport, Status as ExperimentStatus};
62pub use trace::{
63    Attempt, DeferredVerdict, ElasticAction, ElasticDecision, ExperimentRecord, FinalOutcome,
64    PolicyRef, ProbeRegime, ProbeSignal, RequestInfo, ServedFrom, Trace,
65};
66pub use verdict::{GateResult, Score, Verdict};