1 /*
2  * Copyright 2024 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 package android.app.appsearch;
18 
19 import android.annotation.FlaggedApi;
20 import android.annotation.NonNull;
21 import android.annotation.Nullable;
22 import android.app.appsearch.safeparcel.AbstractSafeParcelable;
23 import android.app.appsearch.safeparcel.SafeParcelable;
24 import android.os.Parcel;
25 import android.os.Parcelable;
26 
27 import com.android.appsearch.flags.Flags;
28 
29 import java.util.Arrays;
30 import java.util.Objects;
31 
32 /**
33  * Embeddings are vector representations of data, such as text, images, and audio, which can be
34  * generated by machine learning models and used for semantic search. This class represents an
35  * embedding vector, which wraps a float array for the values of the embedding vector and a model
36  * signature that can be any string to distinguish between embedding vectors generated by different
37  * models.
38  *
39  * <p>For more details on how embedding search works, check {@link AppSearchSession#search} and
40  * {@link SearchSpec.Builder#setRankingStrategy(String)}.
41  *
42  * @see SearchSpec.Builder#addSearchEmbeddings
43  * @see GenericDocument.Builder#setPropertyEmbedding
44  */
45 @FlaggedApi(Flags.FLAG_ENABLE_SCHEMA_EMBEDDING_PROPERTY_CONFIG)
46 @SafeParcelable.Class(creator = "EmbeddingVectorCreator")
47 @SuppressWarnings("HiddenSuperclass")
48 public final class EmbeddingVector extends AbstractSafeParcelable {
49 
50     @NonNull
51     public static final Parcelable.Creator<EmbeddingVector> CREATOR = new EmbeddingVectorCreator();
52 
53     @NonNull
54     @Field(id = 1, getter = "getValues")
55     private final float[] mValues;
56 
57     @NonNull
58     @Field(id = 2, getter = "getModelSignature")
59     private final String mModelSignature;
60 
61     @Nullable private Integer mHashCode;
62 
63     /**
64      * Creates a new {@link EmbeddingVector}.
65      *
66      * @throws IllegalArgumentException if {@code values} is empty.
67      */
68     @Constructor
EmbeddingVector( @aramid = 1) @onNull float[] values, @Param(id = 2) @NonNull String modelSignature)69     public EmbeddingVector(
70             @Param(id = 1) @NonNull float[] values, @Param(id = 2) @NonNull String modelSignature) {
71         mValues = Objects.requireNonNull(values);
72         if (mValues.length == 0) {
73             throw new IllegalArgumentException("Embedding values cannot be empty.");
74         }
75         mModelSignature = Objects.requireNonNull(modelSignature);
76     }
77 
78     /** Returns the values of this embedding vector. */
79     @NonNull
getValues()80     public float[] getValues() {
81         return mValues;
82     }
83 
84     /**
85      * Returns the model signature of this embedding vector, which is an arbitrary string to
86      * distinguish between embedding vectors generated by different models.
87      */
88     @NonNull
getModelSignature()89     public String getModelSignature() {
90         return mModelSignature;
91     }
92 
93     @Override
equals(Object o)94     public boolean equals(Object o) {
95         if (this == o) return true;
96         if (o == null) return false;
97         if (!(o instanceof EmbeddingVector)) return false;
98         EmbeddingVector that = (EmbeddingVector) o;
99         return Arrays.equals(mValues, that.mValues) && mModelSignature.equals(that.mModelSignature);
100     }
101 
102     @Override
hashCode()103     public int hashCode() {
104         if (mHashCode == null) {
105             mHashCode = Objects.hash(Arrays.hashCode(mValues), mModelSignature);
106         }
107         return mHashCode;
108     }
109 
110     @Override
writeToParcel(@onNull Parcel dest, int flags)111     public void writeToParcel(@NonNull Parcel dest, int flags) {
112         EmbeddingVectorCreator.writeToParcel(this, dest, flags);
113     }
114 }
115