Skip to main content

License GitHub Release Codecov PyPI npm node Crates.io Crates.io Crates.io Ask DeepWiki

NeMo Relay

nemo-relay is the NeMo Relay package for Python applications. It gives Python code access to a portable agent runtime for execution scopes, middleware, plugins, lifecycle events, adaptive behavior, and observability around tool and LLM calls.

The package wraps the shared Rust runtime, so Python applications use the same runtime semantics as the Rust and Node.js surfaces.

Why Use It?

Use the Python binding for the following tasks:

  • Own execution context in Python: Group agent, tool, and LLM work into one scope tree from Python application code.
  • Package policy around callbacks: Use guardrails and intercepts to block work, sanitize observability payloads, rewrite requests, or wrap execution.
  • Emit one lifecycle stream: Send runtime events to in-process subscribers, Agent Trajectory Interchange Format (ATIF), or typed OpenTelemetry workflows.
  • Integrate without a framework migration: Wrap framework or provider callbacks while preserving the application’s orchestration model.

What You Get

The Python package provides the following capabilities:

  • Scope, tool, and LLM helpers: Managed boundaries that emit lifecycle events and run middleware in a consistent order.
  • Middleware APIs: Guardrails and intercepts for tool and LLM requests, responses, and execution, plus mark and scope event sanitizers for data, category_profile, and metadata.
  • Subscribers and exporters: OpenTelemetrySubscriber exports traces; OpenTelemetryLogSubscriber and OpenTelemetryMetricSubscriber export severity-tagged marks and typed metric measurements. Bare OTLP/HTTP origins resolve to /v1/traces, /v1/logs, or /v1/metrics for the selected signal. Each direct OTLP subscriber exposes runtime_diagnostics() for bounded exporter and event-processing failure summaries. Trace export failures use otel.traces_export_failed; after a trace export fails, force_flush() continues to return an error until a later trace batch exports successfully. The nemo_relay.observability helpers configure plugin-owned endpoint fan-out.
  • Plugin and typed helpers: Public modules for plugins, codecs, typed wrappers, adaptive runtime behavior, and observability plugin configuration.
  • Shared Rust runtime semantics: Python behavior aligned with the Rust and Node.js surfaces.

Installation

Install the published package with uv:

uv add nemo-relay

If you are not using uv, install it with pip:

pip install nemo-relay

Optional Dependencies

LangChain Integration

LangChain integration is available with the langchain extra:

# With uv
uv add "nemo-relay[langchain]"

# With pip
pip install "nemo-relay[langchain]"

LangGraph Integration

LangGraph integration is available with the langgraph extra, this builds upon and includes the langchain extra as well.

# With uv
uv add "nemo-relay[langgraph]"

# With pip
pip install "nemo-relay[langgraph]"

Deep Agents Integration

Deep Agents integration is available with the deepagents extra. This extra builds upon and includes the langgraph and langchain extras.

# With uv
uv add "nemo-relay[deepagents]"

# With pip
pip install "nemo-relay[deepagents]"

Google ADK Integration

Google Agent Development Kit integration is available with the google-adk extra:

# With uv
uv add "nemo-relay[google-adk]"

# With pip
pip install "nemo-relay[google-adk]"

Add NemoRelayPlugin to your ADK app to record agent runs, model calls, and tool calls. For setup steps and examples, follow the Google ADK Integration Guide.

LangChain NVIDIA Integration

The LangChain NVIDIA extra builds upon the langchain extra adding a compatible version of the langchain-nvidia-ai-endpoints package.

# With uv
uv add "nemo-relay[langchain-nvidia]"

# With pip
pip install "nemo-relay[langchain-nvidia]"

To install this along with the langgraph extra, use:

# With uv
uv add "nemo-relay[langgraph,langchain-nvidia]"
# With pip
pip install "nemo-relay[langgraph,langchain-nvidia]"

Getting Started

