Pre-release

This release is a pre-release and may not be stable for production use.

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. 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]"

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:

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

Project links

Data verified by PyPI on Aug 21, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Stable release available (0.7.3)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for willkill07 from gravatar.com willkill07

Credits

Author: NVIDIA Corporation & Affiliates

GitHub Statistics

Data verified by PyPI on Aug 21, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

Apache-2.0
View SPDX License List

Requires

Python >=3.11

Provides Extra

cli deepagents langchain langchain-nvidia langgraph

Tags

agents ai llm middleware nemo-relay observability runtime tools

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

nemo_relay-0.8.0rc1.tar.gz (1.5 MB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

nemo_relay-0.8.0rc1-cp311-abi3-win_arm64.whl (9.1 MB view details)

Uploaded CPython 3.11+Windows ARM64

nemo_relay-0.8.0rc1-cp311-abi3-win_amd64.whl (9.5 MB view details)

Uploaded CPython 3.11+Windows x86-64

nemo_relay-0.8.0rc1-cp311-abi3-musllinux_1_2_x86_64.whl (11.5 MB view details)

Uploaded CPython 3.11+musllinux: musl 1.2+ x86-64

nemo_relay-0.8.0rc1-cp311-abi3-musllinux_1_2_aarch64.whl (11.1 MB view details)

Uploaded CPython 3.11+musllinux: musl 1.2+ ARM64

nemo_relay-0.8.0rc1-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (9.6 MB view details)

Uploaded CPython 3.11+manylinux: glibc 2.17+ x86-64

nemo_relay-0.8.0rc1-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (9.1 MB view details)

Uploaded CPython 3.11+manylinux: glibc 2.17+ ARM64

nemo_relay-0.8.0rc1-cp311-abi3-macosx_11_0_arm64.whl (10.0 MB view details)

Uploaded CPython 3.11+macOS 11.0+ ARM64

File details

Details for the file nemo_relay-0.8.0rc1.tar.gz.

File metadata

  • Download URL: nemo_relay-0.8.0rc1.tar.gz
  • Upload date:
  • Size: 1.5 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.13

File hashes

Hashes for nemo_relay-0.8.0rc1.tar.gz
Algorithm Hash digest
SHA256 3e3924fee65747e2f54616df788cb641661ec126cae08dcf09baa02d31fde117
MD5 c72dc9261eab0038d61d0bb1a67d684e
BLAKE2b-256 2cf78895b529b722ea66fd4609371ffb392c7b059e5a1f42cce6c07e15eea83f

See more details on using hashes here.

Provenance

The following attestation bundles were made for nemo_relay-0.8.0rc1.tar.gz:

Publisher: ci.yaml on NVIDIA/NeMo-Relay

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file nemo_relay-0.8.0rc1-cp311-abi3-win_arm64.whl.

File metadata

File hashes

Hashes for nemo_relay-0.8.0rc1-cp311-abi3-win_arm64.whl
Algorithm Hash digest
SHA256 cf73a3e81369530559c449eee28db5e93ef54a4ec1919db7e8e218960dc3b037
MD5 d1cf389579aed1faa0c7d5f66653f319
BLAKE2b-256 4b18ea2eef73fcd396e46e0af95c2b5322ad9dcddb4298b34602ee0f63580118

See more details on using hashes here.

Provenance

The following attestation bundles were made for nemo_relay-0.8.0rc1-cp311-abi3-win_arm64.whl:

Publisher: ci.yaml on NVIDIA/NeMo-Relay

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file nemo_relay-0.8.0rc1-cp311-abi3-win_amd64.whl.

File metadata

File hashes

Hashes for nemo_relay-0.8.0rc1-cp311-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 f222bddad89d6650855bc8cee2201586a5c72e6fd17ce14e7b8510e3ba3bfb6b
MD5 1920aebb64c02c38c8f5f32349e612b7
BLAKE2b-256 3aa421c4812f15173b2ed540400842690211c842e2a88dea45134765dcca4bea

See more details on using hashes here.

Provenance

The following attestation bundles were made for nemo_relay-0.8.0rc1-cp311-abi3-win_amd64.whl:

Publisher: ci.yaml on NVIDIA/NeMo-Relay

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file nemo_relay-0.8.0rc1-cp311-abi3-musllinux_1_2_x86_64.whl.

File metadata

File hashes

Hashes for nemo_relay-0.8.0rc1-cp311-abi3-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 abc5ba1b026e8cd3461ea6e4631400aa5d7a38c32f58badb79065dd7bf7cba0e
MD5 18cab33886507e03f77b00a97d401efb
BLAKE2b-256 2d658d88a7aacbeb005ada07fdb2fb118259659872c9837864ec598ed55f74f9

See more details on using hashes here.

Provenance

The following attestation bundles were made for nemo_relay-0.8.0rc1-cp311-abi3-musllinux_1_2_x86_64.whl:

Publisher: ci.yaml on NVIDIA/NeMo-Relay

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file nemo_relay-0.8.0rc1-cp311-abi3-musllinux_1_2_aarch64.whl.

File metadata

File hashes

Hashes for nemo_relay-0.8.0rc1-cp311-abi3-musllinux_1_2_aarch64.whl
Algorithm Hash digest
SHA256 1a342ff9149703c80d80451e3e5c0164e4f36fe660c95f17cd9abf12cdd6a5b5
MD5 625cf29a5c16a4a00382d15fecf35d1b
BLAKE2b-256 4e8a2a4582e4e277559e982a24a7135fecc015fa9faffaaa85efd747572e2efc

See more details on using hashes here.

Provenance

The following attestation bundles were made for nemo_relay-0.8.0rc1-cp311-abi3-musllinux_1_2_aarch64.whl:

Publisher: ci.yaml on NVIDIA/NeMo-Relay

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file nemo_relay-0.8.0rc1-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for nemo_relay-0.8.0rc1-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 88c35d7cdaa1dff8f58218d920343842c954b6c4dc7ba8b823c77b5172b03885
MD5 ff9fa12cf3e34320f01d48285d3faba5
BLAKE2b-256 b234a1145c2e810796173730a161daa3a8a3b79cd8e942a8b79485ef70177d4b

See more details on using hashes here.

Provenance

The following attestation bundles were made for nemo_relay-0.8.0rc1-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: ci.yaml on NVIDIA/NeMo-Relay

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file nemo_relay-0.8.0rc1-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for nemo_relay-0.8.0rc1-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 3f311950a716bf8144f7e71f43244ce1baee2c39131401cf55e21efe73228e35
MD5 4a5d0df4233c170fd05262e79c2e0035
BLAKE2b-256 cbaf5266b2e1f66348e94032b41871f31d207fbf123ebd8f67fffc56d2e4db5e

See more details on using hashes here.

Provenance

The following attestation bundles were made for nemo_relay-0.8.0rc1-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl:

Publisher: ci.yaml on NVIDIA/NeMo-Relay

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file nemo_relay-0.8.0rc1-cp311-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for nemo_relay-0.8.0rc1-cp311-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 7e4a6473a33e2bc8a75401a7936853a69ee68777d9d287c2a4bf111759b1a3c6
MD5 727cc93c89c4ef3cbed45fae7a6490e5
BLAKE2b-256 71ab8a59847928a7940b7d549b996167caa7eb50a13f08309fea835af4f30e9b

See more details on using hashes here.

Provenance

The following attestation bundles were made for nemo_relay-0.8.0rc1-cp311-abi3-macosx_11_0_arm64.whl:

Publisher: ci.yaml on NVIDIA/NeMo-Relay

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release
Pre-release

0.8.0rc1 This release

8 files

0.7.3

8 files

0.7.2

8 files

0.7.1

8 files

0.7.0

8 files

Pre-release

0.7.0rc6

8 files

Pre-release

0.7.0rc5

8 files

Pre-release

0.7.0rc4

7 files

Pre-release

0.7.0rc3

7 files

Pre-release

0.7.0rc2

7 files

Pre-release

0.7.0rc1

7 files

0.6.0

8 files

Pre-release

0.6.0rc4

5 files

Pre-release

0.6.0rc3

5 files

Pre-release

0.6.0rc2

5 files

Pre-release

0.6.0rc1

5 files

0.5.0

5 files

0.4.0

5 files

0.3.0

5 files

Pre-release

0.3.0rc1

5 files

Pre-release

0.3.0b2

5 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page