private-me-xbind 0.2.0

Identity-based M2M authentication - Python bindings for @private.me/xbind

xbind - Python Bindings

Identity-based M2M authentication for Python.

Python bindings for @private.me/xbind - 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

pip install private-me-xbind

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

npm install -g @private.me/xbind

Quick Start

Simple Call API

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

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

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

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

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):

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

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

# 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: [e-mail]

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
• npm Package
• GitHub
• White Paper