hyprstream_decision_head/error.rs
1//! Error types for the encoder and scorer.
2
3use thiserror::Error;
4
5/// Errors from encoding a [`hyprstream_decision::QuestionSet`] or validating an
6/// encoded request against its question specs.
7#[derive(Debug, Error)]
8pub enum Error {
9 /// The tokenizer failed to encode the canonical serialization.
10 #[error("tokenizer encode failed: {0}")]
11 Tokenizer(String),
12
13 /// The learned anchor token could not be assigned an id.
14 #[error("anchor token {token:?} was added but has no id in the tokenizer")]
15 AnchorTokenMissing {
16 /// The anchor token string that failed to resolve.
17 token: &'static str,
18 },
19
20 /// The serialized request exceeds the tokenizer-bound token budget
21 /// ([`hyprstream_decision::serialize::MAX_SERIALIZED_SPEC_TOKENS`] by default).
22 /// Above this budget the two-stage score-then-choice recipe is mandatory (P0.1a).
23 #[error(
24 "serialized request is {tokens} tokens, exceeding the budget of {budget}; \
25 split the request or use the two-stage score-then-choice recipe"
26 )]
27 TokenBudgetExceeded {
28 /// Encoded token count of the full request.
29 tokens: usize,
30 /// The enforced budget.
31 budget: usize,
32 },
33
34 /// The number of anchor tokens in the encoding does not match the question arities.
35 /// This means the tokenizer and the serialization contract disagree (e.g. the anchor
36 /// token id belongs to a different bundle than the tokenizer in use) — fail loudly
37 /// rather than misalign scorer readout positions.
38 #[error(
39 "anchor count mismatch: serialization produced {expected} anchor placeholders \
40 but the encoding contains {found} anchor tokens"
41 )]
42 AnchorCountMismatch {
43 /// Anchors implied by the question specs (1 per noul, 1 per choice option,
44 /// 1 per score level).
45 expected: usize,
46 /// Anchor-token occurrences found in the token ids.
47 found: usize,
48 },
49
50 /// A question's recorded anchor count does not match its spec arity when scoring.
51 #[error("question {question_id:?} ({kind}) expects {expected} anchor(s), got {found}")]
52 QuestionArityMismatch {
53 /// The mismatched question id.
54 question_id: String,
55 /// The question kind.
56 kind: hyprstream_decision::QuestionKind,
57 /// Arity implied by the spec.
58 expected: usize,
59 /// Anchors actually recorded.
60 found: usize,
61 },
62
63 /// The anchor-position batch passed to the scorer does not match the hidden-state
64 /// batch dimension.
65 #[error("hidden-state batch is {batch} sequences but {maps} anchor maps were given")]
66 BatchMismatch {
67 /// Batch size of the hidden-state tensor.
68 batch: usize,
69 /// Number of per-sequence anchor maps supplied.
70 maps: usize,
71 },
72}