smplkit Ruby SDK

Gem Version CI License: MIT

Official Ruby SDK for the smplkit platform — flags, config, and logging APIs with runtime evaluation, live updates, and management operations.

The Ruby SDK mirrors the Python SDK class-for-class. Ruby-specific deviations are documented in ADR-046.

Installation

gem install smplkit

Or in a Gemfile:

gem "smplkit"

Requires Ruby 3.3+.

Quick start

Runtime

require "smplkit"

Smplkit::Client.open(environment: "production", service: "my-svc") do |client|
  checkout_v2 = client.flags.boolean_flag("checkout-v2", default: false)
  client.wait_until_ready

  client.set_context([Smplkit::Context.new("user", "u-1", plan: "enterprise")]) do
    if checkout_v2.get
      # show new checkout
    end
  end
end

Management

manage = Smplkit::ManagementClient.new

flag = manage.flags.new_boolean_flag(
  "checkout-v2", default: false, description: "Controls rollout"
)
flag.add_rule(
  Smplkit::Rule.new("Enable for enterprise users", environment: "staging")
               .when("user.plan", Smplkit::Op::EQ, "enterprise")
               .serve(true)
)
flag.save

Configuration

Resolution order, lowest to highest priority:

  1. SDK hardcoded defaults
  2. ~/.smplkit config file (with [common] and profile sections)
  3. SMPLKIT_* environment variables
  4. Constructor arguments

See ADR-021 for details.

Logging adapters

Two adapters ship at launch (per ADR-046 §2.3):

Adapter Covers
stdlib-logger Ruby stdlib Logger (and Rails via ActiveSupport::Logger)
semantic-logger The semantic_logger gem

Both are auto-loaded by install when the corresponding framework is available. To support an additional framework, subclass Smplkit::Logging::Adapters::Base and implement the five contract methods (name, discover, apply_level, install_hook, uninstall_hook), then register before install:

client.logging.register_adapter(MyFrameworkAdapter.new)
client.logging.install

Calling register_adapter disables auto-loading — only the adapters you register are used.

Rails integration

Add the gem and run:

rails generate smplkit:install

This creates config/initializers/smplkit.rb with documented examples for the per-request context provider and standard configuration knobs.

Development

bundle install
bundle exec rspec        # unit tests — wrapper layer is held to 100% line coverage in CI
bundle exec rubocop      # lint
make generate            # regenerate clients

make generate shells out to npx --yes @openapitools/openapi-generator-cli, so it requires:

  • Node.js 18+ (provides npx)
  • A JRE 11+ (the openapi-generator JAR runs under Java)

Both are pre-installed on the CI matrix runners. On a developer machine, install via Homebrew (brew install node openjdk) or your distribution's package manager.

The repository follows the standard smplkit "every commit lands on main" workflow — see CLAUDE.md.

License

MIT — see LICENSE.