Gh-4182, GH-849: Add HuggingFace EmbeddingModel and ConnectionDetails Auto-Configuration

auto-configurations/models/spring-ai-autoconfigure-model-huggingface/pom.xml

@@ -35,19 +35,37 @@
 
 		<!-- Spring AI auto configurations -->
 
+		<dependency>
+			<groupId>org.springframework.ai</groupId>
+			<artifactId>spring-ai-autoconfigure-model-tool</artifactId>
+			<version>${project.parent.version}</version>
+		</dependency>
+
 		<dependency>
 			<groupId>org.springframework.ai</groupId>
 			<artifactId>spring-ai-autoconfigure-model-chat-observation</artifactId>
 			<version>${project.parent.version}</version>
 		</dependency>
 
+		<dependency>
+			<groupId>org.springframework.ai</groupId>
+			<artifactId>spring-ai-autoconfigure-retry</artifactId>
+			<version>${project.parent.version}</version>
+		</dependency>
+
 		<!-- Boot dependencies -->
 		<dependency>
 			<groupId>org.springframework.boot</groupId>
 			<artifactId>spring-boot-starter</artifactId>
 			<optional>true</optional>
 		</dependency>
 
+		<dependency>
+			<groupId>org.springframework.boot</groupId>
+			<artifactId>spring-boot-starter-restclient</artifactId>
+			<optional>true</optional>
+		</dependency>
+
 		<dependency>
 			<groupId>org.springframework.boot</groupId>
 			<artifactId>spring-boot-configuration-processor</artifactId>

auto-configurations/models/spring-ai-autoconfigure-model-huggingface/src/main/java/org/springframework/ai/model/huggingface/autoconfigure/HuggingfaceApiAutoConfiguration.java

@@ -0,0 +1,61 @@
+/*
+ * Copyright 2023-2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.ai.model.huggingface.autoconfigure;
+
+import org.springframework.ai.huggingface.api.HuggingfaceApi;
+import org.springframework.boot.autoconfigure.AutoConfiguration;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnClass;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
+import org.springframework.boot.context.properties.EnableConfigurationProperties;
+import org.springframework.boot.restclient.autoconfigure.RestClientAutoConfiguration;
+import org.springframework.context.annotation.Bean;
+
+/**
+ * {@link AutoConfiguration Auto-configuration} for HuggingFace API.
+ *
+ * @author Myeongdeok Kang
+ */
+@AutoConfiguration(after = RestClientAutoConfiguration.class)
+@ConditionalOnClass(HuggingfaceApi.class)
+@EnableConfigurationProperties(HuggingfaceConnectionProperties.class)
+public class HuggingfaceApiAutoConfiguration {
+
+	@Bean
+	@ConditionalOnMissingBean(HuggingfaceConnectionDetails.class)
+	PropertiesHuggingfaceConnectionDetails huggingfaceConnectionDetails(HuggingfaceConnectionProperties properties) {
+		return new PropertiesHuggingfaceConnectionDetails(properties);
+	}
+
+	// This bean is no longer created here since Chat and Embedding
+	// need different base URLs. Each AutoConfiguration creates its own API instance.
+
+	static class PropertiesHuggingfaceConnectionDetails implements HuggingfaceConnectionDetails {
+
+		private final HuggingfaceConnectionProperties properties;
+
+		PropertiesHuggingfaceConnectionDetails(HuggingfaceConnectionProperties properties) {
+			this.properties = properties;
+		}
+
+		@Override
+		public String getApiKey() {
+			return this.properties.getApiKey();
+		}
+
+	}
+
+}

auto-configurations/models/spring-ai-autoconfigure-model-huggingface/src/main/java/org/springframework/ai/model/huggingface/autoconfigure/HuggingfaceChatAutoConfiguration.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2023-2024 the original author or authors.
+ * Copyright 2023-2025 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -16,27 +16,101 @@
 
 package org.springframework.ai.model.huggingface.autoconfigure;
 
+import io.micrometer.observation.ObservationRegistry;
+
+import org.springframework.ai.chat.observation.ChatModelObservationConvention;
 import org.springframework.ai.huggingface.HuggingfaceChatModel;
+import org.springframework.ai.huggingface.api.HuggingfaceApi;
 import org.springframework.ai.model.SpringAIModelProperties;
 import org.springframework.ai.model.SpringAIModels;
+import org.springframework.ai.model.tool.DefaultToolExecutionEligibilityPredicate;
+import org.springframework.ai.model.tool.ToolCallingManager;
+import org.springframework.ai.model.tool.ToolExecutionEligibilityPredicate;
+import org.springframework.ai.model.tool.autoconfigure.ToolCallingAutoConfiguration;
+import org.springframework.ai.retry.autoconfigure.SpringAiRetryAutoConfiguration;
+import org.springframework.beans.factory.ObjectProvider;
+import org.springframework.beans.factory.annotation.Qualifier;
 import org.springframework.boot.autoconfigure.AutoConfiguration;
 import org.springframework.boot.autoconfigure.condition.ConditionalOnClass;
 import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
 import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
 import org.springframework.boot.context.properties.EnableConfigurationProperties;
