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 group: Option<Group>,
213}
214
215/// Realtime voice: PCM16 16 kHz in from `audio`, PCM16 24 kHz out as audio events. Each of
216/// `notes` tells the model something to act on now.
217pub async fn generate_voice(
218    authorization: &CredentialsOrApiKey,
219    model: Voice,
220    options: VoiceOptions,
221) -> Result<BoxStream<'static, VoiceEvent>> {
222    socket::stream_voice(
223        authorization,
224        "/agent/voice",
225        model.as_str(),
226        socket::VoiceOptions {
227            content: options.content,
228            audio: options.audio,
229            notes: options.notes,
230            tools: options.tools,
231            max_tools: options.max_tools,
232            voice: options.voice,
233            memories: options.memories,
234            group: options.group,
235        },
236    )
237    .await
238}
239
240pub async fn generate_voice_sync(
241    authorization: &CredentialsOrApiKey,
242    model: Voice,
243    options: VoiceOptions,
244) -> Result<TextResponse> {
245    socket::collect_voice(
246        authorization,
247        generate_voice(authorization, model, options).await?,
248    )
249    .await
250}
251
252/// The `options` argument of the agent's `generate_image`.
253#[derive(Debug, Clone, Default)]
254pub struct ImageOptions {
255    pub content: Option<Vec<Content>>,
256    pub size: Option<[u32; 2]>,
257    pub memories: Option<u32>,
258    pub group: Option<Group>,
259}
260
261pub async fn generate_image(
262    authorization: &CredentialsOrApiKey,
263    model: Image,
264    options: ImageOptions,
265) -> Result<TextResponse> {
266    let mut extra = Map::new();
267    if let Some(size) = options.size {
268        extra.insert("size".to_string(), json!(size));
269    }
270    if let Some(memories) = options.memories {
271        extra.insert("memories".to_string(), Value::from(memories));
272    }
273    socket::generate_media(
274        authorization,
275        "/agent/image",
276        model.as_str(),
277        options.content,
278        options.group,
279        extra,
280        "image/png",
281    )
282    .await
283}
284
285/// The `options` argument of the agent's `generate_video`.
286#[derive(Debug, Clone, Default)]
287pub struct VideoOptions {
288    pub content: Option<Vec<Content>>,
289    pub duration: Option<f64>,
290    pub size: Option<[u32; 2]>,
291    pub memories: Option<u32>,
292    pub group: Option<Group>,
293}
294
295pub async fn generate_video(
296    authorization: &CredentialsOrApiKey,
297    model: Video,
298    options: VideoOptions,
299) -> Result<TextResponse> {
300    let mut extra = Map::new();
301    if let Some(duration) = options.duration {
302        extra.insert("duration".to_string(), Value::from(duration));
303    }
304    if let Some(size) = options.size {
305        extra.insert("size".to_string(), json!(size));
306    }
307    if let Some(memories) = options.memories {
308        extra.insert("memories".to_string(), Value::from(memories));
309    }
310    socket::generate_media(
311        authorization,
312        "/agent/video",
313        model.as_str(),
314        options.content,
315        options.group,
316        extra,
317        "video/mp4",
318    )
319    .await
320}