parsedFilter = JsonUtils.fromJson(filterStr, Map.class);
+ info.setFilter(parsedFilter);
+ }
+
+ info.setNorm((Double) vectorObj[3]);
+ info.setVector((double[]) vectorObj[4]);
+
+ return info;
+ } catch (IOException | InterruptedException e) {
+ if (e instanceof InterruptedException) {
+ Thread.currentThread().interrupt();
+ }
+ throw new EndeeException("Failed to get vector", e);
+ }
+ }
+
+ /**
+ * Returns a description of this index.
+ *
+ * @return the index description
+ */
+ public IndexDescription describe() {
+ return new IndexDescription(
+ name,
+ spaceType,
+ dimension,
+ sparseDimension,
+ isHybrid(),
+ count,
+ precision,
+ m);
+ }
+
+ // ==================== HTTP Request Helper Methods ====================
+
+ /**
+ * Builds a POST request with JSON body.
+ */
+ private HttpRequest buildPostJsonRequest(String path, String jsonBody) {
+ HttpRequest.Builder builder = HttpRequest.newBuilder()
+ .uri(URI.create(url + path))
+ .header("Content-Type", "application/json")
+ .timeout(DEFAULT_TIMEOUT)
+ .POST(HttpRequest.BodyPublishers.ofString(jsonBody));
+
+ if (token != null && !token.isBlank()) {
+ builder.header("Authorization", token);
+ }
+
+ return builder.build();
+ }
+
+ /**
+ * Builds a POST request with MessagePack body.
+ */
+ private HttpRequest buildPostMsgpackRequest(String path, byte[] body) {
+ HttpRequest.Builder builder = HttpRequest.newBuilder()
+ .uri(URI.create(url + path))
+ .header("Content-Type", "application/msgpack")
+ .timeout(DEFAULT_TIMEOUT)
+ .POST(HttpRequest.BodyPublishers.ofByteArray(body));
+
+ if (token != null && !token.isBlank()) {
+ builder.header("Authorization", token);
+ }
+
+ return builder.build();
+ }
+
+ /**
+ * Builds a DELETE request.
+ */
+ private HttpRequest buildDeleteRequest(String path) {
+ HttpRequest.Builder builder = HttpRequest.newBuilder()
+ .uri(URI.create(url + path))
+ .timeout(DEFAULT_TIMEOUT)
+ .DELETE();
+
+ if (token != null && !token.isBlank()) {
+ builder.header("Authorization", token);
+ }
+
+ return builder.build();
+ }
+
+ /**
+ * Builds a DELETE request with JSON body.
+ */
+ private HttpRequest buildDeleteJsonRequest(String path, String jsonBody) {
+ HttpRequest.Builder builder = HttpRequest.newBuilder()
+ .uri(URI.create(url + path))
+ .header("Content-Type", "application/json")
+ .timeout(DEFAULT_TIMEOUT)
+ .method("DELETE", HttpRequest.BodyPublishers.ofString(jsonBody));
+
+ if (token != null && !token.isBlank()) {
+ builder.header("Authorization", token);
+ }
+
+ return builder.build();
+ }
+}
diff --git a/src/main/java/io/endee/client/exception/EndeeApiException.java b/src/main/java/io/endee/client/exception/EndeeApiException.java
new file mode 100644
index 0000000..1a6ab68
--- /dev/null
+++ b/src/main/java/io/endee/client/exception/EndeeApiException.java
@@ -0,0 +1,40 @@
+package io.endee.client.exception;
+
+/**
+ * Exception thrown when the Endee API returns an error response.
+ */
+public class EndeeApiException extends EndeeException {
+
+ private final int statusCode;
+ private final String errorBody;
+
+ public EndeeApiException(String message, int statusCode, String errorBody) {
+ super(message);
+ this.statusCode = statusCode;
+ this.errorBody = errorBody;
+ }
+
+ public int getStatusCode() {
+ return statusCode;
+ }
+
+ public String getErrorBody() {
+ return errorBody;
+ }
+
+ /**
+ * Raises the appropriate exception based on status code.
+ */
+ public static void raiseException(int statusCode, String errorBody) {
+ String message = switch (statusCode) {
+ case 400 -> "Bad Request: " + errorBody;
+ case 401 -> "Unauthorized: " + errorBody;
+ case 403 -> "Forbidden: " + errorBody;
+ case 404 -> "Not Found: " + errorBody;
+ case 409 -> "Conflict: " + errorBody;
+ case 500 -> "Internal Server Error: " + errorBody;
+ default -> "API Error (" + statusCode + "): " + errorBody;
+ };
+ throw new EndeeApiException(message, statusCode, errorBody);
+ }
+}
diff --git a/src/main/java/io/endee/client/exception/EndeeException.java b/src/main/java/io/endee/client/exception/EndeeException.java
new file mode 100644
index 0000000..ea56c96
--- /dev/null
+++ b/src/main/java/io/endee/client/exception/EndeeException.java
@@ -0,0 +1,19 @@
+package io.endee.client.exception;
+
+/**
+ * Base exception for all Endee client errors.
+ */
+public class EndeeException extends RuntimeException {
+
+ public EndeeException(String message) {
+ super(message);
+ }
+
+ public EndeeException(String message, Throwable cause) {
+ super(message, cause);
+ }
+
+ public EndeeException(Throwable cause) {
+ super(cause);
+ }
+}
diff --git a/src/main/java/io/endee/client/types/CreateIndexOptions.java b/src/main/java/io/endee/client/types/CreateIndexOptions.java
new file mode 100644
index 0000000..30ac60c
--- /dev/null
+++ b/src/main/java/io/endee/client/types/CreateIndexOptions.java
@@ -0,0 +1,75 @@
+package io.endee.client.types;
+
+/**
+ * Options for creating an Endee index.
+ */
+public class CreateIndexOptions {
+ private final String name;
+ private final int dimension;
+ private SpaceType spaceType = SpaceType.COSINE;
+ private int m = 16;
+ private int efCon = 128;
+ private Precision precision = Precision.INT8D;
+ private Integer version = null;
+ private Integer sparseDimension = null;
+
+ private CreateIndexOptions(String name, int dimension) {
+ this.name = name;
+ this.dimension = dimension;
+ }
+
+ public static Builder builder(String name, int dimension) {
+ return new Builder(name, dimension);
+ }
+
+ public String getName() { return name; }
+ public int getDimension() { return dimension; }
+ public SpaceType getSpaceType() { return spaceType; }
+ public int getM() { return m; }
+ public int getEfCon() { return efCon; }
+ public Precision getPrecision() { return precision; }
+ public Integer getVersion() { return version; }
+ public Integer getSparseDimension() { return sparseDimension; }
+
+ public static class Builder {
+ private final CreateIndexOptions options;
+
+ private Builder(String name, int dimension) {
+ this.options = new CreateIndexOptions(name, dimension);
+ }
+
+ public Builder spaceType(SpaceType spaceType) {
+ options.spaceType = spaceType;
+ return this;
+ }
+
+ public Builder m(int m) {
+ options.m = m;
+ return this;
+ }
+
+ public Builder efCon(int efCon) {
+ options.efCon = efCon;
+ return this;
+ }
+
+ public Builder precision(Precision precision) {
+ options.precision = precision;
+ return this;
+ }
+
+ public Builder version(Integer version) {
+ options.version = version;
+ return this;
+ }
+
+ public Builder sparseDimension(Integer sparseDimension) {
+ options.sparseDimension = sparseDimension;
+ return this;
+ }
+
+ public CreateIndexOptions build() {
+ return options;
+ }
+ }
+}
diff --git a/src/main/java/io/endee/client/types/IndexDescription.java b/src/main/java/io/endee/client/types/IndexDescription.java
new file mode 100644
index 0000000..045b96d
--- /dev/null
+++ b/src/main/java/io/endee/client/types/IndexDescription.java
@@ -0,0 +1,43 @@
+package io.endee.client.types;
+
+/**
+ * Description of an Endee index.
+ */
+public class IndexDescription {
+ private final String name;
+ private final SpaceType spaceType;
+ private final int dimension;
+ private final int sparseDimension;
+ private final boolean isHybrid;
+ private final long count;
+ private final Precision precision;
+ private final int m;
+
+ public IndexDescription(String name, SpaceType spaceType, int dimension,
+ int sparseDimension, boolean isHybrid, long count,
+ Precision precision, int m) {
+ this.name = name;
+ this.spaceType = spaceType;
+ this.dimension = dimension;
+ this.sparseDimension = sparseDimension;
+ this.isHybrid = isHybrid;
+ this.count = count;
+ this.precision = precision;
+ this.m = m;
+ }
+
+ public String getName() { return name; }
+ public SpaceType getSpaceType() { return spaceType; }
+ public int getDimension() { return dimension; }
+ public int getSparseDimension() { return sparseDimension; }
+ public boolean isHybrid() { return isHybrid; }
+ public long getCount() { return count; }
+ public Precision getPrecision() { return precision; }
+ public int getM() { return m; }
+
+ @Override
+ public String toString() {
+ return "{name='" + name + "', spaceType= " + spaceType +
+ ", dimension=" + dimension + ", precision=" + precision + ", count=" + count + ", isHybrid=" + isHybrid +", sparseDimension=" + sparseDimension + ", M=" + m +"}";
+ }
+}
diff --git a/src/main/java/io/endee/client/types/IndexInfo.java b/src/main/java/io/endee/client/types/IndexInfo.java
new file mode 100644
index 0000000..f732c44
--- /dev/null
+++ b/src/main/java/io/endee/client/types/IndexInfo.java
@@ -0,0 +1,45 @@
+package io.endee.client.types;
+
+/**
+ * Information about an Endee index from the server.
+ */
+public class IndexInfo {
+ private String name;
+ private SpaceType spaceType;
+ private int dimension;
+ private long totalElements;
+ private Precision precision;
+ private int m;
+ private long checksum;
+ private Integer version;
+ private Integer sparseDimension;
+
+ public IndexInfo() {}
+
+ public String getName() { return name; }
+ public void setName(String name) { this.name = name; }
+
+ public SpaceType getSpaceType() { return spaceType; }
+ public void setSpaceType(SpaceType spaceType) { this.spaceType = spaceType; }
+
+ public int getDimension() { return dimension; }
+ public void setDimension(int dimension) { this.dimension = dimension; }
+
+ public long getTotalElements() { return totalElements; }
+ public void setTotalElements(long totalElements) { this.totalElements = totalElements; }
+
+ public Precision getPrecision() { return precision; }
+ public void setPrecision(Precision precision) { this.precision = precision; }
+
+ public int getM() { return m; }
+ public void setM(int m) { this.m = m; }
+
+ public long getChecksum() { return checksum; }
+ public void setChecksum(long checksum) { this.checksum = checksum; }
+
+ public Integer getVersion() { return version; }
+ public void setVersion(Integer version) { this.version = version; }
+
+ public Integer getSparseDimension() { return sparseDimension; }
+ public void setSparseDimension(Integer sparseDimension) { this.sparseDimension = sparseDimension; }
+}
diff --git a/src/main/java/io/endee/client/types/Precision.java b/src/main/java/io/endee/client/types/Precision.java
new file mode 100644
index 0000000..1f0569f
--- /dev/null
+++ b/src/main/java/io/endee/client/types/Precision.java
@@ -0,0 +1,36 @@
+package io.endee.client.types;
+
+/**
+ * Precision types for vector quantization.
+ */
+public enum Precision {
+ BINARY("binary"),
+ INT8D("int8d"),
+ INT16D("int16d"),
+ FLOAT32("float32"),
+ FLOAT16("float16");
+
+ private final String value;
+
+ Precision(String value) {
+ this.value = value;
+ }
+
+ public String getValue() {
+ return value;
+ }
+
+ public static Precision fromValue(String value) {
+ for (Precision p : values()) {
+ if (p.value.equalsIgnoreCase(value)) {
+ return p;
+ }
+ }
+ throw new IllegalArgumentException("Unknown precision: " + value);
+ }
+
+ @Override
+ public String toString() {
+ return value;
+ }
+}
diff --git a/src/main/java/io/endee/client/types/QueryOptions.java b/src/main/java/io/endee/client/types/QueryOptions.java
new file mode 100644
index 0000000..002d70d
--- /dev/null
+++ b/src/main/java/io/endee/client/types/QueryOptions.java
@@ -0,0 +1,93 @@
+package io.endee.client.types;
+
+import java.util.List;
+import java.util.Map;
+
+/**
+ * Options for querying an Endee index.
+ *
+ * Example usage with filters:
+ * {@code
+ * QueryOptions options = QueryOptions.builder()
+ * .vector(new double[]{0.1, 0.2, 0.3})
+ * .topK(10)
+ * .filter(List.of(
+ * Map.of("category", Map.of("$eq", "tech")),
+ * Map.of("score", Map.of("$range", List.of(80, 100)))
+ * ))
+ * .build();
+ * }
+ */
+public class QueryOptions {
+ private double[] vector;
+ private int topK;
+ private List> filter;
+ private int ef = 128;
+ private boolean includeVectors = false;
+ private int[] sparseIndices;
+ private double[] sparseValues;
+
+ private QueryOptions() {}
+
+ public static Builder builder() {
+ return new Builder();
+ }
+
+ public double[] getVector() { return vector; }
+ public int getTopK() { return topK; }
+ public List> getFilter() { return filter; }
+ public int getEf() { return ef; }
+ public boolean isIncludeVectors() { return includeVectors; }
+ public int[] getSparseIndices() { return sparseIndices; }
+ public double[] getSparseValues() { return sparseValues; }
+
+ public static class Builder {
+ private final QueryOptions options = new QueryOptions();
+
+ public Builder vector(double[] vector) {
+ options.vector = vector;
+ return this;
+ }
+
+ public Builder topK(int topK) {
+ options.topK = topK;
+ return this;
+ }
+
+ /**
+ * Sets the filter conditions as an array of filter objects.
+ *
+ * @param filter list of filter conditions, e.g.:
+ * [{"category": {"$eq": "tech"}}, {"score": {"$range": [80, 100]}}]
+ * @return this builder
+ */
+ public Builder filter(List> filter) {
+ options.filter = filter;
+ return this;
+ }
+
+ public Builder ef(int ef) {
+ options.ef = ef;
+ return this;
+ }
+
+ public Builder includeVectors(boolean includeVectors) {
+ options.includeVectors = includeVectors;
+ return this;
+ }
+
+ public Builder sparseIndices(int[] sparseIndices) {
+ options.sparseIndices = sparseIndices;
+ return this;
+ }
+
+ public Builder sparseValues(double[] sparseValues) {
+ options.sparseValues = sparseValues;
+ return this;
+ }
+
+ public QueryOptions build() {
+ return options;
+ }
+ }
+}
diff --git a/src/main/java/io/endee/client/types/QueryResult.java b/src/main/java/io/endee/client/types/QueryResult.java
new file mode 100644
index 0000000..9b27d68
--- /dev/null
+++ b/src/main/java/io/endee/client/types/QueryResult.java
@@ -0,0 +1,49 @@
+package io.endee.client.types;
+
+import java.util.Arrays;
+import java.util.Map;
+
+/**
+ * Result from a query operation.
+ */
+public class QueryResult {
+ private String id;
+ private double similarity;
+ private double distance;
+ private Map meta;
+ private double norm;
+ private Map filter;
+ private double[] vector;
+
+ public QueryResult() {}
+
+ public String getId() { return id; }
+ public void setId(String id) { this.id = id; }
+
+ public double getSimilarity() { return similarity; }
+ public void setSimilarity(double similarity) { this.similarity = similarity; }
+
+ public double getDistance() { return distance; }
+ public void setDistance(double distance) { this.distance = distance; }
+
+ public Map getMeta() { return meta; }
+ public void setMeta(Map meta) { this.meta = meta; }
+
+ public double getNorm() { return norm; }
+ public void setNorm(double norm) { this.norm = norm; }
+
+ public Map getFilter() { return filter; }
+ public void setFilter(Map filter) { this.filter = filter; }
+
+ public double[] getVector() { return vector; }
+ public void setVector(double[] vector) { this.vector = vector; }
+
+ @Override
+ public String toString() {
+ String result = "QueryResult{id='" + id + "', similarity=" + similarity + ", distance=" + distance;
+ if (vector != null) {
+ result += ", vector=" + Arrays.toString(vector);
+ }
+ return result + "}";
+ }
+}
diff --git a/src/main/java/io/endee/client/types/SpaceType.java b/src/main/java/io/endee/client/types/SpaceType.java
new file mode 100644
index 0000000..fb96607
--- /dev/null
+++ b/src/main/java/io/endee/client/types/SpaceType.java
@@ -0,0 +1,34 @@
+package io.endee.client.types;
+
+/**
+ * Space types for distance calculation.
+ */
+public enum SpaceType {
+ COSINE("cosine"),
+ L2("l2"),
+ IP("ip");
+
+ private final String value;
+
+ SpaceType(String value) {
+ this.value = value;
+ }
+
+ public String getValue() {
+ return value;
+ }
+
+ public static SpaceType fromValue(String value) {
+ for (SpaceType t : values()) {
+ if (t.value.equalsIgnoreCase(value)) {
+ return t;
+ }
+ }
+ throw new IllegalArgumentException("Unknown space type: " + value);
+ }
+
+ @Override
+ public String toString() {
+ return value;
+ }
+}
diff --git a/src/main/java/io/endee/client/types/VectorInfo.java b/src/main/java/io/endee/client/types/VectorInfo.java
new file mode 100644
index 0000000..77b832b
--- /dev/null
+++ b/src/main/java/io/endee/client/types/VectorInfo.java
@@ -0,0 +1,36 @@
+package io.endee.client.types;
+
+import java.util.Map;
+
+/**
+ * Information about a vector retrieved from an index.
+ */
+public class VectorInfo {
+ private String id;
+ private Map meta;
+ private Map filter;
+ private double norm;
+ private double[] vector;
+
+ public VectorInfo() {}
+
+ public String getId() { return id; }
+ public void setId(String id) { this.id = id; }
+
+ public Map getMeta() { return meta; }
+ public void setMeta(Map meta) { this.meta = meta; }
+
+ public Map getFilter() { return filter; }
+ public void setFilter(Map filter) { this.filter = filter; }
+
+ public double getNorm() { return norm; }
+ public void setNorm(double norm) { this.norm = norm; }
+
+ public double[] getVector() { return vector; }
+ public void setVector(double[] vector) { this.vector = vector; }
+
+ @Override
+ public String toString() {
+ return "VectorInfo{id='" + id + "', norm=" + norm + ", vectorLength=" + (vector != null ? vector.length : 0) + "}";
+ }
+}
diff --git a/src/main/java/io/endee/client/types/VectorItem.java b/src/main/java/io/endee/client/types/VectorItem.java
new file mode 100644
index 0000000..f773405
--- /dev/null
+++ b/src/main/java/io/endee/client/types/VectorItem.java
@@ -0,0 +1,63 @@
+package io.endee.client.types;
+
+import java.util.Map;
+
+/**
+ * A vector item for upsert operations.
+ */
+public class VectorItem {
+ private final String id;
+ private final double[] vector;
+ private Map meta;
+ private Map filter;
+ private int[] sparseIndices;
+ private double[] sparseValues;
+
+ private VectorItem(String id, double[] vector) {
+ this.id = id;
+ this.vector = vector;
+ }
+
+ public static Builder builder(String id, double[] vector) {
+ return new Builder(id, vector);
+ }
+
+ public String getId() { return id; }
+ public double[] getVector() { return vector; }
+ public Map getMeta() { return meta; }
+ public Map getFilter() { return filter; }
+ public int[] getSparseIndices() { return sparseIndices; }
+ public double[] getSparseValues() { return sparseValues; }
+
+ public static class Builder {
+ private final VectorItem item;
+
+ private Builder(String id, double[] vector) {
+ this.item = new VectorItem(id, vector);
+ }
+
+ public Builder meta(Map meta) {
+ item.meta = meta;
+ return this;
+ }
+
+ public Builder filter(Map filter) {
+ item.filter = filter;
+ return this;
+ }
+
+ public Builder sparseIndices(int[] sparseIndices) {
+ item.sparseIndices = sparseIndices;
+ return this;
+ }
+
+ public Builder sparseValues(double[] sparseValues) {
+ item.sparseValues = sparseValues;
+ return this;
+ }
+
+ public VectorItem build() {
+ return item;
+ }
+ }
+}
diff --git a/src/main/java/io/endee/client/util/CryptoUtils.java b/src/main/java/io/endee/client/util/CryptoUtils.java
new file mode 100644
index 0000000..832b402
--- /dev/null
+++ b/src/main/java/io/endee/client/util/CryptoUtils.java
@@ -0,0 +1,267 @@
+package io.endee.client.util;
+
+import io.endee.client.exception.EndeeException;
+
+import javax.crypto.Cipher;
+import javax.crypto.spec.IvParameterSpec;
+import javax.crypto.spec.SecretKeySpec;
+import java.io.ByteArrayOutputStream;
+import java.nio.charset.StandardCharsets;
+import java.security.SecureRandom;
+import java.util.Arrays;
+import java.util.Map;
+import java.util.zip.Deflater;
+import java.util.zip.Inflater;
+
+/**
+ * Cryptographic utilities for Endee-DB.
+ * Provides compression/decompression and AES encryption/decryption for metadata.
+ */
+public final class CryptoUtils {
+
+ private static final int AES_KEY_SIZE = 32; // 256 bits
+ private static final int IV_SIZE = 16; // 128 bits
+ private static final int BLOCK_SIZE = 16;
+
+ private CryptoUtils() {}
+
+ /**
+ * Gets checksum from key by converting last two hex characters to integer.
+ *
+ * @param key the key string
+ * @return checksum value or -1 if key is null
+ */
+ public static int getChecksum(String key) {
+ if (key == null || key.length() < 2) {
+ return -1;
+ }
+ try {
+ String lastTwo = key.substring(key.length() - 2);
+ return Integer.parseInt(lastTwo, 16);
+ } catch (NumberFormatException e) {
+ return -1;
+ }
+ }
+
+ /**
+ * Compresses a map to deflated JSON bytes, optionally encrypting with AES.
+ *
+ * @param data the map to compress
+ * @return compressed (and optionally encrypted) bytes
+ */
+ public static byte[] jsonZip(Map data) {
+ if (data == null || data.isEmpty()) {
+ return new byte[0];
+ }
+ try {
+ String json = JsonUtils.toJson(data);
+ byte[] compressed = deflateCompress(json.getBytes(StandardCharsets.UTF_8));
+
+ return compressed;
+ } catch (Exception e) {
+ throw new EndeeException("Failed to compress metadata", e);
+ }
+ }
+
+ /**
+ * Decompresses deflated JSON bytes to a map.
+ *
+ * @param data the compressed bytes
+ * @return the decompressed map
+ */
+ public static Map jsonUnzip(byte[] data) {
+ return jsonUnzip(data, null);
+ }
+
+ /**
+ * Decompresses deflated JSON bytes to a map, optionally decrypting with AES.
+ *
+ * @param data the compressed (and optionally encrypted) bytes
+ * @param key optional hex key for AES decryption (64 hex chars = 256 bits)
+ * @return the decompressed map
+ */
+ @SuppressWarnings("unchecked")
+ public static Map jsonUnzip(byte[] data, String key) {
+ if (data == null || data.length == 0) {
+ return Map.of();
+ }
+ try {
+ byte[] buffer = data;
+
+ // If key is provided, decrypt first
+ if (key != null && !key.isEmpty()) {
+ buffer = aesDecrypt(buffer, key);
+ }
+
+ byte[] decompressed = deflateDecompress(buffer);
+ String json = new String(decompressed, StandardCharsets.UTF_8);
+ return JsonUtils.fromJson(json, Map.class);
+ } catch (Exception e) {
+ // Return empty map on failure (matches TypeScript behavior)
+ return Map.of();
+ }
+ }
+
+ /**
+ * Encrypts data using AES-256-CBC.
+ *
+ * @param data the data to encrypt
+ * @param keyHex a 256-bit hex key (64 hex characters)
+ * @return IV + ciphertext (IV is prepended to the ciphertext)
+ */
+ public static byte[] aesEncrypt(byte[] data, String keyHex) {
+ try {
+ byte[] key = hexToBytes(keyHex);
+
+ if (key.length != AES_KEY_SIZE) {
+ throw new IllegalArgumentException("Key must be 256 bits (64 hex characters)");
+ }
+
+ // Generate random IV
+ byte[] iv = new byte[IV_SIZE];
+ new SecureRandom().nextBytes(iv);
+
+ // Pad data with PKCS7
+ byte[] paddedData = pkcs7Pad(data);
+
+ // Create cipher and encrypt
+ Cipher cipher = Cipher.getInstance("AES/CBC/NoPadding");
+ SecretKeySpec keySpec = new SecretKeySpec(key, "AES");
+ IvParameterSpec ivSpec = new IvParameterSpec(iv);
+ cipher.init(Cipher.ENCRYPT_MODE, keySpec, ivSpec);
+
+ byte[] ciphertext = cipher.doFinal(paddedData);
+
+ // Return IV + ciphertext
+ byte[] result = new byte[iv.length + ciphertext.length];
+ System.arraycopy(iv, 0, result, 0, iv.length);
+ System.arraycopy(ciphertext, 0, result, iv.length, ciphertext.length);
+
+ return result;
+ } catch (IllegalArgumentException e) {
+ throw e;
+ } catch (Exception e) {
+ throw new EndeeException("AES encryption failed", e);
+ }
+ }
+
+ /**
+ * Decrypts data using AES-256-CBC.
+ *
+ * @param data the encrypted data (IV + ciphertext)
+ * @param keyHex a 256-bit hex key (64 hex characters)
+ * @return the decrypted data
+ */
+ public static byte[] aesDecrypt(byte[] data, String keyHex) {
+ try {
+ byte[] key = hexToBytes(keyHex);
+
+ if (key.length != AES_KEY_SIZE) {
+ throw new IllegalArgumentException("Key must be 256 bits (64 hex characters)");
+ }
+
+ if (data.length < IV_SIZE) {
+ throw new IllegalArgumentException("Data too short to contain IV");
+ }
+
+ // Extract IV and ciphertext
+ byte[] iv = Arrays.copyOfRange(data, 0, IV_SIZE);
+ byte[] ciphertext = Arrays.copyOfRange(data, IV_SIZE, data.length);
+
+ // Create cipher and decrypt
+ Cipher cipher = Cipher.getInstance("AES/CBC/NoPadding");
+ SecretKeySpec keySpec = new SecretKeySpec(key, "AES");
+ IvParameterSpec ivSpec = new IvParameterSpec(iv);
+ cipher.init(Cipher.DECRYPT_MODE, keySpec, ivSpec);
+
+ byte[] paddedData = cipher.doFinal(ciphertext);
+
+ // Remove PKCS7 padding
+ return pkcs7Unpad(paddedData);
+ } catch (IllegalArgumentException e) {
+ throw e;
+ } catch (Exception e) {
+ throw new EndeeException("AES decryption failed", e);
+ }
+ }
+
+ /**
+ * Compresses data using DEFLATE algorithm (raw, no headers).
+ */
+ private static byte[] deflateCompress(byte[] data) {
+ Deflater deflater = new Deflater();
+ deflater.setInput(data);
+ deflater.finish();
+
+ ByteArrayOutputStream bos = new ByteArrayOutputStream(data.length);
+ byte[] buffer = new byte[1024];
+
+ while (!deflater.finished()) {
+ int count = deflater.deflate(buffer);
+ bos.write(buffer, 0, count);
+ }
+
+ deflater.end();
+ return bos.toByteArray();
+ }
+
+ /**
+ * Decompresses DEFLATE compressed data.
+ */
+ private static byte[] deflateDecompress(byte[] data) throws Exception {
+ Inflater inflater = new Inflater();
+ inflater.setInput(data);
+
+ ByteArrayOutputStream bos = new ByteArrayOutputStream(data.length);
+ byte[] buffer = new byte[1024];
+
+ while (!inflater.finished()) {
+ int count = inflater.inflate(buffer);
+ if (count == 0 && inflater.needsInput()) {
+ break;
+ }
+ bos.write(buffer, 0, count);
+ }
+
+ inflater.end();
+ return bos.toByteArray();
+ }
+
+ /**
+ * Adds PKCS7 padding to data.
+ */
+ private static byte[] pkcs7Pad(byte[] data) {
+ int paddingLength = BLOCK_SIZE - (data.length % BLOCK_SIZE);
+ byte[] padded = new byte[data.length + paddingLength];
+ System.arraycopy(data, 0, padded, 0, data.length);
+ Arrays.fill(padded, data.length, padded.length, (byte) paddingLength);
+ return padded;
+ }
+
+ /**
+ * Removes PKCS7 padding from data.
+ */
+ private static byte[] pkcs7Unpad(byte[] data) {
+ if (data.length == 0) {
+ return data;
+ }
+ int paddingLength = data[data.length - 1] & 0xFF;
+ if (paddingLength > BLOCK_SIZE || paddingLength > data.length) {
+ return data; // Invalid padding, return as-is
+ }
+ return Arrays.copyOfRange(data, 0, data.length - paddingLength);
+ }
+
+ /**
+ * Converts a hex string to byte array.
+ */
+ private static byte[] hexToBytes(String hex) {
+ int len = hex.length();
+ byte[] data = new byte[len / 2];
+ for (int i = 0; i < len; i += 2) {
+ data[i / 2] = (byte) ((Character.digit(hex.charAt(i), 16) << 4)
+ + Character.digit(hex.charAt(i + 1), 16));
+ }
+ return data;
+ }
+}
diff --git a/src/main/java/io/endee/client/util/JsonUtils.java b/src/main/java/io/endee/client/util/JsonUtils.java
new file mode 100644
index 0000000..4d5aa2a
--- /dev/null
+++ b/src/main/java/io/endee/client/util/JsonUtils.java
@@ -0,0 +1,37 @@
+package io.endee.client.util;
+
+import com.fasterxml.jackson.core.JsonProcessingException;
+import com.fasterxml.jackson.databind.DeserializationFeature;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import io.endee.client.exception.EndeeException;
+
+/**
+ * JSON serialization utilities.
+ */
+public final class JsonUtils {
+
+ private static final ObjectMapper OBJECT_MAPPER = new ObjectMapper()
+ .configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false);
+
+ private JsonUtils() {}
+
+ public static ObjectMapper getObjectMapper() {
+ return OBJECT_MAPPER;
+ }
+
+ public static String toJson(Object object) {
+ try {
+ return OBJECT_MAPPER.writeValueAsString(object);
+ } catch (JsonProcessingException e) {
+ throw new EndeeException("Failed to serialize to JSON", e);
+ }
+ }
+
+ public static T fromJson(String json, Class type) {
+ try {
+ return OBJECT_MAPPER.readValue(json, type);
+ } catch (JsonProcessingException e) {
+ throw new EndeeException("Failed to deserialize JSON", e);
+ }
+ }
+}
diff --git a/src/main/java/io/endee/client/util/MessagePackUtils.java b/src/main/java/io/endee/client/util/MessagePackUtils.java
new file mode 100644
index 0000000..bb1faed
--- /dev/null
+++ b/src/main/java/io/endee/client/util/MessagePackUtils.java
@@ -0,0 +1,164 @@
+package io.endee.client.util;
+
+import io.endee.client.exception.EndeeException;
+import org.msgpack.core.MessageBufferPacker;
+import org.msgpack.core.MessagePack;
+import org.msgpack.core.MessageUnpacker;
+import org.msgpack.value.Value;
+
+import java.io.IOException;
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * MessagePack serialization utilities.
+ */
+public final class MessagePackUtils {
+
+ private MessagePackUtils() {
+ }
+
+ /**
+ * Packs vector data for upsert operations.
+ */
+ public static byte[] packVectors(List vectors) {
+ try (MessageBufferPacker packer = MessagePack.newDefaultBufferPacker()) {
+ packer.packArrayHeader(vectors.size());
+
+ for (Object[] vector : vectors) {
+ packVectorTuple(packer, vector);
+ }
+
+ return packer.toByteArray();
+ } catch (IOException e) {
+ throw new EndeeException("Failed to pack vectors", e);
+ }
+ }
+
+ private static void packVectorTuple(MessageBufferPacker packer, Object[] vector) throws IOException {
+ packer.packArrayHeader(vector.length);
+
+ // id (string)
+ packer.packString((String) vector[0]);
+
+ // metadata (bytes)
+ byte[] meta = (byte[]) vector[1];
+ packer.packBinaryHeader(meta.length);
+ packer.writePayload(meta);
+
+ // filter (string)
+ packer.packString((String) vector[2]);
+
+ // norm (double)
+ packer.packDouble((Double) vector[3]);
+
+ // vector (double[])
+ double[] vec = (double[]) vector[4];
+ packer.packArrayHeader(vec.length);
+ for (double v : vec) {
+ packer.packDouble(v);
+ }
+
+ // Optional sparse data
+ if (vector.length > 5) {
+ int[] sparseIndices = (int[]) vector[5];
+ packer.packArrayHeader(sparseIndices.length);
+ for (int idx : sparseIndices) {
+ packer.packInt(idx);
+ }
+
+ double[] sparseValues = (double[]) vector[6];
+ packer.packArrayHeader(sparseValues.length);
+ for (double val : sparseValues) {
+ packer.packDouble(val);
+ }
+ }
+ }
+
+ /**
+ * Unpacks query results from MessagePack bytes.
+ */
+ public static List unpackQueryResults(byte[] data) {
+ List results = new ArrayList<>();
+
+ try (MessageUnpacker unpacker = MessagePack.newDefaultUnpacker(data)) {
+ int arraySize = unpacker.unpackArrayHeader();
+
+ for (int i = 0; i < arraySize; i++) {
+ int tupleSize = unpacker.unpackArrayHeader();
+ Object[] tuple = new Object[tupleSize];
+
+ tuple[0] = unpackNumberAsDouble(unpacker); // similarity
+ tuple[1] = unpacker.unpackString(); // vectorId
+ int metaLen = unpacker.unpackBinaryHeader();
+ tuple[2] = unpacker.readPayload(metaLen); // metadata
+ tuple[3] = unpacker.unpackString(); // filter
+ tuple[4] = unpackNumberAsDouble(unpacker); // norm
+
+ if (tupleSize > 5) {
+ int vecLen = unpacker.unpackArrayHeader();
+ double[] vec = new double[vecLen];
+ for (int j = 0; j < vecLen; j++) {
+ vec[j] = unpackNumberAsDouble(unpacker);
+ }
+ tuple[5] = vec;
+ }
+
+ results.add(tuple);
+ }
+ } catch (IOException e) {
+ throw new EndeeException("Failed to unpack query results", e);
+ }
+
+ return results;
+ }
+
+ /**
+ * Unpacks a single vector from MessagePack bytes.
+ */
+ public static Object[] unpackVector(byte[] data) {
+ try (MessageUnpacker unpacker = MessagePack.newDefaultUnpacker(data)) {
+ int tupleSize = unpacker.unpackArrayHeader();
+ Object[] tuple = new Object[tupleSize];
+
+ tuple[0] = unpacker.unpackString(); // id
+ int metaLen = unpacker.unpackBinaryHeader();
+ tuple[1] = unpacker.readPayload(metaLen); // metadata
+ tuple[2] = unpacker.unpackString(); // filter
+ tuple[3] = unpackNumberAsDouble(unpacker); // norm
+
+ int vecLen = unpacker.unpackArrayHeader();
+ double[] vec = new double[vecLen];
+ for (int i = 0; i < vecLen; i++) {
+ vec[i] = unpackNumberAsDouble(unpacker);
+ }
+ tuple[4] = vec;
+
+ return tuple;
+ } catch (IOException e) {
+ throw new EndeeException("Failed to unpack vector", e);
+ }
+ }
+
+ /**
+ * Helper function to unpackNumber as double even though it
+ * can be integer
+ * @param unpacker
+ * @return
+ * @throws IOException
+ */
+ private static double unpackNumberAsDouble(MessageUnpacker unpacker) throws IOException {
+ Value value = unpacker.unpackValue();
+
+ if (value.isFloatValue()) {
+ return value.asFloatValue().toDouble();
+ }
+
+ if (value.isIntegerValue()) {
+ return value.asIntegerValue().toDouble();
+ }
+
+ throw new IllegalStateException(
+ "Expected numeric value (int/float), got " + value.getValueType());
+ }
+}
diff --git a/src/main/java/io/endee/client/util/ValidationUtils.java b/src/main/java/io/endee/client/util/ValidationUtils.java
new file mode 100644
index 0000000..17afc16
--- /dev/null
+++ b/src/main/java/io/endee/client/util/ValidationUtils.java
@@ -0,0 +1,54 @@
+package io.endee.client.util;
+
+import java.util.HashSet;
+import java.util.List;
+import java.util.Set;
+import java.util.regex.Pattern;
+
+/**
+ * Validation utilities.
+ */
+public final class ValidationUtils {
+
+ private static final Pattern INDEX_NAME_PATTERN = Pattern.compile("^[a-zA-Z0-9_]+$");
+ private static final int MAX_INDEX_NAME_LENGTH = 48;
+
+ private ValidationUtils() {}
+
+ /**
+ * Validates an index name.
+ * Must be alphanumeric with underscores, less than 48 characters.
+ */
+ public static boolean isValidIndexName(String name) {
+ if (name == null || name.isEmpty()) {
+ return false;
+ }
+ if (name.length() >= MAX_INDEX_NAME_LENGTH) {
+ return false;
+ }
+ return INDEX_NAME_PATTERN.matcher(name).matches();
+ }
+
+ /**
+ * Validates that all vector IDs are non-empty and unique.
+ */
+ public static void validateVectorIds(List ids) {
+ Set seenIds = new HashSet<>();
+ Set duplicateIds = new HashSet<>();
+
+ for (String id : ids) {
+ if (id == null || id.isEmpty()) {
+ throw new IllegalArgumentException("All vectors must have a non-empty ID");
+ }
+ if (seenIds.contains(id)) {
+ duplicateIds.add(id);
+ } else {
+ seenIds.add(id);
+ }
+ }
+
+ if (!duplicateIds.isEmpty()) {
+ throw new IllegalArgumentException("Duplicate IDs found: " + String.join(", ", duplicateIds));
+ }
+ }
+}