---
updatedAt: 2026-04-10T10:34:57.000Z
agentTools:
  projectIndex: https://developers.newo.ai/llms.txt
---

# NSL filter and function reference

NSL (Newo Script Language) is built on Jinja2. In addition to standard Jinja2 filters and tests, the platform provides NSL-specific actions and a small set of custom filters. This page lists all available filters and custom functions.

***

## Standard Jinja2 filters

All standard Jinja2 filters are available in NSL. Commonly used filters include:

| **Filter** | **Example**                          | **Description**                                             |
| :--------- | :----------------------------------- | :---------------------------------------------------------- |
| `upper`    | `{{ value\|upper }}`                 | Converts a string to uppercase.                             |
| `lower`    | `{{ value\|lower }}`                 | Converts a string to lowercase.                             |
| `trim`     | `{{ value\|trim }}`                  | Strips leading and trailing whitespace.                     |
| `replace`  | `{{ value\|replace("old", "new") }}` | Replaces all occurrences of a substring.                    |
| `default`  | `{{ value\|default("fallback") }}`   | Returns the default value if `value` is undefined or falsy. |
| `int`      | `{{ value\|int }}`                   | Converts a value to integer.                                |
| `float`    | `{{ value\|float }}`                 | Converts a value to float.                                  |
| `string`   | `{{ value\|string }}`                | Converts a value to string.                                 |
| `length`   | `{{ value\|length }}`                | Returns the length of a string, list, or dict.              |
| `join`     | `{{ list\|join(", ") }}`             | Joins a list into a string using the separator.             |
| `split`    | `{{ value\|split(",") }}`            | Splits a string into a list on the delimiter.               |
| `first`    | `{{ list\|first }}`                  | Returns the first item in a list.                           |
| `last`     | `{{ list\|last }}`                   | Returns the last item in a list.                            |
| `sort`     | `{{ list\|sort }}`                   | Sorts a list.                                               |
| `unique`   | `{{ list\|unique }}`                 | Returns unique items from a list.                           |
| `tojson`   | `{{ value\|tojson }}`                | Serializes a value to JSON string.                          |
| `fromjson` | `{{ value\|fromjson }}`              | Parses a JSON string into a Python object.                  |
| `truncate` | `{{ value\|truncate(100) }}`         | Truncates a string to the given number of characters.       |
| `round`    | `{{ value\|round(2) }}`              | Rounds a number to the given number of decimal places.      |
| `abs`      | `{{ value\|abs }}`                   | Returns the absolute value of a number.                     |
| `bool`     | `{{ value\|bool }}`                  | Converts a value to boolean.                                |

***

## NSL-specific behaviors

### Block scoping

NSL does **not** use standard Jinja2 block scoping. Variables set with `{% set %}` inside `{% if %}` or `{% for %}` blocks are accessible outside those blocks. This differs from standard Jinja2 behavior.

```
{% if condition %}
  {% set result = "yes" %}
{% else %}
  {% set result = "no" %}
{% endif %}

{# result is accessible here in NSL — it would be undefined in standard Jinja2 #}
{{ result }}
```

### Output suppression

Use `{%- -%}` to suppress whitespace around block tags:

```
{%- set x = GetCustomerAttribute(field="project_attributes_business_name") -%}
```

Using `{% set %}` without `-` trimming will produce empty lines in the output. For assignments that should produce no output, use `{%- -%}`.

### Comments

Single-line: `{# This is a comment #}`

Multi-line:

```
{##
  This is a
  multi-line comment
##}
```

***

## Role tags

NSL uses role tags to structure the content passed to the LLM in `Gen()` and `GenStream()` calls:

| **Tag**                      | **Description**                                                 |
| :--------------------------- | :-------------------------------------------------------------- |
| `<system>...</system>`       | System prompt content. Sets context, instructions, and persona. |
| `<user>...</user>`           | User turn content. Represents the human's input.                |
| `<assistant>...</assistant>` | Assistant turn content. Represents prior agent responses.       |

Role tags are only meaningful inside `Gen()` / `GenStream()` calls. Outside of generation calls, they are treated as literal strings.

***

## Custom NSL actions used as expressions

Actions that return values and are commonly used as expressions within `{% set %}` or `{{ }}`:

| **Action**                    | **Returns**  | **Common use**                                        |
| :---------------------------- | :----------- | :---------------------------------------------------- |
| `GetCustomerAttribute(field)` | string / any | Read a customer attribute value                       |
| `GetPersonaAttribute(field)`  | string / any | Read a persona attribute value                        |
| `GetProjectAttribute(field)`  | string / any | Read a project attribute value                        |
| `GetState(name)`              | any          | Read a state field value                              |
| `GetUser(field)`              | string / any | Read a user field (e.g., `id`, `name`, `email`)       |
| `GetSessionInfo(field)`       | string / any | Read session metadata                                 |
| `GetDatetime(format)`         | string       | Current date and time in the specified format         |
| `IsEmpty(value)`              | bool         | Check if a value is null, empty string, or empty list |
| `IsSimilar(a, b, threshold)`  | bool         | Check if two strings are semantically similar         |
| `Concat(a, b)`                | string       | Concatenate two strings                               |
| `Stringify(value)`            | string       | Convert any value to a string representation          |
| `GetRandomChoice(list)`       | any          | Return a random item from a list                      |
| `GetValueJSON(json, path)`    | any          | Extract a value from a JSON object by path            |