opensearch-sugar 1.0.0

data/lib/opensearch/sugar/models.rb

@@ -0,0 +1,209 @@
+module OpenSearch::Sugar
+  # Manages ML models deployed via the
+  # {https://opensearch.org/docs/latest/ml-commons-plugin/index/ OpenSearch ML Commons plugin}.
+  #
+  # Provides methods to register, deploy, list, and delete models, as well as to build
+  # text-embedding ingest pipelines that use a deployed model.
+  #
+  # Access an instance via {OpenSearch::Sugar::Client#models}:
+  #
+  # @example
+  #   models = client.models
+  #   model  = models.register(name: "all-MiniLM-L6-v2", version: "1.0.0")
+  #   puts model.id
+  class Models
+    # Struct representing a deployed ML model with +:name+, +:version+, and +:id+ members.
+    #
+    # @!attribute [r] name
+    #   @return [String] The model name
+    # @!attribute [r] version
+    #   @return [String] The model version string
+    # @!attribute [r] id
+    #   @return [String] The internal OpenSearch model ID (used in API calls)
+    ML_INFO = Struct.new(:name, :version, :id)
+
+    # @param os [OpenSearch::Sugar::Client] The client used for ML API calls
+    def initialize(os)
+      @os = os
+    end
+
+    # Registers and deploys an ML model via the ML Commons plugin.
+    #
+    # Idempotent — if a model matching +name+ is already registered, returns the
+    # existing {ML_INFO} without re-registering. Polls the task status every 5 seconds
+    # until deployment completes or fails.
+    #
+    # @param name [String] The model name (e.g. +"all-MiniLM-L6-v2"+)
+    # @param version [String] The model version (e.g. +"1.0.0"+)
+    # @param format [String] The model format (default: +"TORCH_SCRIPT"+)
+    # @return [ML_INFO, nil] The registered model info, or +nil+ if lookup fails after registration
+    # @raise [RuntimeError] If the registration task reports a +FAILED+ state
+    # @see https://opensearch.org/docs/latest/ml-commons-plugin/api/model-apis/register-model/ OpenSearch register model API
+    # @example
+    #   model = client.models.register(name: "all-MiniLM-L6-v2", version: "1.0.0")
+    #   puts model.id
+    def register(name:, version:, format: "TORCH_SCRIPT")
+      config = {
+        name: name,
+        version: version,
+        model_format: format
+      }
+
+      current = self[name]
+      return current if current
+
+      resp = @os.http.post("/_plugins/_ml/models/_register?deploy=true", body: config)
+      taskid = resp["task_id"]
+      loop do
+        model_install_response = @os.http.get("_plugins/_ml/tasks/#{taskid}")
+        break if model_install_response["state"] == "COMPLETED"
+        raise model_install_response["error"].to_s if model_install_response["state"] == "FAILED"
+        sleep(5)
+      end
+      self[name]
+    end
+
+    # Alias for {#register}.
+    # @see #register
+    alias_method :deploy, :register
+
+    # Get info about the latest version of a model by name, id, or partial name
+    # @todo make sure models are unique by nickname if nickname is found
+    # @param id_or_fullname_or_nickname [String] Exact model name, exact model ID, or
+    #   a case-insensitive partial name. When multiple partial matches exist, returns the
+    #   one with the highest version.
+    # @return [ML_INFO, nil] Matching model info, or +nil+ if not found
+    # @example Look up by exact name
+    #   model = client.models["all-MiniLM-L6-v2"]
+    # @example Look up by partial name
+    #   model = client.models["MiniLM"]
+    def [](id_or_fullname_or_nickname)
+      mlm = list
+      name = mlm.find { |x| x.name == id_or_fullname_or_nickname }
+      return name if name
+
+      id = mlm.find { |m| m.id == id_or_fullname_or_nickname }
+      return id if id
+
+      nickname_pattern = Regexp.new(id_or_fullname_or_nickname, "i")
+      nicks = mlm.find_all { |m| nickname_pattern.match(m.name) }.sort { |a, b| b.version <=> a.version }
+      nicks.first # could be nil
+    end
+
+    # Returns all deployed ML models in the cluster.
+    #
+    # @return [Array<ML_INFO>] Unique name/version/id triples for all deployed models
+    # @example
+    #   client.models.list.each { |m| puts "#{m.name} #{m.version} (#{m.id})" }
+    def list
+      lst = raw_list.dig("hits", "hits").map { |x| x["_source"] }.each_with_object([]) do |ml, a|
+        model = ML_INFO.new(ml["name"], ml["model_version"], ml["model_id"])
+        a << model
+      end
+      lst.uniq
+    end
+
+    # Returns the raw OpenSearch response from the ML models search endpoint.
+    #
+    # This is the unprocessed response from +/_plugins/_ml/models/_search+, filtered
+    # to chunk 0 to avoid returning embedding chunks. Prefer {#list} or {#[]} for
+    # normal usage.
+    #
+    # @return [Hash] Raw OpenSearch search response
+    def raw_list
+      @os.http.get("/_plugins/_ml/models/_search",
+        body: {"query" => {"term" => {"chunk_number" => 0}}})
+    end
+
+    # Undeploys (unloads from memory) a model without deleting its registration.
+    #
+    # @param name_or_id [String] Model name, ID, or partial name accepted by {#[]}
+    # @return [Hash] The OpenSearch undeploy response
+    # @raise [NoMethodError] If no model matching +name_or_id+ is found
+    # @example
+    #   client.models.undeploy!("all-MiniLM-L6-v2")
+    def undeploy!(name_or_id)
+      m = self[name_or_id]
+      @os.http.post("/_plugins/_ml/models/#{m.id}/_undeploy")
+    end
+
+    # Undeploys and permanently deletes a model from the cluster.
+    #
+    # @param name_or_id [String] Model name, ID, or partial name accepted by {#[]}
+    # @return [Hash] The OpenSearch delete response
+    # @raise [NoMethodError] If no model matching +name_or_id+ is found
+    # @example
+    #   client.models.delete!("all-MiniLM-L6-v2")
+    def delete!(name_or_id)
+      m = self[name_or_id]
+      undeploy!(m.id)
+      @os.http.delete("/_plugins/_ml/models/#{m.id}")
+    end
+
+    # Deletes an ingest pipeline by name.
+    #
+    # @param pipeline_name [String] The name of the pipeline to delete
+    # @return [Hash] The OpenSearch acknowledgement response
+    # @example
+    #   client.models.delete_pipeline!("my-embedding-pipeline")
+    def delete_pipeline!(pipeline_name)
+      @os.ingest.delete_pipeline(id: pipeline_name)
+    end
+
+    # Creates a text-embedding ingest pipeline backed by a deployed ML model.
+    #
+    # The pipeline uses the ML Commons +text_embedding+ processor to generate embeddings
+    # for each field in +field_map+. Because +text_embedding+ writes to a temporary field,
+    # the pipeline also inserts +copy+ processors to move the resulting +.knn+ vectors to
+    # the intended target fields.
+    #
+    # @param name [String] The name to give the ingest pipeline
+    # @param model [String] Model name, ID, or partial name accepted by {#[]}
+    # @param description [String] Human-readable description of the pipeline
+    # @param field_map [Hash{String => String}] Mapping of source text fields to target
+    #   vector fields (e.g. +{ "title" => "title_embedding" }+)
+    # @return [Hash] The OpenSearch response
+    # @raise [RuntimeError] If no model matching +model+ is found
+    # @see https://opensearch.org/docs/latest/ml-commons-plugin/semantic-search/ OpenSearch semantic search docs
+    # @example
+    #   client.models.create_pipeline(
+    #     name: "product-embeddings",
+    #     model: "all-MiniLM-L6-v2",
+    #     description: "Generate embeddings for product titles",
+    #     field_map: { "title" => "title_knn" }
+    #   )
+    def create_pipeline(name:, model:, description:, field_map:)
+      m = self[model]
+      raise "Can't find model #{model}" unless m
+      url = "/_ingest/pipeline/#{name.gsub(/\s+/, " ").gsub(/\s+/, "_")}"
+      field_map_to_temp = field_map.transform_values { |actual_target| "#{actual_target}_temp" }
+      temp_to_field_map = field_map.values.each_with_object({}) do |actual_target, h|
+        h["#{actual_target}_temp"] = actual_target
+      end
+
+      payload = {
+        description: description,
+        processors: [
+          {
+            text_embedding: {
+              model_id: m.id,
+              field_map: field_map_to_temp
+            }
+          }
+        ]
+      }
+
+      temp_to_field_map.each_pair do |tmp, real|
+        payload[:processors] << {
+          copy: {
+            source_field: "#{tmp}.knn",
+            target_field: real,
+            ignore_missing: true,
+            remove_source: true
+          }
+        }
+      end
+      @os.http.put(url, body: payload)
+    end
+  end
+end

