Metadata-Version: 2.4
Name: easynet-run-axon
Version: 0.40.3
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
```

## Platform / Native Bundle Notes

The Python wheel contains native runtime + bridge payload and is therefore target-specific.

- Wheels are published to PyPI per target. `pip install` on a host automatically selects the matching wheel.
- For explicit cross-target workflows (CI + dev), use matching GitHub Release packs:
  - `sdk-packs-aarch64-apple-darwin.tar.gz`
  - `sdk-packs-aarch64-apple-ios.tar.gz`
  - `sdk-packs-x86_64-apple-ios.tar.gz`
  - `sdk-packs-x86_64-unknown-linux-gnu.tar.gz`
  - `sdk-packs-aarch64-unknown-linux-gnu.tar.gz`
  - `sdk-packs-aarch64-linux-android.tar.gz`
  - `sdk-packs-x86_64-pc-windows-msvc.tar.gz`
  - `sdk-packs-x86_64-apple-darwin.tar.gz`
- If auto selection is not available (e.g., offline/air-gapped), install from pack file directly:

```bash
pip install /path/to/dist/sdk-packs/<version>/python/easynet_run_axon-<version>-cp*.whl
```
- CI/source cross-target hints:
  - `SDK_VERSION=<version>` (optional; resolver checks this value and then falls back to `0.1.0`)
  - `EASYNET_DENDRITE_BRIDGE_PLATFORM=ios|android|linux|windows|macos`
  - `EASYNET_DENDRITE_BRIDGE_LIB=/abs/path/libaxon_dendrite_bridge.<ext>`
  - `EASYNET_DENDRITE_BRIDGE_HOME=/path/to/sdk-packs-<target>.tar.gz/extracted/package`（例如 `dist/sdk-packs/<version>/python` 或其父级的统一目录）
  - `EASYNET_DENDRITE_BRIDGE_SOURCE=local` to auto-bind from source-tree release output (`core/runtime-rs/dendrite-bridge/target/...`) when running from repository checkout.

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

- `build_ability_descriptor()` / `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.
- Preset status: `FederationCaseKit` is currently the only first-party high-level federation preset helper; other SDKs expose federation through lower-level runtime/client surfaces only.

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