margin-meter 0.1.0__tar.gz

margin_meter-0.1.0/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: margin-meter
+Version: 0.1.0
+Summary: Tiny stdlib-only client that emits LLM call + outcome economics to a Margin ingest API.
+Author: Margin
+License: MIT
+Project-URL: Homepage, https://github.com/subhsubh24/Margin.ai
+Project-URL: Source, https://github.com/subhsubh24/Margin.ai/tree/main/sdk/python
+Keywords: llm,cost,observability,finops,margin
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# margin-meter (Python SDK)
+
+The tiny client a **Python** project imports to connect to Margin. It wraps your
+LLM calls and records their outcomes, emitting each one **over HTTP** to a
+Margin **ingest API** (`POST /api/ingest/calls` / `/api/ingest/outcomes`),
+authenticated with a per-project ingest key. This is the customer-shaped path —
+the same SDK a stranger drops in — not the in-process meter Margin runs on
+itself.
+
+- **Standalone + stdlib-only.** No dependency on Margin's server code and no
+  third-party deps. The default transport is `urllib`.
+- **Fail-safe.** A failed emit returns an `IngestResult(ok=False, …)` instead of
+  crashing your app. Pass `raise_on_error=True` for strict/CI behaviour.
+- **Provenance-honest.** `is_simulated` is carried through untouched; the written
+  `source` is forced server-side to your key's project — you cannot spoof
+  another project's economics.
+
+## Install
+
+Published as a git-installable subpath of the Margin repo (no PyPI account
+needed pre-launch):
+
+```bash
+pip install "git+https://github.com/subhsubh24/Margin.ai.git#subdirectory=sdk/python"
+```
+
+## Configure
+
+Two environment variables — the deployed API base and your project's key:
+
+```bash
+export MARGIN_INGEST_URL="https://margin-ai-rho.vercel.app"
+export MARGIN_INGEST_KEY="mgk_…"   # issued by the Margin owner (see below)
+```
+
+The Margin owner issues your project a key with the provisioning CLI in the
+Margin repo:
+
+```bash
+python3 scripts/issue_ingest_key.py <your-project-slug>
+```
+
+The raw `mgk_…` key is shown **once** — only its hash is stored. Give it to your
+project as `MARGIN_INGEST_KEY`.
+
+## Use
+
+```python
+from margin_meter import MarginMeter
+
+meter = MarginMeter()  # reads MARGIN_INGEST_URL + MARGIN_INGEST_KEY
+
+# 1) Wrap the LLM call — latency is timed automatically, cost computed server-side.
+with meter.measure(workflow_id="fit-scoring", provider="google",
+                   model="gemini-2.5-flash") as m:
+    resp = call_the_model(...)
+    m.set_tokens(input_tokens=1200, output_tokens=300, cache_read_tokens=800)
+
+# 2) Record the outcome it produced (the unit of productivity).
+meter.record_outcome(workflow_id="fit-scoring", passed=True,
+                     quality_score=0.94, quality_method="ground_truth")
+```
+
+Or record a call directly (when you already have the token counts):
+
+```python
+res = meter.record_call(
+    workflow_id="fit-scoring", provider="google", model="gemini-2.5-flash",
+    input_tokens=1200, output_tokens=300, cache_read_tokens=800,
+)
+if not res.ok:
+    log.warning("margin ingest failed: %s (%s)", res.error, res.status_code)
+```
+
+## API
+
+| Method | Emits to | Notes |
+| --- | --- | --- |
+| `record_call(...)` | `POST /api/ingest/calls` | cost computed from the pricing table when `cost_usd` omitted |
+| `record_outcome(...)` | `POST /api/ingest/outcomes` | `quality_method` records HOW the score was graded |
+| `measure(...)` | `record_call` on exit | context manager; times latency, `status="error"` on exception |
+
+Every method returns an `IngestResult(ok, status_code, body, error)`. `ok` is
+True only on HTTP 200; `body` holds `call_id`/`outcome_id` + `source`.
+
+## Testing against a live app (no network)
+
+The network boundary is a single `transport.post(path, json=..., headers=...)`
+protocol, which a FastAPI `TestClient` satisfies exactly — so you can exercise
+the real ingest endpoints hermetically by injecting one:
+
+```python
+from fastapi.testclient import TestClient
+import asgi
+from margin_meter import MarginMeter
+
+meter = MarginMeter(api_key=raw_key, transport=TestClient(asgi.app),
+                    raise_on_error=True)
+```
+
+## Rate + validation bounds
+
+Ingest is auth'd, validated, and rate-bounded server-side. A bad key → 401, a
+malformed/implausible row → 422, and a full rolling per-project window → 429.
+In fail-safe mode these come back as `IngestResult(ok=False, status_code=…)`.