Register a subscriber, create a scope, and emit a mark event:

import nemo_relay


def on_event(event) -> None:
    print(f"{event.kind} {event.name}")


nemo_relay.subscribers.register("printer", on_event)

with nemo_relay.scope.scope("demo-agent", nemo_relay.ScopeType.Agent) as handle:
    nemo_relay.scope.event("initialized", handle=handle, data={"binding": "python"})

nemo_relay.subscribers.flush()
nemo_relay.subscribers.deregister("printer")

Use nemo_relay.scope.event(..., severity=nemo_relay.LogSeverity.Info) for a mark intended for log export. Use nemo_relay.scope.metric() with nemo_relay.MetricMeasurement objects for metrics; Relay validates the complete measurement group before publishing it.

OTLP Logs and Metrics

For plugin-managed export, configure version 4 and enable logs and metrics. Omitting their endpoint lists derives /v1/logs and /v1/metrics from the trace endpoint:

from nemo_relay.observability import (
    ComponentSpec,
    ObservabilityConfig,
    OpenTelemetryEndpointConfig,
    OpenTelemetryLogSectionConfig,
    OpenTelemetryMetricSectionConfig,
    OpenTelemetrySectionConfig,
)

component = ComponentSpec(
    ObservabilityConfig(
        opentelemetry=OpenTelemetrySectionConfig(
            enabled=True,
            endpoints=[
                OpenTelemetryEndpointConfig(
                    type="gen_ai", endpoint="http://localhost:4318/v1/traces"
                )
            ],
            logs=OpenTelemetryLogSectionConfig(enabled=True),
            metrics=OpenTelemetryMetricSectionConfig(enabled=True),
        )
    )
)

Emit a typed log mark and an atomically validated metric group with the public scope helpers:

from nemo_relay import DataSchema, LogSeverity, MetricKind, MetricMeasurement, MetricValueType
from nemo_relay import scope

scope.event(
    "cache-nearly-full",
    data={"entries": 900},
    data_schema=DataSchema("example.cache", "1"),
    severity=LogSeverity.Warn,
)
scope.metric(
    "cache-entries",
    [MetricMeasurement("example.cache.entries", MetricKind.Gauge, MetricValueType.U64, 900)],
)

Direct log and metric subscribers are independently managed. Register each before emitting marks, then deregister, force-flush, and shut it down during graceful teardown. Their runtime_diagnostics() snapshots contain bounded code, message, and count entries:

A successful direct log or trace force_flush() also updates this snapshot with any queue drops observed so far; the diagnostic count remains cumulative through later flushes and shutdown.

from nemo_relay import (
    OpenTelemetryLogConfig,
    OpenTelemetryLogSubscriber,
    OpenTelemetryMetricConfig,
    OpenTelemetryMetricSubscriber,
)

# Equivalent explicit OTLP/HTTP paths are /v1/logs and /v1/metrics, respectively.
logs = OpenTelemetryLogSubscriber(OpenTelemetryLogConfig("http://localhost:4318"))
metrics = OpenTelemetryMetricSubscriber(OpenTelemetryMetricConfig("http://localhost:4318"))
logs.register("otlp-logs")
metrics.register("otlp-metrics")
try:
    for diagnostic in logs.runtime_diagnostics().entries:
        print(diagnostic.code, diagnostic.message)
finally:
    logs.deregister("otlp-logs")
    logs.force_flush()
    logs.shutdown()
    metrics.deregister("otlp-metrics")
    metrics.force_flush()
    metrics.shutdown()

Native subscriber delivery is asynchronous, so call nemo_relay.subscribers.flush() before you read subscriber output or exit. From an asyncio task, use await nemo_relay.subscribers.flush_async() so async event sanitizers can continue running on that event loop.

For host integrations that need a serialized event shape, consume the canonical JSON payload from the subscriber event object:

import json
import nemo_relay