data/lib/opensearch/sugar/version.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module OpenSearch
+  module Sugar
+    # Current gem version.
+    VERSION = "1.0.0"
+  end
+end

data/lib/opensearch/sugar.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module OpenSearch
+  module Sugar
+  end
+end
+
+require "opensearch"
+
+require_relative "sugar/version"
+require_relative "sugar/index"
+require_relative "sugar/client"
+
+module OpenSearch
+  # Top-level namespace for the opensearch-sugar gem.
+  #
+  # Provides a thin, object-oriented wrapper around the {https://github.com/opensearch-project/opensearch-ruby opensearch-ruby}
+  # client. The main entry point is {OpenSearch::Sugar.client}, which returns a
+  # fully configured {OpenSearch::Sugar::Client}.
+  #
+  # @see OpenSearch::Sugar::Client
+  # @see OpenSearch::Sugar::Index
+  # @see OpenSearch::Sugar::Models
+  module Sugar
+    # Base error class for all opensearch-sugar exceptions.
+    #
+    # Raised when operations such as settings or mappings updates fail.
+    # Rescuing this class catches all gem-specific errors without catching
+    # unrelated OpenSearch transport-layer exceptions.
+    #
+    # @example
+    #   begin
+    #     client.update_settings(bad_settings, "my_index")
+    #   rescue OpenSearch::Sugar::Error => e
+    #     puts "Settings update failed: #{e.message}"
+    #   end
+    class Error < StandardError; end
+
+    # Convenience factory that returns a new {OpenSearch::Sugar::Client}.
+    #
+    # Accepts the same keyword arguments as {OpenSearch::Sugar::Client#initialize}.
+    #
+    # @param kwargs [Hash] Keyword arguments forwarded to {OpenSearch::Sugar::Client#initialize}
+    # @return [OpenSearch::Sugar::Client]
+    # @example
+    #   client = OpenSearch::Sugar.client(host: "https://localhost:9200")
+    def self.client(**kwargs)
+      OpenSearch::Sugar::Client.new(**kwargs)
+    end
+
+    # Alias for {.client}. Allows idiomatic +OpenSearch::Sugar.new(...)+ construction.
+    #
+    # @param kwargs [Hash] Keyword arguments forwarded to {OpenSearch::Sugar::Client#initialize}
+    # @return [OpenSearch::Sugar::Client]
+    # @example
+    #   client = OpenSearch::Sugar.new
+    def self.new(**kwargs)
+      client(**kwargs)
+    end
+  end
+end

