Python — Client API

The client page starts with the host-facing workflow: create a connection, open or use a session, submit work, read results, then close. Data structures are linked from the parameter tables instead of repeated as interface-style code blocks.

Imports

Use the high-level client/session APIs for applications. Low-level packet builders remain public for tests, diagnostics, and custom transports.

from nnrp.client import (
    ClientProfile,
    ClientSession,
    NativeClientSessionOpenOptions,
    SubmitRequest,
    connect_client_control,
    connect_client_control_with_probe,
    connect_native_client_connection,
)

Client Workflow

Production host code uses the Rust-backed native runtime:

1. Select or discover a native transport provider.
2. Call connect_native_client_connection.
3. Open a session with NativeClientConnection.open_session.
4. Use coarse native methods for submit, polling, and runtime-control frames.
5. Call close() to release the connection and sessions.

Packet transport helpers remain public, but they are mainly for smoke tests, diagnostics, and custom transports:

1. Build a ClientProfile.
2. Choose TCP, QUIC, or probe-based transport bootstrap.
3. Call connect_client_control or connect_client_control_with_probe.
4. Use the returned bootstrap session's ClientSession for request/response flows, or send_submit plus receive_result when multiple frames are in flight.
5. Keep the async context manager open for the lifetime of the client control session.

connect_native_client_connection

Loads an installed preview4 native artifact, creates a native runtime connection, and returns a NativeClientConnection context manager.

Parameter	Type	Required	Description
options	NativeClientSessionOptions | None	No	Low-level connection id, generation, and transport id options.
artifact_path	Path | str | None	No	Explicit native library path; usually unnecessary.
root	Path | str | None	No	Native artifact root.
native_platform	NativePlatform | None	No	Platform override for diagnostics or tests.
transport	str | None	No	tcp, quic, ipc, or websocket; omitted means default artifact resolution.
library	Any | None	No	Test-injected library.
fallback	NativeRuntimeBackend | None	No	Test or diagnostic fallback.
require_native	bool	No	Recommended as True for production; fails when native runtime is unavailable.

with connect_native_client_connection(require_native=True, transport="tcp") as connection:
    session = connection.open_session(NativeClientSessionOpenOptions(requested_session_id=42))
    result = connection.submit_and_poll_result(session, operation_id=1001, frame_id=1, payload=b"payload")

NativeClientConnection

NativeClientConnection is the primary preview4 Python host API. It preserves coarse native calls through session, operation, event, and owned-buffer objects instead of crossing the ABI for every small field.

NativeClientConnection.open_session

Parameter	Type	Required	Description
options	NativeClientSessionOpenOptions | None	No	Session id, generation, profile, and schema open options.

Returns
NativeRuntimeSession

NativeClientConnection.submit_and_poll_result

Parameter	Type	Required	Description
session	NativeRuntimeSession	Yes	Open native session.
operation_id	int	Yes	Operation id.
frame_id	int	Yes	Frame id.
payload	bytes | bytearray | memoryview	No	Submit payload.
result_payload	bytes | bytearray | memoryview | None	No	Test or loopback result payload.
parent_operation_id	int | None	No	Parent operation.
operation_group_id	int | None	No	Operation group.
max_events	int | None	No	Maximum events processed by this poll.

Returns
NativeRuntimeResult

Runtime control helpers

Method	Message type
cancel_runtime_operation	CANCEL
abort_runtime_operation	ABORT
update_runtime_priority	PRIORITY_UPDATE
update_runtime_deadline	DEADLINE
expire_runtime_operation_at	EXPIRE_AT
supersede_runtime_operation	SUPERSEDE
update_runtime_budget	BUDGET_UPDATE
send_runtime_route_hint	ROUTE_HINT
send_runtime_execution_hint	EXECUTION_HINT
negotiate_runtime_capabilities	CAPABILITY_NEGOTIATION
degrade_runtime_profile	DEGRADE_PROFILE

Event pump helpers include dispatch_events, dispatch_credit_updates, dispatch_result_hints, dispatch_structured_events, dispatch_tool_deltas, and dispatch_workflow_states.

NativeRuntimeSession Preview4 Frames

The session returned by NativeClientConnection.open_session() owns the high-level Preview4 send surface. Applications use these methods instead of constructing frames with the codec functions:

