car-topology 0.55.0

Amortized coordination-topology selection core for Common Agent Runtime
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63

//! Errors surfaced by the topology-selection core.

use thiserror::Error;

/// Every failure this crate can produce. All of them are input-shape problems:
/// nothing here does I/O, calls a model, or reaches the network, so there is no
/// transient class of error to retry.
#[derive(Debug, Clone, PartialEq, Eq, Error)]
pub enum TopologyError {
    /// A one-agent (or zero-agent) team has no adjacency space.
    #[error("a topology needs at least 2 agents, got {n}")]
    TeamTooSmall { n: usize },

    /// `from_matrix` was handed a non-square matrix.
    #[error("adjacency matrix is not square: {rows} rows, a row of length {row_len}")]
    NotSquare { rows: usize, row_len: usize },

    /// `from_flat` was handed the wrong number of off-diagonal entries.
    #[error("flattened adjacency should hold {expected} entries, got {found}")]
    FlatLength { expected: usize, found: usize },

    /// An edge index is out of range or names a self-loop.
    #[error("edge {i}->{j} is not valid in a {n}-agent topology")]
    BadEdge { i: usize, j: usize, n: usize },

    /// Two topologies (or a topology and a codebook) disagree on team size.
    #[error("expected a {expected}-agent topology, got {found}")]
    SizeMismatch { expected: usize, found: usize },

    /// Query embeddings disagree on dimension across a record set.
    #[error("expected a {expected}-dimensional query embedding, got {found}")]
    QueryDimMismatch { expected: usize, found: usize },

    /// Fitting was asked to run on no usable records.
    #[error("no {kind} records to fit on")]
    NoRecords { kind: &'static str },

    /// A record carries a non-finite utility or token count.
    #[error("record {index} carries a non-finite {field}")]
    NonFinite { index: usize, field: &'static str },

    /// A configuration value is outside its usable range.
    #[error("{field} must be {expected}, got {found}")]
    BadConfig {
        field: &'static str,
        expected: &'static str,
        found: String,
    },

    /// The codebook was fitted but produced no codes to select among.
    #[error("codebook is empty — nothing to select")]
    EmptyCodebook,

    /// A query embedding was produced by a different encoder than the one the
    /// selector was fitted under.
    ///
    /// Not a pedantic check. The prior is a kernel over *directions in a
    /// specific embedding space*, so a query from another encoder lands at an
    /// arbitrary cosine similarity to every training condition — the selector
    /// keeps answering, plausibly and wrongly, with nothing to notice.
    #[error("selector was fitted under embedder {fitted}, query came from {query}")]
    EmbedderMismatch { fitted: String, query: String },
}