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:

/ng-rollout/<capture key>[/ng-agent-instance/<name>][/training-token-capture]
    [/ng-sampling/<values>][/ng-trace/<traceparent>]/v1/...

The segments appear in that fixed order. A path may also carry only /ng-sampling/<values>, only /ng-trace/<traceparent>, 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 <agent kind>[.<n>], 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`	The identity a request path carries.
`CorrelationPathError`	A request path carries a malformed correlation prefix. Servers answer it with 404.
`_Resolved`	-

Functions

Name	Description
`agent_kind_of`	Return the agent kind of an agent instance name: the part before the dot.
`encode`	Build the path prefix for `context`; `""` when it carries nothing.
`parse_path`	Split `path` into the context its prefix carries and the remaining path.
`remember`	Store `result` as the resolution of the scope’s current path.
`resolve`	Return the context a request’s path carries and the remaining path, or `None` without a prefix.
`validate_agent_instance`	Return `name` if it is a valid agent instance name; raise `ValueError` otherwise.

Data

AGENT_INSTANCE_PATH_SEGMENT

AGENT_INSTANCE_PATTERN

CORRELATION_STATE_KEY

RESERVED_AGENT_INSTANCE_NAMES

TRACEPARENT_PATTERN

_SEGMENT_LITERALS

API

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

nemo_gym.core.correlation.CorrelationContext.__post_init__() -> None

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.

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

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.

nemo_gym.core.correlation.encode(
    context: nemo_gym.core.correlation.CorrelationContext
) -> str

Build the path prefix for context; "" when it carries nothing.

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.

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.

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.

nemo_gym.core.correlation.validate_agent_instance(
    name: str
) -> str

Return name if it is a valid agent instance name; raise ValueError otherwise.

nemo_gym.core.correlation.AGENT_INSTANCE_PATH_SEGMENT = 'ng-agent-instance'

nemo_gym.core.correlation.AGENT_INSTANCE_PATTERN = re.compile('^[a-z][a-z0-9_-]*(?:\\.[a-z0-9_-]+)?\\Z')

nemo_gym.core.correlation.CORRELATION_STATE_KEY = 'nemo_gym.correlation'

nemo_gym.core.correlation.RESERVED_AGENT_INSTANCE_NAMES = _SEGMENT_LITERALS | {'v1'}

nemo_gym.core.correlation.TRACEPARENT_PATTERN = re.compile('^00-[0-9a-f]{32}-[0-9a-f]{16}-[0-9a-f]{2}\\Z')

nemo_gym.core.correlation._SEGMENT_LITERALS = frozenset({ROLLOUT_PATH_PREFIX, AGENT_INSTANCE_PATH_SEGMENT, TOKEN_CAPTURE_PATH_...