Method	Message
cancel_operation(metadata, diagnostic=b""), abort_operation(...)	CANCEL, ABORT
update_priority(metadata), update_deadline(metadata), expire_at(metadata)	scheduling messages
supersede(metadata, diagnostic=b""), update_budget(metadata)	SUPERSEDE, BUDGET_UPDATE
negotiate_capabilities(metadata, body=b""), degrade_profile(...)	capability messages
send_route_hint(metadata, body=b""), send_execution_hint(...)	routing messages
send_trace_context(metadata, body=b"")	TRACE_CONTEXT
declare_object(metadata, body=b""), reference_object(...)	OBJECT_DECLARE, OBJECT_REF
release_object(metadata, diagnostic=b"")	OBJECT_RELEASE
patch_object(metadata, delta, metadata_body=b"")	OBJECT_PATCH
send_object_delta(metadata, delta, metadata_body=b"")	OBJECT_DELTA
reference_cache(metadata, body=b""), report_cache_miss(...)	cache reference/miss
invalidate_cache(metadata)	CACHE_INVALIDATE

Every method returns None, validates declared lengths, and performs one coarse call to the Rust-owned runtime. The underlying role-neutral frame-send primitive is internal to the SDK and is not exposed on NativeRuntimeSession.

connect_client_control

Opens the selected transport, completes the control handshake, and yields a ClientControlBootstrapSession.

Parameter	Type	Required	Values / Range	Description
host	str	Yes	Hostname or IP	Remote NNRP endpoint.
quic_port	int | None	No	QUIC port	Enables QUIC when provided.
tcp_port	int | None	No	TCP port	Enables TCP when provided.
quic_configuration	QuicConfiguration | None	No	aioquic config	QUIC client configuration.
tcp_configuration	NnrpTcpClientConfiguration | None	No	TCP config	TCP client configuration.
client_profile	ClientProfile	No	Defaults to SDK profile	Client capabilities and cache limits sent during handshake.
selected_transport_id	TransportId	No	UNSPECIFIED, QUIC, TCP	Preferred selected transport when no probe result is supplied.
forced_transport_id	TransportId	No	UNSPECIFIED, QUIC, TCP	Hard transport selection for controlled deployments.
auth_block	bytes	No	Defaults to b""	Application-defined authentication payload.
timeout	float	No	Seconds, default 10.0	Connect and handshake timeout.

Returns	Raises
AsyncIterator[ClientControlBootstrapSession]	Transport errors, malformed handshake errors, or capability rejection errors.

profile = ClientProfile(max_views=1, enable_cache=True)
async with connect_client_control(
    "render.example.com",
    quic_port=4433,
    client_profile=profile,
) as bootstrap:
    result = await bootstrap.session.submit(request)

connect_client_control_with_probe

Probes QUIC and TCP, selects a transport, and uses the selected transport in the handshake.

Parameter	Type	Required	Values / Range	Description
host	str	Yes	Hostname or IP	Remote NNRP endpoint.
quic_port	int	Yes	QUIC port	QUIC probe/connect port.
tcp_port	int	Yes	TCP port	TCP probe/connect port.
quic_configuration	QuicConfiguration | None	No	aioquic config	QUIC client configuration.
tcp_configuration	NnrpTcpClientConfiguration | None	No	TCP config	TCP client configuration.
client_profile	ClientProfile	No	Defaults to SDK profile	Capability and cache preferences.
probe_payload_bytes	int	No	Default 32768	Payload size used by each probe sample.
probe_sample_count	int	No	Default 3	Number of scored probe samples.
include_warmup_probe	bool	No	Default False	Adds a warmup sample before scoring.
auth_block	bytes	No	Defaults to b""	Application auth payload.
timeout	float	No	Seconds, default 10.0	Probe, connect, and handshake timeout.

Returns	Raises
AsyncIterator[ClientControlBootstrapSession]	Probe, transport, or handshake failures.

async with connect_client_control_with_probe(
    "render.example.com",
    quic_port=4433,
    tcp_port=4434,
    client_profile=ClientProfile(),
) as bootstrap:
    result = await bootstrap.session.submit(request)

ClientSession

An established client-side session. Prefer these methods over building FRAME_SUBMIT packets by hand.

ClientSession.submit

Submits one frame and waits for the matching result.

Parameter	Type	Required	Values / Range	Description
request	SubmitRequest	Yes	frame_id must be unique while in flight	Structured frame submit request.
timeout	float | None	No	Seconds; None disables timeout	Maximum wait for the result.

Returns	Raises
Result	asyncio.TimeoutError, transport errors, protocol correlation errors.

result = await session.submit(
    SubmitRequest(
        frame_id=1,
        sections=(tensor_section,),
        input_profile=InputProfile.CHANGED_TILES_LUMA,
        submit_mode=SubmitMode.INLINE,
    ),
    timeout=0.05,
)

