Add builders and docs for fluent-sdk

Author: njfio

README.md

@@ -12,6 +12,8 @@
 
 Fluent CLI is a powerful command-line interface for interacting with various AI engines. It provides a unified way to send requests, receive responses, and manage interactions with different AI services.
 
+For programmatic access, check out the [`fluent-sdk` crate](https://crates.io/crates/fluent-sdk).
+
 ### Installation
 
 Fluent CLI requires Rust and Cargo to be installed on your system. You can install them using the instructions on the [Rust website](https://www.rust-lang.org/tools/install).

crates/fluent-sdk/Cargo.toml

@@ -2,6 +2,11 @@
 name = "fluent-sdk"
 version = "0.1.0"
 edition = "2021"
+description = "SDK for interacting with the Fluent AI engine configurations"
+license = "MIT"
+repository = "https://github.com/njfio/fluent_cli"
+readme = "../../README.md"
+homepage = "https://fluentcli.com"
 
 
 [dependencies]

crates/fluent-sdk/examples/openai.rs

@@ -0,0 +1,13 @@
+use fluent_sdk::prelude::*;
+
+#[tokio::main]
+async fn main() -> anyhow::Result<()> {
+    let request = FluentOpenAIChatRequest::builder()
+        .prompt("Hello, world!".to_string())
+        .openai_key("YOUR_OPENAI_KEY".to_string())
+        .build()?;
+
+    let response = request.run().await?;
+    println!("{:?}", response.data);
+    Ok(())
+}

crates/fluent-sdk/src/lib.rs

@@ -1,3 +1,10 @@
+//! Fluent SDK provides strongly typed builders for composing requests to the
+//! various engines supported by Fluent.
+//!
+//! Most users will interact with the [`FluentOpenAIChatRequestBuilder`], but a
+//! generic [`FluentRequestBuilder`] is also available when you need full
+//! control.
+
 use anyhow::anyhow;
 use serde::{Deserialize, Serialize};
 use serde_json::Value;
@@ -38,6 +45,10 @@ pub struct FluentRequest {
     pub parse_code: Option<bool>,
 }
 impl FluentRequest {
+    /// Creates a new [`FluentRequestBuilder`].
+    pub fn builder() -> FluentRequestBuilder {
+        FluentRequestBuilder::default()
+    }
     pub async fn run(&self) -> anyhow::Result<Response> {
         // Convert the implementing type into a FluentRequest
         let request = self.clone();
@@ -88,6 +99,71 @@ impl FluentRequest {
     }
 }
 
+/// Builder for [`FluentRequest`].
+#[derive(Debug, Clone)]
+pub struct FluentRequestBuilder {
+    request: FluentRequest,
+}
+
+impl Default for FluentRequestBuilder {
+    fn default() -> Self {
+        Self {
+            request: FluentRequest {
+                engine: None,
+                credentials: Some(Vec::new()),
+                overrides: Some(HashMap::new()),
+                request: None,
+                parse_code: Some(false),
+            },
+        }
+    }
+}
+
+impl FluentRequestBuilder {
+    /// Sets the engine template to use.
+    pub fn engine(mut self, engine: EngineTemplate) -> Self {
+        self.request.engine = Some(engine);
+        self
+    }
+
+    /// Sets the request string that will be sent to the engine.
+    pub fn request(mut self, request: impl Into<String>) -> Self {
+        self.request.request = Some(request.into());
+        self
+    }
+
+    /// Adds a credential key/value pair.
+    pub fn credential(mut self, kv: impl Into<KeyValue>) -> Self {
+        let entry = self.request.credentials.get_or_insert_with(Vec::new);
+        entry.push(kv.into());
+        self
+    }
+
+    /// Adds a single override parameter.
+    pub fn override_param(mut self, key: impl Into<String>, value: Value) -> Self {
+        let map = self.request.overrides.get_or_insert_with(HashMap::new);
+        map.insert(key.into(), value);
+        self
+    }
+
+    /// Whether to parse code blocks from the engine output.
+    pub fn parse_code(mut self, parse: bool) -> Self {
+        self.request.parse_code = Some(parse);
+        self
+    }
+
+    /// Finalises the builder returning a [`FluentRequest`].
+    pub fn build(self) -> anyhow::Result<FluentRequest> {
+        if self.request.engine.is_none() {
+            return Err(anyhow!("Engine is required"));
+        }
+        if self.request.request.is_none() {
+            return Err(anyhow!("Request is required"));
+        }
+        Ok(self.request)
+    }
+}
+
 #[derive(Debug, PartialEq, EnumString, Serialize, Deserialize, Display, Clone)]
 pub enum EngineTemplate {
     #[strum(ascii_case_insensitive, to_string = "openai-chat-completions")]

crates/fluent-sdk/src/openai.rs

@@ -6,6 +6,7 @@ use crate::{EngineTemplate, FluentRequest, FluentSdkRequest, KeyValue};
 
 impl FluentSdkRequest for FluentOpenAIChatRequest {}
 
+/// Request data used for OpenAI chat completions.
 #[derive(Debug, Deserialize, Serialize, Clone)]
 pub struct FluentOpenAIChatRequest {
     pub prompt: String,
@@ -20,6 +21,12 @@ pub struct FluentOpenAIChatRequest {
     pub frequency_penalty: Option<f64>,
     pub presence_penalty: Option<f64>,
 }
+impl FluentOpenAIChatRequest {
+    /// Creates a new [`FluentOpenAIChatRequestBuilder`].
+    pub fn builder() -> FluentOpenAIChatRequestBuilder {
+        FluentOpenAIChatRequestBuilder::default()
+    }
+}
 impl From<FluentOpenAIChatRequest> for FluentRequest {
     fn from(request: FluentOpenAIChatRequest) -> Self {
         let mut overrides = vec![];
@@ -60,6 +67,7 @@ impl From<FluentOpenAIChatRequest> for FluentRequest {
     }
 }
 
+/// Builder for [`FluentOpenAIChatRequest`].
 #[derive(Debug, Deserialize, Serialize, Clone)]
 pub struct FluentOpenAIChatRequestBuilder {
     request: FluentOpenAIChatRequest,
@@ -71,12 +79,12 @@ impl Default for FluentOpenAIChatRequestBuilder {
                 prompt: String::new(),
                 openai_key: String::new(),
                 response_format: None,
-                temperature: None,
+                temperature: Some(0.7),
                 max_tokens: None,
-                top_p: None,
+                top_p: Some(1.0),
                 frequency_penalty: None,
                 presence_penalty: None,
-                model: None,
+                model: Some("gpt-3.5-turbo".to_string()),
                 n: None,
                 stop: None,
             },
@@ -85,50 +93,62 @@ impl Default for FluentOpenAIChatRequestBuilder {
 }
 
 impl FluentOpenAIChatRequestBuilder {
+    /// Sets the user prompt.
     pub fn prompt(mut self, prompt: String) -> Self {
         self.request.prompt = prompt;
         self
     }
+    /// Sets the OpenAI API key.
     pub fn openai_key(mut self, openai_key: String) -> Self {
         self.request.openai_key = openai_key;
         self
     }
+    /// Overrides the `response_format` parameter.
     pub fn response_format(mut self, response_format: Value) -> Self {
         self.request.response_format = Some(response_format);
         self
     }
+    /// Overrides the `temperature` parameter.
     pub fn temperature(mut self, temperature: f64) -> Self {
         self.request.temperature = Some(temperature);
         self
     }
+    /// Overrides the `max_tokens` parameter.
     pub fn max_tokens(mut self, max_tokens: i64) -> Self {
         self.request.max_tokens = Some(max_tokens);
         self
     }
+    /// Overrides the `top_p` parameter.
     pub fn top_p(mut self, top_p: f64) -> Self {
         self.request.top_p = Some(top_p);
         self
     }
+    /// Overrides the `frequency_penalty` parameter.
     pub fn frequency_penalty(mut self, frequency_penalty: f64) -> Self {
         self.request.frequency_penalty = Some(frequency_penalty);
         self
     }
+    /// Overrides the `presence_penalty` parameter.
     pub fn presence_penalty(mut self, presence_penalty: f64) -> Self {
         self.request.presence_penalty = Some(presence_penalty);
         self
     }
+    /// Overrides the model to use.
     pub fn model(mut self, model: String) -> Self {
         self.request.model = Some(model);
         self
     }
+    /// Overrides the `n` parameter.
     pub fn n(mut self, n: i8) -> Self {
         self.request.n = Some(n);
         self
     }
+    /// Overrides the `stop` parameter.
     pub fn stop(mut self, stop: Vec<String>) -> Self {
         self.request.stop = Some(stop);
         self
     }
+    /// Builds the request returning an error if required fields are missing.
     pub fn build(self) -> anyhow::Result<FluentOpenAIChatRequest> {
         if self.request.prompt.is_empty() {
             return Err(anyhow!("Prompt is required"));