AetherMesh SDK

AetherMesh SDK is the headless foundation for applications connecting to a future decentralized AetherMesh AI network. Eidolon can use it as an optional provider adapter; other applications can use it independently.

Current status: authenticated direct-peer foundation, no public network. The SDK and optional headless service share a versioned peer protocol. Explicitly configured peers can exchange bounded status and opt-in echo requests over mutual TLS, with cancellation and timeouts. Opt-in small content exchange adds project-scoped, hash-verified opaque bytes. Status and echo are diagnostics, not AI inference. Automatic discovery, NAT traversal, relays, streaming inference and peer-distributed releases are not implemented. Existing local contracts, reference execution, validation, provenance and the localhost development API remain.

The Python distribution remains aethermesh and the import path remains aethermesh_core for compatibility. Neither is being silently renamed as part of the repository cleanup.

Install from source

Requires Python 3.11 or newer. From a checkout of this repository:

python -m pip install .

Use the package directly without a desktop application or API server:

from aethermesh_core import Job, LocalRunner, NodeIdentity, validate_job_result

job = Job(job_id="hello", job_type="echo", payload={"message": "hello mesh"})
result = LocalRunner(NodeIdentity(node_id="example-node")).run(job)
validation = validate_job_result(job, result)
print(result.to_dict())
assert validation.valid

This is an in-process reference job, not a request to a remote AI network. Run the complete no-network example with python examples/sdk_smoke.py.

SDK and optional peer service

The base install includes aethermesh_core.network.PeerClient and aethermesh-peer serve, backed by the same protocol and trust implementation. An application using the client does not listen, host models, train, seed files or start a background process. Running a service is an explicit operator choice; its default capability is status, and echo requires --enable-echo.

Existing hardware-derived node IDs and four-word names can be explicitly shared with --node-identity PATH or the SDK's load_node_profile/node_profile APIs. The selected saved identity is reused without rewriting it. Optional --share-hardware adds coarse hardware categories; raw MAC addresses, device identifiers and private keys are never profile fields. Certificate pins still authenticate connections, and advertised names/hardware remain self-reported.

Use installed aethermesh-peer check for one-shot authenticated diagnostics and aethermesh-peer fingerprint to hash an explicitly selected certificate. Neither command creates identities, enrolls trust or starts a service. Explicit serve --share-file PATH --content-budget BYTES and fetch --output NEW_FILE provide small-content CLI exchange with verified bytes and no-overwrite output; this is not repository sync.

Start with the network foundation guide for certificate/pin configuration, the installed SDK example, protocol contracts, security limits and two-process verification. No privileged installer or extra network dependency is required.

Optional local API and diagnostic CLI

python -m pip install -e ".[dev,api]"
AETHERMESH_HOME=/tmp/aethermesh-dev aethermesh init
AETHERMESH_HOME=/tmp/aethermesh-dev aethermesh status
AETHERMESH_HOME=/tmp/aethermesh-dev aethermesh node start

The development API defaults to 127.0.0.1:7280 and serves JSON. Keep it on localhost: it is not an authenticated public gateway. aethermesh-core retains the deterministic flow/debug commands. The old [ui] dependency extra is an alias for [api]; it no longer installs a dashboard.

See CLI and local API and the cleanup compatibility notes.

Scope and end objectives

Track proposed stages and acceptance criteria in the network and participation backlog.

Read SDK scope and objectives for implemented, partial and planned capabilities and the exact ownership boundaries. In brief:

• Stable, versioned application-facing APIs and protocol contracts
• Authenticated direct connections and capability negotiation; discovery planned
• AI/job submission, streaming, cancellation and predictable failure handling
• Validated results, attribution, lineage and content-addressed artifact transfer
• Project-isolated source/build/release metadata and verification interfaces
• Explicit participation and resource/privacy controls
• App-neutral adapters, package examples and conformance/security tests

Desktop UI, native app installation/relaunch/rollback, Eidolon's agent hierarchy, training engines and full build scheduling belong to their owning applications or services. Existing local runtime and scheduling fixtures remain useful for SDK development; they are not a claim that the network is deployed.

Testing

python -m pip install -e ".[dev,api]" pytest pytest-cov ruff mypy
PYTHONDONTWRITEBYTECODE=1 python scripts/full_test.py --mode fast --base origin/main --keep-going
PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src python -m unittest discover -s tests -v

The fast gate checks tests, 100% branch coverage, lint/format/type checks and repository policy. scripts/full_test.py --list lists the additional full gates. No desktop application or Electron installation is required. Real-network tests use loopback sockets and the OpenSSL executable to create temporary test identities; they do not install certificates or modify the operating system trust store.

Repository layout

• src/aethermesh_core/network/: shared peer protocol, SDK client and opt-in service
• src/aethermesh_core/: compatible Python imports, contracts and local foundations
• examples/: deterministic manifests, schema fixtures and SDK usage example
• docs/: SDK boundaries, reference architecture and prototype contracts
• tests/: unit, protocol and local API/CLI tests
• scripts/: repository validation and package/release metadata helpers
• .github/: SDK CI and contribution templates
• graphify-out/: historical generated navigation, not current scope evidence

Architecture · Persistent goal · Local identity · Local lifecycle

Experimental verified learning

The opt-in tiny-router learning pilot connects a separate CPU trainer to bounded TLS evaluator peers, independent-operator quorums, held-out/regression gates, local promotion and explicit rollback. It is a controlled development experiment, not a public network or production self-improving model platform. Default SDK connections enable no contribution.

For explicit, bounded, resumable opaque-file exchange, see resumable content. The 8-MiB acceptance target does not provide Git import, publisher authorization or general repository synchronization.

Trusted bundle export and header inspection can prepare one pinned local branch for opaque peer transfer without importing received packs.

For operator-approved real-machine setup, use the two-peer runbook and application integration contract. These are deployment guidance; current automated evidence remains loopback-only.

Python applications can use the public resumable-download API for typed progress, scoped cancellation and explicit output publication.

The durable local learning-state utility supports bounded job/checkpoint recovery and coordinator fencing for a separate learning service. It does not train models or provide distributed consensus.

The separate numeric-expert demo fits a synthetic regression model with durable restart, independently recomputed evaluation, promotion and rollback. It uses local unsigned evidence and no replicated coordination.