# le-agent-sdk

[![PyPI version](https://img.shields.io/pypi/v/le-agent-sdk.svg)](https://pypi.org/project/le-agent-sdk/)
[![Tests](https://github.com/ArcadeLabsInc/lightning-enable-agent-sdk-python/actions/workflows/test.yml/badge.svg)](https://github.com/ArcadeLabsInc/lightning-enable-agent-sdk-python/actions/workflows/test.yml)
[![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://pypi.org/project/le-agent-sdk/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Python SDK for Lightning Enable Agent Service Agreements.

Discover, negotiate, and settle agent-to-agent services over Nostr with L402 Lightning payments.

## Installation

```bash
pip install le-agent-sdk
```

## Quick Start

### Provider: Publish a Service

Register an agent capability on the Nostr network so other agents can discover it.

```python
import asyncio
from le_agent_sdk import AgentManager, AgentCapability, AgentPricing

async def main():
    manager = AgentManager(
        private_key="<your_hex_private_key>",
        relay_urls=["wss://agents.lightningenable.com"],
    )

    cap = AgentCapability(
        service_id="translate-v1",
        categories=["ai", "translation"],
        content="AI translation service. Supports 50+ languages.",
        pricing=[
            AgentPricing(amount=10, unit="sats", model="per-request"),
        ],
        l402_endpoint="https://api.lightningenable.com/l402/proxy/translate",
        hashtags=["translation", "ai"],
    )

    event_id = await manager.publish_capability(cap)
    print(f"Published capability: {event_id}")

    # Listen for incoming service requests
    async for request in manager.listen_requests():
        print(f"Request from {request.pubkey}: {request.content}")

asyncio.run(main())
```

### Requester: Discover and Use Services

Find available services and settle via L402 payments.

```python
import asyncio
from le_agent_sdk import AgentManager

async def main():
    manager = AgentManager(
        private_key="<your_hex_private_key>",
        relay_urls=["wss://agents.lightningenable.com"],
    )

    # Discover translation services
    capabilities = await manager.discover(
        categories=["translation"],
        hashtags=["ai"],
        limit=10,
    )

    for cap in capabilities:
        print(f"[{cap.service_id}] {cap.content[:60]}...")
        if cap.pricing:
            print(f"  Price: {cap.pricing[0].amount} {cap.pricing[0].unit}/{cap.pricing[0].model}")

    # Settle via L402 if endpoint available
    chosen = capabilities[0]
    if chosen.l402_endpoint:
        result = await manager.settle_via_l402(chosen)
        print(f"Result: HTTP {result.status_code}")

asyncio.run(main())
```

## API Reference

### Core Classes

| Class | Description |
|-------|-------------|
| `AgentManager` | Main entry point. Manages Nostr connections, publishes capabilities, discovers services, and handles L402 settlement. |
| `AgentCapability` | Defines a service offering with pricing, categories, endpoints, and metadata. Published as Nostr kind 38400 events. |
| `AgentServiceRequest` | Represents a request for service from one agent to another (kind 38401). |
| `AgentServiceAgreement` | Bilateral contract between provider and requester (kind 38402). |

### Nostr Layer

| Class | Description |
|-------|-------------|
| `RelayClient` | WebSocket client for Nostr relay communication. Handles subscriptions and event publishing. |
| `NostrEvent` | Nostr event construction, serialization, and signing. |
| `TagParser` | Utilities for parsing and building Nostr event tags. |

### Payment Layer

| Class | Description |
|-------|-------------|
| `L402Client` | HTTP client with automatic L402 challenge-response handling. Wraps [l402-requests](https://github.com/ArcadeLabsInc/l402-requests). |
| `AgentPricing` | Pricing model (amount, unit, per-request/per-token). |

## Protocol

Agent Service Agreements use three Nostr event kinds:

- **38400** -- Agent Capability: provider advertises available services
- **38401** -- Agent Service Request: requester asks for a service
- **38402** -- Agent Service Agreement: bilateral contract with terms and pricing

Settlement happens via L402 (Lightning HTTP 402) through Lightning Enable endpoints.

## Related Projects

- [le-agent-sdk (TypeScript)](https://github.com/refined-element/le-agent-sdk-ts) -- `npm install le-agent-sdk`
- [le-agent-sdk (.NET)](https://github.com/refined-element/le-agent-sdk-dotnet) -- `dotnet add package LightningEnable.AgentSdk`
- [Lightning Enable MCP Server](https://github.com/refined-element/lightning-enable-mcp) -- MCP server with ASA tools for AI agents
- [l402-requests](https://github.com/refined-element/l402-requests) -- Python L402 HTTP client
- [Lightning Enable](https://lightningenable.com) -- L402 infrastructure and agent payment rails

## License

MIT
