Skip to content
GenAIScript
Blog

Context (env+def)

The information about the context of the script execution are 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
script({
    files: "**/*.pdf",
})

or multiple paths

script({
    files: ["src/*.pdf", "other/*.pdf"],
})

  • the UI location to start the tool

  • CLI files arguments.

The files are stored in env.files which can be injected in the prompt.

  • directly in a $ call
$`Summarize ${env.files}.
  • using def
def("FILE", env.files)
  • filtered,
def("DOCS", env.files, { endsWith: ".md" })
def("CODE", env.files, { endsWith: ".py" })

env.vars

The vars property contains the variables that have been defined in the script execution context.

// grab locale from variable or default to en-US
const locale = env.vars.locale || "en-US"

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

def("FILE", file)

approximately equivalent to:

$`FILE ${file.filename}:
```
${env.file.content}
```

The def function can also be used with an array of files, such as env.files.

def("FILE", env.files)

Language

You can specify the language of the text contained in def. This can help GenAIScript optimize the rendering of the text.

// hint that the output is a diff
def("DIFF", gitdiff, { language: "diff" })

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.

const f = def("FILE", file)


$`Summarize ${f}.`

File filters

Since a script may be executed on a full folder, it is often useful to filter the files based on

  • their extension
def("FILE", env.files, { endsWith: ".md" })
def("FILE", files, { glob: "**/*.{md,mdx}" })

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.

def("FILE", env.files, { endsWith: ".md", ignoreEmpty: 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 indivial file.

def("FILE", env.files, { maxTokens: 100 })

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
def("FILE", env.files, { sliceHead: 100 })
  • sliceTail, keep the last N rows
def("FILE", env.files, { sliceTail: 100 })
  • sliceSample, keep a random sample of N rows
def("FILE", env.files, { sliceSample: 100 })

Prompt Caching

You can specify ephemeral: true to turn on some prompt caching optimization. In paricular, a def with ephemeral will be rendered at the back of the prompt to persist the cache prefix.

def("FILE", env.files, { ephemeral: true })

Safety: Prompt Injection detection

You can schedule a check for prompt injection/jai break with your configured content safety provider.

def("FILE", env.files, { detectPromptInjection: true })

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).

// render to mardownified CSV by default
defData("DATA", data)


// render as yaml
defData("DATA", csv, { format: "yaml" })

The defData function also support functions to slice the input rows and columns.

  • headers, list of column names to include
  • sliceHead, number of rows to include from the beginning
  • sliceTail, number of rows to include from the end
  • sliceSample, number of rows to pick at random
  • distinct, list of column names to deduplicate the data based on
defData("DATA", data, {
    sliceHead: 5,
    sliceTail: 5,
    sliceSample: 100,
})

You can leverage the data filtering functionality using parsers.tidyData as well.

Diff Definition (defDiff)

It is very common to compare two piece of data and ask the LLM to analyze the differences. Using diffs is a great way to naturally compress the information since we only reason about 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.

// diff files
defDiff("DIFF", env.files[0], env.files[1])


// diff strings
defDiff("DIFF", "cat", "dog")


// diff objects
defDiff("DIFF", { name: "cat" }, { name: "dog" })

You can leverage the diff functionality using parsers.diff.