Typed Helpers

Generated from crates/node/typed.d.ts.

Import from nemo-relay-node/typed.

Typed wrappers for NeMo Relay Node.js execute APIs.

Interfaces

JsonObject

A JSON object with recursively JSON-serializable values.

1
export interface JsonObject {
2
  [key: string]: JsonValue;
3
}

JsonArray

A JSON array with recursively JSON-serializable values.

1
export interface JsonArray extends Array<JsonValue> {}

LlmRequestShape

Canonical JSON shape for an opaque LLM request payload.

1
export interface LlmRequestShape {
2
  headers: JsonObject;
3
  content: JsonValue;
4
}

LlmCodec

A codec for annotating and unwrapping LLM JSON request payloads.

Use when an LLM integration needs custom request parsing or normalization before the raw payload is passed through the NeMo Relay LLM middleware pipeline.

1
export interface LlmCodec {
2
  /**
3
   * Decode a raw LLM request payload into the normalized JSON shape used by
4
   * the codec.
5
   *
6
   * @param request - The raw request payload as a JSON-serializable value.
7
   * @returns The decoded or normalized JSON request representation.
8
   */
9
  decode(request: JsonValue): JsonValue;
10
  /**
11
   * Encode an annotated request payload back into the JSON shape expected by
12
   * the underlying LLM implementation.
13
   *
14
   * @param annotated - The normalized or annotated JSON payload produced by middleware.
15
   * @param original - The original JSON request payload before annotation.
16
   * @returns A JSON payload ready to pass to the underlying LLM implementation.
17
   */
18
  encode(annotated: JsonValue, original: JsonValue): JsonValue;
19
}

LlmResponseCodec

A codec for normalizing and decoding raw LLM responses into JsonValue.

Use when model output requires custom parsing or normalization before the response is consumed as plain JSON by the library.

1
export interface LlmResponseCodec {
2
  /**
3
   * Decode a raw LLM response payload into the normalized JSON shape expected
4
   * by the library.
5
   *
6
   * Implementations should return a JSON-serializable value and should prefer
7
   * normalizing missing or provider-specific fields into a stable shape when
8
   * possible.
9
   *
10
   * @param response - The raw response payload as a JSON-serializable value.
11
   * @returns The decoded or normalized JSON response representation.
12
   */
13
  decodeResponse(response: JsonValue): JsonValue;
14
}

Codec

A codec that converts between a typed value T and a JSON-serializable representation (JsonValue by default).

1
export interface Codec<T, TJson = JsonValue> {
2
  /** Convert a typed value to a JSON-serializable object. */
3
  toJson(value: T): TJson;
4
  /** Reconstruct a typed value from a JSON-serializable object. */
5
  fromJson(data: TJson): T;
6
}

TypedToolExecuteOptions

Options for typedToolExecute.

1
export interface TypedToolExecuteOptions {
2
  handle?: ScopeHandle | null;
3
  attributes?: number | null;
4
  data?: JsonValue;
5
  metadata?: JsonValue;
6
}

TypedLlmExecuteOptions

Options for typedLlmExecute.

1
export interface TypedLlmExecuteOptions {
2
  handle?: ScopeHandle | null;
3
  attributes?: number | null;
4
  data?: JsonValue;
5
  metadata?: JsonValue;
6
  modelName?: string | null;
7
  codec?: LlmCodec | null;
8
  responseCodec?: LlmResponseCodec | null;
9
}

TypedLlmStreamExecuteOptions

Options for typedLlmStreamExecute.

1
export interface TypedLlmStreamExecuteOptions {
2
  handle?: ScopeHandle | null;
3
  attributes?: number | null;
4
  data?: JsonValue;
5
  metadata?: JsonValue;
6
  modelName?: string | null;
7
  codec?: LlmCodec | null;
8
  responseCodec?: LlmResponseCodec | null;
9
}

Classes

JsonPassthrough

A passthrough codec that performs no conversion. Use when arguments or results are already plain JSON objects.