margin_meter-0.1.0/README.md

@@ -0,0 +1,105 @@
+# margin-meter (Python SDK)
+
+The tiny client a **Python** project imports to connect to Margin. It wraps your
+LLM calls and records their outcomes, emitting each one **over HTTP** to a
+Margin **ingest API** (`POST /api/ingest/calls` / `/api/ingest/outcomes`),
+authenticated with a per-project ingest key. This is the customer-shaped path —
+the same SDK a stranger drops in — not the in-process meter Margin runs on
+itself.
+
+- **Standalone + stdlib-only.** No dependency on Margin's server code and no
+  third-party deps. The default transport is `urllib`.
+- **Fail-safe.** A failed emit returns an `IngestResult(ok=False, …)` instead of
+  crashing your app. Pass `raise_on_error=True` for strict/CI behaviour.
+- **Provenance-honest.** `is_simulated` is carried through untouched; the written
+  `source` is forced server-side to your key's project — you cannot spoof
+  another project's economics.
+
+## Install
+
+Published as a git-installable subpath of the Margin repo (no PyPI account
+needed pre-launch):
+
+```bash
+pip install "git+https://github.com/subhsubh24/Margin.ai.git#subdirectory=sdk/python"
+```
+
+## Configure
+
+Two environment variables — the deployed API base and your project's key:
+
+```bash
+export MARGIN_INGEST_URL="https://margin-ai-rho.vercel.app"
+export MARGIN_INGEST_KEY="mgk_…"   # issued by the Margin owner (see below)
+```
+
+The Margin owner issues your project a key with the provisioning CLI in the
+Margin repo:
+
+```bash
+python3 scripts/issue_ingest_key.py <your-project-slug>
+```
+
+The raw `mgk_…` key is shown **once** — only its hash is stored. Give it to your
+project as `MARGIN_INGEST_KEY`.
+
+## Use
+
+```python
+from margin_meter import MarginMeter
+
+meter = MarginMeter()  # reads MARGIN_INGEST_URL + MARGIN_INGEST_KEY
+
+# 1) Wrap the LLM call — latency is timed automatically, cost computed server-side.
+with meter.measure(workflow_id="fit-scoring", provider="google",
+                   model="gemini-2.5-flash") as m:
+    resp = call_the_model(...)
+    m.set_tokens(input_tokens=1200, output_tokens=300, cache_read_tokens=800)
+
+# 2) Record the outcome it produced (the unit of productivity).
+meter.record_outcome(workflow_id="fit-scoring", passed=True,
+                     quality_score=0.94, quality_method="ground_truth")
+```
+
+Or record a call directly (when you already have the token counts):
+
+```python
+res = meter.record_call(
+    workflow_id="fit-scoring", provider="google", model="gemini-2.5-flash",
+    input_tokens=1200, output_tokens=300, cache_read_tokens=800,
+)
+if not res.ok:
+    log.warning("margin ingest failed: %s (%s)", res.error, res.status_code)
+```
+
+## API
+
+| Method | Emits to | Notes |
+| --- | --- | --- |
+| `record_call(...)` | `POST /api/ingest/calls` | cost computed from the pricing table when `cost_usd` omitted |
+| `record_outcome(...)` | `POST /api/ingest/outcomes` | `quality_method` records HOW the score was graded |
+| `measure(...)` | `record_call` on exit | context manager; times latency, `status="error"` on exception |
+
+Every method returns an `IngestResult(ok, status_code, body, error)`. `ok` is
+True only on HTTP 200; `body` holds `call_id`/`outcome_id` + `source`.
+
+## Testing against a live app (no network)
+
+The network boundary is a single `transport.post(path, json=..., headers=...)`
+protocol, which a FastAPI `TestClient` satisfies exactly — so you can exercise
+the real ingest endpoints hermetically by injecting one:
+
+```python
+from fastapi.testclient import TestClient
+import asgi
+from margin_meter import MarginMeter
+
+meter = MarginMeter(api_key=raw_key, transport=TestClient(asgi.app),
+                    raise_on_error=True)
+```
+
+## Rate + validation bounds
+
+Ingest is auth'd, validated, and rate-bounded server-side. A bad key → 401, a
+malformed/implausible row → 422, and a full rolling per-project window → 429.
+In fail-safe mode these come back as `IngestResult(ok=False, status_code=…)`.

