Python API

The Python SDK (nnrp-py) public API is organized into protocol primitives, host-facing client/server helpers, native runtime facades, runtime control objects, and transport providers.

Start with Client or Server. Enum, packet, message, and transport pages are reference material linked from method parameter tables.

Group	Description	Status
Enums & Constants	Message types, flags, payload kinds, status enums, and constants	Stable
Header & Packet	NnrpHeader, NnrpPacket, tensor sections, and serialization utilities	Stable
Message Types	Metadata classes and builder functions for control/data messages	Stable
Client	Client profiles, session lifecycle, submit/result helpers, migration, and routing	Stable
Server	Server profiles, session acceptance, frame receive, and result push helpers	Stable
Runtime Control & Objects	Preview4 control metadata, runtime objects, cache references, and WebSocket binary frame helpers	Stable
Transport & Providers	Native transport provider discovery/selection plus tooling TCP/QUIC packet adapters	Stable

Package Info

Property	Value
Distribution	nnrp-py
Import package	nnrp
Current preview package	1.0.0rc4
Min Python	3.11
Runtime deps	aioquic >= 1.2.0, cffi >= 2.0.0

pip install --pre "nnrp-py==1.0.0rc4"

Native Runtime Facades

The top-level nnrp package also exports native runtime helpers such as load_native_runtime, load_native_client, probe_native_artifact, NativeRuntimeBackend, NativeRuntimeClient, NativeRuntimeConnection, NativeRuntimeSession, NativeSchemaCodec, NativeRecoveryCodec, and cache/session diagnostic types.

Preview4 wheels use transport-scoped native artifacts. Entrypoints such as load_native_runtime(..., transport="tcp") and load_native_client(..., transport="ipc") validate the artifact manifest, ABI 1.11.x, protocol version, and transport slot. Production host code should prefer nnrp.client.connect_native_client_connection(require_native=True, transport=...).

Native Transport Providers

API	Description
discover_native_transport_providers()	Scans transport-scoped native artifacts installed with the current package.
select_native_transport_provider(policy_or_name)	Selects from installed providers by auto, probe, or explicit name.
resolve_native_transport_provider(name)	Resolves one provider and raises a native artifact error when unavailable.
diagnose_nnrp_endpoint_support(endpoint)	Diagnoses application-facing nnrp:// / nnrps:// endpoint support.
diagnose_native_transport_endpoint_support(endpoint)	Diagnoses provider-local endpoints such as unix://, npipe://, ws://, and wss://.
native_transport_slot_names(mask)	Converts a native transport slot bitmask to names.

The default binding mode is auto. It prefers the packaged cffi API fast path and falls back to ctypes when the fast path is unavailable. Set NNRP_NATIVE_BINDING_MODE=ctypes to force the compiler-free path during local development, or NNRP_NATIVE_BINDING_MODE=cffi_api to require the fast path.

Tool Entrypoints

Command	Purpose
python -m nnrp.tools.adapter_conformance	Consume a suite-owned adapter execution plan and emit adapter case results.
python -m nnrp.tools.wire_conformance	Generate a wire target manifest or execute a wire plan generated by the suite.
nnrp-wire-conformance	Console-script alias for the wire conformance runner.
nnrp-wire-target-manifest	Console-script alias for wire target manifest generation.
python -m nnrp.tools.benchmark	Consume a benchmark execution plan and emit benchmark results.
nnrp-run-benchmark	Console-script alias for the benchmark runner.

Wire Format

Only NNRP/1 wire format 0 is supported. Every packet header's wire_format field must match this value; otherwise the parser raises ValueError.

Python-specific Expectations

1. Async-first methods are the primary host API contract.
2. Sync helpers are convenience wrappers over the same protocol semantics.
3. Public method names, parameter groups, and returned state objects should not drift without a formal SDK version change.
4. Code blocks should show usage examples; method signatures belong in method-level parameter tables.