Add SAM search helpers to the client API and document usage.

Author: cferrys

README.md

@@ -18,7 +18,7 @@
 
 ### hlquery C++ API Client
 
-A C++ client library for hlquery with modular APIs, authentication support, HTTPS support, and type-safe responses.
+A C++ client library for hlquery with modular APIs, authentication support, HTTPS support, type-safe responses, and basic SAM search helpers.
 
 ### Installation
 
@@ -221,6 +221,10 @@ nlohmann::json vector_body = {
     {"radius", 1.0}
 };
 auto advanced = client.executeRequest("POST", "/collections/collection/vector_search", vector_body);
+
+// SAM search
+auto sam = client.samSearch("collection", "wireless keyboard");
+auto sam_all = client.samSearchAll("guide", {{"limit", "5"}});
 ```
 
 Preferred structure:
@@ -239,6 +243,15 @@ Compatibility note:
 
 still exist for now, but they are compatibility shims. New code should prefer `client.collections()->...` for collection-scoped search operations.
 
+### SAM Search
+
+SAM search calls `/sam/search` directly and is useful for broader intent-style lookup.
+
+```cpp
+auto sam = client.samSearch("products", "nineteen");
+auto sam_all = client.samSearchAll("benchmark", {{"distributed", "on"}, {"limit", "10"}});
+```
+
 ### Collections And Documents
 
 ```cpp

include/hlquery/client.h

@@ -70,6 +70,9 @@ class Client
      std::shared_ptr<Search> searchApi();
      [[deprecated("Use client.collections()->search(...) for collection-scoped searches.")]]
      Response search(const std::string& collection_name, const std::map<std::string, std::string>& params = {});
+     Response samSearch(const std::string& collection_name, const std::string& query,
+                        const std::map<std::string, std::string>& params = {});
+     Response samSearchAll(const std::string& query, const std::map<std::string, std::string>& params = {});
      [[deprecated("Use client.collections()->sql(...) for collection-scoped SQL searches.")]]
      Response sqlSearch(const std::string& collection_name, const std::string& sql,
                         const std::map<std::string, std::string>& params = {});

include/hlquery/search.h

@@ -32,6 +32,9 @@ class Search
      Search(std::shared_ptr<Request> request, std::shared_ptr<Collections> collections);
 
      Response search(const std::string& collection_name, const std::map<std::string, std::string>& params = {});
+     Response samSearch(const std::string& collection_name, const std::string& query,
+                        const std::map<std::string, std::string>& params = {});
+     Response samSearchAll(const std::string& query, const std::map<std::string, std::string>& params = {});
      Response sql(const std::string& collection_name, const std::string& sql,
                   const std::map<std::string, std::string>& params = {});
      Response multiSearch(const std::vector<nlohmann::json>& searches);

src/client.cpp

@@ -161,6 +161,17 @@ Response Client::search(const std::string& collection_name, const std::map<std::
      return collections_->search(collection_name, params);
 }
 
+Response Client::samSearch(const std::string& collection_name, const std::string& query,
+                           const std::map<std::string, std::string>& params)
+{
+     return search_->samSearch(collection_name, query, params);
+}
+
+Response Client::samSearchAll(const std::string& query, const std::map<std::string, std::string>& params)
+{
+     return search_->samSearchAll(query, params);
+}
+
 Response Client::sqlSearch(const std::string& collection_name, const std::string& sql,
                            const std::map<std::string, std::string>& params)
 {

src/search.cpp

@@ -99,6 +99,53 @@ Response Search::search(const std::string& collection_name, const std::map<std::
      return request_->execute("GET", path);
 }
 
+Response Search::samSearch(const std::string& collection_name, const std::string& query,
+                           const std::map<std::string, std::string>& params)
+{
+     utils::validateCollectionName(collection_name);
+
+     if (query.empty())
+     {
+          throw std::invalid_argument("SAM query must be a non-empty string");
+     }
+
+     std::map<std::string, std::string> query_params = params;
+     query_params["collection"] = collection_name;
+     query_params["q"] = query;
+
+     std::string path = "/sam/search";
+     std::string query_string = buildQueryString(query_params);
+
+     if (!query_string.empty())
+     {
+          path += "?" + query_string;
+     }
+
+     return request_->execute("GET", path);
+}
+
+Response Search::samSearchAll(const std::string& query, const std::map<std::string, std::string>& params)
+{
+     if (query.empty())
+     {
+          throw std::invalid_argument("SAM query must be a non-empty string");
+     }
+
+     std::map<std::string, std::string> query_params = params;
+     query_params["q"] = query;
+     query_params["all"] = "true";
+
+     std::string path = "/sam/search";
+     std::string query_string = buildQueryString(query_params);
+
+     if (!query_string.empty())
+     {
+          path += "?" + query_string;
+     }
+
+     return request_->execute("GET", path);
+}
+
 Response Search::sql(const std::string& collection_name, const std::string& sql,
                      const std::map<std::string, std::string>& params)
 {