metrify-sdk 0.1.0__py3-none-any.whl

metrify/__init__.py

@@ -0,0 +1,20 @@
+from metrify.client import Metrify
+from metrify.exceptions import (
+    ConsumerSuspendedError,
+    GatewayError,
+    InsufficientBalanceError,
+    ProviderNotFoundError,
+    ProviderSuspendedError,
+    UpstreamError,
+)
+
+__all__ = [
+    "Metrify",
+    "UpstreamError",
+    "InsufficientBalanceError",
+    "ProviderSuspendedError",
+    "ConsumerSuspendedError",
+    "ProviderNotFoundError",
+    "GatewayError",
+]
+__version__ = "0.1.0"

metrify/billing.py

@@ -0,0 +1,85 @@
+import httpx
+
+from metrify.exceptions import (
+    ConsumerSuspendedError,
+    GatewayError,
+    InsufficientBalanceError,
+    ProviderNotFoundError,
+    ProviderSuspendedError,
+)
+from metrify.models import ChargeRequest, ChargeResponse
+
+_ERROR_MAP = {
+    "INSUFFICIENT_BALANCE": InsufficientBalanceError,
+    "PROVIDER_SUSPENDED": ProviderSuspendedError,
+    "CONSUMER_SUSPENDED": ConsumerSuspendedError,
+    "PROVIDER_NOT_FOUND": ProviderNotFoundError,
+}
+
+_TIMEOUT = 10.0
+
+
+class BillingClient:
+    def __init__(self, gateway_url: str, provider_key: str) -> None:
+        self._gateway_url = gateway_url.rstrip("/")
+        self._provider_key = provider_key
+
+    def check_balance(self, consumer_api_key: str, required: float) -> None:
+        """Verify consumer has at least `required` balance without charging.
+
+        Raises InsufficientBalanceError or GatewayError on failure.
+        """
+        try:
+            with httpx.Client(timeout=_TIMEOUT) as client:
+                response = client.get(
+                    f"{self._gateway_url}/consumers/me",
+                    headers={"X-API-Key": consumer_api_key},
+                )
+        except (httpx.TimeoutException, httpx.NetworkError, httpx.TransportError) as exc:
+            raise GatewayError(f"Request to billing gateway failed: {exc}") from exc
+
+        if response.status_code >= 500:
+            raise GatewayError(f"Billing gateway returned {response.status_code}")
+
+        if not response.is_success:
+            self._raise_api_error(response)
+
+        balance = float(response.json().get("balance", 0.0))
+        if balance < required:
+            raise InsufficientBalanceError(
+                f"Consumer balance {balance:.4f} is insufficient for cost {required:.4f}"
+            )
+
+    def charge(self, consumer_api_key: str, tool_name: str, cost: float) -> ChargeResponse:
+        request = ChargeRequest(
+            provider_key=self._provider_key,
+            tool_name=tool_name,
+            cost=cost,
+        )
+        try:
+            with httpx.Client(timeout=_TIMEOUT) as client:
+                response = client.post(
+                    f"{self._gateway_url}/billing/charge",
+                    json=request.model_dump(),
+                    headers={"X-API-Key": consumer_api_key},
+                )
+        except (httpx.TimeoutException, httpx.NetworkError, httpx.TransportError) as exc:
+            raise GatewayError(f"Request to billing gateway failed: {exc}") from exc
+
+        if response.status_code >= 500:
+            raise GatewayError(f"Billing gateway returned {response.status_code}")
+
+        if not response.is_success:
+            self._raise_api_error(response)
+
+        return ChargeResponse.model_validate(response.json())
+
+    def _raise_api_error(self, response: httpx.Response) -> None:
+        try:
+            body = response.json()
+            error_code = body.get("error") or body.get("code") or ""
+        except Exception:
+            error_code = ""
+
+        exc_class = _ERROR_MAP.get(error_code, GatewayError)
+        raise exc_class(f"Billing gateway error {response.status_code}: {error_code}")

metrify/client.py

