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 published preview package	1.0.0rc4.post12
Frozen next role contract	Contract v9, Rust FFI ABI 4.4.0
Min Python	3.11
Runtime deps	aioquic >= 1.2.0

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

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, exact ABI version, protocol version, and transport slot. Contract v9 requires ABI 4.4.0. Production host code passes one NativeClientOptions value to nnrp.client.connect_native_client_connection(...).

Native Transport Providers

API	Description
discover_native_transport_providers()	Scans transport-scoped native artifacts installed with the current package.
select_native_transport_provider(options)	Selects from installed providers using one frozen NativeTransportSelectionOptions value.
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 production facade uses coarse ABI 4 ctypes calls. The retired compiled CFFI side runtime is not shipped and is not a fallback mode.

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. Packet-level tooling helpers are separate from the native host role API and are not a runtime fallback.
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.