Metadata-Version: 2.4
Name: easynet-run-axon
Version: 0.36.9
Summary: EasyNet Python SDK surface (MVP)
Author-email: Silan Hu <silan.hu@u.nus.edu>
License-Expression: Apache-2.0
Project-URL: Homepage, https://easynet.run
Project-URL: Repository, https://github.com/EasyRemote/EasyNet-Axon
Project-URL: Documentation, https://github.com/EasyRemote/EasyNet-Axon/tree/main/sdk/python
Keywords: easynet,axon,sdk
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Python: >=3.10
Description-Content-Type: text/markdown

<p align="center">
  <a href="https://github.com/EasyRemote"><img src="https://avatars.githubusercontent.com/u/213722898?s=200&v=4" width="200" height="200" alt="EasyRemote"></a>
</p>

<h1 align="center">easynet-run-axon</h1>

<p align="center">
  Python SDK for <strong>EasyNet Axon</strong> — the Capability Control Plane for agent-native distributed execution.
</p>

<p align="center">
  <a href='https://github.com/EasyRemote/EasyNet-Axon'><img src='https://img.shields.io/badge/EasyNet-Axon-00d9ff?style=for-the-badge&labelColor=0f172a'></a>
  <a href='https://github.com/EasyRemote/EasyNet-Axon/blob/main/LICENSE'><img src='https://img.shields.io/badge/License-Apache_2.0-f97316?style=for-the-badge&labelColor=0f172a'></a>
</p>
<p align="center">
  <img src='https://img.shields.io/badge/Python-3.10+-3776ab?style=for-the-badge&logo=python&logoColor=white&labelColor=0f172a'>
  <img src='https://img.shields.io/badge/Platform-macOS_|_Linux_|_Windows-22c55e?style=for-the-badge&labelColor=0f172a'>
</p>

---

## What is this?

This is the Python surface for **Axon**, a protocol-level control plane that treats agent capabilities as first-class network objects — not raw RPC endpoints. Every ability you expose carries its own schema, trust posture, scheduling contract, and tenant isolation rules, enforced atomically at invocation time.

**Why this matters:** In traditional architectures, policy evaluation, node selection, rate limiting, and concurrency admission happen in separate systems with separate state. That creates a race window — OPA approves a call against nodes {A,B,C}, but the load balancer routes to Node D added between decisions. Axon collapses all six checks (tenant isolation, rate limit, policy, node selection, concurrency, circuit breaker) into a **single atomic decision** against the same state snapshot.

> **Note:** The wheel is platform-tagged (not `any`) because it ships a native Dendrite bridge binary — the same C ABI that powers protocol-complete Axon gRPC calls without reimplementing protobuf encoding or streaming semantics in Python.

## Install

```bash
pip install easynet-run-axon
```

## Quick Start

### Expose an ability

```python
from easynet_axon import ability, serve

@ability("easynet:///r/org/reg/agent.quote-bot/abilities/order.quote@1?tenant_id=tenant-test")
def quote(ctx, sku: str, qty: int = 1):
    return {"sku": sku, "price": 19.9 * qty}

serve("agent.quote-bot")
```

### Invoke an ability

```python
from easynet_axon import client

res = (
    client()
    .tenant("tenant-test")
    .ability("easynet:///r/org/reg/agent.quote-bot/abilities/order.quote@1?tenant_id=tenant-test")
    .call({"sku": "A1", "qty": 2})
)
```

### Bootstrap a local runtime behind NAT

No public IP required. The SDK spawns a local Axon runtime that joins a federation Hub over outbound gRPC only:

```python
from easynet_axon import start_server

srv = start_server(
    hub="axon://hub.easynet.run:50084",
    hub_tenant="tenant-test",
    hub_label="alice-macbook",
)
```

## Capabilities

### Core Protocol

- **Fluent builders** — `.tenant()` → `.principal()` → `.ability()` → `.call()` are immutable and chainable.
- **Native Dendrite bridge** — `DendriteBridge` loads the platform C ABI via ctypes; all Axon gRPC shapes (unary, server-stream, client-stream, bidi-stream) are available without gRPC codegen.
- **Semantic DSL** — `SemanticBridge` and `@ability_call` decorator for ergonomic protocol invocation.
- **Subject binding** — `.principal(...)` scopes invocation to a subject identity with automatic URI visibility mapping (`pub`/`prv`/`org`).

### Ability Lifecycle

Full lifecycle management — not just invocation:

- `create_ability()` / `export_ability()` — define and register abilities with schemas
- `deploy_to_node()` — install + activate on target nodes
- `list_abilities()` / `invoke_ability()` / `uninstall_ability()`
- `forget_all()` — bulk removal of all deployed abilities

### MCP & A2A Protocols

- **MCP server** — `StdioMcpServer` hosts JSON-RPC 2.0 tool endpoints over stdio.
- **MCP operations** — `deploy_mcp_list_dir()`, `list_mcp_tools()`, `call_mcp_tool_with_args()`, `update_mcp_list_dir()`
- **A2A agent protocol** — `list_a2a_agents()`, `get_a2a_agent_card()`, `send_a2a_task()` for inter-agent task dispatch.
- **Tool adapter** — `AbilityToolAdapter` converts Axon abilities to OpenAI/Anthropic tool definitions with local handler registration.

### Voice & Media Signaling

First-class voice call lifecycle and transport negotiation:

- Call management: create, join, leave, end, watch events, report metrics
- Transport sessions: create, set description, add ICE candidates, refresh lease
- Codec profile negotiation

### Federation

- `start_server()` spawns a local Axon runtime and joins the Hub — all traffic is outbound.
- `FederationCaseKit` for cross-network orchestration workflows.
- Federated node discovery, heartbeat, and invocation dispatch.

### Remote Control & Orchestration

- `OrchestratorFactory` / `RemoteOrchestratorFactory` for subprocess template building and capability deployment workflows.
- Bundle reading, media persistence, CLI argument handling.

## License

Apache-2.0 — see [LICENSE](https://github.com/EasyRemote/EasyNet-Axon/blob/main/LICENSE).

## Author

[Silan Hu](https://github.com/Qingbolan) · [silan.hu@u.nus.edu](mailto:silan.hu@u.nus.edu)