data/old_docs/DELEGATED_METHODS_ANALYSIS.md

@@ -0,0 +1,361 @@
+# Delegated Method Calls in HOWTO.md
+
+*(Documentation written by GitHub Copilot, powered by Claude Sonnet 4.5)*
+
+This document identifies all method calls in HOWTO.md that rely on delegation to the underlying `OpenSearch::Client` rather than using OpenSearch::Sugar's own implemented methods.
+
+## OpenSearch::Sugar Implemented Methods
+
+### Client Methods (OpenSearch::Sugar::Client)
+- `set_log_level(logger:, level:)`
+- `has_index?(name)`
+- `index_names`
+- `[](index_name)` - index accessor
+- `open_or_create(index_name)`
+- `update_settings(settings, index_name)`
+- `update_mappings(mappings, index_name)`
+- `models` - accessor for Models instance
+- `raw_client` - accessor for underlying client
+
+### Index Methods (OpenSearch::Sugar::Index)
+- `update_settings(settings)`
+- `settings`
+- `update_mappings(mappings)`
+- `mappings`
+- `delete!`
+- `count`
+- `aliases`
+- `create_alias(alias_name)`
+- `all_available_analyzers` / `analyzers`
+- `analyze_text(analyzer:, text:)`
+- `analyze_text_field(field:, text:)`
+- `delete_by_id(id)`
+- `clear!`
+
+---
+
+## Delegated Method Calls in HOWTO.md
+
+### Connection and Configuration Section
+
+**Line 94: `client.cluster.health`**
+```ruby
+response = client.cluster.health
+```
+- **Delegated to:** `OpenSearch::Client#cluster`
+- **OpenSearch API:** [Cluster Health API](https://opensearch.org/docs/latest/api-reference/cluster-api/cluster-health/)
+- **Purpose:** Get cluster health status
+
+---
+
+### Index Management Section
+
+**Line 175: `client.indices.delete(index: 'my_index')`**
+```ruby
+client.indices.delete(index: 'my_index')
+```
+- **Delegated to:** `OpenSearch::Client#indices.delete`
+- **OpenSearch API:** [Delete Index API](https://opensearch.org/docs/latest/api-reference/index-apis/delete-index/)
+- **Note:** Sugar alternative exists: `index.delete!`
+
+---
+
+### Document Operations Section
+
+**Line 196-203: `client.index(...)`**
+```ruby
+# Add with explicit ID
+client.index(
+  index: 'my_index',
+  id: 'doc123',
+  body: {
+    title: 'My Document',
+    content: 'Document content here'
+  }
+)
+
+# Add with auto-generated ID
+response = client.index(
+  index: 'my_index',
+  body: { title: 'My Document' }
+)
+```
+- **Delegated to:** `OpenSearch::Client#index`
+- **OpenSearch API:** [Index Document API](https://opensearch.org/docs/latest/api-reference/document-apis/index-document/)
+- **Purpose:** Index a single document
+
+**Line 220: `client.delete(index: 'my_index', id: 'doc123')`**
+```ruby
+client.delete(index: 'my_index', id: 'doc123')
+```
+- **Delegated to:** `OpenSearch::Client#delete`
+- **OpenSearch API:** [Delete Document API](https://opensearch.org/docs/latest/api-reference/document-apis/delete-document/)
+- **Note:** Sugar alternative exists: `index.delete_by_id('doc123')`
+
+**Line 237-242: `client.get(...)`**
+```ruby
+response = client.get(
+  index: 'my_index',
+  id: 'doc123'
+)
+
+document = response['_source']
+```
+- **Delegated to:** `OpenSearch::Client#get`
+- **OpenSearch API:** [Get Document API](https://opensearch.org/docs/latest/api-reference/document-apis/get-documents/)
+- **Purpose:** Retrieve a document by ID
+
+**Line 250-271: `client.update(...)`**
+```ruby
+# Partial update
+client.update(
+  index: 'my_index',
+  id: 'doc123',
+  body: {
+    doc: {
+      title: 'Updated Title'
+    }
+  }
+)
+
+# Full replacement
+client.index(
+  index: 'my_index',
+  id: 'doc123',
+  body: {
+    title: 'New Title',
+    content: 'New content'
+  }
+)
+```
+- **Delegated to:** `OpenSearch::Client#update`
+- **OpenSearch API:** [Update Document API](https://opensearch.org/docs/latest/api-reference/document-apis/update-document/)
+- **Purpose:** Update an existing document
+
+**Line 283: `client.bulk(body: operations)`**
+```ruby
+response = client.bulk(body: operations)
+```
+- **Delegated to:** `OpenSearch::Client#bulk`
+- **OpenSearch API:** [Bulk API](https://opensearch.org/docs/latest/api-reference/document-apis/bulk/)
+- **Purpose:** Perform multiple index/delete operations in a single request
+
+**Line 301-304: `client.indices.refresh(...)`**
+```ruby
+# Make documents immediately searchable
+client.indices.refresh(index: 'my_index')
+
+# Refresh all indexes
+client.indices.refresh
+```
+- **Delegated to:** `OpenSearch::Client#indices.refresh`
+- **OpenSearch API:** [Refresh API](https://opensearch.org/docs/latest/api-reference/index-apis/refresh/)
+- **Purpose:** Make recent changes searchable
+
+---
+
+### Search and Analysis Section
+
+**Line 320-334: `client.search(...)`**
+```ruby
+response = client.search(
+  index: 'my_index',
+  body: {
+    query: {
+      match: {
+        title: 'search terms'
+      }
+    }
+  }
+)
+
+hits = response['hits']['hits']
+```
+- **Delegated to:** `OpenSearch::Client#search`
+- **OpenSearch API:** [Search API](https://opensearch.org/docs/latest/api-reference/search/)
+- **Purpose:** Execute a search query
+
+**Line 391-406: `client.search(...)` with aggregations**
+```ruby
+response = client.search(
+  index: 'products',
+  body: {
+    size: 0,
+    aggs: {
+      categories: {
+        terms: {
+          field: 'category.keyword',
+          size: 10
+        }
+      }
+    }
+  }
+)
+```
+- **Delegated to:** `OpenSearch::Client#search`
+- **OpenSearch API:** [Search API with Aggregations](https://opensearch.org/docs/latest/aggregations/)
+- **Purpose:** Perform aggregations
+
+**Line 416-426: `client.search(...)` with multi_match**
+```ruby
+response = client.search(
+  index: 'my_index',
+  body: {
+    query: {
+      multi_match: {
+        query: 'search terms',
+        fields: ['title^3', 'description^2', 'content'],
+        type: 'best_fields'
+      }
+    }
+  }
+)
+```
+- **Delegated to:** `OpenSearch::Client#search`
+- **OpenSearch API:** [Multi-Match Query](https://opensearch.org/docs/latest/query-dsl/full-text/multi-match/)
+- **Purpose:** Search across multiple fields
+
+---
+
+### Aliases Section
+
+**Line 547-550: `client.indices.put_alias(...)`**
+```ruby
+client.indices.put_alias(
+  index: 'my_index',
+  name: 'my_alias'
+)
+```
+- **Delegated to:** `OpenSearch::Client#indices.put_alias`
+- **OpenSearch API:** [Create Alias API](https://opensearch.org/docs/latest/api-reference/alias/)
+- **Note:** Sugar alternative exists: `index.create_alias('my_alias')`
+
+**Line 564-567: `client.indices.delete_alias(...)`**
+```ruby
+client.indices.delete_alias(
+  index: 'my_index',
+  name: 'my_alias'
+)
+```
+- **Delegated to:** `OpenSearch::Client#indices.delete_alias`
+- **OpenSearch API:** [Delete Alias API](https://opensearch.org/docs/latest/api-reference/alias/)
+- **Purpose:** Remove an alias
+
+**Line 574-582: `client.indices.update_aliases(...)`**
+```ruby
+client.indices.update_aliases(
+  body: {
+    actions: [
+      { remove: { index: 'old_index', alias: 'my_alias' } },
+      { add: { index: 'new_index', alias: 'my_alias' } }
+    ]
+  }
+)
+```
+- **Delegated to:** `OpenSearch::Client#indices.update_aliases`
+- **OpenSearch API:** [Update Aliases API](https://opensearch.org/docs/latest/api-reference/alias/)
+- **Purpose:** Atomic alias operations (swap aliases)
+
+---
+
+### ML Models Section
+
+**Line 652-660: `client.index(...)` with pipeline**
+```ruby
+client.index(
+  index: 'my_index',
+  pipeline: 'text_embedding',
+  body: {
+    text: 'This is my document text',
+    title: 'Document Title'
+  }
+)
+```
+- **Delegated to:** `OpenSearch::Client#index`
+- **OpenSearch API:** [Index with Pipeline](https://opensearch.org/docs/latest/ingest-pipelines/)
+- **Purpose:** Index document using an ingest pipeline
+
+---
+
+### Error Handling Section
+
+**Line 722: `client.bulk(body: operations)`**
+```ruby
+response = client.bulk(body: operations)
+```
+- **Delegated to:** `OpenSearch::Client#bulk`
+- **OpenSearch API:** [Bulk API](https://opensearch.org/docs/latest/api-reference/document-apis/bulk/)
+- **Purpose:** Bulk operations error handling example
+
+**Line 769-774: `client.index(...)` in retry example**
+```ruby
+client.index(
+  index: 'my_index',
+  id: 'doc123',
+  body: { title: 'My Document' }
+)
+```
+- **Delegated to:** `OpenSearch::Client#index`
+- **OpenSearch API:** [Index Document API](https://opensearch.org/docs/latest/api-reference/document-apis/index-document/)
+- **Purpose:** Retry pattern example
+
+---
+
+## Summary Statistics
+
+### Total Delegated Method Calls: 19 unique examples
+
+### Breakdown by Category:
+- **Connection & Configuration:** 1
+- **Index Management:** 1
+- **Document Operations:** 7
+- **Search & Analysis:** 3
+- **Aliases:** 3
+- **ML Models:** 1
+- **Error Handling:** 2 (duplicates of above)
+
+### Most Common Delegated Methods:
+1. `client.index(...)` - 5 occurrences (indexing documents)
+2. `client.search(...)` - 3 occurrences (searching)
+3. `client.bulk(...)` - 2 occurrences (bulk operations)
+4. `client.indices.*` - 6 occurrences (various index operations)
+5. `client.cluster.*` - 1 occurrence (cluster health)
+6. `client.get(...)` - 1 occurrence (get document)
+7. `client.update(...)` - 1 occurrence (update document)
+8. `client.delete(...)` - 1 occurrence (delete document)
+
+### Methods with Sugar Alternatives Available:
+- `client.indices.delete(index: 'my_index')` → `index.delete!`
+- `client.delete(index: 'my_index', id: 'doc123')` → `index.delete_by_id('doc123')`
+- `client.indices.put_alias(...)` → `index.create_alias('my_alias')`
+
+### Methods Without Sugar Alternatives (Must Use Delegation):
+- `client.index(...)` - Document indexing
+- `client.get(...)` - Get document by ID
+- `client.update(...)` - Update document
+- `client.search(...)` - Search queries
+- `client.bulk(...)` - Bulk operations
+- `client.indices.refresh(...)` - Refresh index
+- `client.indices.delete_alias(...)` - Delete alias
+- `client.indices.update_aliases(...)` - Atomic alias updates
+- `client.cluster.health` - Cluster health
+
+---
+
+## Recommendation
+
+The documentation correctly demonstrates the delegation pattern by showing:
+1. **When Sugar methods exist** - it generally uses them (like `index.count`, `index.delete!`, `index.create_alias`)
+2. **When Sugar methods don't exist** - it demonstrates delegation (like `client.search`, `client.index`, `client.bulk`)
+3. **Both options when available** - showing users they have choices
+
+This aligns with OpenSearch::Sugar's design philosophy: "Use sugar where you want it, raw client where you need it."
+
+The documentation could be improved by adding a note in each delegated example indicating:
+```ruby
+# Using delegation - OpenSearch::Sugar::Client forwards this to OpenSearch::Client
+client.search(...)
+```
+
+This would make it clearer to users which methods are delegated vs. implemented.
+