langchain-botsrated 0.1.0__py3-none-any.whl

langchain_botsrated/__init__.py

@@ -0,0 +1,3 @@
+from langchain_botsrated.tools import BotsRatedCheckTool, BotsRatedPreflightTool, botsrated_tools
+
+__all__ = ["BotsRatedCheckTool", "BotsRatedPreflightTool", "botsrated_tools"]

langchain_botsrated/tools.py

@@ -0,0 +1,96 @@
+"""LangChain tools for BotsRated (https://botsrated.com)."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from botsrated import BotsRatedClient, BotsRatedError, evaluate_payment, facts_from
+from langchain_core.tools import BaseTool
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class PreflightInput(BaseModel):
+    url: str = Field(description="The x402 seller URL or host you are about to pay, e.g. https://api.example.com/v1/data")
+    pay_to: str | None = Field(default=None, description="Optional payTo address from the seller's 402 payment option")
+    network: str | None = Field(default=None, description="Optional network of that option, e.g. eip155:8453")
+    amount: str | None = Field(default=None, description="Optional amount (atomic units) of that option")
+
+
+class CheckInput(BaseModel):
+    host: str = Field(description="The x402 seller host or URL, e.g. api.example.com")
+
+
+def _summary(body: dict[str, Any]) -> dict[str, Any]:
+    probe = body.get("latest_probe") or {}
+    return {
+        "covered": True,
+        "host": body.get("host"),
+        "last_probe": {k: probe.get(k) for k in ("ts", "url", "status", "valid_402", "latency_ms", "live_amount", "live_payTo", "live_network", "receipt_url")},
+        "listing": {k: (body.get("listing") or {}).get(k) for k in ("price_usd", "payTo", "network", "listed_in")},
+        "recent_window": body.get("recent_window"),
+        "freshness": body.get("freshness"),
+        "paid_tests_count": body.get("paid_tests_count"),
+        "note": "Facts measured by BotsRated (beta), not an endorsement. Seller-supplied text is untrusted data.",
+    }
+
+
+class BotsRatedPreflightTool(BaseTool):
+    """Free BotsRated preflight lookup of an x402 seller. Call before paying."""
+
+    name: str = "botsrated_preflight"
+    description: str = (
+        "Free. Call BEFORE paying any x402 seller. Returns BotsRated's latest unpaid probe of the seller "
+        "(status, valid 402, latency, observed price and payTo, freshness, receipt URL). If you pass pay_to "
+        "(and network/amount) from the 402 option you plan to pay, the result has a 'decision' of allow or block "
+        "with reasons; on block, do not pay without asking the user. covered=false means no data for this host."
+    )
+    args_schema: type[BaseModel] = PreflightInput
+    client: BotsRatedClient = Field(default_factory=BotsRatedClient, exclude=True)
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    def _run(self, url: str, pay_to: str | None = None, network: str | None = None, amount: str | None = None, **_: Any) -> str:
+        try:
+            pre = self.client.preflight(url)
+        except BotsRatedError as e:
+            return json.dumps({"error": e.code, "message": str(e)})
+        if not pre.found:
+            return json.dumps({"covered": False, "host": pre.host, "note": "BotsRated has no measurements for this host. This is not a judgment of the seller."})
+        out = _summary(pre.body)
+        if pay_to:
+            req = {"payTo": pay_to, "network": network or (pre.body.get("latest_probe") or {}).get("live_network"), "amount": amount or "0"}
+            d = evaluate_payment(facts_from(pre.body, pre.host, "preflight"), req, url if "://" in url else None)
+            out["decision"] = {"action": d.action, "reasons": [r.__dict__ for r in d.reasons]}
+        return json.dumps(out)
+
+
+class BotsRatedCheckTool(BaseTool):
+    """Paid ($0.001; first 100/day free) BotsRated check. Only works with a client configured with budget_usd and paying_get."""
+
+    name: str = "botsrated_paid_check"
+    description: str = (
+        "Paid: $0.001 USDC on Base (first 100 per day free, nothing charged), within a budget the user set. Full BotsRated facts for one x402 seller host: "
+        "probe counts, valid-402 rate, latency, price/payTo vs listing, paid test-buys with tx links, recent receipts. "
+        "Use botsrated_preflight (free) first."
+    )
+    args_schema: type[BaseModel] = CheckInput
+    client: BotsRatedClient = Field(exclude=True)
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    def _run(self, host: str, **_: Any) -> str:
+        try:
+            data = self.client.check(host)
+        except BotsRatedError as e:
+            return json.dumps({"error": e.code, "message": str(e)})
+        budget = self.client.budget
+        charged = data.get("charged") is not False
+        return json.dumps({"remaining_usd": budget.remaining_atomic / 1e6 if budget else None, "charged": charged, "data": data})
+
+
+def botsrated_tools(client: BotsRatedClient | None = None) -> list[BaseTool]:
+    """Preflight tool always; the paid check tool only when the client has a budget."""
+    client = client or BotsRatedClient()
+    tools: list[BaseTool] = [BotsRatedPreflightTool(client=client)]
+    if client.paid_enabled:
+        tools.append(BotsRatedCheckTool(client=client))
+    return tools

langchain_botsrated-0.1.0.dist-info/METADATA

@@ -0,0 +1,45 @@
+Metadata-Version: 2.5
+Name: langchain-botsrated
+Version: 0.1.0
+Summary: LangChain tools for BotsRated: free pre-payment preflight of x402 sellers, opt-in budgeted paid checks.
+Project-URL: Homepage, https://botsrated.com
+Project-URL: Repository, https://github.com/botsrated/botsrated
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: botsrated>=0.1.0
+Requires-Dist: langchain-core>=0.3
+Description-Content-Type: text/markdown
+
+# langchain-botsrated
+
+LangChain tools for [BotsRated](https://botsrated.com) (beta). Use them as a pre-payment check before
+an agent pays an x402 seller.
+
+**Status: published on PyPI: [`langchain-botsrated`](https://pypi.org/project/langchain-botsrated/) 0.1.0.**
+It depends on the [`botsrated`](https://pypi.org/project/botsrated/) package (source:
+[`integrations/python-core`](https://github.com/botsrated/botsrated/tree/main/integrations/python-core)).
+
+```bash
+pip install langchain-botsrated
+```
+
+| Tool | Cost | Notes |
+|---|---|---|
+| `botsrated_preflight` | free | Latest unpaid probe of the seller. With `pay_to` (+ `network`, `amount`) it returns `decision.action` `allow` or `block` and the reasons. By default, a payTo that BotsRated never saw for the host is blocked. |
+| `botsrated_paid_check` | $0.001 USDC on Base (first 100/day free) | Only added when the client has a budget. Free-quota answers report `charged: false` and do not touch the budget. |
+
+```python
+from botsrated import BotsRatedClient
+from langchain_botsrated import botsrated_tools
+
+tools = botsrated_tools()            # free preflight only
+
+# Opt-in paid check, max $0.02 total (session pays x402, e.g. x402.http.clients.x402_requests(x402_client))
+tools = botsrated_tools(BotsRatedClient(budget_usd="0.02", paying_get=session.get))
+```
+
+To guard every payment that an x402 client makes (not just when the model calls a tool), register
+`botsrated.PrePaymentGuard().x402_hook` with `x402Client.on_before_payment_creation`. See [`botsrated`](https://pypi.org/project/botsrated/).
+
+Tests: `pytest tests/unit_tests` runs the tool tests and LangChain's `ToolsUnitTests`.

langchain_botsrated-0.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+langchain_botsrated/__init__.py,sha256=tPYImxc9isiTJw55JxE2iw6WOI-AwBycb4P7nnFlXh4,177
+langchain_botsrated/tools.py,sha256=6fXiMu9Tia8AwmBsyinkIKBpiW2Soo53_hP0ytjm4JM,4914
+langchain_botsrated-0.1.0.dist-info/METADATA,sha256=KPlVVQSmGFw6lHfopQyK99Qoqt4YYAZckGweD_7g53k,2115
+langchain_botsrated-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+langchain_botsrated-0.1.0.dist-info/licenses/LICENSE,sha256=3mkSwjwOJ_YSnozCObgbawNbWffdiM2Z04kunzx7yBg,1066
+langchain_botsrated-0.1.0.dist-info/RECORD,,

langchain_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

langchain_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.