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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: margin-meter
-Version: 0.6.2
+Version: 0.6.4
 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.4}/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.4}/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.4"

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

@@ -1479,6 +1479,8 @@ class MarginMeter:
         harness: str | None = None,
         finish_reason: str | None = None,
         provider_call_id: str | None = None,
+        case_id: str | None = None,
+        prompt_hash: str | None = None,
     ) -> IngestResult:
         """Emit one measured LLM call to ``POST /api/ingest/calls``.
 
@@ -1630,6 +1632,18 @@ class MarginMeter:
             harness = harness[:64]
         if harness is not None:
             payload["harness"] = harness
+        # WHICH EVAL CASE this call ran under (MAR-1782). Read from MARGIN_CASE_ID AT CALL
+        # TIME, because the case changes per test inside one process; the pytest plugin sets
+        # it around each test. Blank reads as absent. ⛔ It is NOT ``task_key``: that is the
+        # task CLASS the parity gate buckets on, and a unique case id there would give every
+        # call its own class. Only repeat detection reads this. A dimension, never money.
+        case_id = (case_id or os.environ.get("MARGIN_CASE_ID") or "").strip()[:128] or None
+        if case_id is not None:
+            payload["case_id"] = case_id
+        # sha256 hex of the request, never the text. Lets repeat detection tell an identical
+        # re-send from a different request of similar size.
+        if prompt_hash:
+            payload["prompt_hash"] = prompt_hash
         if cost_usd is not None:
             payload["cost_usd"] = cost_usd
         # Only send a non-default tier: a synchronous call omits it (the server
@@ -1719,6 +1733,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 +1763,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 +1810,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(
@@ -1837,6 +1870,7 @@ class MarginMeter:
         substrate: str | None = None,
         task_key: str | None = None,
         provider_call_id: str | None = None,
+        prompt_hash: str | None = None,
     ) -> IngestResult:
         """Meter one call by reading tokens straight off its provider ``response``.
 
@@ -1882,6 +1916,7 @@ class MarginMeter:
             # forwarded as finish_reason (MAR-209). A signal, never a billing verdict.
             finish_reason=usage.stop_reason,
             is_simulated=is_simulated,
+            prompt_hash=prompt_hash,
         )
 
     def wrap(
@@ -2001,6 +2036,7 @@ class MarginMeter:
                     is_retry=is_retry,
                     session_id=session_id,
                     prompt_id=prompt_id_from(kwargs),
+                    prompt_hash=prompt_hash_from(kwargs),
                     operation=operation,
                     substrate=call_substrate,
                     task_key=call_task_key,
@@ -2028,6 +2064,7 @@ class MarginMeter:
                     is_retry=is_retry,
                     session_id=session_id,
                     prompt_id=prompt_id_from(kwargs),
+                    prompt_hash=prompt_hash_from(kwargs),
                     operation=operation,
                     substrate=call_substrate,
                     task_key=call_task_key,
@@ -2084,6 +2121,7 @@ class MarginMeter:
                         is_retry=is_retry,
                         session_id=session_id,
                         prompt_id=prompt_id_from(kwargs),
+                        prompt_hash=prompt_hash_from(kwargs),
                         operation=operation,
                         substrate=call_substrate,
                         task_key=call_task_key,
@@ -2223,6 +2261,28 @@ class MarginMeter:
         return _wrapped
 
 
+_PROMPT_FIELDS = ("messages", "input", "contents", "prompt", "system", "tools")
+
+
+def prompt_hash_from(kwargs: dict) -> str | None:
+    """sha256 hex of the request's prompt-bearing kwargs, or ``None``. Never the text.
+
+    Two calls that send the same messages to the same model hash alike, which is all
+    repeat detection needs. Best-effort: an unserialisable request yields ``None``.
+    """
+    import hashlib
+    import json
+
+    part = {k: kwargs[k] for k in _PROMPT_FIELDS if kwargs.get(k) is not None}
+    if not part:
+        return None
+    try:
+        blob = json.dumps(part, sort_keys=True, default=repr).encode()
+    except Exception:
+        return None
+    return hashlib.sha256(blob).hexdigest()
+
+
 def prompt_id_from(kwargs: dict) -> str | None:
     """Pull a caller-supplied ``margin_prompt_id`` out of call kwargs, if present.
 

{margin_meter-0.6.2 → margin_meter-0.6.4}/margin_meter/pytest_plugin.py

@@ -291,6 +291,12 @@ def pytest_runtest_setup(item):
     nothing and is NOT warned about here. A warning raised in the setup phase becomes an ERROR
     under ``-W error``, which would flip a passing test to a fail in a suite that only has the
     SDK installed (the adapter, when enabled, reports a bad marker itself)."""
+    # Name the eval case for every call this test meters (MAR-1782), unconditionally like
+    # the marker below. Cleared in teardown so a call outside a test carries no stale case.
+    try:
+        os.environ["MARGIN_CASE_ID"] = str(item.nodeid)[:128]
+    except Exception:
+        pass
     try:
         value = value_from_marker(item)
     except ValueError:
@@ -299,6 +305,10 @@ def pytest_runtest_setup(item):
         item.user_properties.append((VALUE_PROPERTY, value))
 
 
+def pytest_runtest_teardown(item):
+    os.environ.pop("MARGIN_CASE_ID", None)
+
+
 def pytest_configure(config):
     # Register the marker unconditionally so a suite that uses it without the
     # flag does not trip PytestUnknownMarkWarning.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: margin-meter
-Version: 0.6.2
+Version: 0.6.4
 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 |