refactor(param): introduce declarative schema and migrate BruteForceParameter

src/CMakeLists.txt

@@ -21,6 +21,7 @@ add_subdirectory (impl)
 add_subdirectory (storage)
 add_subdirectory (attr)
 add_subdirectory (datacell)
+add_subdirectory (param)
 add_subdirectory (algorithm)
 add_subdirectory (utils)
 add_subdirectory (factory)
@@ -62,7 +63,7 @@ foreach (_lib vsag vsag_static)
             $<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}>)
 endforeach ()
 
-set (VSAG_DEP_LIBS antlr4-autogen antlr4-runtime diskann simd io quantizer storage utils factory analyzer
+set (VSAG_DEP_LIBS antlr4-autogen param antlr4-runtime diskann simd io quantizer storage utils factory analyzer
       datacell ${IMPL_LIBS} ${ALGORITHM_LIBS} attr pthread m dl fmt::fmt nlohmann_json::nlohmann_json roaring ${BLAS_LIBRARIES})
 
 # `vsag_src_common` aggregates third-party include paths and link

src/algorithm/bruteforce/bruteforce_parameter.cpp

@@ -15,7 +15,7 @@
 
 #include "bruteforce_parameter.h"
 
-#include <fmt/format.h>
+#include <unordered_set>
 
 #include "datacell/flatten_datacell_parameter.h"
 #include "inner_string_params.h"
@@ -24,23 +24,27 @@
 
 namespace vsag {
 
+VSAG_PARAM_SCHEMA(BruteForceParameter)
+VSAG_PARAM_TYPE_TAG(TYPE_KEY, INDEX_TYPE_BRUTE_FORCE)
+VSAG_PARAM_SUBPARAM_REQUIRED(FlattenInterfaceParameter,
+                             base_codes_param,
+                             BASE_CODES_KEY,
+                             CreateFlattenParam)
+VSAG_PARAM_SCHEMA_END()
+
 BruteForceParameter::BruteForceParameter() : base_codes_param(nullptr) {
 }
 
 void
 BruteForceParameter::FromJson(const JsonType& json) {
     InnerIndexParameter::FromJson(json);
-    CHECK_ARGUMENT(json.Contains(BASE_CODES_KEY),
-                   fmt::format("bruteforce parameters must contains {}", BASE_CODES_KEY));
-    const auto& base_codes_json = json[BASE_CODES_KEY];
-    this->base_codes_param = CreateFlattenParam(base_codes_json);
+    schema().Parse(this, json);
 }
 
 JsonType
 BruteForceParameter::ToJson() const {
     JsonType json = InnerIndexParameter::ToJson();
-    json[TYPE_KEY].SetString(INDEX_TYPE_BRUTE_FORCE);
-    json[BASE_CODES_KEY].SetJson(this->base_codes_param->ToJson());
+    schema().Serialize(this, json);
     return json;
 }
 
@@ -50,7 +54,6 @@ BruteForceParameter::CheckCompatibility(const ParamPtr& other) const {
         return false;
     }
     PARAM_CAST_OR_RETURN(BruteForceParameter, p, other);
-    CHECK_SUB_PARAM(*this, *p, base_codes_param);
-    return true;
+    return schema().Equal(this, p.get());
 }
 }  // namespace vsag

src/algorithm/bruteforce/bruteforce_parameter.h

@@ -16,11 +16,12 @@
 #pragma once
 #include "algorithm/index_search_parameter.h"
 #include "algorithm/inner_index_parameter.h"
