> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/nemo/guardrails/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/nemo/guardrails/_mcp/server.

# nemoguardrails.manifests.surface_reference

Parsing and normalization for configured rail surface references.

## Module Contents

### Functions

| Name                                                                                                                       | Description                                                       |
| -------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| [`_is_surface_parameter_name_character`](#nemoguardrails-manifests-surface_reference-_is_surface_parameter_name_character) | -                                                                 |
| [`_is_surface_parameter_name_start`](#nemoguardrails-manifests-surface_reference-_is_surface_parameter_name_start)         | -                                                                 |
| [`_surface_parse_error`](#nemoguardrails-manifests-surface_reference-_surface_parse_error)                                 | -                                                                 |
| [`normalize_configured_surface_name`](#nemoguardrails-manifests-surface_reference-normalize_configured_surface_name)       | Return the surface name prefix without validating its parameters. |
| [`parse_configured_surface`](#nemoguardrails-manifests-surface_reference-parse_configured_surface)                         | Parse one complete configured surface reference.                  |

### Data

[`_HORIZONTAL_WHITESPACE`](#nemoguardrails-manifests-surface_reference-_HORIZONTAL_WHITESPACE)

[`_QUOTES`](#nemoguardrails-manifests-surface_reference-_QUOTES)

### API

```python
nemoguardrails.manifests.surface_reference._is_surface_parameter_name_character(
    character: str
) -> bool
```

```python
nemoguardrails.manifests.surface_reference._is_surface_parameter_name_start(
    character: str
) -> bool
```

```python
nemoguardrails.manifests.surface_reference._surface_parse_error(
    message: str,
    position: int
) -> typing.NoReturn
```

```python
nemoguardrails.manifests.surface_reference.normalize_configured_surface_name(
    flow_text: str
) -> str
```

Return the surface name prefix without validating its parameters.

Malformed parameter syntax may still yield a normalized name.

```python
nemoguardrails.manifests.surface_reference.parse_configured_surface(
    flow_text: str
) -> typing.Tuple[str, typing.Dict[str, str]]
```

Parse one complete configured surface reference.

The accepted syntax is a bare surface name followed by zero or more
whitespace-separated `$name=value` parameters. Spaces around `=` and
parenthesized parameters are not supported. Values remain strings; bare
values end at whitespace, while single- or double-quoted values may contain
whitespace and punctuation.

**Raises:**

* `ValueError`: If the reference is empty, contains controls, or has malformed,
  blank, adjacent, or duplicate parameters.

```python
nemoguardrails.manifests.surface_reference._HORIZONTAL_WHITESPACE = ' \t'
```

```python
nemoguardrails.manifests.surface_reference._QUOTES = '"\''
```