feat: responses API integration (#2103)

- This PR adds support for the [Responses
API](https://platform.openai.com/docs/api-reference/responses) by OpenAI
by adding a new provider called `openai-responses`

Author: ba11b0y

.claude/settings.local.json

@@ -8,7 +8,8 @@
       "Bash(uv run:*)",
       "Bash(find:*)",
       "Bash(rg:*)",
-      "Bash(cargo check:*)"
+      "Bash(cargo check:*)",
+      "Bash(cargo build:*)"
     ],
     "deny": []
   }

engine/baml-lib/llm-client/src/clients/helpers.rs

@@ -332,13 +332,14 @@ impl<Meta: Clone> PropertyHandler<Meta> {
                 if let StringOr::Value(value) = value {
                     Some(match value.as_str() {
                         "openai" => UnresolvedResponseType::OpenAI,
+                        "openai-responses" => UnresolvedResponseType::OpenAIResponses,
                         "anthropic" => UnresolvedResponseType::Anthropic,
                         "google" => UnresolvedResponseType::Google,
                         "vertex" => UnresolvedResponseType::Vertex,
                         other => {
                             self.push_error(
                                 format!(
-                                    "client_response_type must be one of \"openai\", \"anthropic\", \"google\", or \"vertex\". Got: {other}"
+                                    "client_response_type must be one of \"openai\", \"openai-responses\", \"anthropic\", \"google\", or \"vertex\". Got: {other}"
                                 ),
                                 key_span,
                             );
@@ -347,7 +348,7 @@ impl<Meta: Clone> PropertyHandler<Meta> {
                     })
                 } else {
                     self.push_error(
-                        "client_response_type must be one of \"openai\", \"anthropic\", \"google\", or \"vertex\" and not an environment variable",
+                        "client_response_type must be one of \"openai\", \"openai-responses\", \"anthropic\", \"google\", or \"vertex\" and not an environment variable",
                         key_span,
                     );
                     None

engine/baml-lib/llm-client/src/clients/mod.rs

@@ -184,6 +184,9 @@ impl crate::OpenAIClientProviderVariant {
             crate::OpenAIClientProviderVariant::Generic => {
                 openai::UnresolvedOpenAI::create_generic(properties)
             }
+            crate::OpenAIClientProviderVariant::Responses => {
+                openai::UnresolvedOpenAI::create_responses(properties)
+            }
         }
     }
 }

engine/baml-lib/llm-client/src/clients/openai.rs

@@ -61,9 +61,9 @@ impl<Meta> UnresolvedOpenAI<Meta> {
 pub struct ResolvedOpenAI {
     pub base_url: String,
     pub api_key: Option<ApiKeyWithProvenance>,
-    role_selection: RolesSelection,
+    pub role_selection: RolesSelection,
     pub allowed_metadata: AllowedRoleMetadata,
-    supported_request_modes: SupportedRequestModes,
+    pub supported_request_modes: SupportedRequestModes,
     pub headers: IndexMap<String, String>,
     pub properties: IndexMap<String, serde_json::Value>,
     pub query_params: IndexMap<String, String>,
@@ -349,6 +349,24 @@ impl<Meta: Clone> UnresolvedOpenAI<Meta> {
         Ok(instance)
     }
 
+    pub fn create_responses(
+        mut properties: PropertyHandler<Meta>,
+    ) -> Result<Self, Vec<Error<Meta>>> {
+        let base_url = properties
+            .ensure_base_url_with_default(UnresolvedUrl::new_static("https://api.openai.com/v1"));
+
+        let api_key = Some(
+            properties
+                .ensure_api_key()
+                .unwrap_or_else(|| StringOr::EnvVar("OPENAI_API_KEY".to_string())),
+        );
+
+        let instance =
+            Self::create_common(properties, Some(either::Either::Left(base_url)), api_key)?;
+
+        Ok(instance)
+    }
+
     fn create_common(
         mut properties: PropertyHandler<Meta>,
         base_url: Option<either::Either<UnresolvedUrl, (StringOr, StringOr)>>,

engine/baml-lib/llm-client/src/clientspec.rs

@@ -61,6 +61,8 @@ pub enum OpenAIClientProviderVariant {
     Ollama,
     /// The Azure client provider variant
     Azure,
+    /// The OpenAI Responses API variant
+    Responses,
     /// The generic client provider variant
     Generic,
 }
@@ -93,6 +95,7 @@ impl std::fmt::Display for OpenAIClientProviderVariant {
             OpenAIClientProviderVariant::Base => write!(f, "openai"),
             OpenAIClientProviderVariant::Ollama => write!(f, "ollama"),
             OpenAIClientProviderVariant::Azure => write!(f, "azure-openai"),
+            OpenAIClientProviderVariant::Responses => write!(f, "openai-responses"),
             OpenAIClientProviderVariant::Generic => write!(f, "openai-generic"),
         }
     }
@@ -117,6 +120,9 @@ impl std::str::FromStr for ClientProvider {
             "openai-generic" => Ok(ClientProvider::OpenAI(OpenAIClientProviderVariant::Generic)),
             "azure-openai" => Ok(ClientProvider::OpenAI(OpenAIClientProviderVariant::Azure)),
             "baml-azure-chat" => Ok(ClientProvider::OpenAI(OpenAIClientProviderVariant::Azure)),
+            "openai-responses" => Ok(ClientProvider::OpenAI(
+                OpenAIClientProviderVariant::Responses,
+            )),
             "baml-ollama-chat" => Ok(ClientProvider::OpenAI(OpenAIClientProviderVariant::Ollama)),
             "ollama" => Ok(ClientProvider::OpenAI(OpenAIClientProviderVariant::Ollama)),
             "anthropic" => Ok(ClientProvider::Anthropic),
@@ -141,6 +147,7 @@ impl std::str::FromStr for OpenAIClientProviderVariant {
             "openai" => Ok(OpenAIClientProviderVariant::Base),
             "ollama" => Ok(OpenAIClientProviderVariant::Ollama),
             "azure-openai" => Ok(OpenAIClientProviderVariant::Azure),
+            "openai-responses" => Ok(OpenAIClientProviderVariant::Responses),
             "openai-generic" => Ok(OpenAIClientProviderVariant::Generic),
             _ => Err(anyhow::anyhow!(
                 "Invalid OpenAI client provider variant: {}",
@@ -171,6 +178,7 @@ impl ClientProvider {
             "openai",
             "openai-generic",
             "azure-openai",
+            "openai-responses",
             "anthropic",
             "ollama",
             "round-robin",
@@ -191,7 +199,7 @@ impl std::fmt::Display for ClientSpec {
     }
 }
 
-#[derive(Clone, Debug, Hash)]
+#[derive(Clone, Debug, Hash, Default)]
 pub struct SupportedRequestModes {
     // If unset, treat as auto
     pub stream: Option<bool>,
@@ -325,7 +333,7 @@ impl UnresolvedRolesSelection {
     }
 }
 
-#[derive(Clone, Debug)]
+#[derive(Clone, Debug, Default)]
 pub struct RolesSelection {
     allowed: Option<Vec<String>>,
     default: Option<String>,
@@ -409,6 +417,7 @@ impl AllowedRoleMetadata {
 #[derive(Clone, Debug, Hash)]
 pub enum UnresolvedResponseType {
     OpenAI,
+    OpenAIResponses,
     Anthropic,
     Google,
     Vertex,
@@ -417,6 +426,7 @@ pub enum UnresolvedResponseType {
 #[derive(Clone, Debug, Hash)]
 pub enum ResponseType {
     OpenAI,
+    OpenAIResponses,
     Anthropic,
     Google,
     Vertex,
@@ -430,9 +440,116 @@ impl UnresolvedResponseType {
     pub fn resolve(&self, _: &impl GetEnvVar) -> Result<ResponseType> {
         match self {
             Self::OpenAI => Ok(ResponseType::OpenAI),
+            Self::OpenAIResponses => Ok(ResponseType::OpenAIResponses),
             Self::Anthropic => Ok(ResponseType::Anthropic),
             Self::Google => Ok(ResponseType::Google),
             Self::Vertex => Ok(ResponseType::Vertex),
         }
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use std::str::FromStr;
+
+    use super::*;
+
+    #[test]
+    fn test_client_provider_parsing() {
+        // Test parsing of openai-responses provider
+        let provider = ClientProvider::from_str("openai-responses");
+        assert!(provider.is_ok());
+
+        let provider = provider.unwrap();
+        match provider {
+            ClientProvider::OpenAI(OpenAIClientProviderVariant::Responses) => {
+                // Success!
+            }
+            _ => panic!("Expected OpenAI Responses variant, got {:?}", provider),
+        }
+    }
+
+    #[test]
+    fn test_openai_client_provider_variant_parsing() {
+        let variant = OpenAIClientProviderVariant::from_str("openai-responses");
+        assert!(variant.is_ok());
+        assert_eq!(variant.unwrap(), OpenAIClientProviderVariant::Responses);
+    }
+
+    #[test]
+    fn test_openai_responses_display() {
+        let variant = OpenAIClientProviderVariant::Responses;
+        assert_eq!(variant.to_string(), "openai-responses");
+    }
+
+    #[test]
+    fn test_openai_responses_in_allowed_providers() {
+        let allowed = ClientProvider::allowed_providers();
+        assert!(allowed.contains(&"openai-responses"));
+    }
+
+    #[test]
+    fn test_response_type_parsing() {
+        // Test UnresolvedResponseType
+        let unresolved = match "openai-responses" {
+            "openai" => UnresolvedResponseType::OpenAI,
+            "openai-responses" => UnresolvedResponseType::OpenAIResponses,
+            "anthropic" => UnresolvedResponseType::Anthropic,
+            "google" => UnresolvedResponseType::Google,
+            "vertex" => UnresolvedResponseType::Vertex,
+            _ => panic!("Unknown response type"),
+        };
+
+        assert!(matches!(
+            unresolved,
+            UnresolvedResponseType::OpenAIResponses
+        ));
+    }
+
+    #[test]
+    fn test_response_type_resolution() {
+        use baml_types::GetEnvVar;
+
+        struct MockEnvContext;
+        impl GetEnvVar for MockEnvContext {
+            fn get_env_var(&self, _name: &str) -> Result<String, anyhow::Error> {
+                Err(anyhow::anyhow!("No env var"))
+            }
+
+            fn set_allow_missing_env_var(&self, _: bool) -> Self {
+                MockEnvContext
+            }
+        }
+
+        let unresolved = UnresolvedResponseType::OpenAIResponses;
+        let ctx = MockEnvContext;
+        let resolved = unresolved.resolve(&ctx);
+
+        assert!(resolved.is_ok());
+        assert!(matches!(resolved.unwrap(), ResponseType::OpenAIResponses));
+    }
+
+    #[test]
+    fn test_provider_roundtrip() {
+        // Test that we can convert to string and back
+        let original = ClientProvider::OpenAI(OpenAIClientProviderVariant::Responses);
+        let string_repr = match &original {
+            ClientProvider::OpenAI(variant) => variant.to_string(),
+            _ => panic!("Expected OpenAI provider"),
+        };
+
+        assert_eq!(string_repr, "openai-responses");
+
+        let parsed_back = ClientProvider::from_str(&string_repr).unwrap();
+        assert_eq!(original, parsed_back);
+    }
+
+    #[test]
+    fn test_invalid_provider_parsing() {
+        let result = ClientProvider::from_str("invalid-provider");
+        assert!(result.is_err());
+
+        let result = OpenAIClientProviderVariant::from_str("invalid-variant");
+        assert!(result.is_err());
+    }
+}

engine/baml-runtime/src/internal/llm_client/primitive/mod.rs

@@ -123,6 +123,9 @@ impl TryFrom<(&ClientProperty, &RuntimeContext)> for LLMPrimitiveProvider {
                     OpenAIClientProviderVariant::Generic => {
                         OpenAIClient::dynamic_new_generic(value, ctx).map(Into::into)
                     }
+                    OpenAIClientProviderVariant::Responses => {
+                        OpenAIClient::dynamic_new_responses(value, ctx).map(Into::into)
+                    }
                 }
             }
             ClientProvider::Anthropic => AnthropicClient::dynamic_new(value, ctx).map(Into::into),
@@ -181,6 +184,9 @@ impl TryFrom<(&ClientWalker<'_>, &RuntimeContext)> for LLMPrimitiveProvider {
                     OpenAIClientProviderVariant::Generic => {
                         OpenAIClient::new_generic(client, ctx).map(Into::into)
                     }
+                    OpenAIClientProviderVariant::Responses => {
+                        OpenAIClient::new_responses(client, ctx).map(Into::into)
+                    }
                 }
             }
             ClientProvider::Anthropic => AnthropicClient::new(client, ctx).map(Into::into),