Skip to content

python.mdx

Latest commit

 

History

History
129 lines (91 loc) · 4.03 KB

python.mdx

File metadata and controls

129 lines (91 loc) · 4.03 KB
title Python Quick Start
description
position 1

{/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. SPDX-License-Identifier: Apache-2.0 */}

This quick start shows the smallest Python workflow that emits scope, tool, and LLM events.

LangChain, LangGraph, and Deep Agents users should start with the LangChain integration, LangGraph integration, and Deep Agents integration guides for the best experience in those frameworks.

Choose an Install Path

Pick the installation path that matches whether you are using a published package or a local checkout.

Install from a Package Manager

Use this path when you want the published package for application development.

uv add nemo-relay@0.3.0

Run uv add from an application project that has a pyproject.toml; it records nemo-relay as a dependency. If you are only installing into an active virtual environment, use uv pip install nemo-relay. If you are not using uv, install the published package with pip install nemo-relay.

Install from the Repository

Use this path when you are working from a local checkout and need editable source behavior.

uv sync

This is the right path when you are working from a local checkout and want the editable package plus the native extension build.

If you are consuming the local checkout from another uv project, add the source path from that application's directory instead:

uv add --editable ../NeMo-Relay

This records the local source in the application's pyproject.toml through [tool.uv.sources].

Run One Scope, One Tool Call, and One LLM Call

The example below runs one minimal instrumented workflow through the binding.

import asyncio

import nemo_relay

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

async def search(args):
    return {"echo": args["query"]}

async def model(request):
    return {
        "messages": request.content["messages"],
        "ok": True,
    }

async def main():
    nemo_relay.subscribers.register("quickstart-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"})

        tool_result = await nemo_relay.tools.execute("search", {"query": "hello"}, search, handle=handle)
        llm_result = await nemo_relay.llm.execute(
            "demo-provider",
            nemo_relay.LLMRequest({}, {"messages": [{"role": "user", "content": "hi"}]}),
            model,
            handle=handle,
        )

        print(tool_result)
        print(llm_result)

    nemo_relay.subscribers.deregister("quickstart-printer")

asyncio.run(main())

What Success Looks Like

You should see:

  • Event lines for the scope, tool, LLM, and mark lifecycle
  • {'echo': 'hello'} from the tool call
  • A final object containing ok: True and the echoed message payload from the LLM callback

If you only see the returned values and no event lines, the callbacks ran but you did not verify instrumentation. The subscriber output is the fast check that NeMo Relay actually emitted lifecycle events.

Where the Python Surface Lives

These modules are the main Python APIs to use from applications and integrations.

  • 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.typed
  • nemo_relay.codecs

What to Learn Next

Use these links to continue from the quick start into the core runtime concepts.