marginfuse 0.2.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ed4b052cde767f31778131e10df10f850d206c4db7f2215040de98faec393af0
-  data.tar.gz: 428cb94a4937c73876d998db48026aea9b2f8b69730b1149bd5e3947051a19c9
+  metadata.gz: cae1d3d92e08b1a32116bacfdb72d19db66577325fb861231642792c57269499
+  data.tar.gz: 06f74aaad11706184f3bb865b4138e1a960ecc21db9ea88f94a805aabc8fed2f
 SHA512:
-  metadata.gz: e7d968bfd7aa9d82acaa132b72402396cca466b6940d825da506326b7a508376dcbacf203cc16529a7f8d98c0a52f9e3b6d04ba3341820ca1eea8541b0443bb5
-  data.tar.gz: 2cd18e81de9e717d56607177da46c46c758bb46a443c9bebe2298e16ad68873156bd1e5123d3b09c24460f68823d53ec7064d942be43da0938d52e07fa2b1a5e
+  metadata.gz: ea248283d17a1d94b6344cb75f2369622b98dd58c8f972c206100bf92fb29b7735ce6eb7eae33cfdc39bff4485f94a1dae7a7f768e2a438c452e391ea0b00494
+  data.tar.gz: 3394d7d8f8376c3721686bf11a2cf83687434d369a5e13856d95785b34da97ac720601063ca065915721cc446cad3c2241611300fbc04e36ba7eecd87363b2a5

data/CHANGELOG.md

@@ -1,9 +1,40 @@
 # Changelog
 
+## 0.3.1
+
+- Validate successful decision responses before using routing fields. Malformed
+  responses fail open to the original provider and model, mark the decision
+  degraded, and invoke the error hook. Valid blocks without an id still block.
+- Correct OpenAI examples to separate cached input tokens from fresh input,
+  and clarify provider dispatch for cross-provider downgrade policies.
+
+
 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.3.0]
+
+### Fixed
+
+- A downgrade that crosses vendors is reported against the vendor that actually
+  ran it. `guard()` already ran the model the server chose, but the usage event
+  still named the requested provider, so the call was priced from the wrong
+  catalog and the saving the downgrade exists to prove was computed against the
+  wrong basis. An `allow` is unchanged, because the decision already defaults
+  its provider to the requested one.
+- A downgrade whose provider call then fails is acknowledged as
+  `used_downgrade_model` rather than `proceeded_as_requested`. The cheaper model
+  did run; what failed came after. Reporting otherwise told reconciliation the
+  policy never applied, which skewed realized-savings attribution on the error
+  path.
+
+### Changed
+
+- Pinned contract v2, whose new scenarios cover both corrections above and add
+  a privacy check that hands the SDK content-bearing fields and scans the bytes
+  that actually leave the process.
+
 ## [0.2.0]
 
 ### Added

data/README.md

@@ -26,7 +26,9 @@ bundle add marginfuse
 
 ## Track an AI call
 