1
export declare class JsonPassthrough implements Codec<JsonValue> {
2
  toJson(value: JsonValue): JsonValue;
3
  fromJson(data: JsonValue): JsonValue;
4
}

Functions

typedToolExecute

Execute a typed tool call through the JSON middleware pipeline.

Converts args to JSON, runs the native tool execution lifecycle, and decodes the final JSON result back into the caller’s typed result shape.

Parameters

• name: Tool name.
• args: Typed tool arguments.
• func: The tool implementation.
• argsCodec: Codec for args serialization/deserialization.
• resultCodec: Codec for result serialization/deserialization.
• options: Optional scope handle, attributes, data, metadata.

Returns

A promise resolving to the decoded typed tool result.

Remarks

The wrapper accepts both synchronous and promise-returning tool implementations; codec failures and native execution errors propagate to the returned promise.

1
export declare function typedToolExecute<TArgs, TResult>(
2
  name: string,
3
  args: TArgs,
4
  func: (args: TArgs) => TResult | Promise<TResult>,
5
  argsCodec: Codec<TArgs>,
6
  resultCodec: Codec<TResult>,
7
  options?: TypedToolExecuteOptions,
8
): Promise<TResult>;

typedLlmExecute

Execute a typed LLM call through the JSON middleware pipeline.

Forwards the JSON-shaped request payload into the native LLM lifecycle and decodes the final response with the supplied response codec before resolving.

Parameters

• name: Model/provider name.
• request: The LLM request object ({headers, content}).
• func: The LLM implementation.
• responseCodec: Codec for response serialization/deserialization.
• options: Optional scope handle, attributes, data, metadata, modelName.

Returns

A promise resolving to the decoded typed LLM response.

Remarks

options.responseCodec only affects annotated response event payloads; failures while decoding those event payloads are downgraded to debug logging and do not rewrite the caller-visible response.

1
export declare function typedLlmExecute<TRequest extends LlmRequestShape, TResponse>(
2
  name: string,
3
  request: TRequest,
4
  func: (request: TRequest) => TResponse | Promise<TResponse>,
5
  responseCodec: Codec<TResponse>,
6
  options?: TypedLlmExecuteOptions,
7
): Promise<TResponse>;

typedLlmStreamExecute

Execute a typed streaming LLM call through the JSON middleware pipeline.

Chunks yielded by func are converted to JSON via chunkCodec.toJson before entering the middleware pipeline. After interception, chunks are converted back via chunkCodec.fromJson before reaching collector. The finalizer result is converted via responseCodec.toJson.

Parameters

• name: Model/provider name.
• request: The LLM request object ({headers, content}).
• func: Async iterable producer for typed stream chunks.
• collector: Callback invoked with each decoded typed chunk.
• finalizer: Callback that returns the final typed aggregate response.
• chunkCodec: Codec for stream chunk serialization/deserialization.
• responseCodec: Codec for final response serialization/deserialization.
• options: Optional scope handle, attributes, data, metadata, modelName.

Returns

A promise resolving to the native LlmStream handle.

Remarks

The wrapper bridges async iteration back into the native stream lifecycle and closes the stream even when the source iterator throws.

1
export declare function typedLlmStreamExecute<TRequest extends LlmRequestShape, TChunk, TResponse>(
2
  name: string,
3
  request: TRequest,
4
  func: (request: TRequest) => AsyncIterable<TChunk>,
5
  collector: (chunk: TChunk) => void,
6
  finalizer: () => TResponse,
7
  chunkCodec: Codec<TChunk>,
8
  responseCodec: Codec<TResponse>,
9
  options?: TypedLlmStreamExecuteOptions,
10
): Promise<LlmStream>;

Type Aliases

JsonPrimitive

One JSON scalar value accepted by the typed wrapper APIs.

1
export type JsonPrimitive = string | number | boolean | null;

JsonValue

Any JSON-serializable value accepted by the typed wrapper APIs.

1
export type JsonValue = JsonPrimitive | JsonObject | JsonArray;