feat: core abstraction for image classification models

spring-ai-core/src/main/java/org/springframework/ai/classification/image/ImageClassification.java

@@ -0,0 +1,41 @@
+package org.springframework.ai.classification.image;
+
+/**
+ * Represents a single classification result of an image processed by a model.
+ *
+ * <p>
+ * Each classification consists usually of:
+ * </p>
+ * <ul>
+ * <li>A descriptive label indicating the category or class the image belongs to.</li>
+ * <li>A score representing the probability or confidence level for the
+ * classification.</li>
+ * </ul>
+ *
+ * @author Denis Lobo
+ */
+public class ImageClassification {
+
+	private final String label;
+
+	private final double score;
+
+	public ImageClassification(String label, double score) {
+		this.label = label;
+		this.score = score;
+	}
+
+	public String getLabel() {
+		return label;
+	}
+
+	public double getScore() {
+		return score;
+	}
+
+	@Override
+	public String toString() {
+		return "Classification{" + "label='" + label + '\'' + ", score=" + score + '}';
+	}
+
+}

spring-ai-core/src/main/java/org/springframework/ai/classification/image/ImageClassificationGeneration.java

@@ -0,0 +1,72 @@
+package org.springframework.ai.classification.image;
+
+import org.springframework.ai.model.ModelResult;
+import org.springframework.ai.model.ResultMetadata;
+
+import java.util.List;
+import java.util.Objects;
+
+/**
+ * Represents the classification result of an image processed by a model.
+ *
+ * <p>
+ * Each classification result consists usually of:
+ * </p>
+ * <ul>
+ * <li>A list of {@link ImageClassification} describing the various classifications and
+ * respective scores the model predicted</li>
+ * <li>{@link ImageClassificationMetaData} arbitrary metadata</li>
+ * </ul>
+ *
+ * @author Denis Lobo
+ */
+public class ImageClassificationGeneration implements ModelResult<List<ImageClassification>> {
+
+	private final List<ImageClassification> imageClassification;
+
+	private final ImageClassificationMetaData imageClassificationMetaData;
+
+	public ImageClassificationGeneration(List<ImageClassification> imageClassification) {
+		this(imageClassification, new ImageClassificationMetaData() {
+		});
+	}
+
+	public ImageClassificationGeneration(List<ImageClassification> imageClassification,
+			ImageClassificationMetaData imageClassificationMetaData) {
+		this.imageClassificationMetaData = imageClassificationMetaData;
+		this.imageClassification = imageClassification;
+	}
+
+	@Override
+	public List<ImageClassification> getOutput() {
+		return imageClassification;
+	}
+
+	@Override
+	public ResultMetadata getMetadata() {
+		return imageClassificationMetaData;
+	}
+
+	@Override
+	public boolean equals(Object o) {
+		if (this == o)
+			return true;
+		if (o == null || getClass() != o.getClass())
+			return false;
+		ImageClassificationGeneration that = (ImageClassificationGeneration) o;
+		return Objects.equals(imageClassification, that.imageClassification)
+				&& Objects.equals(imageClassificationMetaData, that.imageClassificationMetaData);
+	}
+
+	@Override
+	public int hashCode() {
+		return Objects.hash(imageClassification, imageClassificationMetaData);
+	}
+
+	@Override
+	public String toString() {
+		return "ImageClassificationGeneration{" + "imageClassification=" + imageClassification
+				+ ", imageClassificationMetaData=" + imageClassificationMetaData + '}';
+	}
+
+}

spring-ai-core/src/main/java/org/springframework/ai/classification/image/ImageClassificationMessage.java

@@ -0,0 +1,10 @@
+package org.springframework.ai.classification.image;
+
+/**
+ * A general image classification message.
+ *
+ * @author Denis Lobo
+ */
+public interface ImageClassificationMessage {
+
+}

spring-ai-core/src/main/java/org/springframework/ai/classification/image/ImageClassificationMetaData.java

@@ -0,0 +1,12 @@
+package org.springframework.ai.classification.image;
+
+import org.springframework.ai.model.ResultMetadata;
+
+/**
+ * Represents the metadata provided with the image classification result
+ *
+ * @author Denis Lobo
+ */
+public interface ImageClassificationMetaData extends ResultMetadata {
+
+}

spring-ai-core/src/main/java/org/springframework/ai/classification/image/ImageClassificationModel.java

