marginfuse 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6594a128c2a5670e8eef2c8da7e21a96c305c3e13f66d4262889169c95df5a8a
+  data.tar.gz: 96e931bd8cf686b799f306483043c965f81f683eba6d377ce3d5d4bd18d2297e
+SHA512:
+  metadata.gz: 139be111ee7a9d54f9c93fd4b2a00712c27c7c2a8ddf0407a7806cd05a43c230dd1714be49654b053cdf3b4db756503f1516ccb42a9f54b859b63acf6924b9c2
+  data.tar.gz: 45f3c6d52858f692f327c7be010b7a082d7ee457f027c028c7d1cec7d8128eea825600d3d40b0e1fe0f5ef3065a8c9bdea2e648f2fc8f7f7ce4730e9fb0700c4

data/CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project
+follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0]
+
+First release. Ruby 3.2+, zero dependencies, standard library only.
+
+### Added
+
+- `MarginFuse::Client#track` reports an AI call that already happened. Returns
+  immediately, sends on a background thread with retries, and never raises into
+  application code.
+- `MarginFuse::Client#decide` asks whether the next call should run. Fails open
+  to `:allow` with `degraded?` true on any timeout or error.
+- `MarginFuse::Client#guard` does the whole loop: ask, yield the decision, report
+  the real cost, acknowledge what the application did.
+- `MarginFuse::Client#flush`, for jobs and scripts that would otherwise exit
+  before their last events are sent.
+- `MarginFuse::OpenRouter.from` maps an OpenRouter usage object, including the
+  gateway's own cost, so gateway figures are exact rather than estimated.
+- `MarginFuse::CONTRACT_VERSION` reports the shared contract this build was
+  verified against.
+
+### Notes on the design
+
+- **No bigdecimal.** The obvious way to format a nano-precision decimal is
+  BigDecimal, and it stopped being a default gem in Ruby 3.4, so requiring it
+  would quietly turn this into a package with a runtime dependency on a third of
+  supported Rubies. `Kernel#format` is core and does the same job.
+- **`guard` yields rather than returning a decision to act on.** Forgetting the
+  check once would let a blocked request reach the provider.
+- **`decide` never raises.** A failed decision is an allow with `degraded?` set.
+- **Ruby 3.2, not 3.1.** The development toolchain does not install on 3.1, so
+  the claim could not be verified, and 3.1 reached end of life in March 2025.
+  Claiming a version CI cannot exercise is how an SDK ends up broken on it.
+- Verified against
+  [marginfuse/sdk-contract](https://github.com/marginfuse/sdk-contract): 16
+  behavioral scenarios and 13 gateway vectors, the same ones the Node, Python,
+  Go, Java and .NET SDKs pass.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pemira Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,189 @@
+# marginfuse
+
+[![Gem](https://img.shields.io/gem/v/marginfuse)](https://rubygems.org/gems/marginfuse)
+[![ci](https://github.com/marginfuse/marginfuse-ruby/actions/workflows/ci.yml/badge.svg)](https://github.com/marginfuse/marginfuse-ruby/actions/workflows/ci.yml)
+[![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
+Server-side SDK for [MarginFuse](https://marginfuse.com): profitability
+guardrails for AI SaaS. Connect revenue to per-request AI cost, see gross margin
+per customer, and stop loss-making requests before they run.
+
+- **Metadata only, by construction.** The event shape has no field for prompts
+  or responses, so they cannot be sent. Not a policy, an absence.
+- **Never breaks your app.** It does not raise into your code, and it does not
+  block your request on MarginFuse being up. If MarginFuse is unreachable, your
+  requests proceed unchanged.
+- **Zero dependencies.** Standard library only, Ruby 3.2+.
+
+> **Server side only.** This SDK carries a secret API key. Never ship it in a
+> desktop or mobile application, or anything else a user can read.
+
+## Install
+
+```bash
+bundle add marginfuse
+```
+
+## Track an AI call
+
+Monitoring. One call after each AI request, metadata only.
+
+```ruby
+require "marginfuse"
+
+mf = MarginFuse.new(api_key: ENV.fetch("MARGINFUSE_KEY"))
+
+response = client.chat(model: "gpt-4.1", messages: messages)
+
+mf.track(
+  customer_id: "cus_8x2m91",   # your Stripe customer id, or your own
+  feature: "ai_chat",
+  provider: "openai",
+  model: "gpt-4.1",
+  usage: {
+    input_tokens: response.usage.prompt_tokens,
+    output_tokens: response.usage.completion_tokens
+  }
+)
+```
+
+`track` returns immediately and sends on a background thread with retries. In a
+rake task, a Sidekiq job or a script, call `mf.flush` before the process exits,
+or the last events go with it.
+
+## Guard a call
+
+Protection. Ask before the call runs, and act on the answer.
+
+```ruby
+outcome = mf.guard(
+  customer_id: "cus_8x2m91",
+  feature: "ai_chat",
+  provider: "openai",
+  model: "gpt-4.1"
+) do |decision|
+  # decision.model is the one to call: a downgrade verdict changes it.
+  response = client.chat(model: decision.model, messages: messages)
+  {
+    result: response,
+    usage: {
+      input_tokens: response.usage.prompt_tokens,
+      output_tokens: response.usage.completion_tokens
+    }
+  }
+end
+
+case outcome.kind
+when :completed then use(outcome.result)
+when :topup_required then show_topup(outcome.decision.topup_context)
+when :blocked then show_limit_reached()
+end
+```
+
+One call does the whole loop: ask, run with the resolved model, report the real
+cost, acknowledge what your application did.
+
+### Why a block rather than a returned decision
+
+Enforcement must not depend on you remembering to check anything. If `guard`
+returned a decision for you to act on, forgetting the check once would mean a
+blocked request reaches the provider anyway. With a block that is structurally
+impossible: when the verdict is `:block`, the block is never yielded to.
+
+### Why decide never raises
+
+There is no failure a caller should branch on. A decision that times out or
+errors is an *allow* with `degraded?` true, because MarginFuse being unreachable
+must never become your outage. Transport failures go to `on_error`.
+
+## OpenRouter and other gateways
+
+Gateways report the real cost of every call. Forward it and your figures are
+exact instead of estimated.
+
+```ruby
+response = client.chat(model: "anthropic/claude-sonnet-4.5", messages: messages)
+
+mf.track(
+  customer_id: "cus_8x2m91",
+  feature: "ai_chat",
+  provider: "openrouter",
+  model: "anthropic/claude-sonnet-4.5",
+  **MarginFuse::OpenRouter.from(response["usage"])
+)
+```
+
+Use the helper rather than mapping the fields yourself. OpenRouter's
+`prompt_tokens` already includes cached reads and cache writes, which MarginFuse
+prices separately, so passing it through directly charges every cached token
+twice at the full input rate. The helper also formats the cost as a decimal
+string, because `1.2e-07.to_s` produces exponent notation and the API rejects
+that.
+
+## Configuration
+
+```ruby
+MarginFuse.new(
+  api_key: ENV.fetch("MARGINFUSE_KEY"),
+  base_url: "https://api.marginfuse.com",  # your own deployment in dev
+  timeout: 1.5,                            # decide budget before failing open
+  on_error: ->(error, context) { Rails.logger.warn("marginfuse #{context}: #{error}") }
+)
+```
+
+`on_error` is the only place transport failures surface. The SDK swallows them
+so they cannot become your outage; without the hook they are silent.
+
+### In Rails
+
+The client is safe to share, so build one at boot:
+
+```ruby
+# config/initializers/marginfuse.rb
+MARGINFUSE = MarginFuse.new(
+  api_key: Rails.application.credentials.marginfuse_key,
+  on_error: ->(error, context) { Rails.logger.warn("marginfuse #{context}: #{error}") }
+)
+```
+
+## What it sends
+
+Everything, and nothing else:
+
+```
+event_id  customer_id  feature  provider  model  requested_model
+usage(input_tokens, output_tokens, cached_input_tokens,
+      cache_creation_tokens, images, audio_seconds)
+cost_usd  occurred_at  outcome  decision_id  retry_of_event_id  corrects_event_id
+```
+
+There is no field for message content anywhere in the wire types. The
+[conformance suite](https://github.com/marginfuse/sdk-contract) checks this
+against the bytes that actually leave the process, on every scenario.
+
+## Conformance
+
+This SDK is verified against
+[marginfuse/sdk-contract](https://github.com/marginfuse/sdk-contract), the same
+contract every MarginFuse SDK in every language is held to. It is a submodule
+here, so the pinned commit records exactly which contract a release passed, and
+`MarginFuse::CONTRACT_VERSION` reports it at runtime.
+
+```bash
+git clone --recurse-submodules https://github.com/marginfuse/marginfuse-ruby
+cd marginfuse-ruby
+bundle install
+bundle exec rake test        # unit tests, plus the shared gateway vectors
+npm --prefix contract/harness install
+npm --prefix contract/harness run conformance ruby
+```
+
+## Links
+
+- [MarginFuse](https://marginfuse.com), product and pricing
+- [Documentation](https://marginfuse.com/docs)
+- [API reference](https://api.marginfuse.com/openapi.json)
+- [Security policy](SECURITY.md)
+- [Contributing](CONTRIBUTING.md)
+
+MIT, Pemira Labs.

data/lib/marginfuse/client.rb

@@ -0,0 +1,300 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "securerandom"
+# Time#iso8601 lives here. Some Rubies load it transitively and some do not, so
+# a library that assumes it is present throws into the caller on the ones that
+# do not, which is the one thing this SDK promises never to do.
+require "time"
+require "uri"
+
+module MarginFuse
+  # Server-side SDK for MarginFuse: profitability guardrails for AI SaaS.
+  #
+  # Reliability contract: this SDK never raises into application code and never
+  # blocks a request on MarginFuse availability. {#decide} fails open to
+  # +:allow+ on any timeout or error; {#track} and {#acknowledge} retry on a
+  # background thread and surface problems only through +on_error+.
+  #
+  # Zero dependencies, standard library only. Server side only: it carries a
+  # secret API key.
+  #
+  #   mf = MarginFuse::Client.new(api_key: ENV.fetch("MARGINFUSE_KEY"))
+  #   mf.track(customer_id: "cus_8x2m91", provider: "openai", model: "gpt-4.1",
+  #            usage: { input_tokens: 1204, output_tokens: 388 })
+  class Client
+    DEFAULT_BASE_URL = "https://api.marginfuse.com"
+    DEFAULT_TIMEOUT = 1.5
+    TRACK_RETRIES = 3
+    USER_AGENT = "marginfuse-ruby/#{VERSION}".freeze
+
+    # Usage keys are snake_case here and camelCase on the wire.
+    USAGE_KEYS = {
+      input_tokens: "inputTokens",
+      output_tokens: "outputTokens",
+      cached_input_tokens: "cachedInputTokens",
+      cache_creation_tokens: "cacheCreationTokens",
+      images: "images",
+      audio_seconds: "audioSeconds"
+    }.freeze
+
+    # @param api_key [String] your project API key
+    # @param base_url [String] point at your own deployment in development
+    # @param timeout [Float] seconds {#decide} waits before failing open
+    # @param on_error [Proc] receives (error, context) for failures the SDK
+    #   swallowed. Without it they are silent by design: this SDK is in your
+    #   request path and must not become your outage.
+    def initialize(api_key:, base_url: DEFAULT_BASE_URL, timeout: DEFAULT_TIMEOUT, on_error: nil)
+      raise ArgumentError, "MarginFuse: api_key is required" if api_key.nil? || api_key.empty?
+
+      @api_key = api_key
+      @base_url = base_url.to_s.sub(%r{/+\z}, "")
+      @timeout = timeout
+      @on_error = on_error
+      @pending = []
+      @mutex = Mutex.new
+    end
+
+    # Asks whether the next call should run. Always returns a decision.
+    #
+    # On any timeout or error this returns +action: :allow+ with
+    # +degraded: true+: MarginFuse being unreachable must never become your
+    # outage.
+    #
+    # @return [Decision]
+    def decide(customer_id:, provider:, model:, feature: nil, expected_usage: nil)
+      body = {
+        "customerId" => customer_id,
+        "feature" => feature,
+        "provider" => provider,
+        "model" => model,
+        "expectedUsage" => usage_payload(expected_usage)
+      }.compact
+      body.delete("expectedUsage") if body["expectedUsage"] && body["expectedUsage"].empty?
+
+      response = post("/v1/decisions", body, @timeout)
+      unless (200..299).cover?(response.code.to_i)
+        report(RuntimeError.new("decide: HTTP #{response.code}"), "decide")
+        return fail_open(provider, model, "server responded #{response.code}")
+      end
+
+      parsed = JSON.parse(response.body)
+      Decision.new(
+        id: parsed["id"],
+        action: Decision.action_from_wire(parsed["action"]),
+        model: parsed["model"] || model,
+        provider: parsed["provider"] || provider,
+        topup_context: parsed["topupContext"],
+        degraded: parsed["degraded"] || false,
+        degraded_reason: parsed["degradedReason"]
+      )
+    # Net::OpenTimeout, Net::ReadTimeout and Net::WriteTimeout are all
+    # Timeout::Error, so this catches every way the request can time out,
+    # including the one an explicit list would have missed.
+    rescue Timeout::Error => e
+      report(e, "decide")
+      fail_open(provider, model, "timeout")
+    rescue StandardError => e
+      report(e, "decide")
+      fail_open(provider, model, "unreachable")
+    end
+
+    # Reports a call that already happened. Returns immediately and sends on a
+    # background thread with retries.
+    #
+    # Call {#flush} before the process exits, or the last events go with it.
+    #
+    # @return [void]
+    def track(customer_id:, provider:, model:, usage: nil, feature: nil, requested_model: nil,
+              cost_usd: nil, event_id: nil, occurred_at: nil, outcome: :success,
+              decision_id: nil, retry_of_event_id: nil, corrects_event_id: nil)
+      event = {
+        "eventId" => event_id || "evt_#{SecureRandom.uuid}",
+        "customerId" => customer_id,
+        "feature" => feature,
+        "provider" => provider,
+        "model" => model,
+        "requestedModel" => requested_model,
+        "usage" => usage_payload(usage) || {},
+        "costUsd" => cost_usd,
+        "occurredAt" => (occurred_at || Time.now).utc.iso8601(6),
+        "outcome" => outcome.to_s,
+        "decisionId" => decision_id,
+        "retryOfEventId" => retry_of_event_id,
+        "correctsEventId" => corrects_event_id
+      }.compact
+
+      background { send_event(event) }
+    end
+
+    # {#track} for jobs and scripts that must not exit early.
+    # @return [void]
+    def track_and_wait(**params)
+      track(**params)
+      flush
+    end
+
+    # Tells MarginFuse what your application did with a decision.
+    # @return [void]
+    def acknowledge(decision_id, acknowledgment)
+      background do
+        response = post("/v1/decisions/#{URI.encode_www_form_component(decision_id)}/ack",
+                        { "acknowledgment" => acknowledgment.to_s }, 5.0)
+        unless (200..299).cover?(response.code.to_i)
+          report(RuntimeError.new("ack: HTTP #{response.code}"), "acknowledge")
+        end
+      rescue StandardError => e
+        report(e, "acknowledge")
+      end
+    end
+
+    # Runs the whole loop: ask, run, report, acknowledge.
+    #
+    # Yields the decision to the block, which must return a hash with +:usage+
+    # and optionally +:result+, +:cost_usd+ and +:outcome+. Use
+    # +decision.model+: a downgrade verdict changes it.
+    #
+    # It yields rather than returning a decision for you to act on, because
+    # enforcement must not depend on the caller remembering to check anything.
+    # When the verdict is block, the block is never yielded to.
+    #
+    # An exception from your block propagates unchanged: your error handling
+    # owns provider failures. The attempt is recorded first, because the
+    # provider may still have charged for it.
+    #
+    # @return [GuardOutcome]
+    def guard(customer_id:, provider:, model:, feature: nil, expected_usage: nil)
+      decision = decide(customer_id: customer_id, provider: provider, model: model,
+                        feature: feature, expected_usage: expected_usage)
+
+      # Enforcement depends on the ACTION alone. A missing id costs an
+      # acknowledgment; it must never turn a block into a provider call.
+      if decision.action == :block
+        acknowledge(decision.id, :blocked_before_provider_call) if decision.id
+        return GuardOutcome.new(kind: :blocked, decision: decision)
+      end
+      if decision.action == :topup_required
+        acknowledge(decision.id, :presented_topup) if decision.id
+        return GuardOutcome.new(kind: :topup_required, decision: decision)
+      end
+
+      model_used = decision.action == :downgrade ? decision.model : model
+
+      begin
+        call = yield(decision)
+      rescue Exception => e # rubocop:disable Lint/RescueException
+        track(customer_id: customer_id, feature: feature, provider: provider,
+              model: model_used, requested_model: model, usage: {},
+              outcome: :provider_error, decision_id: decision.id)
+        acknowledge(decision.id, :proceeded_as_requested) if decision.id
+        raise e
+      end
+
+      call ||= {}
+      track(customer_id: customer_id, feature: feature, provider: provider,
+            model: model_used, requested_model: model, usage: call[:usage],
+            cost_usd: call[:cost_usd], outcome: call[:outcome] || :success,
+            decision_id: decision.id)
+      if decision.id
+        acknowledge(decision.id,
+                    decision.action == :downgrade ? :used_downgrade_model : :proceeded_as_requested)
+      end
+
+      GuardOutcome.new(kind: :completed, decision: decision, result: call[:result])
+    end
+
+    # Waits for queued events and acknowledgments. Never raises.
+    # @return [void]
+    def flush
+      threads = @mutex.synchronize { @pending.dup }
+      threads.each do |thread|
+        thread.join
+      rescue StandardError
+        # already surfaced through on_error
+      end
+      @mutex.synchronize { @pending.compact! }
+      nil
+    end
+
+    private
+
+    def fail_open(provider, model, reason)
+      Decision.new(id: nil, action: :allow, model: model, provider: provider,
+                   topup_context: nil, degraded: true, degraded_reason: reason)
+    end
+
+    def usage_payload(usage)
+      return nil if usage.nil?
+
+      USAGE_KEYS.each_with_object({}) do |(key, wire), out|
+        value = usage.is_a?(Hash) ? (usage[key] || usage[key.to_s]) : nil
+        out[wire] = value unless value.nil?
+      end
+    end
+
+    def report(error, context)
+      return if @on_error.nil?
+
+      @on_error.call(error, context)
+    rescue StandardError
+      # a broken hook is not our failure mode
+    end
+
+    def background(&)
+      thread = Thread.new(&)
+      thread.report_on_exception = false
+      @mutex.synchronize do
+        @pending.select!(&:alive?)
+        @pending << thread
+      end
+    end
+
+    def send_event(event)
+      last = nil
+      attempt = 0
+      while attempt < TRACK_RETRIES
+        outcome, last = attempt_send(event)
+        return if outcome == :done
+
+        sleep(0.25 * (2**attempt))
+        attempt += 1
+      end
+      report(last, "track") if last
+    end
+
+    # Returns [:done, nil] when there is nothing left to try, either because the
+    # event landed or because retrying cannot help.
+    def attempt_send(event)
+      response = post("/v1/events", { "events" => [event] }, 5.0)
+      status = response.code.to_i
+      return [:done, nil] if (200..299).cover?(status)
+
+      if (400..499).cover?(status) && status != 429
+        # A malformed event is malformed on every attempt.
+        report(RuntimeError.new("track: HTTP #{status} #{response.body.to_s[0, 200]}"), "track")
+        return [:done, nil]
+      end
+
+      [:retry, RuntimeError.new("track: HTTP #{status}")]
+    rescue StandardError => e
+      [:retry, e]
+    end
+
+    def post(path, body, timeout)
+      uri = URI.parse("#{@base_url}#{path}")
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = timeout
+      http.read_timeout = timeout
+
+      request = Net::HTTP::Post.new(uri.request_uri)
+      request["authorization"] = "Bearer #{@api_key}"
+      request["content-type"] = "application/json"
+      request["user-agent"] = USER_AGENT
+      request.body = JSON.generate(body)
+
+      http.request(request)
+    end
+  end
+end

data/lib/marginfuse/open_router.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module MarginFuse
+  # OpenRouter helper.
+  #
+  # OpenRouter returns a +usage+ object carrying the provider-final +cost+.
+  # Forwarding it is what makes an OpenRouter integration exact rather than
+  # estimated: MarginFuse cannot know what a gateway charged, because routing,
+  # fees and BYOK terms are not visible in a usage event.
+  #
+  # Two details this helper exists to get right, both of which silently misstate
+  # margin when hand-rolled:
+  #
+  # 1. +prompt_tokens+ is the TOTAL input count. Cached reads and cache writes
+  #    are already inside it, and MarginFuse prices those as three separate
+  #    charges and adds them up, so passing the total through charges every
+  #    cached token twice at the full uncached rate.
+  # 2. +cost+ is a Float, and +to_s+ renders small ones in exponent notation
+  #    ("1.2e-07"), which the API rejects as a decimal string.
+  module OpenRouter
+    module_function
+
+    # Maps an OpenRouter +usage+ object to MarginFuse keyword arguments.
+    #
+    #   r = client.chat(...)
+    #   mf.track(customer_id: cid, provider: "openrouter", model: model,
+    #            **MarginFuse::OpenRouter.from(r["usage"]))
+    #
+    # +:cost_usd+ is omitted when the response carried no cost, which lets the
+    # event fall through to MarginFuse's own pricing instead of claiming a $0
+    # charge.
+    #
+    # @return [Hash]
+    def from(usage = nil)
+      source = usage.is_a?(Hash) ? usage : {}
+      details = source["prompt_tokens_details"] || source[:prompt_tokens_details]
+      details = {} unless details.is_a?(Hash)
+
+      cached = to_int(details["cached_tokens"] || details[:cached_tokens])
+      cache_writes = to_int(details["cache_write_tokens"] || details[:cache_write_tokens])
+      # What is left after the cached parts is what was billed at the full input
+      # rate. Clamped at zero so a provider reporting these differently degrades
+      # to "no fresh input" rather than a negative charge.
+      prompt = to_int(source["prompt_tokens"] || source[:prompt_tokens])
+      fresh = [0, prompt - cached - cache_writes].max
+      completion = to_int(source["completion_tokens"] || source[:completion_tokens])
+
+      mapped = {}
+      mapped[:input_tokens] = fresh if fresh.positive?
+      mapped[:output_tokens] = completion if completion.positive?
+      mapped[:cached_input_tokens] = cached if cached.positive?
+      mapped[:cache_creation_tokens] = cache_writes if cache_writes.positive?
+
+      out = { usage: mapped }
+      cost = source["cost"] || source[:cost]
+      return out unless cost.is_a?(Numeric) && !cost.is_a?(Complex)
+      return out if cost.respond_to?(:nan?) && cost.nan?
+      return out if cost.respond_to?(:infinite?) && cost.infinite?
+      return out if cost.negative?
+
+      out[:cost_usd] = credits_to_usd(cost)
+      out
+    end
+
+    def to_int(value)
+      return 0 unless value.is_a?(Numeric) && !value.is_a?(Complex)
+      return 0 if value.respond_to?(:nan?) && value.nan?
+      return 0 if value.respond_to?(:infinite?) && value.infinite?
+      return 0 unless value.positive?
+
+      value.round
+    end
+
+    # OpenRouter credits (1 credit = 1 USD) as a decimal string the API takes.
+    #
+    # Fixed point to nano precision: +to_s+ emits exponent notation for the
+    # small costs cheap models produce, and money below a nano cannot be
+    # represented at all, so it rounds down rather than pretending otherwise.
+    def credits_to_usd(cost)
+      # Formatted to ten decimals and then truncated to nine, rather than
+      # rounded: money below a nano cannot be represented, so it rounds down
+      # instead of inventing precision it does not have.
+      #
+      # bigdecimal would read more clearly and stopped being a default gem in
+      # Ruby 3.4, so requiring it would quietly turn this into a package with a
+      # runtime dependency. Kernel#format is core.
+      text = format("%.10f", cost)[0..-2]
+      text = text.sub(/\.?0+\z/, "") if text.include?(".")
+      text.empty? || text == "-0" ? "0" : text
+    end
+  end
+end

data/lib/marginfuse/types.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module MarginFuse
+  # The wire values for a verdict. An action a newer server sends and this
+  # version cannot enforce resolves to :allow, because an unrecognised value
+  # must never silently become a block.
+  DECISION_ACTIONS = {
+    "allow" => :allow,
+    "downgrade" => :downgrade,
+    "topup_required" => :topup_required,
+    "block" => :block
+  }.freeze
+
+  # A verdict from MarginFuse.
+  #
+  # +degraded+ is true when MarginFuse could not reach a verdict and the request
+  # was allowed through unprotected. +id+ is nil in that case, which is exactly
+  # why enforcement must depend on +action+ alone.
+  Decision = Struct.new(
+    :id, :action, :model, :provider, :topup_context, :degraded, :degraded_reason,
+    keyword_init: true
+  ) do
+    def self.action_from_wire(value)
+      DECISION_ACTIONS.fetch(value, :allow)
+    end
+
+    def degraded?
+      !!degraded
+    end
+  end
+
+  # The result of the whole guard loop. +kind+ is :completed, :blocked or
+  # :topup_required. +result+ is your block's own return value.
+  GuardOutcome = Struct.new(:kind, :decision, :result, keyword_init: true) do
+    def completed?
+      kind == :completed
+    end
+
+    def blocked?
+      kind == :blocked
+    end
+
+    def topup_required?
+      kind == :topup_required
+    end
+  end
+end

data/lib/marginfuse/version.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module MarginFuse
+  VERSION = "0.1.0"
+
+  # The version of the shared SDK contract this build was verified against.
+  #
+  # Gem versions differ per language, because each tracks its own breaking
+  # changes: a rename in Python must not tell Ruby users something broke. What
+  # makes the SDKs interchangeable is this, not the gem version. Two SDKs
+  # reporting the same contract version have passed the same scenarios and the
+  # same vectors.
+  #
+  # See github.com/marginfuse/sdk-contract
+  CONTRACT_VERSION = 1
+end

data/lib/marginfuse.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative "marginfuse/version"
+require_relative "marginfuse/types"
+require_relative "marginfuse/client"
+require_relative "marginfuse/open_router"
+
+# MarginFuse: profitability guardrails for AI SaaS.
+#
+# Server side only: the SDK carries a secret API key.
+module MarginFuse
+  # Convenience for the common case.
+  #
+  #   mf = MarginFuse.new(api_key: ENV.fetch("MARGINFUSE_KEY"))
+  def self.new(**)
+    Client.new(**)
+  end
+end

metadata

@@ -0,0 +1,59 @@
+--- !ruby/object:Gem::Specification
+name: marginfuse
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Pemira Labs
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-09-02 00:00:00.000000000 Z
+dependencies: []
+description: |-
+  MarginFuse server-side SDK. Connect revenue to per-request AI cost, see gross
+  margin per customer, and stop loss-making requests before they run. Sends
+  usage metadata only, never prompts or responses.
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/marginfuse.rb
+- lib/marginfuse/client.rb
+- lib/marginfuse/open_router.rb
+- lib/marginfuse/types.rb
+- lib/marginfuse/version.rb
+homepage: https://marginfuse.com
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://marginfuse.com
+  documentation_uri: https://marginfuse.com/docs
+  source_code_uri: https://github.com/marginfuse/marginfuse-ruby
+  bug_tracker_uri: https://github.com/marginfuse/marginfuse-ruby/issues
+  changelog_uri: https://github.com/marginfuse/marginfuse-ruby/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: 'AI profitability guardrails: connect revenue to per-request AI cost.'
+test_files: []