Feature add version namespace

include/svs/index/flat/dynamic_flat.h

@@ -20,6 +20,7 @@
 #include <filesystem>
 #include <memory>
 
+// svs
 // Include the flat index
 #include "svs/index/flat/flat.h"
 #include "svs/index/flat/inserters.h"

include/svs/index/vamana/dynamic_index.h

@@ -19,6 +19,7 @@
 // stdlib
 #include <memory>
 
+// svs
 // Include the flat index to spin-up exhaustive searches on demand.
 #include "svs/index/flat/flat.h"
 

include/svs/index/vamana/index.h

@@ -1058,4 +1058,5 @@ void verify_and_set_default_index_parameters(
         throw std::invalid_argument("prune_to must be <= graph_max_degree");
     }
 }
+
 } // namespace svs::index::vamana

include/svs/orchestrators/vamana.h

@@ -21,6 +21,7 @@
 /// @brief Main API for the Vamana type-erased orchestrator.
 ///
 
+#include "svs/version.hpp"
 #include "svs/core/data.h"
 #include "svs/core/distance.h"
 #include "svs/core/graph.h"

include/svs/version.hpp

@@ -0,0 +1,107 @@
+/*
+ * Copyright 2025 Intel Corporation
+ *
+ * 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.
+ */
+
+#pragma once
+
+///
+/// @brief Version information and API versioning for SVS
+///
+/// This header defines the SVS API versioning scheme similar to oneDAL:
+/// 1. Versioned namespaces (e.g., v0, v1) for API stability
+/// 2. Using declarations to bring current version to parent namespace
+/// 3. Clean integration points for external libraries
+///
+/// Usage:
+/// - Users can access APIs via svs::function_name (maps to current version)
+/// - External integrators can use namespace aliases (e.g., namespace svs_api = svs::v0)
+/// - Specific versions can be accessed via svs::v0::function_name
+///
+
+///// Version Numbers
+
+#ifndef SVS_VERSION_MAJOR
+/// Major version number - incremented for breaking API changes
+/// When this changes, a new version namespace (e.g., v0 -> v1) is created
+#define SVS_VERSION_MAJOR 0
+#endif
+
+#ifndef SVS_VERSION_MINOR
+/// Minor version number - incremented for backward-compatible feature additions
+#define SVS_VERSION_MINOR 1
+#endif
+
+#ifndef SVS_VERSION_PATCH
+/// Patch version number - incremented for backward-compatible bug fixes
+#define SVS_VERSION_PATCH 0
+#endif
+
+#ifndef SVS_VERSION_STRING
+/// Complete version string
+#define SVS_VERSION_STRING "0.1.0"
+#endif
+
+///// API Version Namespace Declaration
+
+/// Declare the main SVS namespace with versioned APIs
+/// This makes svs::function_name automatically resolve to svs::v0::function_name (current version)
+namespace svs {
+    /// Current API version namespace (v0)
+    /// All public APIs live here and are accessible as svs::function_name via using declarations
+    namespace v0 {
+        // Public APIs will be defined in their respective headers and brought up via using declarations
+    }
+
+    // Using declarations to bring current version APIs to parent namespace
+    // These will be added as we define versioned APIs in their respective headers
+}
+
+///// Integration Support
+
+/// Helper macro to create namespace aliases for external integrators
+/// Example: SVS_CREATE_API_ALIAS(svs_api, v0) creates: namespace svs_api = svs::v0;
+#define SVS_CREATE_API_ALIAS(alias_name, version_ns) \
+    namespace alias_name = svs::version_ns
+
+///
+/// @brief Version information structure for runtime queries
+///
+namespace svs::v0 {
+
+struct VersionInfo {
+    static constexpr int major = SVS_VERSION_MAJOR;
+    static constexpr int minor = SVS_VERSION_MINOR; 
+    static constexpr int patch = SVS_VERSION_PATCH;
+    static constexpr const char* version_string = SVS_VERSION_STRING;
+    static constexpr const char* api_namespace = "v0";
+
+    /// Get the complete version as a string
+    static const char* get_version() { return version_string; }
+
+    /// Get the API namespace identifier
+    static const char* get_api_namespace() { return api_namespace; }
+
+    /// Check if this version is compatible with a requested major version
+    static bool is_compatible_with_major(int requested_major) {
+        return major == requested_major;
+    }
+};
+
+} // namespace svs::v0
+
+// Bring current version APIs to parent namespace
+namespace svs {
+    using v0::VersionInfo;
+} // namespace svs