Metadata-Version: 2.1
Name: private-me-xbind
Version: 0.2.0
Summary: Identity-based M2M authentication - Python bindings for @private.me/xbind
Author: Private.Me Contributors
Project-URL: Homepage, https://private.me
Project-URL: Documentation, https://private.me/docs/xbind.html
Project-URL: Source Code, https://private.me
Keywords: xbind,ed25519,did-key,split-channel,xorida,transport-envelope,m2m,authentication,identity
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security :: Cryptography
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typing-extensions>=4.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"

# xbind - Python Bindings

![PyPI version](https://img.shields.io/pypi/v/private-me-xbind)
![Python versions](https://img.shields.io/pypi/pyversions/private-me-xbind)
![License](https://img.shields.io/badge/license-Proprietary-blue)

**Identity-based M2M authentication for Python.**

Python bindings for [@private.me/xbind](https://private.me/docs/xbind.html) - Authenticated agent-to-agent messaging with cryptographic identity.

## Requirements

- **Python 3.8+**
- **Node.js 18+** (required for cryptographic operations)
- **@private.me/xbind npm package** (installed via `npm install -g @private.me/xbind`)

## Installation

```bash
pip install private-me-xbind
```

**Note:** This package requires Node.js and the npm package to be installed:

```bash
npm install -g @private.me/xbind
```

## Quick Start

### Simple Call API

```python
from private_me.xbind import call

# Call a remote service with xbind authentication
result = call('stripe:createCharge', {
    'amount': 100,
    'currency': 'usd',
    'description': 'AI agent purchase'
})

if result['ok']:
    print(f"Charge created: {result['value']['id']}")
else:
    print(f"Error: {result['error']['message']}")
```

### Multi-Agent Coordination

```python
from private_me.xbind import connect

# Alice (coordinator)
alice = connect({'role': 'orchestrator'})

# Bob (worker)
bob = connect({'role': 'processor'})

# Alice sends task to Bob
alice['agent'].send({
    'to': bob['did'],
    'type': 'task',
    'data': {
        'batch_id': 'batch_2026_05_06_001',
        'items': encrypted_payload
    }
})

# Bob receives task
message = bob['agent'].receive(timeout=5000)
if message:
    print(f"Received task from {message['from_']}")

    # Bob processes and responds
    bob['agent'].send({
        'to': alice['did'],
        'type': 'task-complete',
        'result': {'processed': 1250, 'status': 'success'}
    })
```

### Agent Creation

```python
from private_me.xbind import Agent

# Create agent with auto-generated identity
agent = Agent.create()
print(f"Agent DID: {agent.identity['did']}")

# Send message
agent.send({
    'to': 'did:key:z6Mk...',
    'type': 'notification',
    'data': {'event': 'task-complete'}
})

# Receive messages
message = agent.receive(timeout=10000)
```

### Identity Operations

```python
from private_me.xbind import generate_identity, sign, verify

# Generate Ed25519 identity
identity = generate_identity()
print(f"DID: {identity['did']}")

# Sign message
message = b"Hello, world!"
signature = sign(message, identity['secretKey'])

# Verify signature
is_valid = verify(message, signature, identity['publicKey'])
print(f"Signature valid: {is_valid}")
```

### Batch Calls

```python
from private_me.xbind import batch_call

# Execute multiple calls in parallel
results = batch_call([
    ('stripe:createCharge', {'amount': 100, 'currency': 'usd'}),
    ('stripe:createCharge', {'amount': 200, 'currency': 'usd'}),
    ('stripe:listCharges', {'limit': 10})
])

for result in results:
    if result['ok']:
        print(f"Success: {result['value']}")
    else:
        print(f"Error: {result['error']}")
```

## API Reference

### call(tool_name, params, options)

Call a remote tool/service with xbind authentication.

**Parameters:**
- `tool_name` (str): Tool identifier (e.g., 'stripe:createCharge')
- `params` (dict, optional): Call parameters
- `options` (dict, optional): Call options (timeout, retries, constraints)

**Returns:** `CallResult` dict with `ok` flag and `value` or `error`

### batch_call(calls, options)

Execute multiple calls in parallel.

**Parameters:**
- `calls` (list): List of (tool_name, params) tuples
- `options` (dict, optional): Call options applied to all calls

**Returns:** List of `CallResult` dicts

### connect(options)

Create a new agent connection.

**Parameters:**
- `options` (dict, optional): Connection options (did, role, privateKey)

**Returns:** `Connection` dict with `did` and `agent`

### Agent.create(options)

Create a new agent with generated or provided identity.

**Parameters:**
- `options` (dict, optional): Agent configuration

**Returns:** `Agent` instance

### Agent Methods

- `send(options)` - Send message to another agent
- `receive(timeout)` - Receive message (blocking)

### Identity Functions

- `generate_identity()` - Generate Ed25519 identity
- `sign(message, secret_key)` - Sign message
- `verify(message, signature, public_key)` - Verify signature
- `public_key_to_did(public_key)` - Convert public key to DID

## Type Hints

All functions include comprehensive type hints (PEP 484):

```python
from private_me.xbind import call, CallResult
from typing import Dict, Any

def my_function(params: Dict[str, Any]) -> CallResult:
    result: CallResult = call('tool:name', params)
    return result
```

## Error Handling

```python
from private_me.xbind import call, XBindAgentError

try:
    result = call('stripe:createCharge', {'amount': 100})
    if not result['ok']:
        print(f"Call failed: {result['error']['message']}")
except XBindAgentError as e:
    print(f"Setup error: {e.message} (code: {e.code})")
```

## Architecture

This Python package wraps the Node.js @private.me/xbind library via subprocess:

1. Python function calls serialize parameters to JSON
2. Node.js subprocess executes xbind operations
3. Results are deserialized and returned to Python

**Performance:** Subprocess overhead is ~10-50ms per call. For high-throughput workloads, use the Node.js API directly.

## Requirements

- Python 3.8+
- Node.js 18+ with @private.me/xbind npm package
- typing-extensions (installed automatically)

## Development

```bash
# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest -v

# Type checking
mypy src/

# Format code
black src/ tests/
```

## License

Copyright © 2025 Standard Clouds, Inc. All rights reserved.

This software is proprietary and confidential. For licensing inquiries: contact@private.me

## Export Control

This software contains encryption technology that may be subject to U.S. export control laws (EAR 15 CFR 730-774). Export to embargoed countries is prohibited.

## Links

- [Documentation](https://private.me/docs/xbind.html)
- [npm Package](https://www.npmjs.com/package/@private.me/xbind)
- [GitHub](https://github.com/xail-io/xail)
- [White Paper](https://private.me/docs/xbind.html)