@@ -0,0 +1,47 @@
+import os
+from typing import Callable, Optional
+
+from dotenv import load_dotenv
+
+from metrify.billing import BillingClient
+from metrify.decorator import make_tool_decorator
+from metrify.models import BillingUnit
+
+load_dotenv()
+
+_DEFAULT_GATEWAY_URL = "https://airy-wholeness-production-fcc4.up.railway.app"
+
+
+class Metrify:
+    def __init__(
+        self,
+        provider_key: Optional[str] = None,
+        gateway_url: Optional[str] = None,
+    ) -> None:
+        resolved_key = provider_key or os.environ.get("METRIFY_PROVIDER_KEY")
+        if not resolved_key:
+            raise ValueError(
+                "provider_key is required. Pass it to Metrify(provider_key=...) "
+                "or set the METRIFY_PROVIDER_KEY environment variable."
+            )
+
+        resolved_url = (
+            gateway_url
+            or os.environ.get("METRIFY_GATEWAY_URL")
+            or _DEFAULT_GATEWAY_URL
+        )
+
+        self._provider_key = resolved_key
+        self._gateway_url = resolved_url
+        self._billing = BillingClient(gateway_url=resolved_url, provider_key=resolved_key)
+
+    def tool(self, price: float, unit: BillingUnit = "per_call") -> Callable:
+        def decorator(func: Callable) -> Callable:
+            return make_tool_decorator(
+                billing=self._billing,
+                price=price,
+                unit=unit,
+                tool_name=func.__name__,
+            )(func)
+
+        return decorator

metrify/decorator.py

@@ -0,0 +1,65 @@
+import functools
+import inspect
+from typing import Any, Callable
+
+from metrify.billing import BillingClient
+from metrify.exceptions import GatewayError, InsufficientBalanceError, UpstreamError
+from metrify.models import BillingUnit
+
+
+def _extract_consumer_key(args: tuple, kwargs: dict, func: Callable) -> str:
+    if "consumer_api_key" in kwargs:
+        return kwargs["consumer_api_key"]
+
+    sig = inspect.signature(func)
+    params = list(sig.parameters.keys())
+    if params and params[0] == "consumer_api_key" and args:
+        return args[0]
+
+    raise TypeError(
+        f"{func.__name__}() missing required argument 'consumer_api_key'. "
+        "Pass it as the first positional argument or as a keyword argument."
+    )
+
+
+def make_tool_decorator(
+    billing: BillingClient,
+    price: float,
+    unit: BillingUnit,
+    tool_name: str,
+) -> Callable:
+    def decorator(func: Callable) -> Callable:
+        if inspect.iscoroutinefunction(func):
+            @functools.wraps(func)
+            async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
+                consumer_api_key = _extract_consumer_key(args, kwargs, func)
+                billing.check_balance(consumer_api_key=consumer_api_key, required=price)
+                try:
+                    result = await func(*args, **kwargs)
+                except UpstreamError as exc:
+                    return str(exc)
+                except (InsufficientBalanceError, GatewayError):
+                    raise
+                except Exception as exc:
+                    return f"Tool error: {exc}"
+                billing.charge(consumer_api_key=consumer_api_key, tool_name=tool_name, cost=price)
+                return result
+            return async_wrapper
+        else:
+            @functools.wraps(func)
+            def sync_wrapper(*args: Any, **kwargs: Any) -> Any:
+                consumer_api_key = _extract_consumer_key(args, kwargs, func)
+                billing.check_balance(consumer_api_key=consumer_api_key, required=price)
+                try:
+                    result = func(*args, **kwargs)
+                except UpstreamError as exc:
+                    return str(exc)
+                except (InsufficientBalanceError, GatewayError):
+                    raise
+                except Exception as exc:
+                    return f"Tool error: {exc}"
+                billing.charge(consumer_api_key=consumer_api_key, tool_name=tool_name, cost=price)
+                return result
+            return sync_wrapper
+
+    return decorator

metrify/exceptions.py

