Skip to main content

fauna_api/ant/
persona.rs

1use serde::{Deserialize, Serialize};
2use serde_json::{Map, Value};
3
4use crate::authentification::CredentialsOrApiKey;
5use crate::error::Result;
6use crate::groups::Group;
7use crate::http::{client, encode, ok};
8
9#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
10#[serde(rename_all = "SCREAMING_SNAKE_CASE")]
11pub enum Sex {
12    Male,
13    Female,
14}
15
16#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
17#[serde(rename_all = "SCREAMING_SNAKE_CASE")]
18pub enum Race {
19    White,
20    Black,
21    NativeAmerican,
22    AlaskanNative,
23    Hawaiian,
24    Asian,
25    PacificIslander,
26    Hispanic,
27}
28
29#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
30#[serde(rename_all = "SCREAMING_SNAKE_CASE")]
31pub enum Ethnicity {
32    Italian,
33    Irish,
34    German,
35    French,
36    Spanish,
37    Portuguese,
38    Polish,
39    Scottish,
40    Norwegian,
41    Danish,
42    Swedish,
43    Finnish,
44    Icelandic,
45    Dutch,
46    Ukrainian,
47    Mexican,
48    Jewish,
49    Korean,
50    Chinese,
51    Japanese,
52    Filipino,
53    Vietnamese,
54    Indian,
55    Tamil,
56    Persian,
57    Arab,
58    Armenian,
59    Russian,
60    Greek,
61    Brazilian,
62    PuertoRican,
63    Haitian,
64}
65
66#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
67#[serde(rename_all = "SCREAMING_SNAKE_CASE")]
68pub enum Religion {
69    Christian,
70    Jewish,
71    Muslim,
72    Hindu,
73    Buddhist,
74    Sikh,
75    Spiritual,
76    Agnostic,
77    Atheist,
78    None,
79}
80
81#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
82#[serde(rename_all = "SCREAMING_SNAKE_CASE")]
83pub enum MaritalStatus {
84    Married,
85    Seperated,
86    Divorced,
87    Widowed,
88    NeverMarried,
89}
90
91#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
92#[serde(rename_all = "SCREAMING_SNAKE_CASE")]
93pub enum Education {
94    Doctoral,
95    Professional,
96    Master,
97    Bachelor,
98    Associate,
99    SomeCollege,
100    HighSchool,
101    None,
102}
103
104#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
105pub struct Demographic {
106    pub age: f64,
107    pub sex: Sex,
108    pub race: Race,
109    pub ethnicity: Vec<Ethnicity>,
110    pub religion: Religion,
111    pub birthplace: [f64; 2],
112    pub location: [f64; 2],
113    pub marital: MaritalStatus,
114    pub education: Education,
115    pub occupation: String,
116    pub income: f64,
117}
118
119/// `Partial<Demographic>` in the TypeScript SDK.
120#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
121pub struct PartialDemographic {
122    #[serde(default, skip_serializing_if = "Option::is_none")]
123    pub age: Option<f64>,
124    #[serde(default, skip_serializing_if = "Option::is_none")]
125    pub sex: Option<Sex>,
126    #[serde(default, skip_serializing_if = "Option::is_none")]
127    pub race: Option<Race>,
128    #[serde(default, skip_serializing_if = "Option::is_none")]
129    pub ethnicity: Option<Vec<Ethnicity>>,
130    #[serde(default, skip_serializing_if = "Option::is_none")]
131    pub religion: Option<Religion>,
132    #[serde(default, skip_serializing_if = "Option::is_none")]
133    pub birthplace: Option<[f64; 2]>,
134    #[serde(default, skip_serializing_if = "Option::is_none")]
135    pub location: Option<[f64; 2]>,
136    #[serde(default, skip_serializing_if = "Option::is_none")]
137    pub marital: Option<MaritalStatus>,
138    #[serde(default, skip_serializing_if = "Option::is_none")]
139    pub education: Option<Education>,
140    #[serde(default, skip_serializing_if = "Option::is_none")]
141    pub occupation: Option<String>,
142    #[serde(default, skip_serializing_if = "Option::is_none")]
143    pub income: Option<f64>,
144}
145
146#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
147pub struct Identity {
148    pub id: String,
149    pub demographic: Demographic,
150    pub background: String,
151    pub dialect: String,
152}
153
154/// The `opts` argument of the persona calls: `group` reads that group's personas.
155#[derive(Debug, Clone, Default)]
156pub struct PersonaOptions {
157    pub group: Option<Group>,
158}
159
160pub async fn all(authorization: &CredentialsOrApiKey, opts: PersonaOptions) -> Result<Vec<String>> {
161    let mut request = client()
162        .get(format!("{}/personas", super::get_url()))
163        .header(
164            "Authorization",
165            match authorization {
166                CredentialsOrApiKey::Credentials(credentials) => {
167                    format!("Token {}", credentials.token)
168                }
169                CredentialsOrApiKey::ApiKey(key) => format!("ApiKey {}", key.id),
170            },
171        );
172    if let Some(group) = &opts.group {
173        request = request.header("Group", &group.id);
174    }
175    Ok(request.send().await?.json().await?)
176}
177
178pub async fn get(
179    authorization: &CredentialsOrApiKey,
180    id: &str,
181    opts: PersonaOptions,
182) -> Result<Identity> {
183    let mut request = client()
184        .get(format!("{}/personas/{}", super::get_url(), encode(id)))
185        .header(
186            "Authorization",
187            match authorization {
188                CredentialsOrApiKey::Credentials(credentials) => {
189                    format!("Token {}", credentials.token)
190                }
191                CredentialsOrApiKey::ApiKey(key) => format!("ApiKey {}", key.id),
192            },
193        );
194    if let Some(group) = &opts.group {
195        request = request.header("Group", &group.id);
196    }
197    Ok(request.send().await?.json().await?)
198}
199
200/// `Race | Race[]` in the TypeScript SDK.
201#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
202#[serde(untagged)]
203pub enum RaceOrRaces {
204    Race(Race),
205    Races(Vec<Race>),
206}
207
208#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
209pub struct DemographicQuery {
210    #[serde(default, skip_serializing_if = "Option::is_none")]
211    pub age: Option<f64>,
212    #[serde(default, skip_serializing_if = "Option::is_none")]
213    pub sex: Option<Sex>,
214    #[serde(default, skip_serializing_if = "Option::is_none")]
215    pub race: Option<RaceOrRaces>,
216    #[serde(default, skip_serializing_if = "Option::is_none")]
217    pub location: Option<[f64; 2]>,
218    #[serde(default, skip_serializing_if = "Option::is_none")]
219    pub occupation: Option<String>,
220    #[serde(default, skip_serializing_if = "Option::is_none")]
221    pub income: Option<f64>,
222    #[serde(default, skip_serializing_if = "Option::is_none")]
223    pub interests: Option<Vec<String>>,
224}
225
226/// `{ min, max }` in the TypeScript SDK.
227#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
228pub struct DemographicRange {
229    pub min: f64,
230    pub max: f64,
231}
232
233#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
234pub struct DemographicFilters {
235    #[serde(default, skip_serializing_if = "Option::is_none")]
236    pub sex: Option<Vec<String>>,
237    #[serde(default, skip_serializing_if = "Option::is_none")]
238    pub race: Option<Vec<String>>,
239    #[serde(default, skip_serializing_if = "Option::is_none")]
240    pub age: Option<DemographicRange>,
241    #[serde(default, skip_serializing_if = "Option::is_none")]
242    pub income: Option<DemographicRange>,
243    #[serde(default, skip_serializing_if = "Option::is_none")]
244    pub occupation: Option<String>,
245}
246
247/// One weighted slice of a seed query.
248#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
249pub struct DemographicSlice {
250    pub weight: f64,
251    pub demographic: DemographicQuery,
252}
253
254/// The `opts` argument of `query_personas`.
255#[derive(Debug, Clone, Default)]
256pub struct PersonaQuery {
257    pub cursor: u32,
258    pub max: u32,
259    pub filters: Option<DemographicFilters>,
260    pub slices: Option<Vec<DemographicSlice>>,
261    pub group: Option<Group>,
262}
263
264/// Catalog browse (filters plus cursor and max) or weighted seed (slices, where max is the sample size).
265pub async fn query_personas(
266    authorization: &CredentialsOrApiKey,
267    opts: PersonaQuery,
268) -> Result<Vec<Identity>> {
269    let mut request = client()
270        .post(format!("{}/persona/query", super::get_url()))
271        .header(
272            "Authorization",
273            match authorization {
274                CredentialsOrApiKey::Credentials(credentials) => {
275                    format!("Token {}", credentials.token)
276                }
277                CredentialsOrApiKey::ApiKey(key) => format!("ApiKey {}", key.id),
278            },
279        );
280    if let Some(group) = &opts.group {
281        request = request.header("Group", &group.id);
282    }
283    let mut body = Map::new();
284    body.insert("cursor".to_string(), Value::from(opts.cursor));
285    body.insert("max".to_string(), Value::from(opts.max));
286    if let Some(filters) = &opts.filters {
287        body.insert("filters".to_string(), serde_json::to_value(filters)?);
288    }
289    if let Some(slices) = &opts.slices {
290        body.insert("slices".to_string(), serde_json::to_value(slices)?);
291    }
292    let response = request.json(&body).send().await?;
293    Ok(ok(response).await?.json().await?)
294}
295
296#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
297#[serde(rename_all = "lowercase")]
298pub enum PriorReason {
299    Hnsw,
300    Occupation,
301    Demo,
302}
303
304#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
305pub struct PriorEdge {
306    pub to: String,
307    pub weight: f64,
308    pub reasons: Vec<PriorReason>,
309}
310
311#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
312pub struct Prior {
313    pub embedder: String,
314    pub k: u32,
315    pub edges: Vec<PriorEdge>,
316}
317
318pub async fn prior(
319    authorization: &CredentialsOrApiKey,
320    id: &str,
321    opts: PersonaOptions,
322) -> Result<Prior> {
323    let mut request = client()
324        .get(format!("{}/persona/prior/{}", super::get_url(), encode(id)))
325        .header(
326            "Authorization",
327            match authorization {
328                CredentialsOrApiKey::Credentials(credentials) => {
329                    format!("Token {}", credentials.token)
330                }
331                CredentialsOrApiKey::ApiKey(key) => format!("ApiKey {}", key.id),
332            },
333        );
334    if let Some(group) = &opts.group {
335        request = request.header("Group", &group.id);
336    }
337    let response = request.send().await?;
338    Ok(ok(response).await?.json().await?)
339}