Skip to main content

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}