margin_meter-0.1.0/margin_meter/__init__.py

@@ -0,0 +1,28 @@
+"""margin_meter — the Python SDK a project imports to connect to Margin.
+
+A tiny, stdlib-only client that wraps an LLM call and emits its measured
+economics (spend + outcome) to a Margin ingest API over HTTP. See
+:mod:`margin_meter.client` for the full contract.
+"""
+
+from margin_meter.client import (
+    CALLS_PATH,
+    OUTCOMES_PATH,
+    IngestResult,
+    MarginConfigError,
+    MarginIngestError,
+    MarginMeter,
+    MarginMeterError,
+)
+
+__all__ = [
+    "MarginMeter",
+    "IngestResult",
+    "MarginMeterError",
+    "MarginConfigError",
+    "MarginIngestError",
+    "CALLS_PATH",
+    "OUTCOMES_PATH",
+]
+
+__version__ = "0.1.0"

margin_meter-0.1.0/margin_meter/client.py

@@ -0,0 +1,373 @@
+"""The Python Margin meter client — emits call + outcome economics OVER HTTP.
+
+This is the importable library a Python sibling (JobScraper, LLM-Quant, or any
+real customer) drops in to connect to Margin. Unlike ``margin.meter`` (the
+in-process, DB-direct meter Margin uses on itself), this client is a *standalone*
+package with NO dependency on the ``margin`` server code: it wraps an LLM call
+and POSTs the measured row to Margin's ingest API (``POST /api/ingest/calls`` and
+``/api/ingest/outcomes``), authenticated with a per-project ingest key. That is
+the customer-shaped path — the same SDK a stranger would install.
+
+Design goals that shaped this module:
+
+- **Standalone + stdlib-only.** A sibling installs ``margin-meter`` and nothing
+  else — no server code, no heavy deps. The default transport is ``urllib``.
+- **Pluggable transport (hermetically testable).** The network boundary is a
+  single ``transport.post(path, json=..., headers=...) -> response`` protocol,
+  so a test can inject a FastAPI ``TestClient`` (which satisfies it exactly) and
+  exercise the real ingest endpoints with no socket. Production uses urllib.
+- **Fail-safe by default.** Telemetry must never crash the host app, so a failed
+  emit returns an :class:`IngestResult` with ``ok=False`` instead of raising.
+  Pass ``raise_on_error=True`` for strict/testing behaviour.
+- **Provenance-honest.** ``is_simulated`` is carried through untouched; a real
+  call stays real. The written ``source`` is forced server-side to the key's
+  project slug — the client cannot spoof another project's economics.
+
+Usage (a sibling wrapping its own call)::
+
+    from margin_meter import MarginMeter
+
+    meter = MarginMeter()  # reads MARGIN_INGEST_URL + MARGIN_INGEST_KEY
+
+    with meter.measure(workflow_id="fit-scoring", provider="google",
+                       model="gemini-2.5-flash") as m:
+        resp = call_the_model(...)
+        m.set_tokens(input_tokens=1200, output_tokens=300, cache_read_tokens=800)
+
+    meter.record_outcome(workflow_id="fit-scoring", passed=True,
+                         quality_score=0.94, quality_method="ground_truth")
+"""
+
+from __future__ import annotations
+
+import json as _json
+import os
+import time
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+from types import TracebackType
+from typing import Any, Optional
+
+CALLS_PATH = "/api/ingest/calls"
+OUTCOMES_PATH = "/api/ingest/outcomes"
+KEY_HEADER = "X-Margin-Key"
+
+DEFAULT_INGEST_URL = "http://127.0.0.1:8000"
+DEFAULT_TIMEOUT_S = 10.0
+
+
+class MarginMeterError(RuntimeError):
+    """Base error for the SDK."""
+
+
+class MarginConfigError(MarginMeterError):
+    """The client is missing required configuration (ingest URL or key)."""
+
+
+class MarginIngestError(MarginMeterError):
+    """A row was rejected by the ingest API (only raised when strict).
+
+    ``status_code`` is the HTTP status (401 bad key, 422 invalid row, 429 rate
+    cap) and ``detail`` the server's reason, so a strict caller gets an
+    actionable error instead of a silent drop.
+    """
+
+    def __init__(self, status_code: int, detail: str) -> None:
+        self.status_code = status_code
+        self.detail = detail
+        super().__init__(f"ingest rejected ({status_code}): {detail}")
+
+
+@dataclass
+class IngestResult:
+    """The outcome of one emit. Returned by every record call.
+
+    ``ok`` is True only on an HTTP 200. On failure ``status_code`` (0 for a
+    transport/network failure) and ``error`` carry the reason; ``body`` holds the
+    parsed success payload (``call_id``/``outcome_id`` + ``source``) when ok.
+    """
+
+    ok: bool
+    status_code: int
+    body: Optional[dict] = None
+    error: Optional[str] = None
+
+
+class _HttpResponse:
+    """Minimal response shape the urllib transport returns (mirrors TestClient)."""
+
+    def __init__(self, status_code: int, body: bytes) -> None:
+        self.status_code = status_code
+        self._body = body
+
+    def json(self) -> Any:
+        if not self._body:
+            return {}
+        return _json.loads(self._body.decode("utf-8"))
+
+
+class _UrllibTransport:
+    """The default transport: POST JSON over HTTP with the stdlib, no deps.
+
+    Satisfies the same ``post(path, json=..., headers=...)`` protocol a FastAPI
+    ``TestClient`` does, so the two are interchangeable — production uses this,
+    tests inject the TestClient.
+    """
+
+    def __init__(self, base_url: str, timeout: float = DEFAULT_TIMEOUT_S) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+
+    def post(self, path: str, json: dict, headers: dict) -> _HttpResponse:
+        url = self.base_url + path
+        data = _json.dumps(json).encode("utf-8")
+        req_headers = {"Content-Type": "application/json", **headers}
+        req = urllib.request.Request(url, data=data, headers=req_headers, method="POST")
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                return _HttpResponse(resp.status, resp.read())
+        except urllib.error.HTTPError as exc:
+            # A 4xx/5xx from the API — surface the status + body, don't raise.
+            return _HttpResponse(exc.code, exc.read())
+
+
+class MarginMeter:
+    """A per-project client that emits measured economics to a Margin ingest API.
+
+    Configuration is read from the environment when not passed explicitly:
+    ``MARGIN_INGEST_URL`` (the deployed API base) and ``MARGIN_INGEST_KEY`` (the
+    project's ``mgk_…`` key). A sibling typically constructs ``MarginMeter()``
+    with no args and lets the env drive it.
+    """
+
+    def __init__(
+        self,
+        *,
+        ingest_url: str | None = None,
+        api_key: str | None = None,
+        transport: Any = None,
+        timeout: float = DEFAULT_TIMEOUT_S,
+        raise_on_error: bool = False,
+    ) -> None:
+        self.ingest_url = ingest_url or os.environ.get("MARGIN_INGEST_URL") or DEFAULT_INGEST_URL
+        self.api_key = api_key or os.environ.get("MARGIN_INGEST_KEY")
+        self.raise_on_error = raise_on_error
+        # An injected transport (e.g. a TestClient) wins; else build the default.
+        self._transport = transport or _UrllibTransport(self.ingest_url, timeout=timeout)
+
+    # ------------------------------------------------------------------ #
+    # Core emit
+    # ------------------------------------------------------------------ #
+    def _emit(self, path: str, payload: dict) -> IngestResult:
+        if not self.api_key:
+            result = IngestResult(
+                ok=False,
+                status_code=0,
+                error="no ingest key (set MARGIN_INGEST_KEY or pass api_key)",
+            )
+            if self.raise_on_error:
+                raise MarginConfigError(result.error)
+            return result
+
+        headers = {KEY_HEADER: self.api_key}
+        try:
+            resp = self._transport.post(path, json=payload, headers=headers)
+        except Exception as exc:  # network/transport failure — fail-safe
+            result = IngestResult(ok=False, status_code=0, error=f"transport error: {exc}")
+            if self.raise_on_error:
+                raise MarginIngestError(0, str(exc)) from exc
+            return result
+
+        status = resp.status_code
+        if status == 200:
+            return IngestResult(ok=True, status_code=200, body=resp.json())
+
+        detail = self._extract_detail(resp)
+        if self.raise_on_error:
+            raise MarginIngestError(status, detail)
+        return IngestResult(ok=False, status_code=status, error=detail)
+
+    @staticmethod
+    def _extract_detail(resp: Any) -> str:
+        try:
+            body = resp.json()
+        except Exception:
+            return "unparseable error body"
+        if isinstance(body, dict) and "detail" in body:
+            return str(body["detail"])
+        return str(body)
+
+    # ------------------------------------------------------------------ #
+    # Public surface — mirrors margin.meter
+    # ------------------------------------------------------------------ #
+    def record_call(
+        self,
+        *,
+        workflow_id: str,
+        provider: str,
+        model: str,
+        input_tokens: int = 0,
+        output_tokens: int = 0,
+        cache_read_tokens: int = 0,
+        latency_ms: int = 0,
+        status: str = "ok",
+        is_retry: bool = False,
+        session_id: str | None = None,
+        prompt_id: str | None = None,
+        cost_usd: float | None = None,
+        is_simulated: bool = False,
+    ) -> IngestResult:
+        """Emit one measured LLM call to ``POST /api/ingest/calls``.
+
+        Cost is computed server-side from the pricing table when ``cost_usd`` is
+        omitted, so a sibling need only report tokens. Returns an
+        :class:`IngestResult` (never raises unless ``raise_on_error``).
+        """
+        payload: dict[str, Any] = {
+            "workflow_id": workflow_id,
+            "provider": provider,
+            "model": model,
+            "input_tokens": input_tokens,
+            "output_tokens": output_tokens,
+            "cache_read_tokens": cache_read_tokens,
+            "latency_ms": latency_ms,
+            "status": status,
+            "is_retry": is_retry,
+            "is_simulated": is_simulated,
+        }
+        if session_id is not None:
+            payload["session_id"] = session_id
+        if prompt_id is not None:
+            payload["prompt_id"] = prompt_id
+        if cost_usd is not None:
+            payload["cost_usd"] = cost_usd
+        return self._emit(CALLS_PATH, payload)
+
+    def record_outcome(
+        self,
+        *,
+        workflow_id: str,
+        passed: bool,
+        quality_score: float | None = None,
+        quality_method: str | None = None,
+        link: str | None = None,
+        is_simulated: bool = False,
+    ) -> IngestResult:
+        """Emit one outcome (a unit of productivity) to ``POST /api/ingest/outcomes``.
+
+        ``quality_method`` records HOW ``quality_score`` was graded (e.g.
+        ``ground_truth``, ``llm_judge``) so a self-report is never mistaken for a
+        graded number. Returns an :class:`IngestResult`.
+        """
+        payload: dict[str, Any] = {
+            "workflow_id": workflow_id,
+            "passed": passed,
+            "is_simulated": is_simulated,
+        }
+        if quality_score is not None:
+            payload["quality_score"] = quality_score
+        if quality_method is not None:
+            payload["quality_method"] = quality_method
+        if link is not None:
+            payload["link"] = link
+        return self._emit(OUTCOMES_PATH, payload)
+
+    def measure(
+        self,
+        *,
+        workflow_id: str,
+        provider: str,
+        model: str,
+        is_retry: bool = False,
+        session_id: str | None = None,
+        prompt_id: str | None = None,
+        is_simulated: bool = False,
+    ) -> "_Measure":
+        """A context manager that times a call and emits it on exit.
+
+        Mirrors ``margin.meter.measure`` but over HTTP. Set token counts inside
+        the block via :meth:`_Measure.set_tokens`; latency is timed
+        automatically. On an exception the call is still emitted with
+        ``status="error"`` and the exception re-raised. The emit's
+        :class:`IngestResult` is available as ``.result`` after the block.
+        """
+        return _Measure(
+            meter=self,
+            workflow_id=workflow_id,
+            provider=provider,
+            model=model,
+            is_retry=is_retry,
+            session_id=session_id,
+            prompt_id=prompt_id,
+            is_simulated=is_simulated,
+        )
+
+
+class _Measure:
+    """Context manager returned by :meth:`MarginMeter.measure`."""
+
+    def __init__(
+        self,
+        *,
+        meter: MarginMeter,
+        workflow_id: str,
+        provider: str,
+        model: str,
+        is_retry: bool,
+        session_id: str | None,
+        prompt_id: str | None,
+        is_simulated: bool,
+    ) -> None:
+        self._meter = meter
+        self.workflow_id = workflow_id
+        self.provider = provider
+        self.model = model
+        self.is_retry = is_retry
+        self.session_id = session_id
+        self.prompt_id = prompt_id
+        self.is_simulated = is_simulated
+        self.input_tokens = 0
+        self.output_tokens = 0
+        self.cache_read_tokens = 0
+        self.result: IngestResult | None = None
+        self._start = 0.0
+
+    def set_tokens(
+        self,
+        *,
+        input_tokens: int = 0,
+        output_tokens: int = 0,
+        cache_read_tokens: int = 0,
+    ) -> None:
+        self.input_tokens = input_tokens
+        self.output_tokens = output_tokens
+        self.cache_read_tokens = cache_read_tokens
+
+    def __enter__(self) -> "_Measure":
+        self._start = time.perf_counter()
+        return self
+
+    def __exit__(
+        self,
+        exc_type: Optional[type[BaseException]],
+        exc: Optional[BaseException],
+        tb: Optional[TracebackType],
+    ) -> None:
+        latency_ms = int((time.perf_counter() - self._start) * 1000)
+        self.result = self._meter.record_call(
+            workflow_id=self.workflow_id,
+            provider=self.provider,
+            model=self.model,
+            input_tokens=self.input_tokens,
+            output_tokens=self.output_tokens,
+            cache_read_tokens=self.cache_read_tokens,
+            latency_ms=latency_ms,
+            status="error" if exc_type is not None else "ok",
+            is_retry=self.is_retry,
+            session_id=self.session_id,
+            prompt_id=self.prompt_id,
+            is_simulated=self.is_simulated,
+        )
+        # Never suppress the host's exception.
+        return None