@@ -0,0 +1,37 @@
+class MetrifyError(Exception):
+    """Base exception for all metrify SDK errors."""
+
+
+class InsufficientBalanceError(MetrifyError):
+    """Consumer does not have enough balance to pay for the tool call."""
+
+
+class ProviderSuspendedError(MetrifyError):
+    """The provider account has been suspended."""
+
+
+class ConsumerSuspendedError(MetrifyError):
+    """The consumer account has been suspended."""
+
+
+class ProviderNotFoundError(MetrifyError):
+    """The provider key is invalid or not registered."""
+
+
+class GatewayError(MetrifyError):
+    """Network error, timeout, or backend returned a 5xx response."""
+
+
+class UpstreamError(MetrifyError):
+    """Raised by a tool when an upstream/external API fails.
+
+    The decorator catches this, skips billing, and returns the message to the
+    consumer as a formatted error string.
+
+    Example::
+
+        try:
+            result = await anthropic_client.complete(...)
+        except anthropic.APIError as e:
+            raise UpstreamError(f"Anthropic API error: {e.message}")
+    """

metrify/models.py

@@ -0,0 +1,25 @@
+from typing import Literal
+from pydantic import BaseModel
+
+BillingUnit = Literal["per_call", "per_token", "per_minute", "per_image", "per_page"]
+
+
+class ChargeRequest(BaseModel):
+    provider_key: str
+    tool_name: str
+    cost: float
+
+
+class ChargeResponse(BaseModel):
+    transaction_id: str
+    status: str
+    cost: float
+    provider_share: float
+    metrify_fee: float
+    consumer_balance_after: float
+
+
+class ToolConfig(BaseModel):
+    name: str
+    price: float
+    unit: BillingUnit

metrify_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,176 @@
+Metadata-Version: 2.1
+Name: metrify-sdk
+Version: 0.1.0
+Summary: Billing SDK for MCP servers
+License: MIT
+Project-URL: Homepage, https://github.com/mangelico/metrify-sdk
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: python-dotenv>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: pytest-mock>=3.12; extra == "dev"
+Requires-Dist: respx>=0.21; extra == "dev"
+
+# metrify
+
+**Billing SDK for MCP servers.** Add pay-per-call monetization to any MCP tool
+in under 5 minutes — no payment infrastructure required.
+
+---
+
+## Quickstart
+
+### 1. Register as a provider
+
+Sign up at the Metrify dashboard and get your `pk_live_...` provider key.
+
+### 2. Install the SDK
+
+```bash
+pip install metrify
+```
+
+### 3. Configure your provider key
+
+```bash
+export METRIFY_PROVIDER_KEY="pk_live_your_key_here"
+```
+
+Or pass it directly in code (see step 4).
+
+### 4. Decorate your tools
+
+```python
+from metrify import Metrify
+
+m = Metrify()  # reads METRIFY_PROVIDER_KEY from env
+
+@m.tool(price=0.01, unit="per_call")
+async def summarize(consumer_api_key: str, text: str) -> str:
+    # Balance is pre-checked before this runs; charge happens only on success
+    return f"Summary of: {text[:50]}..."
+```
+
+### 5. Deploy
+
+Your tool now charges consumers on every call. The `consumer_api_key` is
+extracted automatically by the decorator — consumers pass it as the first
+argument or as a keyword argument.
+
+---
+
+## Full example with FastMCP
+
+```python
+from metrify import Metrify
+from mcp.server.fastmcp import FastMCP
+
+m = Metrify(provider_key="pk_live_your_key_here")
+server = FastMCP("my-mcp-server")
+
+@server.tool()
+@m.tool(price=0.05, unit="per_call")
+async def analyze_document(consumer_api_key: str, content: str) -> str:
+    """Analyze a document and return insights."""
+    # billing.charge() runs before this line
+    analysis = await run_analysis(content)
+    return analysis
+
+@server.tool()
+@m.tool(price=0.001, unit="per_token")
+async def generate_text(consumer_api_key: str, prompt: str) -> str:
+    """Generate text from a prompt."""
+    result = await llm.complete(prompt)
+    return result
+```
+
+---
+
+## Billing flow
+
+The decorator runs a **two-phase billing** flow on every call:
+
+1. **Pre-check** — verify the consumer has enough balance (no charge yet).
+2. **Execute** — run your tool function.
+3. **Charge** — deduct only if the function completed without error.
+
+If the function raises any exception the consumer is never charged.
+
+## Exception reference
+
+| Exception | Raised by | Behavior |
+|-----------|-----------|----------|
+| `InsufficientBalanceError` | Pre-check | Propagated — consumer has no funds |
+| `UpstreamError` | Your tool | Caught — returns message to consumer, no charge |
+| `ProviderSuspendedError` | Pre-check / charge | Propagated — your account is suspended |
+| `ConsumerSuspendedError` | Pre-check / charge | Propagated — consumer account is suspended |
+| `ProviderNotFoundError` | Pre-check / charge | Propagated — your provider key is invalid |
+| `GatewayError` | Pre-check / charge | Propagated — network error or backend 5xx |
+| Any other `Exception` | Your tool | Caught — returns `"Tool error: ..."`, no charge |
+
+### Signalling upstream failures with `UpstreamError`
+
+Use `UpstreamError` when an external API your tool depends on fails. The
+decorator catches it, skips billing, and returns your message to the consumer:
+
+```python
+from metrify import Metrify, UpstreamError
+
+m = Metrify()
+
+@m.tool(price=0.05, unit="per_call")
+async def summarize(consumer_api_key: str, text: str) -> str:
+    try:
+        result = await anthropic_client.messages.create(...)
+    except anthropic.APIError as e:
+        raise UpstreamError(f"Anthropic API error: {e.message}")
+    return result.content[0].text
+```
+
+The consumer receives `"Anthropic API error: ..."` and is not charged.
+
+```python
+from metrify.exceptions import InsufficientBalanceError, GatewayError
+
+# In your MCP server error handler:
+try:
+    result = await my_tool(consumer_api_key=ck, query=q)
+except InsufficientBalanceError:
+    return "Insufficient balance. Please top up at the Metrify dashboard."
+except GatewayError:
+    return "Billing service temporarily unavailable. Please retry."
+```
+
+---
+
+## Environment variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `METRIFY_PROVIDER_KEY` | — | Your provider key (`pk_live_...`) |
+| `METRIFY_GATEWAY_URL` | `https://airy-wholeness-production-fcc4.up.railway.app` | Override backend URL |
+
+---
+
+## Supported billing units (V1)
+
+All units charge a flat `price` per call. The `unit` field is displayed in your
+dashboard for reporting purposes.
+
+| Unit | Use case |
+|------|----------|
+| `per_call` | Fixed price per tool invocation |
+| `per_token` | LLM completions (flat in V1) |
+| `per_minute` | Audio/video processing |
+| `per_image` | Image generation or analysis |
+| `per_page` | Document processing |
+
+---
+
+## License
+
+MIT