-Monitoring. One call after each AI request, metadata only.
+Monitoring. One call after each AI request, metadata only. OpenAI prompt tokens
+include cached reads: subtract them from input and report them separately to
+avoid pricing cached tokens at the full input rate.
 
 ```ruby
 require "marginfuse"
@@ -34,6 +36,7 @@ require "marginfuse"
 mf = MarginFuse.new(api_key: ENV.fetch("MARGINFUSE_KEY"))
 
 response = client.chat(model: "gpt-4.1", messages: messages)
+cached = response.usage.prompt_tokens_details&.cached_tokens || 0
 
 mf.track(
   customer_id: "cus_8x2m91",   # your Stripe customer id, or your own
@@ -41,7 +44,8 @@ mf.track(
   provider: "openai",
   model: "gpt-4.1",
   usage: {
-    input_tokens: response.usage.prompt_tokens,
+    input_tokens: [0, response.usage.prompt_tokens - cached].max,
+    cached_input_tokens: cached,
     output_tokens: response.usage.completion_tokens
   }
 )
@@ -53,7 +57,9 @@ or the last events go with it.
 
 ## Guard a call
 
-Protection. Ask before the call runs, and act on the answer.
+Protection. Ask before the call runs, and act on the answer. This example assumes
+same-provider downgrades; cross-provider policies require dispatching to the
+client named by the decision provider.
 
 ```ruby
 outcome = mf.guard(
@@ -64,10 +70,12 @@ outcome = mf.guard(
 ) do |decision|
   # decision.model is the one to call: a downgrade verdict changes it.
   response = client.chat(model: decision.model, messages: messages)
+  cached = response.usage.prompt_tokens_details&.cached_tokens || 0
   {
     result: response,
     usage: {
-      input_tokens: response.usage.prompt_tokens,
+      input_tokens: [0, response.usage.prompt_tokens - cached].max,
+      cached_input_tokens: cached,
       output_tokens: response.usage.completion_tokens
     }
   }
@@ -98,9 +106,11 @@ must never become your outage. Transport failures go to `on_error`.
 
 ## Tell MarginFuse what a customer pays
 
-Margin needs a revenue side. With Stripe connected it comes from there. Without
-one, you declare your plans in MarginFuse and say which plan each customer is
-on:
+Margin needs a revenue side: Stripe for web billing, RevenueCat for App Store
+and Google Play proceeds, or declared plan prices. RevenueCat joins by App User
+ID; use that same ID in your events. Without a billing connection, declare your
+plans in MarginFuse and say which plan each customer is on. Declared revenue
+is unverified and does not confirm payment:
 
 ```ruby
 result = mf.identify(
@@ -182,7 +192,7 @@ MARGINFUSE = MarginFuse.new(
 Everything, and nothing else:
 
 ```
-event_id  customer_id  feature  provider  model  requested_model
+event_id  customer_id  feature  provider  model  requested_model  plan
 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

data/lib/marginfuse/client.rb

@@ -81,6 +81,10 @@ module MarginFuse
       end
 
       parsed = JSON.parse(response.body)
+      unless valid_wire_decision?(parsed)
+        report(RuntimeError.new("decide: invalid response payload"), "decide")
+        return fail_open(provider, model, "invalid response")
+      end
       Decision.new(
         id: parsed["id"],
         action: Decision.action_from_wire(parsed["action"]),
@@ -208,7 +212,8 @@ module MarginFuse
     #
     # 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.
+    # +decision.model+ and +decision.provider+: a downgrade verdict changes
+    # them, and it can send you to another vendor.
     #
     # It yields rather than returning a decision for you to act on, because
     # enforcement must not depend on the caller remembering to check anything.
@@ -234,27 +239,34 @@ module MarginFuse
         return GuardOutcome.new(kind: :topup_required, decision: decision)
       end
 
+      # A downgrade can cross vendors, so the vendor that ran the call comes
+      # from the decision exactly as the model does. Reporting the caller's
+      # would price the call from the wrong catalog and credit the saving to the
+      # wrong vendor. The decision defaults both to what was asked for, so
+      # anything but a downgrade reports what it always did.
       model_used = decision.action == :downgrade ? decision.model : model
+      provider_used = decision.action == :downgrade ? decision.provider : provider
+      # A downgrade whose provider call then fails is still a downgrade: the
+      # cheaper model is the one that ran, so both paths acknowledge the same.
+      acknowledgment =
+        decision.action == :downgrade ? :used_downgrade_model : :proceeded_as_requested
 
       begin
         call = yield(decision)
       rescue Exception => e # rubocop:disable Lint/RescueException
-        track(customer_id: customer_id, plan: plan, feature: feature, provider: provider,
+        track(customer_id: customer_id, plan: plan, feature: feature, provider: provider_used,
               model: model_used, requested_model: model, usage: {},
               outcome: :provider_error, decision_id: decision.id)
-        acknowledge(decision.id, :proceeded_as_requested) if decision.id
+        acknowledge(decision.id, acknowledgment) if decision.id
         raise e
       end
 
       call ||= {}
-      track(customer_id: customer_id, plan: plan, feature: feature, provider: provider,
+      track(customer_id: customer_id, plan: plan, feature: feature, provider: provider_used,
             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
+      acknowledge(decision.id, acknowledgment) if decision.id
 
       GuardOutcome.new(kind: :completed, decision: decision, result: call[:result])
     end
@@ -274,6 +286,23 @@ module MarginFuse
 
     private
 
+    def valid_wire_decision?(value)
+      return false unless value.is_a?(Hash)
+      return false unless %w[allow block topup_required downgrade].include?(value["action"])
+
+      %w[id model provider topupContext degradedReason].each do |key|
+        return false if value.key?(key) && !value[key].is_a?(String)
+      end
+      if value.key?("degraded") && value["degraded"] != true && value["degraded"] != false
+        return false
+      end
+
+      %w[model provider].each do |key|
+        return false if value.key?(key) && value[key].strip.empty?
+      end
+      value["action"] != "downgrade" || value.key?("model")
+    end
+
     def fail_open(provider, model, reason)
       Decision.new(id: nil, action: :allow, model: model, provider: provider,
                    topup_context: nil, degraded: true, degraded_reason: reason)

data/lib/marginfuse/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module MarginFuse
-  VERSION = "0.2.0"
+  VERSION = "0.3.1"
 
   # The version of the shared SDK contract this build was verified against.
   #
@@ -12,5 +12,5 @@ module MarginFuse
   # same vectors.
   #
   # See github.com/marginfuse/sdk-contract
-  CONTRACT_VERSION = 1
+  CONTRACT_VERSION = 2
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: marginfuse
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Pemira Labs
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-03 00:00:00.000000000 Z
+date: 2026-09-06 00:00:00.000000000 Z
 dependencies: []
 description: |-
   MarginFuse server-side SDK. Connect revenue to per-request AI cost, see gross