marginfuse 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c0b1ac060efeb37a1cff83a21bfec10f5e5972c67622a637100b00746a9defbe
-  data.tar.gz: '0058b2089e6d46488e0db908ad66e675f83e1b4a8116abdb2edef4a557e7445f'
+  metadata.gz: cae1d3d92e08b1a32116bacfdb72d19db66577325fb861231642792c57269499
+  data.tar.gz: 06f74aaad11706184f3bb865b4138e1a960ecc21db9ea88f94a805aabc8fed2f
 SHA512:
-  metadata.gz: 79059326eec63bb75f28c62b93d144d236d14450d477100be60423b7a6a655dfba9556277f9452ae55f204b8c90e60bb43fcc9008fe3bfedc5b4dbf8f0c334a8
-  data.tar.gz: 0f8bea6add4ee66ac6badb04073b362b08f1ab22524479407b9cd1b475b7d2f152e69d020a41c712eadef3dcf5fd667bc82ce005edb8e39b3682bc4f7734ceb9
+  metadata.gz: ea248283d17a1d94b6344cb75f2369622b98dd58c8f972c206100bf92fb29b7735ce6eb7eae33cfdc39bff4485f94a1dae7a7f768e2a438c452e391ea0b00494
+  data.tar.gz: 3394d7d8f8376c3721686bf11a2cf83687434d369a5e13856d95785b34da97ac720601063ca065915721cc446cad3c2241611300fbc04e36ba7eecd87363b2a5

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # 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).

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"]),
@@ -282,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.3.0"
+  VERSION = "0.3.1"
 
   # The version of the shared SDK contract this build was verified against.
   #

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: marginfuse
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Pemira Labs
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-04 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