> 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 full documentation content, see https://docs.nvidia.com/nemo/guardrails/llms-full.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/nemo/guardrails/_mcp/server.

# nemoguardrails.colang.v2_x.lang.colang_ast

The data types that are used when constructing the Abstract Syntax Tree after parsing.

## Module Contents

### Classes

| Name                                                                                     | Description                                                                                         |
| ---------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| [`Abort`](#nemoguardrails-colang-v2_x-lang-colang_ast-Abort)                             | -                                                                                                   |
| [`Assignment`](#nemoguardrails-colang-v2_x-lang-colang_ast-Assignment)                   | -                                                                                                   |
| [`BeginScope`](#nemoguardrails-colang-v2_x-lang-colang_ast-BeginScope)                   | Defines the start of a new scope in a flow to keep track of all started actions/flows.              |
| [`Break`](#nemoguardrails-colang-v2_x-lang-colang_ast-Break)                             | -                                                                                                   |
| [`CatchPatternFailure`](#nemoguardrails-colang-v2_x-lang-colang_ast-CatchPatternFailure) | Set the pattern failure catcher to catch a failing pattern and forward it to the specified label.   |
| [`Continue`](#nemoguardrails-colang-v2_x-lang-colang_ast-Continue)                       | -                                                                                                   |
| [`Decorator`](#nemoguardrails-colang-v2_x-lang-colang_ast-Decorator)                     | The definition for a flow decorator.                                                                |
| [`Element`](#nemoguardrails-colang-v2_x-lang-colang_ast-Element)                         | Base class for all elements in the AST.                                                             |
| [`Elements`](#nemoguardrails-colang-v2_x-lang-colang_ast-Elements)                       | Element that encapsulates multiple sub-elements.                                                    |
| [`EndScope`](#nemoguardrails-colang-v2_x-lang-colang_ast-EndScope)                       | Defines the end of a scope in a flow that will stop all active actions/flows that have been started |
| [`Flow`](#nemoguardrails-colang-v2_x-lang-colang_ast-Flow)                               | Element that represents a flow.                                                                     |
| [`FlowParamDef`](#nemoguardrails-colang-v2_x-lang-colang_ast-FlowParamDef)               | The definition for a flow parameter.                                                                |
| [`FlowReturnMemberDef`](#nemoguardrails-colang-v2_x-lang-colang_ast-FlowReturnMemberDef) | The definition for a flow return member.                                                            |
| [`ForkHead`](#nemoguardrails-colang-v2_x-lang-colang_ast-ForkHead)                       | Element to fork the current head into multiple heads.                                               |
| [`Global`](#nemoguardrails-colang-v2_x-lang-colang_ast-Global)                           | Declare a global variable.                                                                          |
| [`Goto`](#nemoguardrails-colang-v2_x-lang-colang_ast-Goto)                               | Element for navigating to a label.                                                                  |
| [`If`](#nemoguardrails-colang-v2_x-lang-colang_ast-If)                                   | -                                                                                                   |
| [`Import`](#nemoguardrails-colang-v2_x-lang-colang_ast-Import)                           | The definition for an import statement.                                                             |
| [`Label`](#nemoguardrails-colang-v2_x-lang-colang_ast-Label)                             | -                                                                                                   |
| [`Log`](#nemoguardrails-colang-v2_x-lang-colang_ast-Log)                                 | Log a message.                                                                                      |
| [`MergeHeads`](#nemoguardrails-colang-v2_x-lang-colang_ast-MergeHeads)                   | Merge heads based on uid from same flow.                                                            |
| [`Meta`](#nemoguardrails-colang-v2_x-lang-colang_ast-Meta)                               | -                                                                                                   |
| [`Print`](#nemoguardrails-colang-v2_x-lang-colang_ast-Print)                             | Print a message.                                                                                    |
| [`Priority`](#nemoguardrails-colang-v2_x-lang-colang_ast-Priority)                       | Set the priority of the flow in terms of action resolution.                                         |
| [`Return`](#nemoguardrails-colang-v2_x-lang-colang_ast-Return)                           | -                                                                                                   |
| [`Source`](#nemoguardrails-colang-v2_x-lang-colang_ast-Source)                           | Information about the source of an element.                                                         |
| [`Spec`](#nemoguardrails-colang-v2_x-lang-colang_ast-Spec)                               | Element that represents a spec.                                                                     |
| [`SpecAnd`](#nemoguardrails-colang-v2_x-lang-colang_ast-SpecAnd)                         | A conjunction of specs.                                                                             |
| [`SpecOp`](#nemoguardrails-colang-v2_x-lang-colang_ast-SpecOp)                           | An operation performed on a spec.                                                                   |
| [`SpecOpType`](#nemoguardrails-colang-v2_x-lang-colang_ast-SpecOpType)                   | All internal event types.                                                                           |
| [`SpecOr`](#nemoguardrails-colang-v2_x-lang-colang_ast-SpecOr)                           | A disjunction of spects.                                                                            |
| [`SpecType`](#nemoguardrails-colang-v2_x-lang-colang_ast-SpecType)                       | The type of a spec.                                                                                 |
| [`Value`](#nemoguardrails-colang-v2_x-lang-colang_ast-Value)                             | Element that contains a value.                                                                      |
| [`WaitForHeads`](#nemoguardrails-colang-v2_x-lang-colang_ast-WaitForHeads)               | Wait for a number of heads.                                                                         |
| [`When`](#nemoguardrails-colang-v2_x-lang-colang_ast-When)                               | -                                                                                                   |
| [`While`](#nemoguardrails-colang-v2_x-lang-colang_ast-While)                             | -                                                                                                   |

### Functions

| Name                                                                           | Description                            |
| ------------------------------------------------------------------------------ | -------------------------------------- |
| [`_make_hashable`](#nemoguardrails-colang-v2_x-lang-colang_ast-_make_hashable) | Make all subtypes of Element hashable. |

### Data

[`ElementType`](#nemoguardrails-colang-v2_x-lang-colang_ast-ElementType)

[`SpecElementType`](#nemoguardrails-colang-v2_x-lang-colang_ast-SpecElementType)

### API

```python
class nemoguardrails.colang.v2_x.lang.colang_ast.Abort(
    _type: str = 'abort',
    _source: typing.Optional[nemoguardrails.colang.v2_x.lang.colang_ast.Source] = None
)
```

Dataclass

**Bases:** [Element](#nemoguardrails-colang-v2_x-lang-colang_ast-Element)

```python
class nemoguardrails.colang.v2_x.lang.colang_ast.Assignment(
    _type: str = 'assignment',
    _source: typing.Optional[nemoguardrails.colang.v2_x.lang.colang_ast.Source] = None,
    key: str = '',
    expression: str = ''
)
```

Dataclass

**Bases:** [Element](#nemoguardrails-colang-v2_x-lang-colang_ast-Element)

```python
class nemoguardrails.colang.v2_x.lang.colang_ast.BeginScope(
    _type: str = '_begin_scope',
    _source: typing.Optional[nemoguardrails.colang.v2_x.lang.colang_ast.Source] = None,
    name: str = ''
)
```

Dataclass

**Bases:** [Element](#nemoguardrails-colang-v2_x-lang-colang_ast-Element)

Defines the start of a new scope in a flow to keep track of all started actions/flows.

```python
class nemoguardrails.colang.v2_x.lang.colang_ast.Break(
    _type: str = 'break',
    _source: typing.Optional[nemoguardrails.colang.v2_x.lang.colang_ast.Source] = None,
    label: typing.Optional[str] = None
)
```

Dataclass

**Bases:** [Element](#nemoguardrails-colang-v2_x-lang-colang_ast-Element)

```python
class nemoguardrails.colang.v2_x.lang.colang_ast.CatchPatternFailure(
    _type: str = '_catch_pattern_failure',
    _source: typing.Optional[nemoguardrails.colang.v2_x.lang.colang_ast.Source] = None,
    label: typing.Optional[str] = None
)
```

Dataclass

**Bases:** [Element](#nemoguardrails-colang-v2_x-lang-colang_ast-Element)

Set the pattern failure catcher to catch a failing pattern and forward it to the specified label.
If the label is not set the failure will be propagated to the parent flow.

```python
class nemoguardrails.colang.v2_x.lang.colang_ast.Continue(
    _type: str = 'continue',
    _source: typing.Optional[nemoguardrails.colang.v2_x.lang.colang_ast.Source] = None,
    label: typing.Optional[str] = None
)
```

Dataclass

**Bases:** [Element](#nemoguardrails-colang-v2_x-lang-colang_ast-Element)

```python
class nemoguardrails.colang.v2_x.lang.colang_ast.Decorator(
    _type: str = 'decorator',
    _source: typing.Optional[nemoguardrails.colang.v2_x.lang.colang_ast.Source] = None,
    name: str = '',
    parameters: dict = dict()
)
```

Dataclass

**Bases:** [Element](#nemoguardrails-colang-v2_x-lang-colang_ast-Element)

The definition for a flow decorator.

Explicit typing is not yet supported.

```python
class nemoguardrails.colang.v2_x.lang.colang_ast.Element(
    _type: str,
    _source: typing.Optional[nemoguardrails.colang.v2_x.lang.colang_ast.Source] = None
)
```

Dataclass

Base class for all elements in the AST.

```python
nemoguardrails.colang.v2_x.lang.colang_ast.Element.__eq__(
    other
)
```

```python
nemoguardrails.colang.v2_x.lang.colang_ast.Element.__getitem__(
    key
)
```

```python
nemoguardrails.colang.v2_x.lang.colang_ast.Element.get(
    key,
    default_value = None
)
```

Getter for backward compatibility with dict elements.

TODO: to remove at some point.

```python
nemoguardrails.colang.v2_x.lang.colang_ast.Element.hash()
```

Return the hash for the current object.

```python
class nemoguardrails.colang.v2_x.lang.colang_ast.Elements(
    _type: str = 'value',
    _source: typing.Optional[nemoguardrails.colang.v2_x.lang.colang_ast.Source] = None,
    elements: typing.List[nemoguardrails.colang.v2_x.lang.colang_ast.Element] = list()
)
```

Dataclass

**Bases:** [Element](#nemoguardrails-colang-v2_x-lang-colang_ast-Element)

Element that encapsulates multiple sub-elements.

```python
class nemoguardrails.colang.v2_x.lang.colang_ast.EndScope(
    _type: str = '_end_scope',
    _source: typing.Optional[nemoguardrails.colang.v2_x.lang.colang_ast.Source] = None,
    name: str = ''
)
```

Dataclass

**Bases:** [Element](#nemoguardrails-colang-v2_x-lang-colang_ast-Element)

Defines the end of a scope in a flow that will stop all active actions/flows that have been started
within that scope.

```python
class nemoguardrails.colang.v2_x.lang.colang_ast.Flow(
    _type: str = 'flow',
    _source: typing.Optional[nemoguardrails.colang.v2_x.lang.colang_ast.Source] = None,
    name: str = '',
    decorators: typing.List[nemoguardrails.colang.v2_x.lang.colang_ast.Decorator] = list(),
    parameters: typing.List[nemoguardrails.colang.v2_x.lang.colang_ast.FlowParamDef] = list(),
    return_members: typing.List[nemoguardrails.colang.v2_x.lang.colang_ast.FlowReturnMemberDef] = list(),
    elements: typing.List[nemoguardrails.colang.v2_x.lang.colang_ast.Element] = list(),
    source_code: typing.Optional[str] = None,
    file_info: typing.Dict[str, typing.Any] = dict()
)
```

Dataclass

**Bases:** [Element](#nemoguardrails-colang-v2_x-lang-colang_ast-Element)

Element that represents a flow.

```python
class nemoguardrails.colang.v2_x.lang.colang_ast.FlowParamDef(
    name: str,
    default_value_expr: typing.Optional[str] = None
)
```

Dataclass

The definition for a flow parameter.

Explicit typing is not yet supported.

```python
class nemoguardrails.colang.v2_x.lang.colang_ast.FlowReturnMemberDef(
    name: str,
    default_value_expr: typing.Optional[str] = None
)
```

Dataclass

The definition for a flow return member.

Explicit typing is not yet supported.

```python
class nemoguardrails.colang.v2_x.lang.colang_ast.ForkHead(
    _type: str = '_fork',
    _source: typing.Optional[nemoguardrails.colang.v2_x.lang.colang_ast.Source] = None,
    fork_uid: str = '',
    labels: typing.List[str] = list()
)
```

Dataclass

**Bases:** [Element](#nemoguardrails-colang-v2_x-lang-colang_ast-Element)

Element to fork the current head into multiple heads.

For each label a new head.

```python
class nemoguardrails.colang.v2_x.lang.colang_ast.Global(
    _type: str = '_global',
    _source: typing.Optional[nemoguardrails.colang.v2_x.lang.colang_ast.Source] = None,
    name: str = ''
)
```

Dataclass

**Bases:** [Element](#nemoguardrails-colang-v2_x-lang-colang_ast-Element)

Declare a global variable.

```python
class nemoguardrails.colang.v2_x.lang.colang_ast.Goto(
    _type: str = 'goto',
    _source: typing.Optional[nemoguardrails.colang.v2_x.lang.colang_ast.Source] = None,
    label: str = '',
    expression: str = 'True'
)
```

Dataclass

**Bases:** [Element](#nemoguardrails-colang-v2_x-lang-colang_ast-Element)

Element for navigating to a label.

If the expression is not True, just skips to the next element.

```python
class nemoguardrails.colang.v2_x.lang.colang_ast.If(
    _type: str = 'if',
    _source: typing.Optional[nemoguardrails.colang.v2_x.lang.colang_ast.Source] = None,
    expression: str = '',
    then_elements: typing.List[nemoguardrails.colang.v2_x.lang.colang_ast.ElementType] = list(),
    else_elements: typing.Optional[typing.List[nemoguardrails.colang.v2_x.lang.colang_ast.ElementType]] = None
)
```

Dataclass

**Bases:** [Element](#nemoguardrails-colang-v2_x-lang-colang_ast-Element)

```python
class nemoguardrails.colang.v2_x.lang.colang_ast.Import(
    _type: str = 'import',
    _source: typing.Optional[nemoguardrails.colang.v2_x.lang.colang_ast.Source] = None,
    path: typing.Optional[str] = None,
    package: typing.Optional[str] = None
)
```

Dataclass

**Bases:** [Element](#nemoguardrails-colang-v2_x-lang-colang_ast-Element)

The definition for an import statement.

We support both "path mode" and "package" mode.

import core
import rag.advanced
import "some-spec/some-sub-package"

```python
class nemoguardrails.colang.v2_x.lang.colang_ast.Label(
    _type: str = 'label',
    _source: typing.Optional[nemoguardrails.colang.v2_x.lang.colang_ast.Source] = None,
    name: str = ''
)
```

Dataclass

**Bases:** [Element](#nemoguardrails-colang-v2_x-lang-colang_ast-Element)

```python
class nemoguardrails.colang.v2_x.lang.colang_ast.Log(
    _type: str = '_log',
    _source: typing.Optional[nemoguardrails.colang.v2_x.lang.colang_ast.Source] = None,
    info: str = ''
)
```

Dataclass

**Bases:** [Element](#nemoguardrails-colang-v2_x-lang-colang_ast-Element)

Log a message.

```python
class nemoguardrails.colang.v2_x.lang.colang_ast.MergeHeads(
    _type: str = '_merge',
    _source: typing.Optional[nemoguardrails.colang.v2_x.lang.colang_ast.Source] = None,
    fork_uid: str = ''
)
```

Dataclass

**Bases:** [Element](#nemoguardrails-colang-v2_x-lang-colang_ast-Element)

Merge heads based on uid from same flow.

Only one head will advance from this element.

```python
class nemoguardrails.colang.v2_x.lang.colang_ast.Meta(
    _type: str = 'meta',
    _source: typing.Optional[nemoguardrails.colang.v2_x.lang.colang_ast.Source] = None,
    meta: dict = dict()
)
```

Dataclass

**Bases:** [Element](#nemoguardrails-colang-v2_x-lang-colang_ast-Element)

```python
class nemoguardrails.colang.v2_x.lang.colang_ast.Print(
    _type: str = '_print',
    _source: typing.Optional[nemoguardrails.colang.v2_x.lang.colang_ast.Source] = None,
    info: str = ''
)
```

Dataclass

**Bases:** [Element](#nemoguardrails-colang-v2_x-lang-colang_ast-Element)

Print a message.

```python
class nemoguardrails.colang.v2_x.lang.colang_ast.Priority(
    _type: str = '_priority',
    _source: typing.Optional[nemoguardrails.colang.v2_x.lang.colang_ast.Source] = None,
    priority_expr: str = '1.0'
)
```

Dataclass

**Bases:** [Element](#nemoguardrails-colang-v2_x-lang-colang_ast-Element)

Set the priority of the flow in terms of action resolution.

```python
class nemoguardrails.colang.v2_x.lang.colang_ast.Return(
    _type: str = 'return',
    _source: typing.Optional[nemoguardrails.colang.v2_x.lang.colang_ast.Source] = None,
    expression: typing.Optional[str] = None
)
```

Dataclass

**Bases:** [Element](#nemoguardrails-colang-v2_x-lang-colang_ast-Element)

```python
class nemoguardrails.colang.v2_x.lang.colang_ast.Source(
    line: int,
    column: int,
    start_pos: int,
    end_pos: int
)
```

Dataclass

Information about the source of an element.

```python
class nemoguardrails.colang.v2_x.lang.colang_ast.Spec(
    _type: str = 'spec',
    _source: typing.Optional[nemoguardrails.colang.v2_x.lang.colang_ast.Source] = None,
    name: typing.Optional[str] = None,
    spec_type: nemoguardrails.colang.v2_x.lang.colang_ast.SpecType = SpecType.EVENT,
    arguments: typing.Dict[str, typing.Any] = dict(),
    members: typing.Optional[typing.List[nemoguardrails.colang.v2_x.lang.colang_ast.Spec]] = None,
    var_name: typing.Optional[str] = None,
    ref: typing.Optional[typing.Union[str, dict]] = None
)
```

Dataclass

**Bases:** [Element](#nemoguardrails-colang-v2_x-lang-colang_ast-Element)

Element that represents a spec.

A spec can represent a flow, an action or an event. Currently, we will determine
at runtime what the spec is.

A spec is either specified directly through a name and arguments, or through a
variable. In both cases, additional members can be accessed, e.g., .Finished().

```python
class nemoguardrails.colang.v2_x.lang.colang_ast.SpecAnd(
    _type: str = 'spec_and',
    _source: typing.Optional[nemoguardrails.colang.v2_x.lang.colang_ast.Source] = None,
    specs: typing.List[nemoguardrails.colang.v2_x.lang.colang_ast.Spec] = list()
)
```

Dataclass

**Bases:** [Element](#nemoguardrails-colang-v2_x-lang-colang_ast-Element)

A conjunction of specs.

```python
class nemoguardrails.colang.v2_x.lang.colang_ast.SpecOp(
    _type: str = 'spec_op',
    _source: typing.Optional[nemoguardrails.colang.v2_x.lang.colang_ast.Source] = None,
    op: str = '',
    spec: typing.Union[nemoguardrails.colang.v2_x.lang.colang_ast.Spec, dict] = Spec(),
    return_var_name: typing.Optional[str] = None,
    info: dict = dict()
)
```

Dataclass

**Bases:** [Element](#nemoguardrails-colang-v2_x-lang-colang_ast-Element)

An operation performed on a spec.

Valid operations are: send, match, start, stop, await, activate, deactivate.

```python
class nemoguardrails.colang.v2_x.lang.colang_ast.SpecOpType
```

**Bases:** `enum.Enum`

All internal event types.

```python
class nemoguardrails.colang.v2_x.lang.colang_ast.SpecOr(
    _type: str = 'spec_or',
    _source: typing.Optional[nemoguardrails.colang.v2_x.lang.colang_ast.Source] = None,
    specs: typing.List[nemoguardrails.colang.v2_x.lang.colang_ast.Spec] = list()
)
```

Dataclass

**Bases:** [Element](#nemoguardrails-colang-v2_x-lang-colang_ast-Element)

A disjunction of spects.

```python
class nemoguardrails.colang.v2_x.lang.colang_ast.SpecType
```

**Bases:** `enum.Enum`

The type of a spec.

```python
class nemoguardrails.colang.v2_x.lang.colang_ast.Value(
    _type: str = 'value',
    _source: typing.Optional[nemoguardrails.colang.v2_x.lang.colang_ast.Source] = None,
    value: typing.Any = None
)
```

Dataclass

**Bases:** [Element](#nemoguardrails-colang-v2_x-lang-colang_ast-Element)

Element that contains a value.

```python
class nemoguardrails.colang.v2_x.lang.colang_ast.WaitForHeads(
    _type: str = '_wait_for_heads',
    _source: typing.Optional[nemoguardrails.colang.v2_x.lang.colang_ast.Source] = None,
    number: int = 1
)
```

Dataclass

**Bases:** [Element](#nemoguardrails-colang-v2_x-lang-colang_ast-Element)

Wait for a number of heads.

Once enough heads have reached this element they will be merged
and only one head will advance.

```python
class nemoguardrails.colang.v2_x.lang.colang_ast.When(
    _type: str = 'when',
    _source: typing.Optional[nemoguardrails.colang.v2_x.lang.colang_ast.Source] = None,
    when_specs: typing.List[nemoguardrails.colang.v2_x.lang.colang_ast.SpecElementType] = list(),
    then_elements: typing.List[typing.List[nemoguardrails.colang.v2_x.lang.colang_ast.ElementType]] = list(),
    else_elements: typing.Optional[typing.List[nemoguardrails.colang.v2_x.lang.colang_ast.ElementType]] = None
)
```

Dataclass

**Bases:** [Element](#nemoguardrails-colang-v2_x-lang-colang_ast-Element)

```python
class nemoguardrails.colang.v2_x.lang.colang_ast.While(
    _type: str = 'while',
    _source: typing.Optional[nemoguardrails.colang.v2_x.lang.colang_ast.Source] = None,
    expression: str = '',
    elements: typing.List[nemoguardrails.colang.v2_x.lang.colang_ast.ElementType] = list()
)
```

Dataclass

**Bases:** [Element](#nemoguardrails-colang-v2_x-lang-colang_ast-Element)

```python
nemoguardrails.colang.v2_x.lang.colang_ast._make_hashable(
    obj: typing.Any
) -> typing.Any
```

Make all subtypes of Element hashable.

```python
nemoguardrails.colang.v2_x.lang.colang_ast.ElementType = Union[Element, dict]
```

```python
nemoguardrails.colang.v2_x.lang.colang_ast.SpecElementType = Union[Spec, SpecAnd, SpecOr]
```