+import org.springframework.boot.restclient.autoconfigure.RestClientAutoConfiguration;
 import org.springframework.context.annotation.Bean;
+import org.springframework.core.retry.RetryTemplate;
+import org.springframework.util.StringUtils;
+import org.springframework.web.client.ResponseErrorHandler;
+import org.springframework.web.client.RestClient;
 
-@AutoConfiguration
+/**
+ * {@link AutoConfiguration Auto-configuration} for HuggingFace Chat Model.
+ *
+ * @author Mark Pollack
+ * @author Josh Long
+ * @author Soby Chacko
+ * @author Ilayaperumal Gopinathan
+ * @author Myeongdeok Kang
+ */
+@AutoConfiguration(after = { RestClientAutoConfiguration.class, HuggingfaceApiAutoConfiguration.class,
+		SpringAiRetryAutoConfiguration.class, ToolCallingAutoConfiguration.class })
 @ConditionalOnClass(HuggingfaceChatModel.class)
-@EnableConfigurationProperties(HuggingfaceChatProperties.class)
 @ConditionalOnProperty(name = SpringAIModelProperties.CHAT_MODEL, havingValue = SpringAIModels.HUGGINGFACE,
 		matchIfMissing = true)
+@EnableConfigurationProperties({ HuggingfaceConnectionProperties.class, HuggingfaceChatProperties.class })
 public class HuggingfaceChatAutoConfiguration {
 
+	@Bean
+	@ConditionalOnMissingBean(name = "huggingfaceChatApi")
+	@ConditionalOnProperty(prefix = HuggingfaceChatProperties.CONFIG_PREFIX, name = "enabled", havingValue = "true",
+			matchIfMissing = true)
+	public HuggingfaceApi huggingfaceChatApi(HuggingfaceConnectionDetails connectionDetails,
+			HuggingfaceChatProperties chatProperties, ObjectProvider<RestClient.Builder> restClientBuilderProvider,
+			ObjectProvider<ResponseErrorHandler> responseErrorHandlerProvider) {
+
+		String apiKey = connectionDetails.getApiKey();
+		if (!StringUtils.hasText(apiKey)) {
+			throw new IllegalArgumentException(
+					"HuggingFace API key must be set. Please configure spring.ai.huggingface.api-key");
+		}
+
+		RestClient.Builder restClientBuilder = restClientBuilderProvider.getIfAvailable(RestClient::builder);
+		ResponseErrorHandler responseErrorHandler = responseErrorHandlerProvider.getIfAvailable(() -> null);
+
+		HuggingfaceApi.Builder apiBuilder = HuggingfaceApi.builder()
+			.baseUrl(chatProperties.getUrl())
+			.apiKey(apiKey)
+			.restClientBuilder(restClientBuilder);
+
+		if (responseErrorHandler != null) {
+			apiBuilder.responseErrorHandler(responseErrorHandler);
+		}
+
+		return apiBuilder.build();
+	}
+
 	@Bean
 	@ConditionalOnMissingBean
-	public HuggingfaceChatModel huggingfaceChatModel(HuggingfaceChatProperties huggingfaceChatProperties) {
-		return new HuggingfaceChatModel(huggingfaceChatProperties.getApiKey(), huggingfaceChatProperties.getUrl());
+	@ConditionalOnProperty(prefix = HuggingfaceChatProperties.CONFIG_PREFIX, name = "enabled", havingValue = "true",
+			matchIfMissing = true)
+	public HuggingfaceChatModel huggingfaceChatModel(@Qualifier("huggingfaceChatApi") HuggingfaceApi huggingfaceApi,
+			HuggingfaceChatProperties chatProperties, ToolCallingManager toolCallingManager,
+			ObjectProvider<ObservationRegistry> observationRegistry,
+			ObjectProvider<ChatModelObservationConvention> observationConvention, RetryTemplate retryTemplate,
+			ObjectProvider<ToolExecutionEligibilityPredicate> huggingfaceToolExecutionEligibilityPredicate) {
+
+		var chatModel = HuggingfaceChatModel.builder()
+			.huggingfaceApi(huggingfaceApi)
+			.defaultOptions(chatProperties.getOptions())
+			.toolCallingManager(toolCallingManager)
+			.toolExecutionEligibilityPredicate(huggingfaceToolExecutionEligibilityPredicate
+				.getIfUnique(DefaultToolExecutionEligibilityPredicate::new))
+			.observationRegistry(observationRegistry.getIfUnique(() -> ObservationRegistry.NOOP))
+			.retryTemplate(retryTemplate)
+			.build();
+
+		observationConvention.ifAvailable(chatModel::setObservationConvention);
+
+		return chatModel;
 	}
 
 }

auto-configurations/models/spring-ai-autoconfigure-model-huggingface/src/main/java/org/springframework/ai/model/huggingface/autoconfigure/HuggingfaceChatProperties.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2023-2024 the original author or authors.
+ * Copyright 2023-2025 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -16,7 +16,11 @@
 
 package org.springframework.ai.model.huggingface.autoconfigure;
 
+import org.springframework.ai.huggingface.HuggingfaceChatOptions;
+import org.springframework.ai.huggingface.api.HuggingfaceApi;
+import org.springframework.ai.huggingface.api.common.HuggingfaceApiConstants;
 import org.springframework.boot.context.properties.ConfigurationProperties;
+import org.springframework.boot.context.properties.NestedConfigurationProperty;
 
 /**
  * Configuration properties for Hugging Face chat model.
@@ -25,28 +29,39 @@
  * @author Josh Long
  * @author Mark Pollack
  * @author Thomas Vitale
+ * @author Myeongdeok Kang
  */
 @ConfigurationProperties(HuggingfaceChatProperties.CONFIG_PREFIX)
 public class HuggingfaceChatProperties {
 
 	public static final String CONFIG_PREFIX = "spring.ai.huggingface.chat";
 
 	/**
-	 * API Key to authenticate with the Inference Endpoint.
+	 * Enable HuggingFace chat model autoconfiguration.
 	 */
-	private String apiKey;
+	private boolean enabled = true;
 
 	/**
-	 * URL of the Inference Endpoint.
+	 * Base URL for the HuggingFace Chat API (OpenAI-compatible endpoint).
 	 */
-	private String url;
+	private String url = HuggingfaceApiConstants.DEFAULT_CHAT_BASE_URL;
 
-	public String getApiKey() {
-		return this.apiKey;
+	/**
+	 * Client-level HuggingFace chat options. Use this property to configure the model,
+	 * temperature, max_tokens, and other parameters. Null values are ignored, defaulting
+	 * to the API defaults.
+	 */
+	@NestedConfigurationProperty
+	private final HuggingfaceChatOptions options = HuggingfaceChatOptions.builder()
+		.model(HuggingfaceApi.DEFAULT_CHAT_MODEL)
+		.build();
+
+	public boolean isEnabled() {
+		return this.enabled;
 	}
 
-	public void setApiKey(String apiKey) {
-		this.apiKey = apiKey;
+	public void setEnabled(boolean enabled) {
+		this.enabled = enabled;
 	}
 
 	public String getUrl() {
@@ -57,4 +72,16 @@ public void setUrl(String url) {
 		this.url = url;
 	}
 
+	public String getModel() {
+		return this.options.getModel();
+	}
+
+	public void setModel(String model) {
+		this.options.setModel(model);
+	}
+
+	public HuggingfaceChatOptions getOptions() {
+		return this.options;
+	}
+
 }

auto-configurations/models/spring-ai-autoconfigure-model-huggingface/src/main/java/org/springframework/ai/model/huggingface/autoconfigure/HuggingfaceConnectionDetails.java

@@ -0,0 +1,32 @@
+/*
+ * Copyright 2023-2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.ai.model.huggingface.autoconfigure;
+
+/**
+ * Details required to establish a connection to HuggingFace Inference API.
+ *
+ * @author Myeongdeok Kang
+ */
+public interface HuggingfaceConnectionDetails {
+
+	/**
+	 * The API key for authenticating with HuggingFace.
+	 * @return the API key
+	 */
+	String getApiKey();
+
+}

auto-configurations/models/spring-ai-autoconfigure-model-huggingface/src/main/java/org/springframework/ai/model/huggingface/autoconfigure/HuggingfaceConnectionProperties.java

@@ -0,0 +1,45 @@
+/*
+ * Copyright 2023-2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.ai.model.huggingface.autoconfigure;
+
+import org.springframework.boot.context.properties.ConfigurationProperties;
+
+/**
+ * HuggingFace connection configuration properties. These properties are shared across all
+ * HuggingFace model types (chat, embedding, etc.).
+ *
+ * @author Myeongdeok Kang
+ */
+@ConfigurationProperties(HuggingfaceConnectionProperties.CONFIG_PREFIX)
+public class HuggingfaceConnectionProperties {
+
+	public static final String CONFIG_PREFIX = "spring.ai.huggingface";
+
+	/**
+	 * API Key to authenticate with HuggingFace Inference API.
+	 */
+	private String apiKey;
+
+	public String getApiKey() {
+		return this.apiKey;
+	}
+
+	public void setApiKey(String apiKey) {
+		this.apiKey = apiKey;
+	}
+
+}