metrify_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+metrify/__init__.py,sha256=LkFYq9U0TIJbdOm_HJ7wYd4azvvM51kuX4spIbQR06M,434
+metrify/billing.py,sha256=iS-5MQYd2Htsb3Y4WcGUjsIgqml6q-D8QlcW4S9i5J4,3129
+metrify/client.py,sha256=X_F6pL0srSIi75Zy93LVAGaAv2fi83l9KfLcsQStOVM,1439
+metrify/decorator.py,sha256=WMTrlD6bio5hhzawPdzlQ6wVAz6kdyUIXDnPPi2YznU,2522
+metrify/exceptions.py,sha256=XgNYGpMkUjCAPNT8jz66XDC9JDZwjYCpG8iImTvkLek,1031
+metrify/models.py,sha256=_UYhZ_ge32j4oW_f5-YTE8SnCFchL0LTGCnAwny-ZGo,494
+metrify_sdk-0.1.0.dist-info/METADATA,sha256=f46sjpS6jX9ff2-mRTO6Nw044tEaOeOy4Zwshs0RtCk,5268
+metrify_sdk-0.1.0.dist-info/WHEEL,sha256=BNRMDyzLkkcmlv0J8ppDQkk2VED33SesJDynr9ED1gc,91
+metrify_sdk-0.1.0.dist-info/top_level.txt,sha256=aMBu6UysoY7pXDQfpfXLpTWXGV0tOgnX95Ha8t0tOFY,8
+metrify_sdk-0.1.0.dist-info/RECORD,,

metrify_sdk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (75.3.4)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

metrify_sdk-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+metrify