ClientSession.send_submit

Sends a frame without waiting for its result. Use it with receive_result or ResultRouter.

Parameter	Type	Required	Values / Range	Description
request	SubmitRequest	Yes	frame_id must be unique while in flight	Request to serialize and send as FRAME_SUBMIT.

Returns	Raises
int	Transport errors or local serialization errors.

await session.send_submit(request)

ClientSession.receive_result

Receives the next server-pushed result on the result channel.

Parameter	Type	Required	Values / Range	Description
timeout	float | None	No	Seconds; None disables timeout	Maximum wait for the next result.

Returns	Raises
Result	asyncio.TimeoutError, malformed result, or correlation errors.

result = await session.receive_result(timeout=0.05)

ClientSession.patch_session

Updates negotiated runtime parameters without reopening the session.

Parameter	Type	Required	Values / Range	Description
patch_fields	SessionPatchField	Yes	Bitmask	Selects which fields the server should apply.
target_cadence	int	No	0 leaves unchanged	Target FPS or cadence value.
quality_tier	int	No	0..255	Application-defined quality tier.
active_lane_mask	int	No	Bitmask	Active lane/view mask.
preferred_codec	int	No	Codec id	Preferred codec.
preferred_compression	int	No	Compression id	Preferred compression mode.

Returns	Raises
SessionPatchAckMetadata	Rejection, timeout, or malformed ack errors.

ack = await session.patch_session(
    SessionPatchField.TARGET_CADENCE | SessionPatchField.QUALITY_TIER,
    target_cadence=60,
    quality_tier=2,
)

ClientSession.close

Closes the session and underlying connection gracefully.

Parameter	Type	Required	Values / Range	Description
None	-	-	-	No parameters.

Returns	Raises
None	Transport close errors.

try:
    await session.submit(request)
finally:
    await session.close()

Core Types

ClientProfile

Client capabilities and cache preferences used during handshake.

Field	Type	Default	Description
max_views	int	1	Maximum concurrent views.
enable_cache	bool	True	Whether to negotiate server-side cache support.
max_cache_entries	int	256	Maximum cache entries requested from the server.
max_cache_bytes	int	8388608	Maximum cache bytes requested from the server.

ClientDialPolicy

Transport policy included in the client handshake.

Field	Type	Description
selected_transport_id	TransportId	Transport selected by probing or policy.
forced_transport_id	TransportId	Forced transport; UNSPECIFIED means no force.

SubmitRequest

Frame submission request.

Field	Type	Required	Description
frame_id	int	Yes	Unique frame id while in flight.
tile_ids	tuple[int, ...]	No	Tile ids included in the request.
sections	tuple[TensorSectionData, ...]	No	Tensor payload sections. See packet types.
typed_payloads	tuple[TypedPayload, ...]	No	Non-tensor payload frames.
input_profile	InputProfile	Yes	Input data profile.
submit_mode	SubmitMode	Yes	Inline or reference mode.
budget_policy	BudgetPolicy	No	Allowed degradation behavior.
inference_budget_ms	int	No	Relative inference budget in milliseconds; 0 means unlimited.
deadline_ms	int	No	Absolute Unix timestamp in milliseconds.

TypedPayload

Non-tensor payload container.

Field	Type	Required	Description
payload_kind	PayloadKind	Yes	Payload family.
data	bytes	Yes	Raw payload bytes.

Result

Server-pushed inference result.

Field	Type	Description
packet	NnrpPacket	Raw result packet.
metadata	ResultPushMetadata	Parsed result metadata.
sections	tuple[TensorSectionData, ...]	Tensor result sections.
typed_payloads	tuple[TypedPayload, ...]	Non-tensor result payloads.

ResultRouter

Use ResultRouter when multiple frame ids are in flight and consumers need per-frame awaiters.

Method	Parameter	Returns	Description
send_submit	SubmitRequest	int	Sends a request through the wrapped session.
receive	frame_id, optional view_id, optional timeout	Result	Waits for a specific frame result.
close	None	None	Stops the router task.

Common Pitfalls

WARNING

1. Always close ClientSession; unclosed sessions keep server-side resources alive until timeout.
2. Do not send from multiple coroutines through the same session without an application-level queue.
3. deadline_ms is absolute Unix time in milliseconds. inference_budget_ms is relative.
4. FORCE_QUIC hard-fails in TCP-only networks; prefer probing or fallback policies in production.