agent-framework-botsrated 0.1.0__py3-none-any.whl

agent_framework_botsrated/__init__.py

@@ -0,0 +1,28 @@
+"""BotsRated pre-payment checks for Microsoft Agent Framework (Python)."""
+
+from agent_framework_botsrated._middleware import (
+    DECISION_METADATA_KEY,
+    BotsRatedPaymentBlocked,
+    BotsRatedPaymentMiddleware,
+    PaymentQuote,
+    QuoteExtractor,
+    botsrated_check_payment_tool,
+    decision_to_dict,
+    default_quote_extractor,
+)
+
+BOTSRATED_MCP_URL = "https://botsrated.com/mcp"
+"""BotsRated's remote MCP server (streamable HTTP, no auth). Free tools: preflight, coverage, sample, history."""
+
+__all__ = [
+    "BOTSRATED_MCP_URL",
+    "DECISION_METADATA_KEY",
+    "BotsRatedPaymentBlocked",
+    "BotsRatedPaymentMiddleware",
+    "PaymentQuote",
+    "QuoteExtractor",
+    "botsrated_check_payment_tool",
+    "decision_to_dict",
+    "default_quote_extractor",
+]
+__version__ = "0.1.0"

agent_framework_botsrated/_middleware.py

@@ -0,0 +1,168 @@
+"""BotsRated pre-payment check for Microsoft Agent Framework function tools."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from collections.abc import Awaitable, Callable, Collection, Mapping
+from dataclasses import dataclass
+from typing import Annotated, Any, Literal
+
+from agent_framework import FunctionInvocationContext, FunctionMiddleware, FunctionTool, MiddlewareFailure, tool
+from botsrated import BotsRatedClient, Decision, PrePaymentGuard, Reason
+from pydantic import BaseModel, Field
+
+DECISION_METADATA_KEY = "botsrated_decision"
+"""Key of the ``botsrated.Decision`` stored in ``FunctionInvocationContext.metadata`` for checked calls."""
+
+DEFAULT_NETWORK = "eip155:8453"
+
+
+@dataclass(frozen=True)
+class PaymentQuote:
+    """The x402 payment option a payment tool is about to pay."""
+
+    url: str
+    pay_to: str
+    amount: str
+    network: str = DEFAULT_NETWORK
+    scheme: str = "exact"
+
+    def requirements(self) -> dict[str, str]:
+        return {"scheme": self.scheme, "network": self.network, "payTo": self.pay_to, "amount": self.amount}
+
+
+QuoteExtractor = Callable[[Mapping[str, Any]], PaymentQuote]
+"""Reads the payment quote from a payment tool's arguments. Raise any exception if it can't."""
+
+
+def _first(args: Mapping[str, Any], *names: str) -> Any:
+    for name in names:
+        value = args.get(name)
+        if value not in (None, ""):
+            return value
+    return None
+
+
+def default_quote_extractor(args: Mapping[str, Any]) -> PaymentQuote:
+    """Read ``url``, ``pay_to`` (or ``payTo``), ``amount`` and optional ``network``/``scheme`` arguments."""
+    url = _first(args, "url", "resource_url", "resource")
+    pay_to = _first(args, "pay_to", "payTo")
+    amount = _first(args, "amount", "amount_atomic", "max_amount_required", "maxAmountRequired")
+    if not isinstance(url, str) or not isinstance(pay_to, str) or amount is None:
+        missing = [n for n, v in (("url", url), ("pay_to", pay_to), ("amount", amount)) if v is None]
+        raise ValueError(f"payment arguments are missing or not text: {', '.join(missing) or 'url/pay_to'}")
+    if isinstance(amount, bool) or not str(amount).isdigit():
+        raise ValueError("amount must be an integer number of atomic units")
+    network = _first(args, "network") or DEFAULT_NETWORK
+    scheme = _first(args, "scheme") or "exact"
+    return PaymentQuote(url=url, pay_to=pay_to, amount=str(amount), network=str(network), scheme=str(scheme))
+
+
+class BotsRatedPaymentBlocked(MiddlewareFailure):
+    """Raised for a blocked payment when the middleware uses ``on_block="raise"``. It ends the run."""
+
+    def __init__(self, decision: Decision) -> None:
+        super().__init__(decision.summary())
+        self.decision = decision
+
+
+def _as_mapping(arguments: BaseModel | Mapping[str, Any]) -> Mapping[str, Any]:
+    if isinstance(arguments, BaseModel):
+        return arguments.model_dump(mode="json")
+    return arguments
+
+
+class BotsRatedPaymentMiddleware(FunctionMiddleware):
+    """Function middleware that checks an x402 payment with BotsRated before a payment tool runs.
+
+    Only the functions named in ``payment_tools`` are checked; every other call passes through
+    untouched. For a payment tool, the middleware reads the quote (URL, payTo, amount, network)
+    from the call's arguments and asks BotsRated's free preflight (no key, no wallet) whether
+    that payTo was observed for the seller. A blocked call never reaches ``call_next``: the
+    reason becomes the call's result, so the model reads it, or with ``on_block="raise"`` the
+    run ends with ``BotsRatedPaymentBlocked``.
+
+    Default policy (from ``botsrated.GuardPolicy``): a payTo that BotsRated has not seen for the
+    host is blocked; an uncovered host or stale data is allowed; a price above the observed one
+    is a warning. If BotsRated can't be reached, the payment is allowed (``fail_open=True`` on
+    the guard). If the quote can't be read from the arguments, the call is blocked.
+
+    Args:
+        payment_tools: Names of the payment functions to check, or a mapping from name to a
+            ``QuoteExtractor`` (``None`` uses ``default_quote_extractor``).
+        guard: A ``botsrated.PrePaymentGuard``. Defaults to a free-only guard (nothing is paid).
+        on_block: ``"result"`` (default) returns the reason as the call's result; ``"raise"`` ends the run.
+    """
+
+    def __init__(
+        self,
+        payment_tools: Collection[str] | Mapping[str, QuoteExtractor | None],
+        *,
+        guard: PrePaymentGuard | None = None,
+        on_block: Literal["result", "raise"] = "result",
+    ) -> None:
+        if isinstance(payment_tools, str):
+            payment_tools = [payment_tools]
+        if isinstance(payment_tools, Mapping):
+            self.extractors: dict[str, QuoteExtractor] = {
+                name: extractor or default_quote_extractor for name, extractor in payment_tools.items()
+            }
+        else:
+            self.extractors = {name: default_quote_extractor for name in payment_tools}
+        if not self.extractors:
+            raise ValueError("payment_tools must name at least one payment function")
+        self.guard = guard or PrePaymentGuard(BotsRatedClient())
+        self.on_block = on_block
+
+    async def process(
+        self,
+        context: FunctionInvocationContext,
+        call_next: Callable[[], Awaitable[None]],
+    ) -> None:
+        extractor = self.extractors.get(context.function.name)
+        if extractor is None:
+            await call_next()
+            return
+        try:
+            quote = extractor(_as_mapping(context.arguments))
+        except Exception as error:  # noqa: BLE001 - any unreadable quote fails closed
+            decision = Decision("block", None, [Reason("quote_unreadable", str(error), "block")])
+        else:
+            decision = await asyncio.to_thread(self.guard.decide, quote.url, quote.requirements())
+        context.metadata[DECISION_METADATA_KEY] = decision
+        if self.guard.on_decision:
+            self.guard.on_decision(decision)
+        if decision.action == "allow":
+            await call_next()
+            return
+        if self.on_block == "raise":
+            raise BotsRatedPaymentBlocked(decision)
+        context.result = f"Payment tool '{context.function.name}' was not executed. {decision.summary()}"
+
+
+def decision_to_dict(decision: Decision) -> dict[str, Any]:
+    return {
+        "action": decision.action,
+        "host": decision.host,
+        "reasons": [{"code": r.code, "detail": r.detail, "effect": r.effect} for r in decision.reasons],
+        "receipt_url": decision.facts.receipt_url if decision.facts else None,
+    }
+
+
+def botsrated_check_payment_tool(guard: PrePaymentGuard | None = None) -> FunctionTool:
+    """A function tool the model can call to check an x402 payment option before paying it (free preflight)."""
+    checker = guard or PrePaymentGuard(BotsRatedClient())
+
+    async def botsrated_check_payment(
+        url: Annotated[str, Field(description="The seller URL you are about to pay.")],
+        pay_to: Annotated[str, Field(description="The payTo address from the seller's 402 payment option.")],
+        amount: Annotated[str, Field(description="The amount in atomic units from that option.")],
+        network: Annotated[str, Field(description="The CAIP-2 network of that option.")] = DEFAULT_NETWORK,
+    ) -> str:
+        """Check an x402 payment option against BotsRated's measurements BEFORE paying it."""
+        quote = PaymentQuote(url=url, pay_to=pay_to, amount=amount, network=network)
+        decision = await asyncio.to_thread(checker.decide, quote.url, quote.requirements())
+        return json.dumps(decision_to_dict(decision))
+
+    return tool(botsrated_check_payment)

