Skip to main content

fauna_api/parrot/
agent.rs

1use futures_util::stream::BoxStream;
2use serde::{Deserialize, Serialize};
3use serde_json::{Map, Value, json};
4
5use super::generative::{
6    Content, Image, StreamEvent, Text, TextResponse, ToolsOrTool, Video, Voice, VoiceEvent,
7};
8use super::socket;
9use crate::ant::persona::PartialDemographic;
10use crate::authentification::CredentialsOrApiKey;
11use crate::error::Result;
12use crate::groups::Group;
13use crate::http::{client, ok};
14
15#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
16pub struct Memory {
17    pub id: u64,
18    pub memory: String,
19    pub scope: String,
20    #[serde(default)]
21    pub embedding: Vec<f64>,
22}
23
24#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
25pub struct Memories {
26    pub nodes: Vec<Memory>,
27    pub edges: Vec<(u64, u64)>,
28    pub scopes: Vec<String>,
29}
30
31/// Observe: store a new memory. Pass `group` to act on that group's shared
32/// memory graph instead of the caller's personal one (caller must be a member).
33pub async fn observe(
34    authorization: &CredentialsOrApiKey,
35    content: &str,
36    group: Option<&Group>,
37) -> Result<Memory> {
38    let mut request = client()
39        .post(format!("{}/agent/memories", super::get_url()))
40        .header(
41            "Authorization",
42            match authorization {
43                CredentialsOrApiKey::Credentials(credentials) => {
44                    format!("Token {}", credentials.token)
45                }
46                CredentialsOrApiKey::ApiKey(key) => format!("ApiKey {}", key.id),
47            },
48        );
49    if let Some(group) = group {
50        request = request.header("Group", &group.id);
51    }
52    let response = request.json(&json!({ "content": content })).send().await?;
53    Ok(ok(response).await?.json().await?)
54}
55
56/// Recall: query associative memory. Pass `group` for that group's shared graph.
57pub async fn recall(
58    authorization: &CredentialsOrApiKey,
59    query: &str,
60    scope: Option<&str>,
61    group: Option<&Group>,
62) -> Result<Vec<Memory>> {
63    let mut request = client()
64        .post(format!("{}/agent/recall", super::get_url()))
65        .header(
66            "Authorization",
67            match authorization {
68                CredentialsOrApiKey::Credentials(credentials) => {
69                    format!("Token {}", credentials.token)
70                }
71                CredentialsOrApiKey::ApiKey(key) => format!("ApiKey {}", key.id),
72            },
73        );
74    if let Some(group) = group {
75        request = request.header("Group", &group.id);
76    }
77    let mut body = Map::new();
78    body.insert("query".to_string(), Value::from(query));
79    if let Some(scope) = scope {
80        body.insert("scope".to_string(), Value::from(scope));
81    }
82    let response = request.json(&body).send().await?;
83    Ok(ok(response).await?.json().await?)
84}
85
86/// Export: get the full memory graph. Pass `group` for that group's shared graph.
87pub async fn export_memory(
88    authorization: &CredentialsOrApiKey,
89    group: Option<&Group>,
90) -> Result<Memories> {
91    let mut request = client()
92        .get(format!("{}/agent/memories", super::get_url()))
93        .header(
94            "Authorization",
95            match authorization {
96                CredentialsOrApiKey::Credentials(credentials) => {
97                    format!("Token {}", credentials.token)
98                }
99                CredentialsOrApiKey::ApiKey(key) => format!("ApiKey {}", key.id),
100            },
101        );
102    if let Some(group) = group {
103        request = request.header("Group", &group.id);
104    }
105    let response = request.send().await?;
106    Ok(ok(response).await?.json().await?)
107}
108
109/// Remove: delete a specific memory node. Pass `group` for that group's graph.
110pub async fn remove_memory(
111    authorization: &CredentialsOrApiKey,
112    id: u64,
113    group: Option<&Group>,
114) -> Result<()> {
115    let mut request = client()
116        .delete(format!("{}/agent/memories/{id}", super::get_url()))
117        .header(
118            "Authorization",
119            match authorization {
120                CredentialsOrApiKey::Credentials(credentials) => {
121                    format!("Token {}", credentials.token)
122                }
123                CredentialsOrApiKey::ApiKey(key) => format!("ApiKey {}", key.id),
124            },
125        );
126    if let Some(group) = group {
127        request = request.header("Group", &group.id);
128    }
129    ok(request.send().await?).await?;
130    Ok(())
131}
132
133/// Clear: wipe the entire memory graph. Pass `group` for that group's graph.
134pub async fn clear_memory(
135    authorization: &CredentialsOrApiKey,
136    group: Option<&Group>,
137) -> Result<()> {
138    let mut request = client()
139        .delete(format!("{}/agent/memories", super::get_url()))
140        .header(
141            "Authorization",
142            match authorization {
143                CredentialsOrApiKey::Credentials(credentials) => {
144                    format!("Token {}", credentials.token)
145                }
146                CredentialsOrApiKey::ApiKey(key) => format!("ApiKey {}", key.id),
147            },
148        );
149    if let Some(group) = group {
150        request = request.header("Group", &group.id);
151    }
152    ok(request.send().await?).await?;
153    Ok(())
154}
155
156/// The `options` argument of the agent's `generate_text` and `generate_text_sync`:
157/// the generative options plus `memories`, how many to recall on the latest
158/// request, and `group`, whose memory graph. Dropping the returned stream
159/// closes the socket.
160#[derive(Debug, Clone, Default)]
161pub struct TextOptions {
162    pub content: Option<Vec<Content>>,
163    pub tools: Option<ToolsOrTool>,
164    pub max_tools: Option<u32>,
165    pub memories: Option<u32>,
166    pub reasoning: Option<String>,
167    pub group: Option<Group>,
168}
169
170/// Streaming text generation. A singular Tool forces it; an array lets the model
171/// choose. Where the model can call tools it can also save memories with
172/// observe_memory.
173pub async fn generate_text(
174    authorization: &CredentialsOrApiKey,
175    model: Text,
176    options: TextOptions,
177) -> Result<BoxStream<'static, StreamEvent>> {
178    socket::stream_text(
179        authorization,
180        "/agent/text",
181        model.as_str(),
182        socket::TextOptions {
183            content: options.content,
184            tools: options.tools,
185            max_tools: options.max_tools,
186            memories: options.memories,
187            reasoning: options.reasoning,
188            group: options.group,
189        },
190    )
191    .await
192}
193
194pub async fn generate_text_sync(
195    authorization: &CredentialsOrApiKey,
196    model: Text,
197    options: TextOptions,
198) -> Result<TextResponse> {
199    socket::collect_text(generate_text(authorization, model, options).await?).await
200}
201
202/// The `options` argument of the agent's `generate_voice` and `generate_voice_sync`.
203#[derive(Default)]
204pub struct VoiceOptions {
205    pub content: Option<Vec<Content>>,
206    pub audio: Option<BoxStream<'static, Vec<u8>>>,
207    pub notes: Option<BoxStream<'static, String>>,
208    pub tools: Option<ToolsOrTool>,
209    pub max_tools: Option<u32>,
210    pub voice: Option<PartialDemographic>,
211    pub memories: Option<u32>,
212    pub brain: Option<Text>,
213    pub reasoning: Option<String>,
214    pub group: Option<Group>,
215}
216
217/// Realtime voice: PCM16 16 kHz in from `audio`, PCM16 24 kHz out as audio events. Each of
218/// `notes` tells the model something to act on now. An ElevenLabs voice thinks with `brain`
219/// (a text model, through Fauna) at `reasoning`, and needs one; OpenAI and xAI voices are
220/// their own brain.
221pub async fn generate_voice(
222    authorization: &CredentialsOrApiKey,
223    model: Voice,
224    options: VoiceOptions,
225) -> Result<BoxStream<'static, VoiceEvent>> {
226    socket::stream_voice(
227        authorization,
228        "/agent/voice",
229        model.as_str(),
230        socket::VoiceOptions {
231            content: options.content,
232            audio: options.audio,
233            notes: options.notes,
234            tools: options.tools,
235            max_tools: options.max_tools,
236            voice: options.voice,
237            memories: options.memories,
238            brain: options.brain.map(|brain| brain.as_str().to_string()),
239            reasoning: options.reasoning,
240            group: options.group,
241        },
242    )
243    .await
244}
245
246pub async fn generate_voice_sync(
247    authorization: &CredentialsOrApiKey,
248    model: Voice,
249    options: VoiceOptions,
250) -> Result<TextResponse> {
251    socket::collect_voice(
252        authorization,
253        generate_voice(authorization, model, options).await?,
254    )
255    .await
256}
257
258/// The `options` argument of the agent's `generate_image`.
259#[derive(Debug, Clone, Default)]
260pub struct ImageOptions {
261    pub content: Option<Vec<Content>>,
262    pub size: Option<[u32; 2]>,
263    pub memories: Option<u32>,
264    pub group: Option<Group>,
265}
266
267pub async fn generate_image(
268    authorization: &CredentialsOrApiKey,
269    model: Image,
270    options: ImageOptions,
271) -> Result<TextResponse> {
272    let mut extra = Map::new();
273    if let Some(size) = options.size {
274        extra.insert("size".to_string(), json!(size));
275    }
276    if let Some(memories) = options.memories {
277        extra.insert("memories".to_string(), Value::from(memories));
278    }
279    socket::generate_media(
280        authorization,
281        "/agent/image",
282        model.as_str(),
283        options.content,
284        options.group,
285        extra,
286        "image/png",
287    )
288    .await
289}
290
291/// The `options` argument of the agent's `generate_video`.
292#[derive(Debug, Clone, Default)]
293pub struct VideoOptions {
294    pub content: Option<Vec<Content>>,
295    pub duration: Option<f64>,
296    pub size: Option<[u32; 2]>,
297    pub memories: Option<u32>,
298    pub group: Option<Group>,
299}
300
301pub async fn generate_video(
302    authorization: &CredentialsOrApiKey,
303    model: Video,
304    options: VideoOptions,
305) -> Result<TextResponse> {
306    let mut extra = Map::new();
307    if let Some(duration) = options.duration {
308        extra.insert("duration".to_string(), Value::from(duration));
309    }
310    if let Some(size) = options.size {
311        extra.insert("size".to_string(), json!(size));
312    }
313    if let Some(memories) = options.memories {
314        extra.insert("memories".to_string(), Value::from(memories));
315    }
316    socket::generate_media(
317        authorization,
318        "/agent/video",
319        model.as_str(),
320        options.content,
321        options.group,
322        extra,
323        "video/mp4",
324    )
325    .await
326}