popsam-core 0.1.1

Core library for AI-assisted selection of semantically representative texts
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
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97

use serde::{Deserialize, Serialize};

/// Raw input text identified by a caller-provided ID.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct InputRecord {
    /// Stable caller-provided identifier for the record.
    pub id: String,
    /// Optional original text content.
    #[serde(default)]
    pub text: Option<String>,
}

/// Input record with a caller-provided embedding vector.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct EmbeddedTextInput {
    /// Stable caller-provided identifier for the record.
    pub id: String,
    /// Optional original text content.
    #[serde(default)]
    pub text: Option<String>,
    /// Embedding vector for the record.
    pub embedding: Vec<f32>,
}

/// Record returned by an embedding provider or included in an election result.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct EmbeddedText {
    /// Stable caller-provided identifier for the record.
    pub id: String,
    /// Optional original text content.
    #[serde(default)]
    pub text: Option<String>,
    /// Normalized embedding vector for the record.
    pub embedding: Vec<f32>,
}

/// Vote totals for a candidate in a single round.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CandidateRoundVotes {
    /// Candidate identifier.
    pub id: String,
    /// Number of first-preference votes.
    pub first_votes: u32,
    /// Number of second-preference votes.
    pub second_votes: u32,
    /// Number of third-preference votes.
    pub third_votes: u32,
}

/// Best round result reached by a candidate during the full election.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CandidateBestResult {
    /// Candidate identifier.
    pub id: String,
    /// One-based round index within the full election.
    pub full_round_index: usize,
    /// Number of candidates still active at the start of that round.
    pub active_candidates: usize,
    /// One-based rank among active candidates in that round.
    pub rank: usize,
    /// Number of first-preference votes in that round.
    pub first_votes: u32,
    /// Number of second-preference votes in that round.
    pub second_votes: u32,
    /// Number of third-preference votes in that round.
    pub third_votes: u32,
}

/// Summary of a reported round among the final `k` candidates.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct RoundSummary {
    /// One-based round index within the reported suffix of the election.
    pub round_index: usize,
    /// Number of candidates still active at the start of the round.
    pub active_candidates: usize,
    /// Candidate IDs eliminated at the end of the round.
    pub eliminated_candidate_ids: Vec<String>,
    /// Vote totals for all active candidates in that round.
    pub votes: Vec<CandidateRoundVotes>,
}

/// Result of running the elimination algorithm on a collection of embeddings.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ElectionResult {
    /// ID of the final surviving candidate.
    pub winner_id: String,
    /// IDs of the last `k` candidates, captured when reporting begins.
    pub representative_ids: Vec<String>,
    /// Full ranking from winner to first eliminated candidate.
    pub all_ranked_ids: Vec<String>,
    /// Reported round summaries for the final `k` rounds.
    pub rounds: Vec<RoundSummary>,
    /// Best round result reached by each candidate during the full election, ordered like `all_ranked_ids`.
    pub candidate_best_results: Vec<CandidateBestResult>,
    /// Normalized embeddings associated with the processed records.
    pub embeddings: Vec<EmbeddedText>,
}