margin_meter-0.1.0/margin_meter.egg-info/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: margin-meter
+Version: 0.1.0
+Summary: Tiny stdlib-only client that emits LLM call + outcome economics to a Margin ingest API.
+Author: Margin
+License: MIT
+Project-URL: Homepage, https://github.com/subhsubh24/Margin.ai
+Project-URL: Source, https://github.com/subhsubh24/Margin.ai/tree/main/sdk/python
+Keywords: llm,cost,observability,finops,margin
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# margin-meter (Python SDK)
+
+The tiny client a **Python** project imports to connect to Margin. It wraps your
+LLM calls and records their outcomes, emitting each one **over HTTP** to a
+Margin **ingest API** (`POST /api/ingest/calls` / `/api/ingest/outcomes`),
+authenticated with a per-project ingest key. This is the customer-shaped path —
+the same SDK a stranger drops in — not the in-process meter Margin runs on
+itself.
+
+- **Standalone + stdlib-only.** No dependency on Margin's server code and no
+  third-party deps. The default transport is `urllib`.
+- **Fail-safe.** A failed emit returns an `IngestResult(ok=False, …)` instead of
+  crashing your app. Pass `raise_on_error=True` for strict/CI behaviour.
+- **Provenance-honest.** `is_simulated` is carried through untouched; the written
+  `source` is forced server-side to your key's project — you cannot spoof
+  another project's economics.
+
+## Install
+
+Published as a git-installable subpath of the Margin repo (no PyPI account
+needed pre-launch):
+
+```bash
+pip install "git+https://github.com/subhsubh24/Margin.ai.git#subdirectory=sdk/python"
+```
+
+## Configure
+
+Two environment variables — the deployed API base and your project's key:
+
+```bash
+export MARGIN_INGEST_URL="https://margin-ai-rho.vercel.app"
+export MARGIN_INGEST_KEY="mgk_…"   # issued by the Margin owner (see below)
+```
+
+The Margin owner issues your project a key with the provisioning CLI in the
+Margin repo:
+
+```bash
+python3 scripts/issue_ingest_key.py <your-project-slug>
+```
+
+The raw `mgk_…` key is shown **once** — only its hash is stored. Give it to your
+project as `MARGIN_INGEST_KEY`.
+
+## Use
+
+```python
+from margin_meter import MarginMeter
+
+meter = MarginMeter()  # reads MARGIN_INGEST_URL + MARGIN_INGEST_KEY
+
+# 1) Wrap the LLM call — latency is timed automatically, cost computed server-side.
+with meter.measure(workflow_id="fit-scoring", provider="google",
+                   model="gemini-2.5-flash") as m:
+    resp = call_the_model(...)
+    m.set_tokens(input_tokens=1200, output_tokens=300, cache_read_tokens=800)
+
+# 2) Record the outcome it produced (the unit of productivity).
+meter.record_outcome(workflow_id="fit-scoring", passed=True,
+                     quality_score=0.94, quality_method="ground_truth")
+```
+
+Or record a call directly (when you already have the token counts):
+
+```python
+res = meter.record_call(
+    workflow_id="fit-scoring", provider="google", model="gemini-2.5-flash",
+    input_tokens=1200, output_tokens=300, cache_read_tokens=800,
+)
+if not res.ok:
+    log.warning("margin ingest failed: %s (%s)", res.error, res.status_code)
+```
+
+## API
+
+| Method | Emits to | Notes |
+| --- | --- | --- |
+| `record_call(...)` | `POST /api/ingest/calls` | cost computed from the pricing table when `cost_usd` omitted |
+| `record_outcome(...)` | `POST /api/ingest/outcomes` | `quality_method` records HOW the score was graded |
+| `measure(...)` | `record_call` on exit | context manager; times latency, `status="error"` on exception |
+
+Every method returns an `IngestResult(ok, status_code, body, error)`. `ok` is
+True only on HTTP 200; `body` holds `call_id`/`outcome_id` + `source`.
+
+## Testing against a live app (no network)
+
+The network boundary is a single `transport.post(path, json=..., headers=...)`
+protocol, which a FastAPI `TestClient` satisfies exactly — so you can exercise
+the real ingest endpoints hermetically by injecting one:
+
+```python
+from fastapi.testclient import TestClient
+import asgi
+from margin_meter import MarginMeter
+
+meter = MarginMeter(api_key=raw_key, transport=TestClient(asgi.app),
+                    raise_on_error=True)
+```
+
+## Rate + validation bounds
+
+Ingest is auth'd, validated, and rate-bounded server-side. A bad key → 401, a
+malformed/implausible row → 422, and a full rolling per-project window → 429.
+In fail-safe mode these come back as `IngestResult(ok=False, status_code=…)`.

margin_meter-0.1.0/margin_meter.egg-info/SOURCES.txt

@@ -0,0 +1,8 @@
+README.md
+pyproject.toml
+margin_meter/__init__.py
+margin_meter/client.py
+margin_meter.egg-info/PKG-INFO
+margin_meter.egg-info/SOURCES.txt
+margin_meter.egg-info/dependency_links.txt
+margin_meter.egg-info/top_level.txt

margin_meter-0.1.0/margin_meter.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

margin_meter-0.1.0/margin_meter.egg-info/top_level.txt

@@ -0,0 +1 @@
+margin_meter

margin_meter-0.1.0/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "margin-meter"
+version = "0.1.0"
+description = "Tiny stdlib-only client that emits LLM call + outcome economics to a Margin ingest API."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Margin" }]
+keywords = ["llm", "cost", "observability", "finops", "margin"]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/subhsubh24/Margin.ai"
+Source = "https://github.com/subhsubh24/Margin.ai/tree/main/sdk/python"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["margin_meter*"]

margin_meter-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+