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//! - [`eprocess`] — anytime-valid risk control: a bound that holds at *every* round, for the
21//! continuously-recalibrated regime where the fixed-sample guarantees above do not compose.
22//! - [`error`] — the crate [`Error`] type.
23
24#![cfg_attr(test, allow(clippy::unwrap_used, clippy::expect_used))]
25#![doc(html_root_url = "https://docs.rs/firstpass-core")]
26
27pub mod config;
28pub mod conformal;
29pub mod cost;
30pub mod eprocess;
31pub mod error;
32pub mod features;
33pub mod guardrail;
34pub mod hashchain;
35pub mod ltt;
36pub mod predictor;
37pub mod rollout;
38pub mod trace;
39pub mod verdict;
40
41pub use config::{
42 AbstainPolicy, AuthScheme, BanditAlgorithm, BanditConfig, Budget, Config, ConsistencyDef,
43 Dialect, Escalation, GateDef, JudgeDef, Mode, ModePreset, ModelRef, OnExhausted,
44 PredictorConfig, PriceDef, ProbeConfig, ProviderDef, Route, RoutingMode, SessionPromotion,
45};
46pub use conformal::{ConformalResult, calibrate, served_failure_rate};
47pub use cost::{ModelPrice, PriceTable};
48pub use error::{Error, Result};
49pub use features::{FEATURE_VERSION, Features, TaskKind};
50pub use guardrail::{Guardrail, GuardrailAction, GuardrailVerdict};
51pub use hashchain::{Chained, GENESIS_HASH, canonical_json, record_hash, verify_chain};
52pub use ltt::{LttDiagnostic, LttResult};
53pub use predictor::PassPredictor;
54pub use rollout::{Rollout, RolloutDecision, RolloutKey};
55pub use trace::{
56 Attempt, DeferredVerdict, ElasticAction, ElasticDecision, FinalOutcome, PolicyRef, ProbeRegime,
57 ProbeSignal, RequestInfo, ServedFrom, Trace,
58};
59pub use verdict::{GateResult, Score, Verdict};