opensearch-sugar 1.0.0

data/README.md

@@ -0,0 +1,143 @@
+# opensearch-sugar
+
+[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.1.0-ruby.svg)](https://www.ruby-lang.org/)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+A Ruby gem that wraps the [opensearch-ruby](https://github.com/opensearch-project/opensearch-ruby)
+client with an object-oriented shell -- collections (indexes), documents, ML models, etc --
+instead of having everything runn straight off the client. I find it an easier way
+to think about and code interactions with OpenSearch.
+
+The gem was a finished product before I had access to LLMs. All the _original_ code
+is hand-crafted like a Seattle beer, but a variety of improvements and much
+of the documentation (and rbs) is AI-generated. 
+
+Of course, AI may have negated the need for nice interfaces and 
+human-centered program design. So...YMMV in terms of usefulness. 
+
+
+## Quick example
+
+```ruby
+require "opensearch/sugar"
+
+client = OpenSearch::Sugar::Client.new   # Pass credentials, or default uses ENV variables
+
+index = client.open_or_create_index("products")
+
+index.update_mappings(
+  mappings: {
+    properties: {
+      title:    { type: "text" },
+      category: { type: "keyword" },
+      price:    { type: "float" }
+    }
+  }
+)
+
+index.index_document({ title: "Dune", category: "fiction", price: 12.99 }, "isbn-0441013597")
+index.refresh   # make the document immediately searchable
+
+results = client.search(
+  index: "products",
+  body: { query: { match: { title: "dune" } } }
+)
+puts results["hits"]["hits"].first.dig("_source", "title")
+#=> "Dune"
+```
+
+The underlying Client object is attatched to every object created through the API,
+and is a paper-thin shell on a client from the official ruby gem.
+
+See the AI-written [Tutorial](docs/TUTORIAL.md) for a full walkthrough.
+
+## Installation
+
+```ruby
+# Gemfile
+gem "opensearch-sugar"
+```
+
+```bash
+bundle install
+```
+
+## Configuration
+
+Connection details are read from environment variables:
+
+| Variable | Used for | Default |
+|----------|----------|---------|
+| `OPENSEARCH_URL` | Cluster URL | `https://localhost:9000` |
+| `OPENSEARCH_HOST` | Cluster URL (lower priority) | — |
+| `OPENSEARCH_USER` | Basic auth user | `"admin"` |
+| `OPENSEARCH_PASSWORD` | Basic auth password | — |
+| `OPENSEARCH_INITIAL_ADMIN_PASSWORD` | Basic auth password (lower priority) | — |
+
+Any keyword argument accepted by `OpenSearch::Client.new` can be passed to
+`OpenSearch::Sugar::Client.new` and will override the defaults.
+
+## Documentation
+
+Provided by various AI models, although I've done some editing. Those things are faily good at this, even though
+they don't so much have a unique voice (or, rather, they all have the same unique voice)
+
+- **[Tutorial](docs/TUTORIAL.md)** — step-by-step walkthrough building a searchable book catalog from scratch
+- **[How-to Guides](docs/HOWTO.md)** — practical recipes for connection options, document CRUD, search, aliases, ML models, error handling, and more
+- **[API Reference](docs/REFERENCE.md)** — complete method reference for `Client`, `Index`, and `Models`
+
+## Tests and development
+
+I'v never seen the point of writing unit tests for this sort of thing. I mean, a few, but anything
+that interacts with a server and needs to verify that The Right Thing Happened benefits from
+talking to the real thing. Plus I don't have to maintain the mocks. Something like
+[VCR](https://github.com/vcr/vcr) is appealing; maybe soon.
+
+### To run the tests:
+
+
+Start a local OpenSearch cluster:
+
+```bash
+docker compose up -d
+```
+
+OpenSearch takes ~30 seconds to be ready. Wait until the following command succeeds
+before running the test suite:
+
+```bash
+❯ curl -sk https://localhost:29200 -u 'admin:Dw2F%3E*!m&psx64' | grep -q tagline && echo "Ready"
+```
+
+Run the specs:
+
+```bash
+bundle exec rspec
+```
+
+To generate a coverage report:
+
+```bash
+bundle exec rake coverage
+```
+
+or:
+
+```bash
+COVERAGE=true bundle exec rspec
+```
+
+Coverage reports are written to `coverage/index.html`.
+
+To see full HTTP request/response logs during a run:
+
+```bash
+OPENSEARCH_LOG=true bundle exec rspec
+```
+
+### Contributing
+
+Bug reports and pull requests are welcome at
+<https://github.com/mlibrary/opensearch-sugar>. Please open an issue before
+submitting large changes.
+

data/Rakefile

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "yard"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "standard/rake"
+
+YARD::Rake::YardocTask.new(:yard) do |t|
+  t.files = ["lib/**/*.rb"]
+  t.options = ["--output-dir", "doc/", "--markup", "markdown"]
+end
+
+desc "Run Steep type checker"
+task :steep do
+  sh "bundle exec steep check"
+end
+
+desc "Run specs with coverage report"
+task :coverage do
+  ENV["COVERAGE"] = "true"
+  Rake::Task["spec"].invoke
+end
+
+task default: %i[spec standard]

data/Steepfile

@@ -0,0 +1,23 @@
+D = Steep::Diagnostic
+
+target :lib do
+  signature "sig"
+
+  check "lib"
+
+  library "logger"
+  library "delegate"
+  library "json"
+
+  configure_code_diagnostics(D::Ruby.default) do |hash|
+    # OpenSearch::Sugar::Client extends SimpleDelegator; delegated methods (e.g. `indices`,
+    # `cluster`) are resolved dynamically at runtime and cannot be statically typed.
+    hash[D::Ruby::NoMethod] = :information
+
+    # opensearch-ruby and other third-party gems ship no RBS; suppress noise from
+    # unresolvable constants and untyped collection literals that arise at their boundaries.
+    hash[D::Ruby::UnknownConstant] = :information
+    hash[D::Ruby::UnannotatedEmptyCollection] = :information
+    hash[D::Ruby::ArgumentTypeMismatch] = :information
+  end
+end

data/adrs/ADR-000-template.md

@@ -0,0 +1,87 @@
+# ADR-NNN: Title
+
+## Status
+
+<!-- One of: Proposed | Accepted | Deprecated | Superseded by [ADR-NNN](ADR-NNN-title.md) -->
+
+## Date
+
+YYYY-MM-DD
+
+## Context
+
+<!--
+Describe the problem, the forces at play, and the background needed to understand
+the decision. Include:
+  - What situation requires a decision
+  - Prior art or existing approaches (e.g., how a reference implementation handles this)
+  - Constraints imposed by earlier decisions
+  - Options that were on the table (summarized here; detailed in Alternatives Considered)
+
+This section answers: "Why are we making a decision at all?"
+-->
+
+## Decision
+
+<!--
+State the decision clearly and unambiguously. Use present tense ("We use...", not
+"We will use..." or "We used...").
+
+Include code samples (real Kotlin or clearly-marked pseudocode) demonstrating the
+chosen approach at the API level. Samples should show both the definition and the
+call site where relevant.
+-->
+
+## Consequences
+
+### Positive
+
+<!-- Benefits, improvements, and capabilities unlocked by this decision. -->
+
+### Negative
+
+<!-- Costs, limitations, and risks introduced. Be honest. -->
+
+### Neutral
+
+<!-- Things that are neither good nor bad but worth recording — behavioral changes,
+     constraints on future decisions, things that may surprise readers, etc. -->
+
+## Alternatives Considered
+
+<!--
+For each rejected alternative:
+  - Name or brief description
+  - Why it was rejected
+
+If the Context section already covers alternatives in sufficient detail, this
+section may be omitted.
+-->
+
+## Diagram
+
+<!--
+Optional. Include a Mermaid diagram when the decision has a structural, flow, or
+sequence component worth visualizing. Use flowchart, sequenceDiagram, or classDiagram
+as appropriate.
+
+```mermaid
+flowchart LR
+    A --> B
+```
+-->
+
+## Open Questions
+
+<!--
+Optional. Deferred sub-decisions that follow directly from this decision but are
+not yet settled. Each item should reference the constraint or choice that makes
+it dependent on future work.
+-->
+
+## Documentation Requirements
+
+<!--
+Optional. Explicit callouts for what must be documented in the public API,
+README, or contributor guide as a direct result of this decision.
+-->

data/adrs/ADR-001-simpledelegator-for-client.md

@@ -0,0 +1,138 @@
+# ADR-001: Use SimpleDelegator to Wrap OpenSearch::Client
+
+## Status
+
+Accepted
+
+## Date
+
+2026-04-28
+
+## Context
+
+`OpenSearch::Sugar::Client` needs to provide convenient, higher-level methods (e.g., `has_index?`,
+`open_or_create_index`, index management helpers) while also giving callers access to the full
+`OpenSearch::Client` API. The OpenSearch Ruby client exposes a large, versioned surface area —
+cluster operations, document APIs, index APIs, ML Commons, and more — that would be impractical
+to wrap exhaustively and expensive to keep in sync as the upstream client evolves.
+
+Options considered:
+
+- **Inheritance** — subclass `OpenSearch::Client` directly
+- **Manual delegation** — write `def_delegator` calls for every method needed
+- **`SimpleDelegator` (Forwardable)** — wrap the client via Ruby's built-in delegation mechanism
+- **Composition with `method_missing`** — forward unknown calls via `method_missing`/`respond_to_missing?`
+
+## Decision
+
+We use `SimpleDelegator` from Ruby's standard library to wrap an `OpenSearch::Client` instance.
+`Client` inherits from `SimpleDelegator`, calls `__setobj__` with the raw client at initialization,
+and adds Sugar methods on top.
+
+```ruby
+class OpenSearch::Sugar::Client < SimpleDelegator
+  def initialize(**kwargs)
+    @raw_client = OpenSearch::Client.new(**kwargs)
+    super(@raw_client)
+  end
+
+  # Sugar methods
+  def has_index?(name)
+    indices.exists?(index: name)
+  end
+
+  def open_or_create_index(name, ...)
+    # ...
+  end
+end
+
+# Call site — Sugar method
+client.has_index?("my_index")
+
+# Call site — delegated to raw OpenSearch::Client transparently
+client.search(index: "my_index", body: { query: { match_all: {} } })
+client.cluster.health
+client.bulk(body: operations)
+```
+
+The raw client remains accessible via `__getobj__` (or an explicit `raw_client` accessor) when
+callers need it explicitly.
+
+## Consequences
+
+### Positive
+
+- **Zero maintenance burden for the full API**: every current and future `OpenSearch::Client`
+  method is automatically available without any wrapper code.
+- **No abstraction trap**: callers are never forced to find a Sugar equivalent; they can drop
+  through to the raw client at any time.
+- **Official documentation applies directly**: users can read opensearch-ruby docs and apply
+  them without translation.
+- **Transparent migration**: code already written against `OpenSearch::Client` works without
+  modification when the object is a `Sugar::Client`.
+
+### Negative
+
+- **`is_a?` / `instance_of?` surprises**: `SimpleDelegator` instances do not report as instances
+  of the wrapped class. Callers relying on `client.is_a?(OpenSearch::Client)` will get `false`.
+- **Method resolution ambiguity**: if Sugar adds a method with the same name as a raw-client
+  method, the Sugar method wins silently. This requires discipline when naming Sugar helpers.
+- **`SimpleDelegator` is less common than plain composition**: contributors unfamiliar with
+  Ruby's delegator classes may find the inheritance unusual.
+
+### Neutral
+
+- `__getobj__` / `__setobj__` are available for testing and introspection but are not part of
+  the public Sugar API.
+- Adding Sugar methods that conflict with upstream client methods is a breaking change; names
+  must be chosen carefully.
+
+## Alternatives Considered
+
+**Inheritance from `OpenSearch::Client`**
+Rejected because `OpenSearch::Client` is not designed for subclassing; its initializer and
+internal wiring make safe subclassing fragile and likely to break across upstream releases.
+
+**Manual delegation with `Forwardable`**
+Rejected because it requires enumerating every method to forward. Any new method added to the
+upstream client would be invisible until manually added here — exactly the maintenance trap we
+want to avoid.
+
+**`method_missing` / `respond_to_missing?`**
+Rejected because `SimpleDelegator` already implements this pattern correctly and is battle-tested
+in Ruby's standard library. Rolling our own would duplicate that work with higher risk.
+
+## Diagram
+
+```mermaid
+classDiagram
+    class SimpleDelegator {
+        +__getobj__()
+        +__setobj__(obj)
+    }
+    class `OpenSearch::Sugar::Client` {
+        -@raw_client : OpenSearch::Client
+        +has_index?(name) bool
+        +open_or_create_index(name) Index
+        +index_names() Array
+        +models() Models
+    }
+    class `OpenSearch::Client` {
+        +indices IndicesNamespace
+        +cluster ClusterNamespace
+        +search(...) Hash
+        +bulk(...) Hash
+        +index(...) Hash
+    }
+
+    SimpleDelegator <|-- `OpenSearch::Sugar::Client`
+    `OpenSearch::Sugar::Client` --> `OpenSearch::Client` : wraps via __setobj__
+```
+
+## Documentation Requirements
+
+- The public README and HOWTO must explain that `Sugar::Client` exposes the full
+  `OpenSearch::Client` API via delegation, and show side-by-side examples of Sugar methods
+  vs. delegated calls.
+- The EXPLANATION doc should describe the `SimpleDelegator` pattern and its implications for
+  `is_a?` checks.

data/adrs/ADR-002-facade-pattern-for-index.md

@@ -0,0 +1,126 @@
+# ADR-002: Facade Pattern for OpenSearch::Sugar::Index
+
+## Status
+
+Accepted
+
+## Date
+
+2026-04-28
+
+## Context
+
+Several OpenSearch index operations require multiple coordinated API calls to complete safely.
+The clearest example is updating certain index settings (e.g., analyzer configuration): OpenSearch
+requires the index to be closed before applying the settings and then reopened afterward. If any
+step fails partway through, the index can be left in an inconsistent state.
+
+Other examples of multi-step sequences include:
+
+- Applying settings or mappings that require a close/reopen cycle
+- Introspecting settings or mappings (requires knowing which sub-keys to traverse)
+- Managing aliases (creating, listing)
+- Text analysis testing (`analyze` API)
+
+Without a wrapper, callers must remember and correctly sequence every step every time. This is
+error-prone and produces repeated, scattered boilerplate across application code.
+
+Options considered:
+
+- **Expose raw client methods only** — callers assemble sequences themselves
+- **Module of helper functions** — stateless utility methods that accept an index name
+- **`Index` class as a Facade** — an object that encapsulates the index name, holds a client
+  reference, and exposes single-method operations for each multi-step sequence
+
+## Decision
+
+`OpenSearch::Sugar::Index` acts as a Facade over the raw index APIs. It holds the index name
+and a reference to the `Sugar::Client`, and exposes single-method operations that internally
+perform all necessary steps with consistent error handling.
+
+```ruby
+# Behind the scenes: close → put_settings → open
+index.update_settings(
+  settings: {
+    analysis: { analyzer: { my_analyzer: { type: "standard" } } }
+  }
+)
+
+# Behind the scenes: get_settings, traverse nested keys, return clean hash
+index.settings
+
+# Behind the scenes: close → open (if index exists); create (if not)
+index = client.open_or_create_index("my_index")
+
+# Single call for text analysis
+tokens = index.test_analyzer_by_name(analyzer: "my_analyzer", text: "Hello World")
+```
+
+Each method handles errors uniformly and raises `OpenSearch::Sugar::Error` (or a subclass) on
+failure, rather than leaking raw transport exceptions from intermediate steps.
+
+## Consequences
+
+### Positive
+
+- **Error-prone sequences become single calls**: callers cannot accidentally omit a step or
+  leave an index closed after a settings update.
+- **Consistent error handling**: all multi-step operations funnel through the same error
+  boundary; callers handle one exception type.
+- **Encapsulation**: the index name is carried by the object, eliminating repetitive
+  `index: name` keyword arguments scattered throughout call sites.
+- **Easier to test**: sequence logic is isolated in one class, making it straightforward to
+  verify the correct sequence is called.
+
+### Negative
+
+- **Increased abstraction**: callers working with the raw client directly may find it confusing
+  that `Index` and `Client` both offer some overlapping capabilities (e.g., `update_settings`
+  exists on both, with `Index#update_settings` being the preferred single-object entry point).
+- **Performance transparency**: the automatic close/reopen cycle for settings updates is hidden
+  from callers. A caller unaware of this could be surprised by the two extra API calls and the
+  brief unavailability of the index.
+
+### Neutral
+
+- `Index` objects are lightweight value-like wrappers; they do not cache state from OpenSearch
+  and always fetch fresh data on each call.
+- The Facade does not prevent callers from accessing the raw client via `index.client` (or
+  through the delegated `Sugar::Client`) when they need finer control.
+
+## Alternatives Considered
+
+**Raw client methods only**
+Rejected because it pushes multi-step orchestration into every call site. The close/reopen
+sequence for settings updates is particularly easy to get wrong (e.g., forgetting to reopen
+after a failure).
+
+**Module of stateless helper functions**
+Rejected because it requires passing the index name (and client) on every call, which is
+repetitive. It also makes it harder to build a coherent, discoverable API — callers would
+need to know which helpers to compose for each task.
+
+## Diagram
+
+```mermaid
+sequenceDiagram
+    participant Caller
+    participant Index as Sugar::Index
+    participant OS as OpenSearch::Client
+
+    Caller->>Index: update_settings(settings)
+    Index->>OS: indices.close(index: name)
+    OS-->>Index: ok
+    Index->>OS: indices.put_settings(index: name, body: settings)
+    OS-->>Index: ok
+    Index->>OS: indices.open(index: name)
+    OS-->>Index: ok
+    Index-->>Caller: (returns)
+```
+
+## Documentation Requirements
+
+- HOWTO must note that `update_settings` for analyzer-related settings automatically performs
+  the close/reopen cycle and that the index is briefly unavailable during the operation.
+- EXPLANATION should describe the Facade pattern and explain why certain operations require
+  closing the index.

data/adrs/ADR-003-repository-pattern-for-models.md

@@ -0,0 +1,148 @@
+# ADR-003: Repository Pattern for OpenSearch::Sugar::Models
+
+## Status
+
+Accepted
+
+## Date
+
+2026-04-28
+
+## Context
+
+OpenSearch ML Commons stores models with internal IDs that are opaque UUIDs assigned at
+registration time. Callers typically know a model by its human-readable name or a short
+nickname, not its UUID. Retrieving, deploying, and deleting a model through the raw client
+requires:
+
+1. Listing all models (paginated)
+2. Scanning results to match by name or ID
+3. Using the resolved UUID in subsequent calls
+
+This lookup-then-act sequence must be repeated at every call site that needs to work with a
+model by name. Additionally, the ML model lifecycle has strict ordering requirements:
+
+- A model must be registered and fully deployed before it can be used
+- A model must be undeployed before it can be deleted
+
+Without a dedicated abstraction, callers are responsible for both the lookup logic and the
+lifecycle sequencing — producing fragile, repetitive code.
+
+Options considered:
+
+- **Raw client calls at each call site** — callers handle lookup and lifecycle themselves
+- **Module of helper functions** — stateless helpers that accept a client and model identifier
+- **`Models` class as a Repository** — an object bound to a client that treats ML models as
+  first-class resources and unifies lookup, lifecycle management, and pipeline construction
+
+## Decision
+
+`OpenSearch::Sugar::Models` implements the Repository pattern. It is accessed via
+`client.models` and provides a unified interface for all ML model operations. Lookup accepts
+a name, UUID, or partial name match via `[]`:
+
+```ruby
+models = client.models
+
+# Register and wait for deployment (blocks until deployed)
+model = models.register(
+  name: "huggingface/sentence-transformers/all-MiniLM-L12-v2",
+  version: "1.0.1"
+)
+
+# Look up by name, UUID, or partial match
+model = models["all-MiniLM-L12-v2"]
+model = models["3a4b5c6d-..."]   # UUID
+
+# List all registered models
+all_models = models.list
+
+# Delete safely (undeploys first)
+models.delete!(model)
+
+# Build an ingest pipeline for embeddings
+models.create_pipeline(
+  name: "embedding_pipeline",
+  model: model.name,
+  field_map: { "text" => "text_embedding" }
+)
+```
+
+The `Models` class hides the paginated list API, name/ID resolution, and the undeploy-before-delete
+requirement behind these single-purpose methods.
+
+## Consequences
+
+### Positive
+
+- **Unified lookup**: callers do not need to know whether they have a name or UUID; `[]` resolves
+  either, hiding the paginated scan.
+- **Lifecycle safety**: `delete!` always undeploys before deleting; callers cannot accidentally
+  delete a deployed model and produce an error.
+- **`register` blocks until deployed**: removes the need for callers to poll deployment status
+  themselves.
+- **Discoverable API**: all model operations are co-located on one object, making the surface
+  easy to explore.
+
+### Negative
+
+- **Blocking `register`**: waiting synchronously for model deployment may be unacceptable in
+  latency-sensitive contexts (e.g., a web request). Callers in those contexts must run
+  registration in a background job.
+- **Partial-match ambiguity**: `[]` with a partial name string will match the first result;
+  if multiple models share a partial name, the result is non-deterministic. Callers must use
+  sufficiently specific identifiers.
+- **Pagination hidden**: `list` returns all models by iterating pages internally. For clusters
+  with very large model catalogs this could be slow; there is no lazy/streaming alternative.
+
+### Neutral
+
+- `Models` does not cache; each `list` call hits OpenSearch. Callers that need repeated
+  lookups in a tight loop should retrieve and store the model object themselves.
+- The pipeline construction method (`create_pipeline`) is included here because pipelines are
+  tightly coupled to a specific model ID. This is a design convenience, not a strict Repository
+  concern.
+
+## Alternatives Considered
+
+**Raw client calls at each call site**
+Rejected because the paginated lookup and lifecycle sequencing would be duplicated everywhere
+models are used. The undeploy-before-delete requirement is easy to forget and results in
+confusing OpenSearch errors.
+
+**Module of stateless helper functions**
+Rejected for the same reasons as in ADR-002: requires passing the client on every call,
+produces a flat, less discoverable API, and makes it harder to enforce invariants like
+blocking until deployment is complete.
+
+## Diagram
+
+```mermaid
+sequenceDiagram
+    participant Caller
+    participant Models as Sugar::Models
+    participant OS as OpenSearch ML Commons
+
+    Caller->>Models: register(name:, version:)
+    Models->>OS: ml.register_model(...)
+    OS-->>Models: task_id
+    loop Poll until deployed
+        Models->>OS: ml.get_task(task_id)
+        OS-->>Models: status
+    end
+    Models-->>Caller: Model object
+
+    Caller->>Models: delete!(model)
+    Models->>OS: ml.undeploy_model(model_id)
+    OS-->>Models: ok
+    Models->>OS: ml.delete_model(model_id)
+    OS-->>Models: ok
+    Models-->>Caller: (returns)
+```
+
+## Documentation Requirements
+
+- HOWTO must warn that `register` blocks and is not appropriate for use in a hot path.
+- HOWTO must document the partial-match behavior of `[]` and recommend using explicit names
+  or UUIDs where uniqueness matters.
+- REFERENCE must document the `Models` public API with parameter types and return values.