@@ -0,0 +1,15 @@
+package org.springframework.ai.classification.image;
+
+import org.springframework.ai.model.Model;
+
+/**
+ * Interface to invoke image classification models
+ *
+ * @author Denis Lobo
+ */
+@FunctionalInterface
+public interface ImageClassificationModel extends Model<ImageClassificationPrompt, ImageClassificationResponse> {
+
+	ImageClassificationResponse call(ImageClassificationPrompt request);
+
+}

spring-ai-core/src/main/java/org/springframework/ai/classification/image/ImageClassificationOptions.java

@@ -0,0 +1,12 @@
+package org.springframework.ai.classification.image;
+
+import org.springframework.ai.model.ModelOptions;
+
+/**
+ * Interface for image classification options
+ *
+ * @author Denis Lobo
+ */
+public interface ImageClassificationOptions extends ModelOptions {
+
+}

spring-ai-core/src/main/java/org/springframework/ai/classification/image/ImageClassificationPrompt.java

@@ -0,0 +1,40 @@
+package org.springframework.ai.classification.image;
+
+import org.springframework.ai.model.ModelRequest;
+
+/**
+ * Represents a request for image classification models.
+ *
+ * <p>
+ * Each prompt consists of:
+ * </p>
+ * <ul>
+ * <li>{@link ImageClassificationMessage} (e.g. binary or base64 encoded image</li>
+ * <li>{@link ImageClassificationOptions} (e.g. configuration options (e.g. top_k,
+ * function_to_apply on scores</li>
+ * </ul>
+ *
+ * @author Denis Lobo
+ */
+public class ImageClassificationPrompt implements ModelRequest<ImageClassificationMessage> {
+
+	private final ImageClassificationMessage message;
+
+	private final ImageClassificationOptions options;
+
+	public ImageClassificationPrompt(ImageClassificationMessage message, ImageClassificationOptions options) {
+		this.message = message;
+		this.options = options;
+	}
+
+	@Override
+	public ImageClassificationMessage getInstructions() {
+		return message;
+	}
+
+	@Override
+	public ImageClassificationOptions getOptions() {
+		return options;
+	}
+
+}

spring-ai-core/src/main/java/org/springframework/ai/classification/image/ImageClassificationResponse.java

@@ -0,0 +1,56 @@
+package org.springframework.ai.classification.image;
+
+import org.springframework.ai.model.ModelResponse;
+import org.springframework.ai.model.ResponseMetadata;
+
+import java.util.List;
+
+/**
+ * The image classification response returned by an image classification model.
+ *
+ * <p>
+ * Each response consists of:
+ * </p>
+ * <ul>
+ * <li>{@link ImageClassificationGeneration} holding the results of an classified
+ * image</li>
+ * <li>{@link ImageClassificationResponseMetadata} holding metadata provided by the image
+ * classifying model</li>
+ * </ul>
+ *
+ * @author Denis Lobo
+ */
+public class ImageClassificationResponse implements ModelResponse<ImageClassificationGeneration> {
+
+	private final ImageClassificationGeneration imageClassification;
+
+	private final ImageClassificationResponseMetadata metadata;
+
+	public ImageClassificationResponse(ImageClassificationGeneration imageClassification,
+			ImageClassificationResponseMetadata metadata) {
+		this.imageClassification = imageClassification;
+		this.metadata = metadata;
+	}
+
+	@Override
+	public ImageClassificationGeneration getResult() {
+		return imageClassification;
+	}
+
+	@Override
+	public List<ImageClassificationGeneration> getResults() {
+		return List.of(imageClassification);
+	}
+
+	@Override
+	public ResponseMetadata getMetadata() {
+		return metadata;
+	}
+
+	@Override
+	public String toString() {
+		return "ImageClassificationResponse{" + "imageClassification=" + imageClassification + ", metadata=" + metadata
+				+ '}';
+	}
+
+}

spring-ai-core/src/main/java/org/springframework/ai/classification/image/ImageClassificationResponseMetadata.java

@@ -0,0 +1,47 @@
+/*
+ * Copyright 2023-2024 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.classification.image;
+
+import org.springframework.ai.model.MutableResponseMetadata;
+
+/**
+ * Metadata associated with an image classification response.
+ *
+ * @author Denis Lobo
+ */
+public class ImageClassificationResponseMetadata extends MutableResponseMetadata {
+
+	private final Long created;
+
+	public ImageClassificationResponseMetadata() {
+		this(System.currentTimeMillis());
+	}
+
+	public ImageClassificationResponseMetadata(Long created) {
+		this.created = created;
+	}
+
+	public Long getCreated() {
+		return this.created;
+	}
+
+	@Override
+	public String toString() {
+		return "ImageClassificationResponseMetadata{" + "created=" + created + '}';
+	}
+
+}