[Rule-based Auto Tagging] Add rule schema for auto tagging (#17238) (#17653)

Signed-off-by: Ruirui Zhang <[email protected]>

* add rule schema for workload management
Signed-off-by: Ruirui Zhang <[email protected]>

* modify rule structure based on comment
Signed-off-by: Ruirui Zhang <[email protected]>

* update based on comments
Signed-off-by: Ruirui Zhang <[email protected]>

* add javadoc for autotagging directory
Signed-off-by: Ruirui Zhang <[email protected]>

* change field name from 'name' to 'description'
Signed-off-by: Ruirui Zhang <[email protected]>

* update the rule schema
Signed-off-by: Ruirui Zhang <[email protected]>

* simplify autotagging registry
Signed-off-by: Ruirui Zhang <[email protected]>

* remove generic type parameter from Rule class
Signed-off-by: Ruirui Zhang <[email protected]>

* modify based on comments
Signed-off-by: Ruirui Zhang <[email protected]>
(cherry picked from commit b24c72b)

Signed-off-by: Ruirui Zhang <[email protected]>

Author: ruai0511

CHANGELOG.md

@@ -6,6 +6,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 ## [Unreleased 2.x]
 ### Added
 - Improve performace of NumericTermAggregation by avoiding unnecessary sorting([#17252](https://github.com/opensearch-project/OpenSearch/pull/17252))
+- [Rule Based Auto-tagging] Add rule schema for auto tagging ([#17238](https://github.com/opensearch-project/OpenSearch/pull/17238))
 - Add execution_hint to cardinality aggregator request (#[17419](https://github.com/opensearch-project/OpenSearch/pull/17419))
 - [Rule Based Auto-tagging] Add in-memory attribute value store ([#17342](https://github.com/opensearch-project/OpenSearch/pull/17342))
 

server/src/main/java/org/opensearch/autotagging/Attribute.java

@@ -0,0 +1,59 @@
+/*
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * The OpenSearch Contributors require contributions made to
+ * this file be licensed under the Apache-2.0 license or a
+ * compatible open source license.
+ */
+
+package org.opensearch.autotagging;
+
+import org.opensearch.core.common.io.stream.StreamInput;
+import org.opensearch.core.common.io.stream.StreamOutput;
+import org.opensearch.core.common.io.stream.Writeable;
+
+import java.io.IOException;
+
+/**
+ * Represents an attribute within the auto-tagging feature. Attributes define characteristics that can
+ * be used for tagging and classification. Implementations must ensure that attributes
+ * are uniquely identifiable by their name. Attributes should be singletons and managed centrally to
+ * avoid duplicates.
+ *
+ * @opensearch.experimental
+ */
+public interface Attribute extends Writeable {
+    String getName();
+
+    /**
+     * Ensure that `validateAttribute` is called in the constructor of attribute implementations
+     * to prevent potential serialization issues.
+     */
+    default void validateAttribute() {
+        String name = getName();
+        if (name == null || name.isEmpty()) {
+            throw new IllegalArgumentException("Attribute name cannot be null or empty");
+        }
+    }
+
+    @Override
+    default void writeTo(StreamOutput out) throws IOException {
+        out.writeString(getName());
+    }
+
+    /**
+     * Retrieves an attribute from the given feature type based on its name.
+     * Implementations of `FeatureType.getAttributeFromName` must be thread-safe as this method
+     * may be called concurrently.
+     * @param in - the {@link StreamInput} from which the attribute name is read
+     * @param featureType - the FeatureType used to look up the attribute
+     */
+    static Attribute from(StreamInput in, FeatureType featureType) throws IOException {
+        String attributeName = in.readString();
+        Attribute attribute = featureType.getAttributeFromName(attributeName);
+        if (attribute == null) {
+            throw new IllegalStateException(attributeName + " is not a valid attribute under feature type " + featureType.getName());
+        }
+        return attribute;
+    }
+}

server/src/main/java/org/opensearch/autotagging/AutoTaggingRegistry.java

@@ -0,0 +1,68 @@
+/*
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * The OpenSearch Contributors require contributions made to
+ * this file be licensed under the Apache-2.0 license or a
+ * compatible open source license.
+ */
+
+package org.opensearch.autotagging;
+
+import org.opensearch.ResourceNotFoundException;
+
+import java.util.HashMap;
+import java.util.Map;
+
+/**
+ *  Registry for managing auto-tagging attributes and feature types.
+ *  This class provides functionality to register and retrieve {@link Attribute} and {@link FeatureType} instances
+ *  used for auto-tagging.
+ *
+ * @opensearch.experimental
+ */
+public class AutoTaggingRegistry {
+    /**
+     * featureTypesRegistryMap should be concurrently readable but not concurrently writable.
+     * The registration of FeatureType should only be done during boot-up.
+     */
+    public static final Map<String, FeatureType> featureTypesRegistryMap = new HashMap<>();
+    public static final int MAX_FEATURE_TYPE_NAME_LENGTH = 30;
+
+    public static void registerFeatureType(FeatureType featureType) {
+        validateFeatureType(featureType);
+        String name = featureType.getName();
+        if (featureTypesRegistryMap.containsKey(name) && featureTypesRegistryMap.get(name) != featureType) {
+            throw new IllegalStateException("Feature type " + name + " is already registered. Duplicate feature type is not allowed.");
+        }
+        featureTypesRegistryMap.put(name, featureType);
+    }
+
+    private static void validateFeatureType(FeatureType featureType) {
+        if (featureType == null) {
+            throw new IllegalStateException("Feature type can't be null. Unable to register.");
+        }
+        String name = featureType.getName();
+        if (name == null || name.isEmpty() || name.length() > MAX_FEATURE_TYPE_NAME_LENGTH) {
+            throw new IllegalStateException(
+                "Feature type name " + name + " should not be null, empty or have more than  " + MAX_FEATURE_TYPE_NAME_LENGTH + "characters"
+            );
+        }
+    }
+
+    /**
+     * Retrieves the registered {@link FeatureType} instance based on class name and feature type name.
+     * This method assumes that FeatureTypes are singletons, meaning that each unique
+     * (className, featureTypeName) pair corresponds to a single, globally shared instance.
+     *
+     * @param featureTypeName The name of the feature type.
+     */
+    public static FeatureType getFeatureType(String featureTypeName) {
+        FeatureType featureType = featureTypesRegistryMap.get(featureTypeName);
+        if (featureType == null) {
+            throw new ResourceNotFoundException(
+                "Couldn't find a feature type with name: " + featureTypeName + ". Make sure you have registered it."
+            );
+        }
+        return featureType;
+    }
+}

server/src/main/java/org/opensearch/autotagging/FeatureType.java

@@ -0,0 +1,73 @@
+/*
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * The OpenSearch Contributors require contributions made to
+ * this file be licensed under the Apache-2.0 license or a
+ * compatible open source license.
+ */
+
+package org.opensearch.autotagging;
+
+import org.opensearch.core.common.io.stream.StreamInput;
+import org.opensearch.core.common.io.stream.StreamOutput;
+import org.opensearch.core.common.io.stream.Writeable;
+
+import java.io.IOException;
+import java.util.Map;
+
+/**
+ * Represents a feature type within the auto-tagging feature. Feature types define different categories of
+ * characteristics that can be used for tagging and classification. Implementations of this interface are
+ * responsible for registering feature types in {@link AutoTaggingRegistry}. Implementations must ensure that
+ * feature types are uniquely identifiable by their class and name.
+ *
+ * Implementers should follow these guidelines:
+ * Feature types should be singletons and managed centrally to avoid duplicates.
+ * {@link #registerFeatureType()} must be called during initialization to ensure the feature type is available.
+ *
+ * @opensearch.experimental
+ */
+public interface FeatureType extends Writeable {
+    int DEFAULT_MAX_ATTRIBUTE_VALUES = 10;
+    int DEFAULT_MAX_ATTRIBUTE_VALUE_LENGTH = 100;
+
+    String getName();
+
+    /**
+     * Returns the registry of allowed attributes for this feature type.
+     * Implementations must ensure that access to this registry is thread-safe.
+     */
+    Map<String, Attribute> getAllowedAttributesRegistry();
+
+    default int getMaxNumberOfValuesPerAttribute() {
+        return DEFAULT_MAX_ATTRIBUTE_VALUES;
+    }
+
+    default int getMaxCharLengthPerAttributeValue() {
+        return DEFAULT_MAX_ATTRIBUTE_VALUE_LENGTH;
+    }
+
+    void registerFeatureType();
+
+    default boolean isValidAttribute(Attribute attribute) {
+        return getAllowedAttributesRegistry().containsValue(attribute);
+    }
+
+    /**
+     * Retrieves an attribute by its name from the allowed attributes' registry.
+     * Implementations must ensure that this method is thread-safe.
+     * @param name The name of the attribute.
+     */
+    default Attribute getAttributeFromName(String name) {
+        return getAllowedAttributesRegistry().get(name);
+    }
+
+    @Override
+    default void writeTo(StreamOutput out) throws IOException {
+        out.writeString(getName());
+    }
+
+    static FeatureType from(StreamInput in) throws IOException {
+        return AutoTaggingRegistry.getFeatureType(in.readString());
+    }
+}