1use std::sync::Arc;
10
11use base64::engine::general_purpose::STANDARD as BASE64_STANDARD;
12use base64::Engine as _;
13
14use agent_framework_core::client::EmbeddingClient;
15use agent_framework_core::error::{Error, Result};
16use agent_framework_core::types::{
17 Embedding, EmbeddingGenerationOptions, EmbeddingInput, GeneratedEmbeddings, UsageDetails,
18};
19use serde_json::{json, Map, Value};
20
21use crate::{classify_service_error, parse_retry_after, DEFAULT_BASE_URL};
22
23#[derive(Clone)]
38pub struct OpenAIEmbeddingClient {
39 inner: Arc<Inner>,
40}
41
42struct Inner {
43 http: reqwest::Client,
44 api_key: String,
45 base_url: String,
46 model: String,
47 organization: Option<String>,
48}
49
50impl OpenAIEmbeddingClient {
51 pub fn new(api_key: impl Into<String>, model: impl Into<String>) -> Self {
53 Self {
54 inner: Arc::new(Inner {
55 http: crate::http_client(),
56 api_key: api_key.into(),
57 base_url: DEFAULT_BASE_URL.to_string(),
58 model: model.into(),
59 organization: None,
60 }),
61 }
62 }
63
64 pub fn from_env(model: impl Into<String>) -> Result<Self> {
69 let key = std::env::var("OPENAI_API_KEY")
70 .map_err(|_| Error::Configuration("OPENAI_API_KEY is not set".into()))?;
71 let mut model = model.into();
72 if model.is_empty() {
73 model = std::env::var("OPENAI_EMBEDDING_MODEL").map_err(|_| {
74 Error::Configuration(
75 "no embedding model: pass one or set OPENAI_EMBEDDING_MODEL".into(),
76 )
77 })?;
78 }
79 let mut client = Self::new(key, model);
80 if let Ok(base) = std::env::var("OPENAI_BASE_URL") {
81 client = client.with_base_url(base);
82 }
83 Ok(client)
84 }
85
86 pub fn with_base_url(mut self, base_url: impl Into<String>) -> Self {
88 arc_inner(&mut self.inner).base_url = base_url.into();
89 self
90 }
91
92 pub fn with_organization(mut self, org: impl Into<String>) -> Self {
94 arc_inner(&mut self.inner).organization = Some(org.into());
95 self
96 }
97
98 fn build_body(&self, values: &[String], options: Option<&EmbeddingGenerationOptions>) -> Value {
99 let mut body = Map::new();
100 let model = options
101 .and_then(|o| o.model.clone())
102 .unwrap_or_else(|| self.inner.model.clone());
103 body.insert("model".into(), json!(model));
104 body.insert("input".into(), json!(values));
105 if let Some(options) = options {
106 if let Some(dimensions) = options.dimensions {
107 body.insert("dimensions".into(), json!(dimensions));
108 }
109 for key in ["encoding_format", "user"] {
112 if let Some(v) = options.additional_properties.get(key) {
113 body.insert(key.into(), v.clone());
114 }
115 }
116 }
117 Value::Object(body)
118 }
119}
120
121fn arc_inner(inner: &mut Arc<Inner>) -> &mut Inner {
125 if Arc::strong_count(inner) != 1 {
126 *inner = Arc::new(Inner {
127 http: inner.http.clone(),
128 api_key: inner.api_key.clone(),
129 base_url: inner.base_url.clone(),
130 model: inner.model.clone(),
131 organization: inner.organization.clone(),
132 });
133 }
134 Arc::get_mut(inner).expect("just ensured unique")
135}
136
137fn parse_embedding_vector(field: Option<&Value>) -> Result<Vec<f32>> {
146 match field {
147 Some(Value::Array(values)) => Ok(values
148 .iter()
149 .map(|v| v.as_f64().unwrap_or_default() as f32)
150 .collect()),
151 Some(Value::String(encoded)) => {
152 let bytes = BASE64_STANDARD.decode(encoded.as_bytes()).map_err(|e| {
153 Error::service(format!("embeddings item has undecodable base64: {e}"))
154 })?;
155 if bytes.len() % 4 != 0 {
156 return Err(Error::service(format!(
157 "base64 embedding decodes to {} bytes, not a whole number of f32s",
158 bytes.len()
159 )));
160 }
161 let mut vector = Vec::with_capacity(bytes.len() / 4);
168 let mut rest = bytes.as_slice();
169 while let Some((chunk, tail)) = rest.split_first_chunk::<4>() {
170 vector.push(f32::from_le_bytes(*chunk));
171 rest = tail;
172 }
173 Ok(vector)
174 }
175 _ => Err(Error::service("embeddings item missing 'embedding' vector")),
176 }
177}
178
179pub fn parse_embeddings_response(value: &Value) -> Result<GeneratedEmbeddings> {
187 let model = value.get("model").and_then(Value::as_str);
188 let data = value
189 .get("data")
190 .and_then(Value::as_array)
191 .ok_or_else(|| Error::service("embeddings response missing 'data' array"))?;
192
193 let mut indexed: Vec<(usize, Embedding)> = Vec::with_capacity(data.len());
194 for (position, item) in data.iter().enumerate() {
195 let vector = parse_embedding_vector(item.get("embedding"))?;
196 let index = item
197 .get("index")
198 .and_then(Value::as_u64)
199 .map(|i| i as usize)
200 .unwrap_or(position);
201 indexed.push((
202 index,
203 Embedding {
204 vector,
205 model: model.map(String::from),
206 },
207 ));
208 }
209 indexed.sort_by_key(|(i, _)| *i);
210
211 let mut batch = GeneratedEmbeddings::new(indexed.into_iter().map(|(_, e)| e).collect());
212 if let Some(usage) = value.get("usage") {
213 let input = usage.get("prompt_tokens").and_then(Value::as_u64);
214 let total = usage.get("total_tokens").and_then(Value::as_u64);
215 if input.is_some() || total.is_some() {
216 batch.usage = Some(UsageDetails {
217 input_token_count: input,
218 total_token_count: total,
219 ..Default::default()
220 });
221 }
222 }
223 Ok(batch)
224}
225
226#[async_trait::async_trait]
227impl EmbeddingClient for OpenAIEmbeddingClient {
228 async fn get_embeddings(
229 &self,
230 values: Vec<EmbeddingInput>,
231 options: Option<EmbeddingGenerationOptions>,
232 ) -> Result<GeneratedEmbeddings> {
233 let values = EmbeddingInput::into_texts(values, "OpenAI")?;
234 let body = self.build_body(&values, options.as_ref());
235 let url = format!("{}/embeddings", self.inner.base_url.trim_end_matches('/'));
236 let mut req = self
237 .inner
238 .http
239 .post(&url)
240 .bearer_auth(&self.inner.api_key)
241 .json(&body);
242 if let Some(org) = &self.inner.organization {
243 req = req.header("OpenAI-Organization", org);
244 }
245 let resp = req.send().await.map_err(|e| {
246 Error::service(format!(
247 "request failed: {}",
248 agent_framework_core::error::error_chain(&e)
249 ))
250 })?;
251 if !resp.status().is_success() {
252 let status = resp.status();
253 let retry_after = parse_retry_after(resp.headers());
254 let text = resp.text().await.unwrap_or_default();
255 return Err(classify_service_error(
256 status.as_u16(),
257 &text,
258 format!("OpenAI API error {status}: {text}"),
259 retry_after,
260 ));
261 }
262 let value: Value = resp
263 .json()
264 .await
265 .map_err(|e| Error::service(format!("invalid response json: {e}")))?;
266 parse_embeddings_response(&value)
267 }
268
269 fn model(&self) -> Option<&str> {
270 Some(&self.inner.model)
271 }
272}
273
274#[cfg(test)]
275mod tests {
276 use super::*;
277
278 #[test]
279 fn build_body_includes_model_input_and_dimensions() {
280 let client = OpenAIEmbeddingClient::new("sk-test", "text-embedding-3-small");
281 let options = EmbeddingGenerationOptions::new().with_dimensions(256);
282 let body = client.build_body(&["a".into(), "b".into()], Some(&options));
283 assert_eq!(body["model"], "text-embedding-3-small");
284 assert_eq!(body["input"], json!(["a", "b"]));
285 assert_eq!(body["dimensions"], 256);
286 }
287
288 #[test]
289 fn build_body_option_model_overrides_default() {
290 let client = OpenAIEmbeddingClient::new("sk-test", "text-embedding-3-small");
291 let options = EmbeddingGenerationOptions::new().with_model("text-embedding-3-large");
292 let body = client.build_body(&["a".into()], Some(&options));
293 assert_eq!(body["model"], "text-embedding-3-large");
294 }
295
296 #[test]
297 fn build_body_forwards_known_additional_properties_only() {
298 let client = OpenAIEmbeddingClient::new("sk-test", "m");
299 let mut options = EmbeddingGenerationOptions::new();
300 options
301 .additional_properties
302 .insert("encoding_format".into(), json!("float"));
303 options
304 .additional_properties
305 .insert("unrelated".into(), json!(true));
306 let body = client.build_body(&["a".into()], Some(&options));
307 assert_eq!(body["encoding_format"], "float");
308 assert!(body.get("unrelated").is_none());
309 }
310
311 #[test]
312 fn parse_response_restores_index_order_and_usage() {
313 let value = json!({
314 "model": "text-embedding-3-small",
315 "data": [
316 { "index": 1, "embedding": [0.3, 0.4] },
317 { "index": 0, "embedding": [0.1, 0.2] },
318 ],
319 "usage": { "prompt_tokens": 5, "total_tokens": 5 }
320 });
321 let batch = parse_embeddings_response(&value).unwrap();
322 assert_eq!(batch.len(), 2);
323 assert_eq!(batch[0].vector, vec![0.1, 0.2]);
324 assert_eq!(batch[1].vector, vec![0.3, 0.4]);
325 assert_eq!(batch[0].model.as_deref(), Some("text-embedding-3-small"));
326 let usage = batch.usage.as_ref().unwrap();
327 assert_eq!(usage.input_token_count, Some(5));
328 assert_eq!(usage.total_token_count, Some(5));
329 }
330
331 #[test]
332 fn parse_response_missing_data_errors() {
333 assert!(parse_embeddings_response(&json!({})).is_err());
334 }
335
336 #[test]
341 fn parse_response_decodes_base64_embeddings() {
342 let vector: [f32; 3] = [1.0, -2.5, 0.125];
343 let mut bytes = Vec::new();
344 for f in vector {
345 bytes.extend_from_slice(&f.to_le_bytes());
346 }
347 let encoded = BASE64_STANDARD.encode(&bytes);
348
349 let value = json!({
350 "data": [{ "index": 0, "embedding": encoded }],
351 "model": "text-embedding-3-small",
352 });
353 let batch = parse_embeddings_response(&value).unwrap();
354 assert_eq!(batch.embeddings[0].vector, vector.to_vec());
355 }
356
357 #[test]
358 fn parse_response_mixes_base64_and_array_items_by_index() {
359 let encoded = BASE64_STANDARD.encode(2.0f32.to_le_bytes());
360 let value = json!({
361 "data": [
362 { "index": 1, "embedding": encoded },
363 { "index": 0, "embedding": [1.0] },
364 ],
365 });
366 let batch = parse_embeddings_response(&value).unwrap();
367 assert_eq!(batch.embeddings[0].vector, vec![1.0]);
368 assert_eq!(batch.embeddings[1].vector, vec![2.0]);
369 }
370
371 #[test]
372 fn parse_response_rejects_undecodable_or_misaligned_base64() {
373 let bad = json!({ "data": [{ "index": 0, "embedding": "!!!not base64!!!" }] });
375 assert!(parse_embeddings_response(&bad).is_err());
376
377 let misaligned = BASE64_STANDARD.encode([1u8, 2, 3, 4, 5]);
380 let value = json!({ "data": [{ "index": 0, "embedding": misaligned }] });
381 let err = parse_embeddings_response(&value).unwrap_err();
382 assert!(err.to_string().contains("whole number of f32s"), "{err}");
383 }
384}