popsam_core/
model.rs

1use serde::{Deserialize, Serialize};
2
3/// Raw input text identified by a caller-provided ID.
4#[derive(Debug, Clone, Serialize, Deserialize)]
5pub struct InputRecord {
6    /// Stable caller-provided identifier for the record.
7    pub id: String,
8    /// Optional original text content.
9    #[serde(default)]
10    pub text: Option<String>,
11}
12
13/// Input record with a caller-provided embedding vector.
14#[derive(Debug, Clone, Serialize, Deserialize)]
15pub struct EmbeddedTextInput {
16    /// Stable caller-provided identifier for the record.
17    pub id: String,
18    /// Optional original text content.
19    #[serde(default)]
20    pub text: Option<String>,
21    /// Embedding vector for the record.
22    pub embedding: Vec<f32>,
23}
24
25/// Record returned by an embedding provider or included in an election result.
26#[derive(Debug, Clone, Serialize, Deserialize)]
27pub struct EmbeddedText {
28    /// Stable caller-provided identifier for the record.
29    pub id: String,
30    /// Optional original text content.
31    #[serde(default)]
32    pub text: Option<String>,
33    /// Normalized embedding vector for the record.
34    pub embedding: Vec<f32>,
35}
36
37/// Vote totals for a candidate in a single round.
38#[derive(Debug, Clone, Serialize, Deserialize)]
39pub struct CandidateRoundVotes {
40    /// Candidate identifier.
41    pub id: String,
42    /// Number of first-preference votes.
43    pub first_votes: u32,
44    /// Number of second-preference votes.
45    pub second_votes: u32,
46    /// Number of third-preference votes.
47    pub third_votes: u32,
48}
49
50/// Summary of a reported round among the final `k` candidates.
51#[derive(Debug, Clone, Serialize, Deserialize)]
52pub struct RoundSummary {
53    /// One-based round index within the reported suffix of the election.
54    pub round_index: usize,
55    /// Number of candidates still active at the start of the round.
56    pub active_candidates: usize,
57    /// Candidate IDs eliminated at the end of the round.
58    pub eliminated_candidate_ids: Vec<String>,
59    /// Vote totals for all active candidates in that round.
60    pub votes: Vec<CandidateRoundVotes>,
61}
62
63/// Result of running the elimination algorithm on a collection of embeddings.
64#[derive(Debug, Clone, Serialize, Deserialize)]
65pub struct ElectionResult {
66    /// ID of the final surviving candidate.
67    pub winner_id: String,
68    /// IDs of the last `k` candidates, captured when reporting begins.
69    pub representative_ids: Vec<String>,
70    /// Full ranking from winner to first eliminated candidate.
71    pub all_ranked_ids: Vec<String>,
72    /// Reported round summaries for the final `k` rounds.
73    pub rounds: Vec<RoundSummary>,
74    /// Normalized embeddings associated with the processed records.
75    pub embeddings: Vec<EmbeddedText>,
76}
popsam_core/model.rs

popsam_core/
model.rs
