Context (env+def)
Information about the context of script execution is available in the env
global object.
Environment (env
)
The env
global object contains properties that provide information about the script execution context.
env
is populated automatically by the GenAIScript runtime.
env.files
The env.files
array contains all files within the execution context. The context is defined implicitly
by the user based on:
script
files
option
or multiple paths
-
the UI location to start the tool
-
CLI files arguments.
The files are stored in env.files
which can be injected in the prompt.
- using
def
- filtered,
- directly in a
$
call
In this case, the prompt is automatically expanded with a def
call and the value of env.files
.
env.vars
The vars
property contains the variables that have been defined in the script execution context.
Read more about variables.
Definition (def
)
The def("FILE", file)
function is a shorthand for generating a fenced variable output.
The “meta-variable” (FILE
in this example) name should be all uppercase (but can include
approximately equivalent to:
The def
function can also be used with an array of files, such as env.files
.
Language
You can specify the language of the text contained in def
. This can help GenAIScript optimize the rendering of the text.
Referencing
The def
function returns a variable name that can be used in the prompt.
The name might be formatted differently to accommodate the model’s preference.
File filters
Since a script may be executed on a full folder, it is often useful to filter the files based on
- their extension
- or using a glob:
Empty files
By default, if def
is used with an empty array of files, it will cancel the prompt. You can override this behavior
by setting ignoreEmpty
to true
.
maxTokens
It is possible to limit the number of tokens that are generated by the def
function. This can be useful when the output is too large and the model has a token limit.
The maxTokens
option can be set to a number to limit the number of tokens generated for each individual file.
Data filters
The def
function treats data files such as CSV and XLSX specially. It will automatically convert the data into a
markdown table format to improve tokenization.
sliceHead
, keep the top N rows
sliceTail
, keep the last N rows
sliceSample
, keep a random sample of N rows
Prompt Caching
You can specify ephemeral: true
to enable prompt caching optimization. In particular, a def
with ephemeral
will be rendered at the back of the prompt
to persist the cache prefix.
Safety: Prompt Injection detection
You can schedule a check for prompt injection/jai break with your configured content safety provider.
Predicted output
Some models, like OpenAI gpt-4o and gpt-4o-mini, support specifying a predicted output (with some limitations). This helps reduce latency for model responses where much of the response is known ahead of time. This can be helpful when asking the LLM to edit specific files.
Set the prediction: true
flag to enable it on a def
call. Note that only a single file can be predicted.
Data definition (defData
)
The defData
function offers additional formatting options for converting a data object into a textual representation. It supports rendering objects as YAML, JSON, or CSV (formatted as a Markdown table).
The defData
function also supports functions to slice the input rows and columns.
headers
, list of column names to includesliceHead
, number of rows to include from the beginningsliceTail
, number of rows to include from the endsliceSample
, number of rows to pick at randomdistinct
, list of column names to deduplicate the data based on
You can leverage the data filtering functionality
using parsers.tidyData
as well.
Diff Definition (defDiff
)
It is very common to compare two pieces of data and ask the LLM to analyze the differences. Using diffs is a great way to naturally compress the information since we only focus on differences!
The defDiff
takes care of formatting the diff in a way that helps LLM reason. It behaves similarly to def
and assigns
a name to the diff.
You can leverage the diff functionality using parsers.diff
.