> This page is for version 0.4.0. > For other versions, use one of these documentation indexes: > - Main (default): https://docs.nvidia.com/nemo/gym/main/llms.txt > - 0.7.0: https://docs.nvidia.com/nemo/gym/v0.7.0/llms.txt > - 0.6.0: https://docs.nvidia.com/nemo/gym/v0.6.0/llms.txt > - 0.5.1: https://docs.nvidia.com/nemo/gym/v0.5.1/llms.txt > - 0.5.0: https://docs.nvidia.com/nemo/gym/v0.5.0/llms.txt > - 0.4.0: https://docs.nvidia.com/nemo/gym/v0.4.0/llms.txt > - 0.3.0: https://docs.nvidia.com/nemo/gym/v0.3.0/llms.txt > - 0.2.1: https://docs.nvidia.com/nemo/gym/v0.2.1/llms.txt > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.nvidia.com/nemo/gym/llms.txt. # nemo_gym.core.correlation Read and build the correlation prefix of a Gym request path. A Gym component that hands a model URL to a client puts the request's identity in the path: ```python /ng-rollout/[/ng-agent-instance/][/training-token-capture] [/ng-sampling/][/ng-trace/]/v1/... ``` The segments appear in that fixed order. A path may also carry only `/ng-sampling/`, only `/ng-trace/`, or both. `resolve` reads the prefix and `encode` builds it. Readers that still parse the path by hand are moving onto this module. An agent instance name is `[.]`, for example `assistant`, `judge` or `debater.1`. The name never equals a segment literal or `v1`, so a missing name cannot swallow the next segment. The `/ng-sampling/` value is a training framework's sampling values for the call, or `null` for a caller it does not train; `nemo_gym.core.model_call_sampling` encodes and checks it. Like an agent instance name, it never equals a segment literal or `v1`. On a Gym server, `TraceContextPathMiddleware`, the outermost layer that reads the path, resolves it and shares the result through `scope["state"]`; inner middleware reads it there instead of parsing again. `resolve` reads only the path. ## Module Contents ### Classes | Name | Description | | ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | | [`CorrelationContext`](#nemo_gym-core-correlation-CorrelationContext) | The identity a request path carries. | | [`CorrelationPathError`](#nemo_gym-core-correlation-CorrelationPathError) | A request path carries a malformed correlation prefix. Servers answer it with 404. | | [`_Resolved`](#nemo_gym-core-correlation-_Resolved) | - | ### Functions | Name | Description | | ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | | [`agent_kind_of`](#nemo_gym-core-correlation-agent_kind_of) | Return the agent kind of an agent instance name: the part before the dot. | | [`encode`](#nemo_gym-core-correlation-encode) | Build the path prefix for `context`; `""` when it carries nothing. | | [`parse_path`](#nemo_gym-core-correlation-parse_path) | Split `path` into the context its prefix carries and the remaining path. | | [`remember`](#nemo_gym-core-correlation-remember) | Store `result` as the resolution of the scope's current path. | | [`resolve`](#nemo_gym-core-correlation-resolve) | Return the context a request's path carries and the remaining path, or `None` without a prefix. | | [`validate_agent_instance`](#nemo_gym-core-correlation-validate_agent_instance) | Return `name` if it is a valid agent instance name; raise `ValueError` otherwise. | ### Data [`AGENT_INSTANCE_PATH_SEGMENT`](#nemo_gym-core-correlation-AGENT_INSTANCE_PATH_SEGMENT) [`AGENT_INSTANCE_PATTERN`](#nemo_gym-core-correlation-AGENT_INSTANCE_PATTERN) [`CORRELATION_STATE_KEY`](#nemo_gym-core-correlation-CORRELATION_STATE_KEY) [`RESERVED_AGENT_INSTANCE_NAMES`](#nemo_gym-core-correlation-RESERVED_AGENT_INSTANCE_NAMES) [`TRACEPARENT_PATTERN`](#nemo_gym-core-correlation-TRACEPARENT_PATTERN) [`_SEGMENT_LITERALS`](#nemo_gym-core-correlation-_SEGMENT_LITERALS) ### API ```python class nemo_gym.core.correlation.CorrelationContext( capture_key: str | None = None, agent_instance: str | None = None, token_capture: bool = False, model_sampling: str | None = None, trace_parent: str | None = None ) ``` Dataclass The identity a request path carries. `capture_key` is `None` for a path without a rollout prefix. `agent_instance` is `None` when the path names no agent instance, as in a single-agent episode. `model_sampling` is the `/ng-sampling/` value, or `None` when the path carries none. **`agent_instance`** `str | None = None` --- **`agent_kind`** `str | None` --- **`capture_key`** `str | None = None` --- **`model_sampling`** `str | None = None` --- **`token_capture`** `bool = False` --- **`trace_parent`** `str | None = None` --- ```python nemo_gym.core.correlation.CorrelationContext.__post_init__() -> None ``` ```python class nemo_gym.core.correlation.CorrelationPathError( reason: str, path: str ) ``` **Bases:** `ValueError` A request path carries a malformed correlation prefix. Servers answer it with 404. ```python class nemo_gym.core.correlation._Resolved( path: str, result: tuple[nemo_gym.core.correlation.CorrelationContext, str] | None ) ``` Dataclass **`path`** `str` --- **`result`** `tuple[CorrelationContext, str] | None` --- ```python nemo_gym.core.correlation.agent_kind_of( agent_instance: str ) -> str ``` Return the agent kind of an agent instance name: the part before the dot. ```python nemo_gym.core.correlation.encode( context: nemo_gym.core.correlation.CorrelationContext ) -> str ``` Build the path prefix for `context`; `""` when it carries nothing. ```python nemo_gym.core.correlation.parse_path( path: str, allow_empty_rest: bool = False ) -> tuple[nemo_gym.core.correlation.CorrelationContext, str] | None ``` Split `path` into the context its prefix carries and the remaining path. Return `None` when `path` starts with no correlation segment, or, unless `allow_empty_rest`, when nothing follows the prefix. Raise `CorrelationPathError` for a malformed prefix: segments out of order or repeated, a missing value, an invalid agent instance name or traceparent. ```python nemo_gym.core.correlation.remember( scope: dict[str, typing.Any], result: tuple[nemo_gym.core.correlation.CorrelationContext, str] | None ) -> None ``` Store `result` as the resolution of the scope's current path. A middleware that rewrites the path after resolving it calls this, so inner middleware reading the rewritten path finds the context without parsing it again. ```python nemo_gym.core.correlation.resolve( scope: dict[str, typing.Any] ) -> tuple[nemo_gym.core.correlation.CorrelationContext, str] | None ``` Return the context a request's path carries and the remaining path, or `None` without a prefix. Resolve once per request: the result is stored in `scope["state"]` for the path it was read from, and a later call for the same path returns it. The cache is keyed by path, so `resolve` must read only the path. Raise `CorrelationPathError` for a malformed prefix. ```python nemo_gym.core.correlation.validate_agent_instance( name: str ) -> str ``` Return `name` if it is a valid agent instance name; raise `ValueError` otherwise. ```python nemo_gym.core.correlation.AGENT_INSTANCE_PATH_SEGMENT = 'ng-agent-instance' ``` ```python nemo_gym.core.correlation.AGENT_INSTANCE_PATTERN = re.compile('^[a-z][a-z0-9_-]*(?:\\.[a-z0-9_-]+)?\\Z') ``` ```python nemo_gym.core.correlation.CORRELATION_STATE_KEY = 'nemo_gym.correlation' ``` ```python nemo_gym.core.correlation.RESERVED_AGENT_INSTANCE_NAMES = _SEGMENT_LITERALS | {'v1'} ``` ```python nemo_gym.core.correlation.TRACEPARENT_PATTERN = re.compile('^00-[0-9a-f]{32}-[0-9a-f]{16}-[0-9a-f]{2}\\Z') ``` ```python nemo_gym.core.correlation._SEGMENT_LITERALS = frozenset({ROLLOUT_PATH_PREFIX, AGENT_INSTANCE_PATH_SEGMENT, TOKEN_CAPTURE_PATH_... ```