agent_framework_botsrated-0.1.0.dist-info/METADATA

@@ -0,0 +1,127 @@
+Metadata-Version: 2.5
+Name: agent-framework-botsrated
+Version: 0.1.0
+Summary: BotsRated pre-payment check for Microsoft Agent Framework: function middleware that checks an x402 payTo with the free BotsRated preflight before a payment tool runs.
+Project-URL: Homepage, https://botsrated.com
+Project-URL: Repository, https://github.com/botsrated/botsrated
+Project-URL: Documentation, https://github.com/botsrated/botsrated/blob/main/integrations/microsoft-agent-framework/README.md
+Project-URL: Issues, https://github.com/botsrated/botsrated/issues
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent-framework,base,botsrated,microsoft-agent-framework,middleware,payments,usdc,x402
+Requires-Python: >=3.10
+Requires-Dist: agent-framework-core<2,>=1.22
+Requires-Dist: botsrated<0.2,>=0.1.2
+Provides-Extra: mcp
+Requires-Dist: mcp<3,>=1.24; extra == 'mcp'
+Requires-Dist: tenacity<10,>=9.1.4; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# agent-framework-botsrated: BotsRated pre-payment check for Microsoft Agent Framework (Python)
+
+Function middleware for [Microsoft Agent Framework](https://github.com/microsoft/agent-framework) that checks an
+x402 payment with [BotsRated](https://botsrated.com) **before a payment tool runs**. BotsRated probes x402 sellers on
+Base and records which `payTo` wallet each one actually quoted. The middleware asks BotsRated's free preflight
+(no API key, no wallet) whether the `payTo` your agent is about to pay was observed for that seller, and stops the call
+if it wasn't.
+
+Maintained by BotsRated, not by Microsoft. Issues: https://github.com/botsrated/botsrated/issues/new
+
+## Install
+
+```bash
+pip install "agent-framework-botsrated @ git+https://github.com/botsrated/botsrated#subdirectory=integrations/microsoft-agent-framework"
+# with the hosted MCP server example:
+pip install "agent-framework-botsrated[mcp] @ git+https://github.com/botsrated/botsrated#subdirectory=integrations/microsoft-agent-framework"
+```
+
+Requires Python 3.10+, `agent-framework-core>=1.22,<2` and [`botsrated`](https://pypi.org/project/botsrated/) 0.1.2+.
+Tested with agent-framework-core 1.22.0 (with mcp 1.30) and 1.23.0 (with mcp 2.3). agent-framework-core 1.22 can't
+initialize MCP sessions with mcp 2.x, so pin `mcp<2` there if you use the hosted MCP server.
+
+## Middleware: check payments before they run
+
+```python
+from agent_framework import Agent
+from agent_framework_botsrated import BotsRatedPaymentMiddleware
+
+
+def pay_x402(url: str, pay_to: str, amount: str, network: str = "eip155:8453") -> str:
+    """Pay an x402 seller."""
+    ...  # your payment code
+
+
+agent = Agent(
+    client=chat_client,
+    tools=[pay_x402],
+    middleware=[BotsRatedPaymentMiddleware(["pay_x402"])],
+)
+```
+
+- Only the functions you name are checked. Every other function call passes through untouched.
+- The quote is read from the call's arguments: `url`, `pay_to` (or `payTo`), `amount` (atomic units) and optional
+  `network` (CAIP-2, default `eip155:8453`). For other argument names pass an extractor:
+  `BotsRatedPaymentMiddleware({"buy": lambda a: PaymentQuote(url=a["endpoint"], pay_to=a["recipient"], amount=str(a["atomic"]))})`.
+- A blocked call never reaches `call_next`. The reason (with a link to the BotsRated probe receipt) becomes the call's
+  result, so the model reads it. With `on_block="raise"` the run ends with `BotsRatedPaymentBlocked` (a
+  `MiddlewareFailure`).
+- The `botsrated.Decision` is stored in `context.metadata["botsrated_decision"]`; `guard.on_decision` is also called.
+
+Default policy (from `botsrated.GuardPolicy`, configurable through `guard=PrePaymentGuard(policy=...)`):
+
+| Situation | Result |
+|---|---|
+| `payTo` never observed by BotsRated for that host (same network) | **blocked** (`payto_mismatch`) |
+| Quote can't be read from the arguments | **blocked** (`quote_unreadable`) |
+| Price above the last observed price on the same route | allowed with a warning |
+| Host not covered, or data older than 24 h | allowed (info) |
+| BotsRated unreachable | allowed (`fail_open=True`); set `PrePaymentGuard(fail_open=False)` to block |
+
+The middleware checks what the payment tool was asked to pay. If your tool fetches the 402 itself and signs it, also
+register `botsrated.PrePaymentGuard().x402_hook` on your `x402Client`'s `on_before_payment_creation` so the check
+runs on the exact quote being signed.
+
+## Tool: let the model check a payment option
+
+```python
+from agent_framework_botsrated import botsrated_check_payment_tool
+
+agent = Agent(client=chat_client, tools=[botsrated_check_payment_tool(), pay_x402])
+```
+
+`botsrated_check_payment(url, pay_to, amount, network)` returns JSON with `action` (`allow`/`block`), `reasons` and
+`receipt_url`. It uses the free preflight only.
+
+## Hosted MCP server (no package needed)
+
+BotsRated also runs a remote MCP server (streamable HTTP, no auth). Its free tools are `preflight`, `coverage`,
+`sample` and `history`:
+
+```python
+from agent_framework import MCPStreamableHTTPTool
+
+botsrated_mcp = MCPStreamableHTTPTool(
+    name="botsrated",
+    url="https://botsrated.com/mcp",
+    allowed_tools=["preflight", "coverage", "sample", "history"],
+)
+async with botsrated_mcp:
+    result = await Agent(client=chat_client, tools=[botsrated_mcp]).run("Is blockrun.ai a known x402 seller?")
+```
+
+The paid lookups (`check` $0.001, `report` $0.002, `best` $0.01 USDC on Base; the first 100 checks and 10 reports per
+client per day are free) are not used by this package unless you pass a paid-enabled `BotsRatedClient` to the guard.
+
+## Run the example and tests
+
+```bash
+pip install -e ".[mcp]" pytest pytest-asyncio
+python examples/quickstart.py   # scripted model, real free preflight, stub payment
+pytest -m "not live"            # offline
+pytest -m live                  # real free BotsRated preflight + hosted MCP server; nothing is paid
+```
+
+`examples/quickstart.py` uses a scripted chat client instead of a model, so it runs without an API key. One payment
+call uses an unknown `payTo` and is blocked; the other uses the `payTo` BotsRated observed for blockrun.ai and runs.
+
+BotsRated results are measurements, not endorsements. MIT licensed.

agent_framework_botsrated-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+agent_framework_botsrated/__init__.py,sha256=JS6gucnzE3OTWNgM5pwkGB3RqsS-7_HMLTkCR8szvic,793
+agent_framework_botsrated/_middleware.py,sha256=2DttyywIlrOBb7IWFY50h-b7j1M7rIHBtgqtFNkBNR0,7740
+agent_framework_botsrated/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+agent_framework_botsrated-0.1.0.dist-info/METADATA,sha256=wSCGL6rUANn8Y93roKoMajbx3bhG28P2v0yhk8QEhw4,6147
+agent_framework_botsrated-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+agent_framework_botsrated-0.1.0.dist-info/licenses/LICENSE,sha256=3mkSwjwOJ_YSnozCObgbawNbWffdiM2Z04kunzx7yBg,1066
+agent_framework_botsrated-0.1.0.dist-info/RECORD,,

agent_framework_botsrated-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

agent_framework_botsrated-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BotsRated
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.