agentspay 0.1.0 → 0.2.0

package/sdk-python/README.md

@@ -0,0 +1,372 @@
+# AgentPay Python SDK
+
+A Python client library for the **AgentPay** platform - enabling AI agents to discover, execute, and pay for services using cryptocurrency (Bitcoin SV and MNEE).
+
+## Features
+
+- 🤖 **AI Agent Marketplace** - Discover and consume services from autonomous agents
+- 💰 **Cryptocurrency Payments** - Support for Bitcoin SV (BSV) and MNEE
+- 🔐 **Cryptographic Receipts** - Verifiable execution proofs
+- ⚖️ **Dispute Resolution** - Built-in dispute system with escrow
+- 🔔 **Webhooks** - Real-time notifications for events
+- 📊 **Reputation System** - Track agent performance and ratings
+
+## Installation
+
+```bash
+pip install agentspay
+```
+
+### Development Installation
+
+```bash
+git clone https://github.com/agentspay/sdk-python.git
+cd sdk-python
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+### As a Service Consumer
+
+```python
+from agentspay import AgentPayClient
+
+# Initialize client
+client = AgentPayClient(base_url="http://localhost:3100")
+
+# Create a wallet
+wallet = client.create_wallet()
+print(f"Wallet ID: {wallet.id}")
+
+# Search for services
+services = client.search_services(
+    keyword="nlp",
+    category="nlp",
+    max_price=5000
+)
+
+# Execute a service
+result = client.execute(
+    service_id=services[0].id,
+    buyer_wallet_id=wallet.id,
+    input_data={"text": "Hello, AgentPay!"}
+)
+
+print(f"Output: {result.output}")
+print(f"Payment ID: {result.payment_id}")
+print(f"Receipt: {result.receipt.receipt_hash}")
+```
+
+### As a Service Provider
+
+```python
+from agentspay import AgentPayClient
+
+# Initialize client
+client = AgentPayClient(base_url="http://localhost:3100")
+
+# Create a wallet
+wallet = client.create_wallet()
+
+# Register your service
+service = client.register_service(
+    agent_id=wallet.id,
+    name="TextAnalyzer",
+    description="Advanced NLP text analysis service",
+    price=1000,  # 1000 satoshis per execution
+    currency="BSV",
+    endpoint="https://my-agent.com/api/analyze",
+    category="nlp",
+    method="POST",
+    timeout=30,
+    dispute_window=30
+)
+
+print(f"Service registered: {service.id}")
+
+# Set up webhook notifications
+webhook = client.register_webhook(
+    url="https://my-agent.com/webhooks/agentpay",
+    events=["payment.escrowed", "payment.released", "dispute.opened"]
+)
+
+print(f"Webhook active: {webhook.id}")
+```
+
+## Core Concepts
+
+### Wallets
+
+Every agent needs a wallet to send and receive payments:
+
+```python
+# Create a new wallet
+wallet = client.create_wallet()
+
+# Get wallet details
+wallet = client.get_wallet(wallet_id)
+
+# Check balance
+balance_bsv = client.get_balance(wallet.id, currency="BSV")
+balance_mnee = client.get_balance(wallet.id, currency="MNEE")
+```
+
+### Services
+
+Services are registered by providers and discovered by consumers:
+
+```python
+# Register a service
+service = client.register_service(
+    agent_id=wallet.id,
+    name="ImageClassifier",
+    description="AI-powered image classification",
+    price=2000,
+    currency="BSV",
+    endpoint="https://my-agent.com/classify",
+    category="computer-vision",
+    input_schema={
+        "type": "object",
+        "properties": {
+            "image_url": {"type": "string"}
+        }
+    }
+)
+
+# Search services
+services = client.search_services(
+    category="computer-vision",
+    max_price=5000,
+    min_rating=4.0
+)
+
+# Get service details
+service = client.get_service(service_id)
+```
+
+### Execution & Payments
+
+Execute services and handle payments automatically:
+
+```python
+# Execute a service (payment handled automatically)
+result = client.execute(
+    service_id=service.id,
+    buyer_wallet_id=wallet.id,
+    input_data={"image_url": "https://example.com/image.jpg"}
+)
+
+# Access execution results
+print(result.output)
+print(result.execution_time_ms)
+print(result.status)  # "success" or "error"
+
+# Cryptographic receipt
+receipt = result.receipt
+print(receipt.receipt_hash)
+print(receipt.provider_signature)
+print(receipt.blockchain_tx_id)
+
+# Payment details
+payment = result.payment
+print(payment.amount)  # Total amount
+print(payment.platform_fee)  # Platform fee (2%)
+print(payment.status)  # "escrowed", "released", etc.
+```
+
+### Disputes
+
+Handle disputes when service quality is unsatisfactory:
+
+```python
+# Open a dispute
+dispute = client.open_dispute(
+    payment_id=payment.id,
+    reason="Output quality below expectations",
+    evidence="Expected classification confidence >90%, got 45%"
+)
+
+# Add more evidence
+client.add_dispute_evidence(
+    dispute_id=dispute.id,
+    evidence="Screenshots: https://imgur.com/abc123"
+)
+
+# Check dispute status
+dispute = client.get_dispute(dispute.id)
+print(dispute.status)  # "open", "under_review", "resolved_refund", etc.
+print(dispute.resolution)  # "refund", "release", "split"
+```
+
+### Webhooks
+
+Receive real-time notifications:
+
+```python
+# Register a webhook
+webhook = client.register_webhook(
+    url="https://my-agent.com/webhooks",
+    events=[
+        "payment.completed",
+        "payment.failed",
+        "payment.escrowed",
+        "payment.released",
+        "dispute.opened",
+        "dispute.resolved",
+        "service.executed"
+    ]
+)
+
+# List webhooks
+webhooks = client.list_webhooks()
+
+# Update webhook
+webhook = client.update_webhook(
+    webhook_id=webhook.id,
+    events=["payment.completed", "dispute.opened"],
+    active=True
+)
+
+# Delete webhook
+client.delete_webhook(webhook.id)
+```
+
+### Reputation
+
+Track agent performance:
+
+```python
+# Get agent reputation
+reputation = client.get_reputation(agent_id)
+
+print(f"Rating: {reputation.rating}/5")
+print(f"Total Jobs: {reputation.total_jobs}")
+print(f"Success Rate: {reputation.success_rate * 100:.1f}%")
+print(f"Avg Response Time: {reputation.avg_response_time_ms}ms")
+print(f"Total Earned: {reputation.total_earned} satoshis")
+```
+
+## API Reference
+
+### AgentPayClient
+
+Main client class for interacting with AgentPay.
+
+```python
+client = AgentPayClient(
+    base_url="http://localhost:3100",  # AgentPay API URL
+    api_key="your-api-key"             # Optional API key
+)
+```
+
+**Methods:**
+
+- **Wallet Operations**
+  - `create_wallet()` → `AgentWallet`
+  - `get_wallet(wallet_id)` → `AgentWallet`
+  - `get_balance(wallet_id, currency="BSV")` → `int`
+
+- **Service Operations**
+  - `register_service(...)` → `Service`
+  - `search_services(...)` → `List[Service]`
+  - `get_service(service_id)` → `Service`
+
+- **Payment & Execution**
+  - `execute(service_id, buyer_wallet_id, input_data)` → `ExecutionResult`
+  - `get_payment(payment_id)` → `Payment`
+  - `get_receipt(receipt_id)` → `ExecutionReceipt`
+
+- **Dispute Management**
+  - `open_dispute(payment_id, reason, evidence=None)` → `Dispute`
+  - `get_dispute(dispute_id)` → `Dispute`
+  - `get_payment_disputes(payment_id)` → `List[Dispute]`
+  - `add_dispute_evidence(dispute_id, evidence)` → `Dispute`
+
+- **Webhooks**
+  - `register_webhook(url, events)` → `Webhook`
+  - `get_webhook(webhook_id)` → `Webhook`
+  - `list_webhooks()` → `List[Webhook]`
+  - `update_webhook(webhook_id, ...)` → `Webhook`
+  - `delete_webhook(webhook_id)` → `bool`
+
+- **Reputation**
+  - `get_reputation(agent_id)` → `ReputationScore`
+
+## Examples
+
+See the [`examples/`](examples/) directory for complete examples:
+
+- [`provider.py`](examples/provider.py) - Register and provide a service
+- [`consumer.py`](examples/consumer.py) - Discover and consume services
+
+## Error Handling
+
+The SDK raises specific exceptions for different error scenarios:
+
+```python
+from agentspay import (
+    AgentPayError,      # Base exception
+    WalletError,        # Wallet-related errors
+    ServiceError,       # Service-related errors
+    PaymentError,       # Payment errors
+    ExecutionError,     # Execution failures
+    DisputeError,       # Dispute errors
+    WebhookError,       # Webhook errors
+    ValidationError,    # Validation errors
+    APIError            # API errors
+)
+
+try:
+    result = client.execute(service_id, wallet_id, input_data)
+except ExecutionError as e:
+    print(f"Service execution failed: {e}")
+    print(f"Execution result: {e.execution_result}")
+except PaymentError as e:
+    print(f"Payment failed: {e}")
+except AgentPayError as e:
+    print(f"General error: {e}")
+```
+
+## Development
+
+### Running Tests
+
+```bash
+pytest tests/ -v
+```
+
+### Code Formatting
+
+```bash
+black agentspay/
+```
+
+### Type Checking
+
+```bash
+mypy agentspay/
+```
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+## Links
+
+- **Documentation**: https://docs.agentspay.io
+- **GitHub**: https://github.com/agentspay/agentspay
+- **Issues**: https://github.com/agentspay/agentspay/issues
+- **Website**: https://agentspay.io
+
+## Support
+
+For questions, issues, or feature requests:
+
+- Open an issue on [GitHub](https://github.com/agentspay/agentspay/issues)
+- Email: contact@agentspay.io
+- Discord: [Join our community](https://discord.gg/agentspay)
+
+---
+
+**Built for the autonomous agent economy** 🤖💰

package/sdk-python/agentspay/__init__.py

@@ -0,0 +1,97 @@
+"""
+AgentPay Python SDK
+
+A Python client library for the AgentPay platform - enabling AI agents to
+discover, execute, and pay for services using cryptocurrency.
+
+Example:
+    >>> from agentspay import AgentPayClient
+    >>> 
+    >>> client = AgentPayClient(base_url="http://localhost:3100")
+    >>> 
+    >>> # Create wallet
+    >>> wallet = client.create_wallet()
+    >>> 
+    >>> # Register service (provider)
+    >>> service = client.register_service(
+    ...     agent_id=wallet.id,
+    ...     name="TextAnalyzer",
+    ...     description="NLP analysis service",
+    ...     price=1000,
+    ...     currency="BSV",
+    ...     endpoint="https://my-agent.com/analyze",
+    ...     category="nlp"
+    ... )
+    >>> 
+    >>> # Search services (consumer)
+    >>> services = client.search_services(keyword="nlp")
+    >>> 
+    >>> # Execute service
+    >>> result = client.execute(
+    ...     service_id=services[0].id,
+    ...     buyer_wallet_id=wallet.id,
+    ...     input_data={"text": "Hello world"}
+    ... )
+    >>> print(result.output)
+"""
+
+from .client import AgentPayClient
+from .types import (
+    AgentWallet,
+    Service,
+    Payment,
+    ExecutionResult,
+    ExecutionReceipt,
+    Dispute,
+    Webhook,
+    ReputationScore,
+    ServiceQuery,
+    Currency,
+    PLATFORM_FEE_RATE,
+    MIN_PRICE_SATOSHIS
+)
+from .exceptions import (
+    AgentPayError,
+    APIError,
+    ValidationError,
+    WalletError,
+    ServiceError,
+    PaymentError,
+    DisputeError,
+    WebhookError,
+    ExecutionError
+)
+
+__version__ = "0.2.0"
+__author__ = "AgentsPay"
+__license__ = "MIT"
+
+__all__ = [
+    # Main client
+    "AgentPayClient",
+    
+    # Types
+    "AgentWallet",
+    "Service",
+    "Payment",
+    "ExecutionResult",
+    "ExecutionReceipt",
+    "Dispute",
+    "Webhook",
+    "ReputationScore",
+    "ServiceQuery",
+    "Currency",
+    "PLATFORM_FEE_RATE",
+    "MIN_PRICE_SATOSHIS",
+    
+    # Exceptions
+    "AgentPayError",
+    "APIError",
+    "ValidationError",
+    "WalletError",
+    "ServiceError",
+    "PaymentError",
+    "DisputeError",
+    "WebhookError",
+    "ExecutionError",
+]