hermes-spend 0.1.0__tar.gz

hermes_spend-0.1.0/PKG-INFO

@@ -0,0 +1,221 @@
+Metadata-Version: 2.4
+Name: hermes-spend
+Version: 0.1.0
+Summary: Native wallet, service registration, and reputation ledger for Hermes Agent. Implements Hermes issue #38280.
+License: Apache-2.0
+Project-URL: Homepage, https://bonanza-labs.com
+Project-URL: Repository, https://github.com/c6zks4gssn-droid/hermes-spend
+Project-URL: Issues, https://github.com/c6zks4gssn-droid/hermes-spend/issues
+Keywords: hermes,agent,wallet,x402,payments,reputation,service-registry,ai,spending
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: x402
+Requires-Dist: x402-firewall>=0.1.0; extra == "x402"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+
+# hermes-spend
+
+**Native wallet, service registry, and reputation ledger for Hermes Agent.**
+
+Directly implements [Hermes Agent GitHub issue #38280](https://github.com/NousResearch/hermes/issues/38280):
+> *"[Feature Request] Native Wallet, Service Registration, Reputation Ledger"*
+
+```bash
+pip install hermes-spend
+```
+
+---
+
+## What this gives Hermes agents
+
+| Feature | Description |
+|---|---|
+| **Wallet** | Pay x402 endpoints with hard budget caps, vendor lists, and approval callbacks |
+| **Service Registry** | Discover and register paid services by query, category, or price |
+| **Reputation Ledger** | Track vendor trustworthiness — auto-updates on every payment |
+
+---
+
+## Quickstart
+
+```python
+from hermes_spend import HermesSpendSkill
+
+skill = HermesSpendSkill.from_config({
+    "budget_per_session": 10.00,
+    "require_approval_above": 2.00,
+    "block_vendors": ["untrusted.com"],
+})
+
+# Pay an x402 endpoint
+result = await skill.wallet_pay(
+    vendor_url="https://data.example.com/report",
+    amount_usd=1.50,
+    chain="base",
+)
+# → {"status": "ok", "receipt": {"vendor": "data.example.com", ...}}
+
+# Check balance
+bal = skill.wallet_balance()
+# → {"available_usd": 8.50, "spent_usd": 1.50, "payment_count": 1}
+```
+
+---
+
+## Wallet
+
+```python
+# Pay with budget enforcement
+result = await skill.wallet_pay("https://api.example.com/data", 1.50)
+
+# Check balance
+bal = skill.wallet_balance()
+print(f"${bal['available_usd']:.2f} remaining")
+
+# Full payment history
+history = skill.wallet_history()
+```
+
+**Config options:**
+
+| Key | Default | Description |
+|---|---|---|
+| `budget_per_session` | `∞` | Max total spend per session |
+| `require_approval_above` | `None` | Payments ≥ this USD need human approval |
+| `block_vendors` | `[]` | Blocked hostnames |
+| `allow_vendors` | `None` | Allowlist (blocks all others if set) |
+| `max_single_payment` | `∞` | Hard cap per payment |
+| `webhook_url` | `""` | Webhook for approval requests |
+
+---
+
+## Service Registry
+
+Agents can register services they provide and discover services provided by others.
+
+```python
+# Register a service you offer
+skill.service_register(
+    service_id="weather-api-v1",
+    name="Real-time Weather",
+    endpoint_url="https://weather.example.com/v1",
+    price_per_call_usd=0.002,
+    chain="base",
+    category="data",
+    tags=["weather", "realtime"],
+)
+
+# Discover services
+results = skill.service_search("weather", max_price_usd=0.01)
+for svc in results:
+    print(f"{svc['name']} — ${svc['price_per_call_usd']:.4f}/call at {svc['endpoint_url']}")
+
+# Pay and use a discovered service
+service = results[0]
+receipt = await skill.wallet_pay(service["endpoint_url"], service["price_per_call_usd"])
+```
+
+---
+
+## Reputation Ledger
+
+The reputation ledger auto-updates on every successful payment. Agents can also record data quality events.
+
+```python
+# Automatic — every wallet_pay() records "payment_success"
+await skill.wallet_pay("https://good-vendor.com/data", 1.00)
+
+# Manual events
+skill.reputation_record("good-vendor.com", "data_quality_good", note="accurate and fast")
+skill.reputation_record("bad-vendor.com", "fraud_detected", note="returned fake data")
+
+# Check before paying
+score = skill.reputation_score("shady.example.com")
+if not score["is_trusted"]:
+    raise Exception(f"Vendor not trusted: {score['trust_level']}")
+
+# Top vendors
+top = skill.reputation_top(limit=5)
+```
+
+**Event types and their impact:**
+
+| Event | Score delta | Use case |
+|---|---|---|
+| `data_quality_good` | +1.0 | Service returned accurate data |
+| `payment_success` | +0.5 | Payment completed successfully |
+| `payment_failed` | -1.0 | Payment failed or bounced |
+| `data_quality_bad` | -1.5 | Service returned bad/stale data |
+| `service_unavailable` | -0.5 | Service was down |
+| `payment_disputed` | -2.0 | Payment disputed |
+| `fraud_detected` | -10.0 | Confirmed fraud |
+
+**Trust levels:** `high` (score ≥ 1.0) · `medium` (≥ 0) · `low` (> -20) · `blocked` (≤ -20)
+
+Scores decay over time (30-day half-life) so recent events matter more than old ones.
+
+---
+
+## Direct module usage
+
+```python
+from hermes_spend import Wallet, ServiceRegistry, ReputationLedger
+
+# Wallet
+wallet = Wallet(
+    session_budget=10.00,
+    require_approval_above=2.00,
+    on_approval_needed=lambda receipt: my_approval_fn(receipt),
+)
+receipt = await wallet.pay("https://data.example.com", 1.50)
+
+# Service Registry
+registry = ServiceRegistry()
+registry.register(ServiceRecord(
+    service_id="svc-1",
+    name="My API",
+    endpoint_url="https://my-api.com",
+    price_per_call_usd=0.001,
+))
+results = registry.search("my")
+
+# Reputation Ledger
+ledger = ReputationLedger()
+ledger.record("vendor.com", "payment_success")
+score = ledger.score("vendor.com")
+```
+
+---
+
+## Hermes skill config (hermes-spend.yaml)
+
+Place in your Hermes skills directory:
+
+```yaml
+name: hermes-spend
+version: "0.1.0"
+description: "Native wallet, service registration, and reputation ledger"
+author: bonanza-labs
+
+config:
+  budget_per_session: 10.00
+  require_approval_above: 2.00
+  block_vendors: []
+  webhook_url: "${BONANZA_WEBHOOK_URL}"
+```
+
+---
+
+## License
+
+Apache 2.0. Built by [Bonanza Labs](https://bonanza-labs.com).
+
+For a managed dashboard with approval UI, policy editor, and audit reports:
+→ **[bonanza-labs.com/firewall](https://bonanza-labs.com/firewall)**

hermes_spend-0.1.0/README.md

@@ -0,0 +1,199 @@
+# hermes-spend
+
+**Native wallet, service registry, and reputation ledger for Hermes Agent.**
+
+Directly implements [Hermes Agent GitHub issue #38280](https://github.com/NousResearch/hermes/issues/38280):
+> *"[Feature Request] Native Wallet, Service Registration, Reputation Ledger"*
+
+```bash
+pip install hermes-spend
+```
+
+---
+
+## What this gives Hermes agents
+
+| Feature | Description |
+|---|---|
+| **Wallet** | Pay x402 endpoints with hard budget caps, vendor lists, and approval callbacks |
+| **Service Registry** | Discover and register paid services by query, category, or price |
+| **Reputation Ledger** | Track vendor trustworthiness — auto-updates on every payment |
+
+---
+
+## Quickstart
+
+```python
+from hermes_spend import HermesSpendSkill
+
+skill = HermesSpendSkill.from_config({
+    "budget_per_session": 10.00,
+    "require_approval_above": 2.00,
+    "block_vendors": ["untrusted.com"],
+})
+
+# Pay an x402 endpoint
+result = await skill.wallet_pay(
+    vendor_url="https://data.example.com/report",
+    amount_usd=1.50,
+    chain="base",
+)
+# → {"status": "ok", "receipt": {"vendor": "data.example.com", ...}}
+
+# Check balance
+bal = skill.wallet_balance()
+# → {"available_usd": 8.50, "spent_usd": 1.50, "payment_count": 1}
+```
+
+---
+
+## Wallet
+
+```python
+# Pay with budget enforcement
+result = await skill.wallet_pay("https://api.example.com/data", 1.50)
+
+# Check balance
+bal = skill.wallet_balance()
+print(f"${bal['available_usd']:.2f} remaining")
+
+# Full payment history
+history = skill.wallet_history()
+```
+
+**Config options:**
+
+| Key | Default | Description |
+|---|---|---|
+| `budget_per_session` | `∞` | Max total spend per session |
+| `require_approval_above` | `None` | Payments ≥ this USD need human approval |
+| `block_vendors` | `[]` | Blocked hostnames |
+| `allow_vendors` | `None` | Allowlist (blocks all others if set) |
+| `max_single_payment` | `∞` | Hard cap per payment |
+| `webhook_url` | `""` | Webhook for approval requests |
+
+---
+
+## Service Registry
+
+Agents can register services they provide and discover services provided by others.
+
+```python
+# Register a service you offer
+skill.service_register(
+    service_id="weather-api-v1",
+    name="Real-time Weather",
+    endpoint_url="https://weather.example.com/v1",
+    price_per_call_usd=0.002,
+    chain="base",
+    category="data",
+    tags=["weather", "realtime"],
+)
+
+# Discover services
+results = skill.service_search("weather", max_price_usd=0.01)
+for svc in results:
+    print(f"{svc['name']} — ${svc['price_per_call_usd']:.4f}/call at {svc['endpoint_url']}")
+
+# Pay and use a discovered service
+service = results[0]
+receipt = await skill.wallet_pay(service["endpoint_url"], service["price_per_call_usd"])
+```
+
+---
+
+## Reputation Ledger
+
+The reputation ledger auto-updates on every successful payment. Agents can also record data quality events.
+
+```python
+# Automatic — every wallet_pay() records "payment_success"
+await skill.wallet_pay("https://good-vendor.com/data", 1.00)
+
+# Manual events
+skill.reputation_record("good-vendor.com", "data_quality_good", note="accurate and fast")
+skill.reputation_record("bad-vendor.com", "fraud_detected", note="returned fake data")
+
+# Check before paying
+score = skill.reputation_score("shady.example.com")
+if not score["is_trusted"]:
+    raise Exception(f"Vendor not trusted: {score['trust_level']}")
+
+# Top vendors
+top = skill.reputation_top(limit=5)
+```
+
+**Event types and their impact:**
+
+| Event | Score delta | Use case |
+|---|---|---|
+| `data_quality_good` | +1.0 | Service returned accurate data |
+| `payment_success` | +0.5 | Payment completed successfully |
+| `payment_failed` | -1.0 | Payment failed or bounced |
+| `data_quality_bad` | -1.5 | Service returned bad/stale data |
+| `service_unavailable` | -0.5 | Service was down |
+| `payment_disputed` | -2.0 | Payment disputed |
+| `fraud_detected` | -10.0 | Confirmed fraud |
+
+**Trust levels:** `high` (score ≥ 1.0) · `medium` (≥ 0) · `low` (> -20) · `blocked` (≤ -20)
+
+Scores decay over time (30-day half-life) so recent events matter more than old ones.
+
+---
+
+## Direct module usage
+
+```python
+from hermes_spend import Wallet, ServiceRegistry, ReputationLedger
+
+# Wallet
+wallet = Wallet(
+    session_budget=10.00,
+    require_approval_above=2.00,
+    on_approval_needed=lambda receipt: my_approval_fn(receipt),
+)
+receipt = await wallet.pay("https://data.example.com", 1.50)
+
+# Service Registry
+registry = ServiceRegistry()
+registry.register(ServiceRecord(
+    service_id="svc-1",
+    name="My API",
+    endpoint_url="https://my-api.com",
+    price_per_call_usd=0.001,
+))
+results = registry.search("my")
+
+# Reputation Ledger
+ledger = ReputationLedger()
+ledger.record("vendor.com", "payment_success")
+score = ledger.score("vendor.com")
+```
+
+---
+
+## Hermes skill config (hermes-spend.yaml)
+
+Place in your Hermes skills directory:
+
+```yaml
+name: hermes-spend
+version: "0.1.0"
+description: "Native wallet, service registration, and reputation ledger"
+author: bonanza-labs
+
+config:
+  budget_per_session: 10.00
+  require_approval_above: 2.00
+  block_vendors: []
+  webhook_url: "${BONANZA_WEBHOOK_URL}"
+```
+
+---
+
+## License
+
+Apache 2.0. Built by [Bonanza Labs](https://bonanza-labs.com).
+
+For a managed dashboard with approval UI, policy editor, and audit reports:
+→ **[bonanza-labs.com/firewall](https://bonanza-labs.com/firewall)**

hermes_spend-0.1.0/hermes_spend/__init__.py

@@ -0,0 +1,35 @@
+"""
+hermes-spend: Native wallet, service registration, and reputation ledger for Hermes Agent.
+
+Directly addresses Hermes Agent GitHub issue #38280:
+"[Feature Request] Native Wallet, Service Registration, Reputation Ledger"
+
+Install as a Hermes skill:
+    hermes skill install bonanza/hermes-spend
+
+Or manually:
+    pip install hermes-spend
+    # Add to your hermes config:
+    # skills:
+    #   - name: hermes-spend
+    #     config:
+    #       api_key: "${BONANZA_API_KEY}"
+    #       budget_per_session: 10.00
+"""
+
+from .wallet import Wallet, WalletBalance, PaymentReceipt
+from .registration import ServiceRegistry, ServiceRecord
+from .reputation import ReputationLedger, ReputationScore
+from .skill import HermesSpendSkill
+
+__version__ = "0.1.0"
+__all__ = [
+    "HermesSpendSkill",
+    "Wallet",
+    "WalletBalance",
+    "PaymentReceipt",
+    "ServiceRegistry",
+    "ServiceRecord",
+    "ReputationLedger",
+    "ReputationScore",
+]

hermes_spend-0.1.0/hermes_spend/registration.py

@@ -0,0 +1,122 @@
+"""
+Service Registry: lets Hermes agents discover and register paid services.
+Addresses Hermes issue #38280 — "Service Registration".
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+from dataclasses import dataclass, field
+from typing import Literal
+
+
+ServiceCategory = Literal["data", "compute", "storage", "api", "media", "other"]
+
+
+@dataclass
+class ServiceRecord:
+    """A registered service that agents can discover and pay to use."""
+    service_id: str
+    name: str
+    endpoint_url: str
+    price_per_call_usd: float
+    chain: str = "base"
+    category: ServiceCategory = "other"
+    description: str = ""
+    tags: list[str] = field(default_factory=list)
+    registered_at: float = field(default_factory=time.time)
+    calls_total: int = 0
+    revenue_total_usd: float = 0.0
+
+    def matches(self, query: str) -> bool:
+        q = query.lower()
+        return (
+            q in self.name.lower()
+            or q in self.description.lower()
+            or q in self.category.lower()
+            or any(q in t.lower() for t in self.tags)
+        )
+
+
+class ServiceRegistry:
+    """
+    In-memory service registry for Hermes agents.
+
+    Agents can register services they provide and discover services
+    provided by others. Combined with Wallet, agents can pay for
+    discovered services automatically.
+
+    Example:
+        registry = ServiceRegistry()
+
+        # Register your service
+        registry.register(ServiceRecord(
+            service_id="my-data-api",
+            name="Real-time Market Data",
+            endpoint_url="https://market.example.com/v1",
+            price_per_call_usd=0.001,
+            category="data",
+            tags=["finance", "realtime"],
+        ))
+
+        # Discover services
+        results = registry.search("market data")
+        service = results[0]
+
+        # Pay and call
+        receipt = await wallet.pay(service.endpoint_url, service.price_per_call_usd)
+    """
+
+    def __init__(self) -> None:
+        self._services: dict[str, ServiceRecord] = {}
+        self._lock = threading.Lock()
+
+    def register(self, service: ServiceRecord) -> ServiceRecord:
+        with self._lock:
+            self._services[service.service_id] = service
+        return service
+
+    def unregister(self, service_id: str) -> bool:
+        with self._lock:
+            return self._services.pop(service_id, None) is not None
+
+    def get(self, service_id: str) -> ServiceRecord | None:
+        with self._lock:
+            return self._services.get(service_id)
+
+    def search(
+        self,
+        query: str = "",
+        category: ServiceCategory | None = None,
+        max_price_usd: float | None = None,
+        chain: str | None = None,
+        limit: int = 20,
+    ) -> list[ServiceRecord]:
+        with self._lock:
+            results = list(self._services.values())
+
+        if query:
+            results = [s for s in results if s.matches(query)]
+        if category:
+            results = [s for s in results if s.category == category]
+        if max_price_usd is not None:
+            results = [s for s in results if s.price_per_call_usd <= max_price_usd]
+        if chain:
+            results = [s for s in results if s.chain == chain]
+
+        return sorted(results, key=lambda s: s.price_per_call_usd)[:limit]
+
+    def list_all(self) -> list[ServiceRecord]:
+        with self._lock:
+            return list(self._services.values())
+
+    def record_call(self, service_id: str, revenue_usd: float) -> None:
+        with self._lock:
+            svc = self._services.get(service_id)
+            if svc:
+                svc.calls_total += 1
+                svc.revenue_total_usd += revenue_usd
+
+    def __len__(self) -> int:
+        return len(self._services)