margin-meter 0.6.2__tar.gz → 0.6.3__tar.gz

{margin_meter-0.6.2 → margin_meter-0.6.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: margin-meter
-Version: 0.6.2
+Version: 0.6.3
 Summary: Tiny stdlib-only client that auto-instruments OpenAI/Anthropic/Gemini and emits LLM call + outcome economics to a Margin ingest API.
 Author: Margin
 License: MIT
@@ -452,6 +452,50 @@ current_task.set(ticket.topic)   # "billing" | "password-reset" | …
 Leave it off and the row's `task_key` is simply unset (`unknown`) — never a
 fabricated bucket.
 
+## Say where each call RAN (`environment`)
+
+`environment` splits the work you sell from the work you did to decide what to
+sell. A spike, an eval pass and your production traffic are three different kinds
+of spend, and only one of them belongs in the number you report upward.
+
+```python
+meter.record_call(
+    workflow_id="support-triage",
+    provider="openai",
+    model="gpt-4o-mini",
+    input_tokens=812,
+    output_tokens=96,
+    environment="prod",           # "prod" | "dev" | "eval"
+)
+```
+
+Setting it once per process is usually easier. A deployment already knows whether
+it is production; the call site does not:
+
+```bash
+export MARGIN_ENVIRONMENT=prod
+```
+
+An explicit argument wins over the variable, so one process can still label a
+single call differently.
+
+| value | send it for |
+| --- | --- |
+| `prod` | traffic your customers cause |
+| `dev` | a spike, a local run, a branch deploy |
+| `eval` | a graded pass, in CI or from an eval harness |
+
+Why it earns a field. `cost_per_outcome` is total call spend divided by passed
+outcomes. With `environment` unset, your R&D and your operations land in that one
+number, so "your AI workforce costs $X per outcome" describes neither. Margin
+already keeps its own face-off spend out of your number; this is how you get the
+same split on your side.
+
+Two things it will not do. It does not default: leave it off and the row is
+`unknown`, which is honest and costs you nothing, where guessing `prod` would book
+your spike as production. And it is never priced and never rolled into cost. It is
+a label, like `team`.
+
 ## API
 
 | Method | Emits to | Notes |

{margin_meter-0.6.2 → margin_meter-0.6.3}/README.md

@@ -440,6 +440,50 @@ current_task.set(ticket.topic)   # "billing" | "password-reset" | …
 Leave it off and the row's `task_key` is simply unset (`unknown`) — never a
 fabricated bucket.
 
+## Say where each call RAN (`environment`)
+
+`environment` splits the work you sell from the work you did to decide what to
+sell. A spike, an eval pass and your production traffic are three different kinds
+of spend, and only one of them belongs in the number you report upward.
+
+```python
+meter.record_call(
+    workflow_id="support-triage",
+    provider="openai",
+    model="gpt-4o-mini",
+    input_tokens=812,
+    output_tokens=96,
+    environment="prod",           # "prod" | "dev" | "eval"
+)
+```
+
+Setting it once per process is usually easier. A deployment already knows whether
+it is production; the call site does not:
+
+```bash
+export MARGIN_ENVIRONMENT=prod
+```
+
+An explicit argument wins over the variable, so one process can still label a
+single call differently.
+
+| value | send it for |
+| --- | --- |
+| `prod` | traffic your customers cause |
+| `dev` | a spike, a local run, a branch deploy |
+| `eval` | a graded pass, in CI or from an eval harness |
+
+Why it earns a field. `cost_per_outcome` is total call spend divided by passed
+outcomes. With `environment` unset, your R&D and your operations land in that one
+number, so "your AI workforce costs $X per outcome" describes neither. Margin
+already keeps its own face-off spend out of your number; this is how you get the
+same split on your side.
+
+Two things it will not do. It does not default: leave it off and the row is
+`unknown`, which is honest and costs you nothing, where guessing `prod` would book
+your spike as production. And it is never priced and never rolled into cost. It is
+a label, like `team`.
+
 ## API
 
 | Method | Emits to | Notes |

{margin_meter-0.6.2 → margin_meter-0.6.3}/margin_meter/__init__.py

@@ -106,4 +106,4 @@ __all__ = [
 # closing the invoice-reconcile coverage gap is "ship the fix, wait for the seed's
 # dependency refresh, re-run the reconcile", and a runtime that misreports which
 # SDK metered a call makes that unanswerable.
-__version__ = "0.6.2"
+__version__ = "0.6.3"

{margin_meter-0.6.2 → margin_meter-0.6.3}/margin_meter/client.py

@@ -1719,6 +1719,7 @@ class MarginMeter:
         is_simulated: bool = False,
         event_id: str | None = None,
         span_id: str | None = None,
+        environment: str | None = None,
         value_usd: float | None = None,
     ) -> IngestResult:
         """Emit one outcome (a unit of productivity) to ``POST /api/ingest/outcomes``.
@@ -1748,11 +1749,25 @@ class MarginMeter:
         value (revenue booked, a ticket's handling cost avoided); omit it and the
         outcome is measured as cost-per-outcome, the honest default. It is optional
         by construction — absent is the normal case, never defaulted to 0.
+
+        ``environment`` is WHERE this outcome was produced — the DENOMINATOR twin of
+        :meth:`record_call`'s (MAR-1562): ``prod`` for the work the customer sells,
+        ``dev``/``eval`` for the work they did to decide what to sell. Same resolution
+        rules as the call path — explicit wins, then ``MARGIN_ENVIRONMENT``, then
+        absent. ⛔ Omit it and the server stores NULL (UNKNOWN); it is never assumed to
+        be ``prod``.
         """
         if span_id is None:
             _span = _SPAN.get()
             if _span is not None:
                 span_id = _span.span_id
+        # Same env-var fallback and same server-width clamp as `record_call`, for the same
+        # reason: `ingest._require_str` RAISES (422) on an over-long value, so an outcome
+        # label longer than the column would drop the metered row rather than mislabel it —
+        # and a dropped outcome is a silently smaller denominator, the flattering direction.
+        environment = environment or (os.environ.get("MARGIN_ENVIRONMENT") or "").strip() or None
+        if environment:
+            environment = environment[:32]
         payload: dict[str, Any] = {
             "workflow_id": workflow_id,
             "passed": passed,
@@ -1781,6 +1796,10 @@ class MarginMeter:
         # send. An older server that predates the column ignores an unknown key.
         if value_usd is not None:
             payload["value_usd"] = value_usd
+        # Rides only when one was declared (explicitly or via the process env). An
+        # unlabelled outcome sends nothing and the server stores NULL, never `prod`.
+        if environment is not None:
+            payload["environment"] = environment
         return self._emit(OUTCOMES_PATH, payload)
 
     def measure(

{margin_meter-0.6.2 → margin_meter-0.6.3}/margin_meter.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: margin-meter
-Version: 0.6.2
+Version: 0.6.3
 Summary: Tiny stdlib-only client that auto-instruments OpenAI/Anthropic/Gemini and emits LLM call + outcome economics to a Margin ingest API.
 Author: Margin
 License: MIT
@@ -452,6 +452,50 @@ current_task.set(ticket.topic)   # "billing" | "password-reset" | …
 Leave it off and the row's `task_key` is simply unset (`unknown`) — never a
 fabricated bucket.
 
+## Say where each call RAN (`environment`)
+
+`environment` splits the work you sell from the work you did to decide what to
+sell. A spike, an eval pass and your production traffic are three different kinds
+of spend, and only one of them belongs in the number you report upward.
+
+```python
+meter.record_call(
+    workflow_id="support-triage",
+    provider="openai",
+    model="gpt-4o-mini",
+    input_tokens=812,
+    output_tokens=96,
+    environment="prod",           # "prod" | "dev" | "eval"
+)
+```
+
+Setting it once per process is usually easier. A deployment already knows whether
+it is production; the call site does not:
+
+```bash
+export MARGIN_ENVIRONMENT=prod
+```
+
+An explicit argument wins over the variable, so one process can still label a
+single call differently.
+
+| value | send it for |
+| --- | --- |
+| `prod` | traffic your customers cause |
+| `dev` | a spike, a local run, a branch deploy |
+| `eval` | a graded pass, in CI or from an eval harness |
+
+Why it earns a field. `cost_per_outcome` is total call spend divided by passed
+outcomes. With `environment` unset, your R&D and your operations land in that one
+number, so "your AI workforce costs $X per outcome" describes neither. Margin
+already keeps its own face-off spend out of your number; this is how you get the
+same split on your side.
+
+Two things it will not do. It does not default: leave it off and the row is
+`unknown`, which is honest and costs you nothing, where guessing `prod` would book
+your spike as production. And it is never priced and never rolled into cost. It is
+a label, like `team`.
+
 ## API
 
 | Method | Emits to | Notes |