def on_event(event) -> None:
    payload = event.to_dict()
    print(payload["kind"], payload["name"])
    assert json.loads(event.to_json()) == payload


nemo_relay.subscribers.register("host-exporter", on_event)
try:
    with nemo_relay.scope.scope("demo-agent", nemo_relay.ScopeType.Agent):
        nemo_relay.scope.event("initialized", data={"binding": "python"})
finally:
    nemo_relay.subscribers.flush()
    nemo_relay.subscribers.deregister("host-exporter")

Package Surface

The public package modules are:

  • nemo_relay.scope
  • nemo_relay.tools
  • nemo_relay.llm
  • nemo_relay.guardrails
  • nemo_relay.intercepts
  • nemo_relay.subscribers
  • nemo_relay.plugin
  • nemo_relay.adaptive
  • nemo_relay.observability
  • nemo_relay.typed
  • nemo_relay.codecs

Integrations

  • nemo_relay.integrations.langchain
  • nemo_relay.integrations.langgraph
  • nemo_relay.integrations.deepagents

The compiled extension is exposed as nemo_relay._native.

Documentation

NeMo Relay Documentation: https://docs.nvidia.com/nemo/relay

Metadata

Release files for nemo-relay 0.11.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for nemo-relay 0.11.2
File Size Uploaded Provenance Actions
nemo_relay-0.11.2.tar.gz 2.4 MB With provenance Details for nemo_relay-0.11.2.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for nemo-relay 0.11.2
File Actions
nemo_relay-0.11.2-cp311-abi3-win_arm64.whl CPython 3.11 abi3 Windows ARM64 Details for nemo_relay-0.11.2-cp311-abi3-win_arm64.whl
nemo_relay-0.11.2-cp311-abi3-win_amd64.whl CPython 3.11 abi3 Windows x86-64 Details for nemo_relay-0.11.2-cp311-abi3-win_amd64.whl
nemo_relay-0.11.2-cp311-abi3-musllinux_1_2_x86_64.whl CPython 3.11 abi3 Linux musl 1.2+ x86-64 Details for nemo_relay-0.11.2-cp311-abi3-musllinux_1_2_x86_64.whl
nemo_relay-0.11.2-cp311-abi3-musllinux_1_2_aarch64.whl CPython 3.11 abi3 Linux musl 1.2+ ARM64 Details for nemo_relay-0.11.2-cp311-abi3-musllinux_1_2_aarch64.whl
nemo_relay-0.11.2-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl CPython 3.11 abi3 Linux glibc 2.17+ x86-64 Details for nemo_relay-0.11.2-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
nemo_relay-0.11.2-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl CPython 3.11 abi3 Linux glibc 2.17+ ARM64 Details for nemo_relay-0.11.2-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
nemo_relay-0.11.2-cp311-abi3-macosx_11_0_arm64.whl CPython 3.11 abi3 macOS 11.0+ ARM64 Details for nemo_relay-0.11.2-cp311-abi3-macosx_11_0_arm64.whl

Total release size: 83.3 MB

Release files / nemo_relay-0.11.2.tar.gz

Download URL nemo_relay-0.11.2.tar.gz
Size 2.4 MB
Tags Source
SHA-256 checksum
How to use checksums
e125c01c04f870d8a14a29b79a36e5f4940ba5f4d1ba1501a72b49bf5bc1a9a3
BLAKE2b-256 checksum
How to use checksums
07e024293abe46d83e943e65f09ba697ff2eef955175b2898c666d6aeae17341
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.

Transparency log

Release files / nemo_relay-0.11.2-cp311-abi3-win_arm64.whl

Download URL nemo_relay-0.11.2-cp311-abi3-win_arm64.whl
Size 10.5 MB
Tags CPython 3.11 Windows ARM64 abi3
SHA-256 checksum
How to use checksums
45063ea3d99cdf2f0e093f0a1fc31f142f7e5ee552c8af72fdc3b186facb6775
BLAKE2b-256 checksum
How to use checksums
79d1180567fa90d9bf9bf4a649b48261f87e1cece9ad70cfa87b93e51949177b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.