+#include "datacell/flatten_interface_parameter.h"
+#include "param/schema.h"
 #include "typing.h"
 #include "utils/pointer_define.h"
 #include "vsag/constants.h"
 namespace vsag {
-DEFINE_POINTER2(FlattenDataCellParam, FlattenDataCellParameter);
 class BruteForceParameter : public InnerIndexParameter {
 public:
     explicit BruteForceParameter();
@@ -34,8 +35,8 @@ class BruteForceParameter : public InnerIndexParameter {
     bool
     CheckCompatibility(const vsag::ParamPtr& other) const override;
 
-public:
     FlattenInterfaceParamPtr base_codes_param{nullptr};
+    VSAG_PARAM_SCHEMA_DECL();
 };
 
 DEFINE_POINTER(BruteForceParameter);

src/inner_string_params.h

@@ -200,6 +200,7 @@ const std::unordered_map<std::string, std::string> DEFAULT_MAP = {
     {"INDEX_TYPE_IVF", INDEX_TYPE_IVF},
     {"INDEX_TYPE_GNO_IMI", INDEX_TYPE_GNO_IMI},
     {"INDEX_TYPE_PYRAMID", INDEX_TYPE_PYRAMID},
+    {"INDEX_BRUTE_FORCE", INDEX_BRUTE_FORCE},
     {"TYPE_KEY", TYPE_KEY},
     {"HGRAPH_USE_ELP_OPTIMIZER_KEY", HGRAPH_USE_ELP_OPTIMIZER_KEY},
     {"HGRAPH_IGNORE_REORDER_KEY", HGRAPH_IGNORE_REORDER_KEY},

src/param/CMakeLists.txt

@@ -0,0 +1,28 @@
+
+# Copyright 2024-present the vsag project
+#
+# 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
+#
+#     http://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.
+
+
+file (GLOB PARAM_SRCS "*.cpp")
+list (FILTER PARAM_SRCS EXCLUDE REGEX "_test.cpp")
+
+add_library (param OBJECT ${PARAM_SRCS})
+target_link_libraries (param PRIVATE coverage_config vsag_src_common)
+
+if (ENABLE_TESTS)
+    file (GLOB_RECURSE PARAM_TESTS "*_test.cpp")
+    add_library (param_test STATIC ${PARAM_TESTS})
+    target_link_libraries (param_test PRIVATE Catch2::Catch2 vsag_static unittest_deps)
+    add_dependencies (param_test Catch2)
+endif ()

src/param/schema.cpp

@@ -0,0 +1,169 @@
+
+// Copyright 2024-present the vsag project
+//
+// 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
+//
+//     http://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.
+
+#include "param/schema.h"
+
+#include <fmt/format.h>
+
+#include <nlohmann/json.hpp>
+
+#include "common.h"
+
+namespace vsag::param {
+
+// ---------------------------------------------------------------------------
+// Schema
+// ---------------------------------------------------------------------------
+
+void
+Schema::AddField(FieldPtr field) {
+    this->known_keys_.insert(field->Key());
+    this->fields_.push_back(std::move(field));
+}
+
+void
+Schema::Parse(void* instance, const JsonType& parent) const {
+    for (const auto& field : this->fields_) {
+        field->Parse(instance, parent);
+    }
+}
+
+void
+Schema::Serialize(const void* instance, JsonType& parent) const {
+    for (const auto& field : this->fields_) {
+        field->Serialize(instance, parent);
+    }
+}
+
+bool
+Schema::Equal(const void* lhs, const void* rhs) const {
+    for (const auto& field : this->fields_) {
+        if (not field->Equal(lhs, rhs)) {
+            return false;
+        }
+    }
+    return true;
+}
+
+void
+Schema::CheckUnknownKeys(const JsonType& parent,
+                         const std::unordered_set<std::string>& extra_known_keys) const {
+    auto* inner = parent.GetInnerJson();
+    if (inner == nullptr || not inner->is_object()) {
+        return;
+    }
+    for (const auto& item : inner->items()) {
+        const auto& key = item.key();
+        if (this->known_keys_.count(key) != 0U) {
+            continue;
+        }
+        if (extra_known_keys.count(key) != 0U) {
+            continue;
+        }
+        throw VsagException(
+            ErrorType::INVALID_ARGUMENT,
+            fmt::format("unknown parameter key '{}' is not declared by the schema", key));
+    }
+}
+
+// ---------------------------------------------------------------------------
+// ConstantStringField
+// ---------------------------------------------------------------------------
+
+ConstantStringField::ConstantStringField(std::string key, std::string value)
+    : key_(std::move(key)), value_(std::move(value)) {
+}
+
+void
+ConstantStringField::Parse(void* /*instance*/, const JsonType& parent) const {
+    if (not parent.Contains(this->key_)) {
+        return;
+    }
+    auto actual = parent[this->key_].GetString();
+    CHECK_ARGUMENT(
+        actual == this->value_,
+        fmt::format("parameter '{}' must be '{}', got '{}'", this->key_, this->value_, actual));
+}
+
+void
+ConstantStringField::Serialize(const void* /*instance*/, JsonType& parent) const {
+    parent[this->key_].SetString(this->value_);
+}
+
+// ---------------------------------------------------------------------------
+// Scalar JSON read/write specializations
+// ---------------------------------------------------------------------------
+
+template <>
+uint64_t
+ReadJsonValue<uint64_t>(const JsonType& json) {
+    return json.GetUint64();
+}
+
+template <>
+int64_t
+ReadJsonValue<int64_t>(const JsonType& json) {
+    return json.GetInt();
+}
+
+template <>
+std::string
+ReadJsonValue<std::string>(const JsonType& json) {
+    return json.GetString();
+}
+
+template <>
+bool
+ReadJsonValue<bool>(const JsonType& json) {
+    return json.GetBool();
+}
+
+template <>
+float
+ReadJsonValue<float>(const JsonType& json) {
+    return json.GetFloat();
+}
+
+template <>
+void
+WriteJsonValueAt<uint64_t>(JsonType& parent, const std::string& key, const uint64_t& value) {
+    parent[key].SetUint64(value);
+}
+
+template <>
+void
+WriteJsonValueAt<int64_t>(JsonType& parent, const std::string& key, const int64_t& value) {
+    parent[key].SetInt(value);
+}
+
+template <>
+void
+WriteJsonValueAt<std::string>(JsonType& parent, const std::string& key, const std::string& value) {
+    parent[key].SetString(value);
+}
+
+template <>
+void
+WriteJsonValueAt<bool>(JsonType& parent, const std::string& key, const bool& value) {
+    parent[key].SetBool(value);
+}
+
+template <>
+void
+WriteJsonValueAt<float>(JsonType& parent, const std::string& key, const float& value) {
+    parent[key].SetFloat(value);
+}
+
+}  // namespace vsag::param