Transparency log

Release files / nemo_relay-0.11.2-cp311-abi3-win_amd64.whl

Download URL nemo_relay-0.11.2-cp311-abi3-win_amd64.whl
Size 11.0 MB
Tags CPython 3.11 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
69162aa56f72aca9b1943b7c3d9e40c5fd9c4e462059dc3a1db72cfe70f663f8
BLAKE2b-256 checksum
How to use checksums
3e443771c5f9141245b90b2bfcf1f7a68e2e1354ea25ee0938e9ac0b05768a35
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.

Transparency log

Release files / nemo_relay-0.11.2-cp311-abi3-musllinux_1_2_x86_64.whl

Download URL nemo_relay-0.11.2-cp311-abi3-musllinux_1_2_x86_64.whl
Size 13.4 MB
Tags CPython 3.11 Linux musl 1.2+ x86-64 abi3
SHA-256 checksum
How to use checksums
d5eff15444decfd7d6d7040915d939f30b6d22e8e5c12b71d920210a42ad61b8
BLAKE2b-256 checksum
How to use checksums
305062190372b6aac0c4ff3619d6a86507ccc221b00039e4a83a2f2f4e09bc1f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.

Transparency log

Release files / nemo_relay-0.11.2-cp311-abi3-musllinux_1_2_aarch64.whl

Download URL nemo_relay-0.11.2-cp311-abi3-musllinux_1_2_aarch64.whl
Size 12.8 MB
Tags CPython 3.11 Linux musl 1.2+ ARM64 abi3
SHA-256 checksum
How to use checksums
6ae36af02f718a3628bccd2515396d793fadb1d9424aa8a11b8326eb67fb2f87
BLAKE2b-256 checksum
How to use checksums
4868e9b477833a94c5c1de23736dc60831ecfe85412078a3f1ed1f92051f61e2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.

Transparency log

Release files / nemo_relay-0.11.2-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Download URL nemo_relay-0.11.2-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Size 11.1 MB
Tags CPython 3.11 Linux glibc 2.17+ x86-64 abi3
SHA-256 checksum
How to use checksums
9dedae82d27155657b3d20a1d8fd09ffa189c16cdd7f198991006ae582169c9d
BLAKE2b-256 checksum
How to use checksums
41ee899eba00db547826926179d1ca45187d12bec8c88cb3b8563e86be99cc04
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.

Transparency log

Release files / nemo_relay-0.11.2-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

Download URL nemo_relay-0.11.2-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Size 10.4 MB
Tags CPython 3.11 Linux glibc 2.17+ ARM64 abi3
SHA-256 checksum
How to use checksums
1764cc9c7d87611127fbd7cf95f6d70b50c0bafdc52f33a543de322b2b4c05f8
BLAKE2b-256 checksum
How to use checksums
8084e434a2e30264699bab91469d76f64e94d88c1105962999624e93c9663d69
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.

Transparency log

Release files / nemo_relay-0.11.2-cp311-abi3-macosx_11_0_arm64.whl

Download URL nemo_relay-0.11.2-cp311-abi3-macosx_11_0_arm64.whl
Size 11.6 MB
Tags CPython 3.11 abi3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
9ffa9362ebca29df82ed3dd95d6f8172a1fa02633d315a030e55d8a6ee0684a1
BLAKE2b-256 checksum
How to use checksums
63d6ad84b168ca28a09875fb70c539fa9dc7b5d581897a0d01c5801dd0c26411
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.

Transparency log

Security for nemo-relay 0.11.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

All 8 files in this release have been uploaded with provenance metadata.

Select from 8 files

Attestation for nemo_relay-0.11.2.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.11.2 This release

8 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page