This is the full developer documentation for GenAIScript
=|=|=|=|=|=
# Generative AI Scripting
> GenAIScript, scripting for Generative AI.
## Prompting is Coding
[Section titled “Prompting is Coding”](#prompting-is-coding)
Programmatically assemble prompts for LLMs using JavaScript. Orchestrate LLMs, tools, and data in a single script.
* JavaScript toolbox to work with prompts
* Abstraction to make it easy and productive
* Seamless Visual Studio Code integration or flexible command line
* Built-in support for GitHub Copilot and GitHub Models, OpenAI, Azure OpenAI, Anthropic, and more
## Hello world
[Section titled “Hello world”](#hello-world)
Say to you want to create an LLM script that generates a ‘hello world’ poem. You can write the following script:
```js
$`Write a 'hello world' poem.`
```
The `$` function is a template tag that creates a prompt. The prompt is then sent to the LLM (you configured), which generates the poem.
Let’s make it more interesting by adding files, data, and structured output. Say you want to include a file in the prompt, and then save the output in a file. You can write the following script:
```js
// read files
const file = await workspace.readText("data.txt")
// include the file content in the prompt in a context-friendly way
def("DATA", file)
// the task
$`Analyze DATA and extract data in JSON in data.json.`
```
The `def` function includes the content of the file, and optimizes it if necessary for the target LLM. GenAIScript script also parses the LLM output and will extract the `data.json` file automatically.
[Play](https://youtube.com/watch?v=ajEbAm6kjI4)
## Next steps
[Section titled “Next steps”](#next-steps)
Install the extension or cli
Install the [Visual Studio Code Extension or the CLI](/genaiscript/getting-started/installation/) to get started.
Configure your LLMs
Configure the [secrets](/genaiscript/getting-started/configuration) to access your LLMs.
Write your first script
Follow [Getting Started](/genaiscript/getting-started/your-first-genai-script/) to write your first script.
Read the docs
Learn more about GenAIScript in the [Scripting Reference](/genaiscript/reference/).
[Play](https://youtube.com/watch?v=ENunZe--7j0)
## Latest news
[Section titled “Latest news”](#latest-news)
[More posts... ](/genaiscript/blog)Open the blog page to see more posts
## Features
[Section titled “Features”](#features)
GenAIScript brings essential LLM prompt tooling into a cohesive scripting environment.
Stylized JavaScript
Minimal syntax to build prompts using [JavaScript](/genaiscript/reference/scripts/) or [TypeScript](/genaiscript/reference/scripts/typescript).
```js
$`Summarize ${env.files}. Today is ${new Date()}.`
```
Fast Development Loop
Edit, [Debug](/genaiscript/getting-started/debugging-scripts/), [Run](/genaiscript/getting-started/running-scripts/), [Test](/genaiscript/getting-started/testing-scripts/) your scripts in [Visual Studio Code](/genaiscript/getting-started/installation) or with a [command line](/genaiscript/getting-started/installation).
LLM Tools
Register JavaScript functions as [LLM tools](/genaiscript/reference/scripts/tools/) (with fallback for models that don’t support tools).
```js
defTool("weather", "live weather",
{ city: "Paris" }, // schema
async ({ city }) => // callback
{ ... "sunny" }
)
```
MCP Client
Use [tools](https://modelcontextprotocol.io/docs/concepts/tools) exposed in [Model Context Provider Servers](/genaiscript/reference/scripts/mcp-tools)
```js
defTool({
memory: {
command: "npx",
args: ["-y", "@modelcontextprotocol/server-memory"],
},
})
```
MCP Server
Every script is a [Model Context Provider Tool](/genaiscript/reference/scripts/mcp-server).
```js
script({
parameters: {
question: "What is the weather in Paris?",
},
})
$`Answer the question ${env.parameters.question}.`
```
LLM Agents
Combine [tools](/genaiscript/reference/scripts/tools) and [inline prompts](/genaiscript/reference/scripts/inline-prompts/) into an [agent](/genaiscript/reference/scripts/agents).
```js
defAgent(
"git",
"Agent that answer git questions for the current repo",
"You are a helpful expert in using git.",
{ tools: ["git"] }
)
```
```js
script({ tools: "agent" })
$`Do a statistical analysis of the last commits`
```
Reuse and Share Scripts
Scripts are [files](/genaiscript/reference/scripts/)! They can be versioned, shared, forked, …
* genaisrc
* my-script.genai.mjs
* another-great-script.genai.mjs
Data Schemas
Define, validate, repair data using [schemas](/genaiscript/reference/scripts/schemas).
```js
const data = defSchema("MY_DATA",
{ type: "array", items: { ... }, })
$`Extract data from files using ${data} schema.`
```
Ingest text from PDFs, DOCX, ...
Manipulate [PDFs](/genaiscript/reference/scripts/pdf), [DOCX](/genaiscript/reference/scripts/docx), …
```js
// automatically convert to text
def("PDF", env.files, { endsWith: ".pdf" })
// or parse and process
const { pages } = await parsers.PDF(env.files[0])
```
Ingest tables from CSV, XLSX, ..
Manipulate tabular data from [CSV](/genaiscript/reference/scripts/csv), [XLSX](/genaiscript/reference/scripts/xlsx), …
```js
// automatically convert to text
def("DATA", env.files, {
endsWith: ".csv",
// take top 100 rows
sliceHead: 100,
})
// or parse to JavaScript object array
const rows = await parsers.CSV(env.files[0])
// render as markdown table
defData("ROWS", rows, { sliceHead: 100 })
```
Speech To Text
Automatically transcribe audio or videos using [OpenAI](/genaiscript/getting-started/configuration#openai) or [others](/genaiscript/getting-started/configuration#whisperasr).
```js
const transcript = await transcript("path/to/audio.mp3")
const { srt, vtt, segments } = transcript
```
Images
Include images in prompts, we’ll crop/resize/resize then for you.
```js
defImages(images, { autoCrop: true, details: "low" })
```
[Play](https://youtube.com/watch?v=XbWgDn7NdTg)
Videos
Extract frames from videos using timestamps or even transcripts.
```js
const frames = await ffmpeg.extractFrames("...", { count: 10 })
defImages(frames, { details: "low" })
```
Generate Files
Extract files and diff from the LLM output. Preview changes in Refactoring UI.
```js
$`Save the result in poem.txt.`
```
````txt
FILE ./poem.txt
```txt
The quick brown fox jumps over the lazy dog.
```
````
* poem.txt extracted by genaiscript
File search
Grep or fuzz search [files](/genaiscript/reference/scripts/files)
```js
const { files } = await workspace.grep(/[a-z][a-z0-9]+/, { globs: "*.md" })
```
Web search
[Web search](/genaiscript/reference/scripts/web-search) using Bing or Tavily.
```js
const pages = await retrieval.webSearch("what are the latest news about AI?")
```
Browser automation
Browse and scrape the web with [Playwright](/genaiscript/reference/scripts/browser).
```js
const page = await host.browse("https://...")
const table = await page.locator("table[...]").innerHTML()
def("TABLE", await HTML.convertToMarkdown(table))
```
RAG built-in
[Vector search](/genaiscript/reference/scripts/vector-search/) using a local database or [Azure AI Search](https://learn.microsoft.com/en-us/azure/search/search-what-is-azure-search).
```js
const index = await retrieval.index("animals", { type: "azure_ai_search" })
await index.insertOrUpdate(env.files)
const docs = await index.search("cat dog")
```
Safety First!
GenAIScript provides built-in Responsible AI system prompts and Azure Content Safety supports to validate [content safety](/genaiscript/reference/scripts/content-safety).
```js
script({ ...,
systemSafety: "default",
contentSafety: "azure" // use azure content safety
})
const safety = await host.contentSafety()
const res = await safety.detectPromptInjection(env.vars.input)
```
GitHub Models and GitHub Copilot
Run models through GitHub using [GitHub Models](/genaiscript/getting-started/configuration#github) or [GitHub Copilot](/genaiscript/getting-started/configuration/#github_copilot_chat).
```js
script({ ..., model: "github:gpt-4o" })
```
[Play](https://youtube.com/watch?v=Wya3MQRIbmE)
Azure AI Foundry, Google, Anthropic, Amazon, Alibaba, ...
Run models from [Azure AI Foundry](https://ai.azure.com/), [Google](https://aistudio.google.com/), [Anthropic](https://www.anthropic.com/), [Alibaba](https://www.alibaba.com/), and more. See [Configuration](/genaiscript/getting-started/configuration/).
```js
script({ ..., model: "azure_ai_inference:o3-mini"})
```
Local Models
Run your scripts with [Open Source models](/genaiscript/getting-started/configuration/), like [Phi-3](https://azure.microsoft.com/en-us/blog/introducing-phi-3-redefining-whats-possible-with-slms/), using [Ollama](https://ollama.com/), [LocalAI](https://localai.io/)…
```js
script({ ..., model: "ollama:phi3" })
```
Code Interpreter
Let the LLM run code in a sandboxed execution environment.
```js
script({ tools: ["python_code_interpreter"] })
```
Containers
Run code in Docker [containers](/genaiscript/reference/scripts/container).
```js
const c = await host.container({
image: "python:alpine",
})
const res = await c.exec("python --version")
```
LLM Composition
[Run LLMs](/genaiscript/reference/scripts/inline-prompts/) to build your LLM prompts.
```js
// summarize each files individually
for (const file of env.files) {
const { text } = await runPrompt((_) => {
_.def("FILE", file)
_.$`Summarize the FILE.`
})
// use result in main prompt
def("SUMMARY", text)
}
// use summary
$`Summarize all the summaries.`
```
Generate Images
[Generate images](/genaiscript/reference/scripts/image-generation) using OpenAI DALL-E or others.
```js
const { image, revisedPrompt } = await generateImage(
`a cute cat. only one. photographic, high details. 4k resolution.`
)
```
Classify
Classify text, images or a mix of all.
```js
const joke = await classify(
"Why did the chicken cross the roard? To fry in the sun.",
{
yes: "funny",
no: "not funny",
}
)
```
Prompty
Run or convert [Prompty](https://prompty.ai/) files using GenAIScript.
poem.prompty
```markdown
---
name: poem
---
system:
Write a short poem about
user:
{{something}}.
```
```js
importTemplate("poem.prompty", { something: "code " })
```
Pluggable Secret Scanning
Scan your chats for secrets using [secret scanning](/genaiscript/reference/scripts/secret-scanning).
genaiscript.config.json
```json
{
"secretPatterns": {
...,
"OpenAI API Key": "sk-[A-Za-z0-9]{32,48}"
}
}
```
Automate with CLI
Automate using the [CLI](/genaiscript/reference/cli), integrate reports in your CI/CD pipeline.
```bash
npx genaiscript run tlaplus-linter "*.tla"
```
Pull Request Reviews
Integrate into your [Pull Requests checks](/genaiscript/reference/cli/run/#pull-requests) through comments, reviews or description updates. Supports GitHub Actions and Azure DevOps pipelines.
```bash
npx genaiscript ... --pull-request-reviews
```
Tests and Evals
Build reliable prompts using [tests and evals](/genaiscript/reference/scripts/tests) powered by [promptfoo](https://promptfoo.dev/).
```js
script({ ..., tests: {
files: "penguins.csv",
rubric: "is a data analysis report",
facts: "The data refers about penguin population in Antartica.",
}})
```
## Case Studies
[Section titled “Case Studies”](#case-studies)
Tales from the real world using GenAIScript.
[Bicep Best Practices ](/genaiscript/case-studies/bicep-best-practices)Learn how to apply best practices to Azure Bicep files for more efficient and maintainable infrastructure as code.
[SEO Front Matter ](/genaiscript/case-studies/seo-frontmatter)Learn how to automate the creation of SEO-optimized front matter for your markdown documents with GenAIScript.
[Documentation Translations ](/genaiscript/case-studies/documentation-translations)Explore the challenges and solutions for localizing MakeCode documentation with custom macros while maintaining rich rendering in multiple languages.
[Blocks Localization ](/genaiscript/case-studies/blocks-localization)Learn how to localize MakeCode programming blocks while preserving block properties and variable names for international audiences.
[Release Notes ](/genaiscript/case-studies/release-notes)Generate comprehensive release notes combining commit history and code diffs
[TLA+ AI Linter ](/genaiscript/case-studies/tla-ai-linter)Explore how the TLA+ AI Linter leverages GenAI scripts and LLMs to enhance TLA+ specifications with automated linting and consistent comment verification.
[Image Alt Text ](/genaiscript/case-studies/image-alt-text)Learn how to automatically generate descriptive alt text for images using OpenAI Vision model to enhance accessibility and SEO.
## Samples
[Section titled “Samples”](#samples)
Fully fledged scripts ready to use.
[Awesome Scripts ](/genaiscript/samples/awesome)A curated list of awesome scripts
[Diagram ](/genaiscript/samples/diagram)Class diagram generator
[Lint ](/genaiscript/samples/lint)An Easy Universal Linter
[Pull Request Descriptor ](/genaiscript/samples/prd)Generate a pull request description from the git diff
[Image Alt Textify ](/genaiscript/samples/iat)Generate alt text for images in markdown files
[Pull Request Reviewer ](/genaiscript/samples/prr)Review the current files or changes
[Git Commit Message ](/genaiscript/samples/gcm)Generate a commit message for all staged changes
[Search and transform ](/genaiscript/samples/st)Search for a pattern in files and apply an LLM transformation to the match
[Commenter ](/genaiscript/samples/cmt)Adds comments to your code
[GitHub Action Investigator ](/genaiscript/samples/gai)Investigate GitHub Actions failures
[Spell Checker ](/genaiscript/samples/sc)Spell check a document
## Guides
[Section titled “Guides”](#guides)
A cookbook full of recipes to make you a genius scripter.
[Sharing scripts ](/genaiscript/guides/sharing-scripts)Learn how to share GenAIScript scripts across projects using Git repositories, submodules, and GitHub Gists.
[Prompt As Code ](/genaiscript/guides/prompt-as-code)Tutorial on using GenAIScript runtime and syntax to assemble prompts
[Ask My PDF ](/genaiscript/guides/ask-my-pdf)Quick-start guide to using GenAIScript for summarizing and critiquing PDF documents with AI assistance.
[Agentic tools ](/genaiscript/guides/agentic-tools)Using agentic tools in your script
[Ask My Image ](/genaiscript/guides/ask-my-image)Learn how to apply GenAIScript to images for data extraction and analysis using AI models.
[Present My Code ](/genaiscript/guides/present-my-code)Step-by-step instructions on presenting code effectively using GenAIScript and creating engaging slides.
[Search and Fetch ](/genaiscript/guides/search-and-fetch)Learn how to leverage web search and fetching pages in GenAIScript
[Tool Agent ](/genaiscript/guides/tool-agent)Learn how to define a built-in agent using functions for decision-making and reasoning in arithmetic operations.
[Detection of Outdated Descriptions ](/genaiscript/guides/detection-outdated-descriptions)Automate the detection of outdated descriptions in markdown documentation to maintain accuracy and consistency.
[Summarize Many Documents ](/genaiscript/guides/summarize-many-documents)Learn how to run a GenAIScript over many documents
[DeepSeek R1 and V3 ](/genaiscript/guides/deepseek)DeepSeek is a powerful tool for searching and filtering data in a deep structure. There are multiple LLM providers that can run DeepSeek.
[Generated Knowledge ](/genaiscript/guides/generated-knowledge)Explore the technique of generated knowledge in AI prompting to enhance accuracy in answering questions.
[Phi-3 Mini with Ollama ](/genaiscript/guides/phi3-with-ollama)Learn how to integrate Phi-3 Mini, a powerful 3.8B parameter model by Microsoft, with Ollama for local execution of state-of-the-art AI models.
[Containerized Tools ](/genaiscript/guides/containerized-tools)Learn how to create and use containerized tools with executable dependencies in a secure environment using GCC as an example.
[Business card scanner ](/genaiscript/guides/business-card-scanner)Using OpenAI Vision to scan business cards.
[Evals with multiple Models ](/genaiscript/guides/eval-models)Evaluating multiple models in a single script
[Automated Git Commit Messages ](/genaiscript/guides/auto-git-commit-message)Streamline your Git workflow with an automation script for generating commit messages
[Issue Reviewer ](/genaiscript/guides/issue-reviewer)Learn how to automate reviewing issues with a script.
[Llama Guard your files ](/genaiscript/guides/llama-guard-your-files)Automate the process of checking your files for harmful content using Llama-guard3.
[LLM Agents ](/genaiscript/guides/llm-agents)Learn how to use the inline prompts to create a LLM agent.
[Pull Request Reviewer ](/genaiscript/guides/pull-request-reviewer)Learn how to automate pull request reviews with a GenAIScript that provides feedback and code analysis in GitHub Actions.
[Search And Transform ](/genaiscript/guides/search-and-transform)Learn how to search and transform data in your data sources.
[Transformer.js ](/genaiscript/guides/transformers-js)Implement summarization with Transformers.js and leverage local hardware acceleration
[Using Secrets ](/genaiscript/guides/using-secrets)Utilize secrets to augment documents with TypeScript and REST APIs
[Video Alt Text ](/genaiscript/guides/video-alt-textgenai)Learn how to generate alt text for videos
[Images in Azure Blob Storage ](/genaiscript/guides/images-in-azure-blob-storage)Leverage Azure SDK to handle image files in Blob Storage within prompts
[LLM as a tool ](/genaiscript/guides/llm-as-tool)Create tools and inline prompts using LLM models for executing various tasks
[PDF Vision ](/genaiscript/guides/pdf-vision)
[Zod Schema ](/genaiscript/guides/zod-schema)Learn how to define and convert TypeScript-first Zod schemas to JSON schema
[Make It Better ](/genaiscript/guides/make-it-better)Ask the LLM to make your code better!
## Agents
[Section titled “Agents”](#agents)
### Builtin Agents
[Section titled “Builtin Agents”](#builtin-agents)
[agent data ](/genaiscript/reference/scripts/system#systemagent_data)query data from files
[agent docs ](/genaiscript/reference/scripts/system#systemagent_docs)query the documentation
[agent fs ](/genaiscript/reference/scripts/system#systemagent_fs)query files to accomplish tasks
[agent git ](/genaiscript/reference/scripts/system#systemagent_git)query the current repository using Git to accomplish tasks. Provide all the context information available to execute git queries.
[agent github ](/genaiscript/reference/scripts/system#systemagent_github)query GitHub to accomplish tasks
[agent interpreter ](/genaiscript/reference/scripts/system#systemagent_interpreter)run code interpreters for Python, Math. Use this agent to ground computation questions.
[agent planner ](/genaiscript/reference/scripts/system#systemagent_planner)generates a plan to solve a task
[agent user\_input ](/genaiscript/reference/scripts/system#systemagent_user_input)ask user for input to confirm, select or answer the question in the query. The message should be very clear and provide all the context.
[agent video ](/genaiscript/reference/scripts/system#systemagent_video)Analyze and process video files or urls.
[agent web ](/genaiscript/reference/scripts/system#systemagent_web)search the web to accomplish tasks.
[agent z3 ](/genaiscript/reference/scripts/system#systemagent_z3)can formalize and solve problems using the Z3 constraint solver. If you need to run Z3 or solve constraint systems, use this tool.
## LLM friendly docs
[Section titled “LLM friendly docs”](#llm-friendly-docs)
If you are an LLM crawler, fetch for a documentation map or add the `.md` suffix to any documentation URLs to get a raw markdown content.
For example, (note the .md extension)
=|=|=|=|=|=
# Getting Started
> Start developing with the GenAIScript VS Code Extension to create AI scripts efficiently.
GenAIScript is a scripting language that integrates LLMs into the scripting process using a simplified JavaScript syntax. Supported by our VS Code GenAIScript extension, it allows users to create, debug, and automate LLM-based scripts.
[Play](https://youtube.com/watch?v=ENunZe--7j0)
## Preamble
[Section titled “Preamble”](#preamble)
Before you start writing GenAIScripts, you will need to configure your environment to have access to a LLM. The [configuration](/genaiscript/getting-started/configuration) covers this topic in details as they are a lot of options to consider.
Tip
If you are running GenAIScript from a [GitHub CodeSpaces](https://github.com/features/codespaces), you can skip the configuration step as the extension will automatically use [GitHub Models](/genaiscript/getting-started/configuration#github).
## Hello World
[Section titled “Hello World”](#hello-world)
A GenAIScript is a JavaScript program that builds an LLM which is then executed by the GenAIScript runtime. Let’s start with a simple script that tells the LLM to generate a poem. In typical use, GenAIScript files have the naming convention `.genai.mjs` and are stored in the `genaisrc` directory in a repository. Let’s call this script `poem.genai.mjs`.
poem.genai.mjs
```js
$`Write a poem in code.`
```
The `$...` syntax is [template literal](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals) that renders to a user message to the LLM prompt. In this example, it would be:
```txt
Write a poem in code.
```
In practice, your script may also import [system scripts](/genaiscript/reference/scripts/system) (automatically or manually specified) that add more messages to the requests. So the final JSON payload sent to the LLM server might look more like this:
```js
{ ...
messages: [
{ role: "system", content: "You are helpful. ..." },
{ role: "user", content: "Write a poem in code." }
]
}
```
GenAIScripts can be executed from the [command line](/genaiscript/reference/cli) or run with a right-click context menu selection inside Visual Studio Code. Because a GenAIScript is just JavaScript, the execution of a script follows the normal JavaScript evaluation rules. Once the script is executed, the generated messages are sent to the LLM server, and the response is processed by the GenAIScript runtime.
* npm
```sh
npx genaiscript run poem
```
* pnpm
```sh
pnpx genaiscript run poem
```
* yarn
```sh
yarn dlx genaiscript run poem
```
Here is an example output for this prompt (shortened) that got returned by OpenAI gpt-4o.
````markdown
```python
def poem():
# In the silence of code,
...
# And thus, in syntax sublime,
# We find the art of the rhyme.
```
````
GenAIScript supports extracting structured data and files from the LLM output as we will see later.
Note
The CLI will scan you project for `*.genai.mjs/mts` files and you can use the filename without the extension to refer to them.
## Variables
[Section titled “Variables”](#variables)
GenAIScripts support a way to declare [prompt variables](/genaiscript/reference/scripts/context), which allow to include content into the prompt and to refer to it later in the script.
Let’s take a look at a `summarize` script that includes the content of a file and asks the LLM to summarize it.
summarize.genai.mjs
```js
def("FILE", workspace.readText("some/relative/markdown.txt"))
$`Summarize FILE in one sentence.`
```
In this snippet, we use `workspace.readText` to read the content of a file (path relatie to workspace root) and we use `def` to include it in the prompt as a `prompt variable`. We then “referenced” this variable in the prompt.
prompt
````markdown
FILE:
```text file="some/relative/markdown.txt"
What is Markdown?
Markdown is a lightweight markup language that you can use to add formatting elements to plaintext text documents. Created by John Gruber in 2004, Markdown is now one of the world’s most popular markup languages.
```
Summarize FILE in one sentence.
````
The `def` function supports many configuration flags to control how the content is included in the prompt. For example, you can insert line numbers or limit the number of tokens.
```js
def("FILE", ..., { lineNumbers: true, maxTokens: 100 })
```
Note
The variable name (FILE) matters! Make sure it represents the content of the variable or it might confuse the LLM.
## Files parameters
[Section titled “Files parameters”](#files-parameters)
GenAIScript are meant to work on a file or set of files. When you run a script in Visual Studio Code on a file or a folder, those files are passed to the script using the `env.files` variable. You can use this `env.files` to replace hard-coded paths and make your scripts more resuable.
summarize.genai.mjs
```js
// summarize all files in the env.files array
def("FILE", env.files)
$`Summarize FILE in one sentence.`
```
And now apply it to a bunch of files
* npm
```sh
npx genaiscript run summarize "**/*.md"
```
* pnpm
```sh
pnpx genaiscript run summarize "**/*.md"
```
* yarn
```sh
yarn dlx genaiscript run summarize "**/*.md"
```
## Processing outputs
[Section titled “Processing outputs”](#processing-outputs)
GenAIScript processes the outputs of the LLM and extracts files, diagnostics and code sections when possible.
Let’s update the summarizer script to specify an output file pattern.
summarize.genai.mjs
```js
// summarize all files in the env.files array
def("FILE", env.files)
$`Summarize each FILE in one sentence.
Save each generated summary to ".summary"`
```
Given this input, the model returns a string, which the GenAIScript runtime interprets based on what the prompt requested from the model:
````markdown
File src/samples/markdown-small.txt.summary:
```text
Markdown is a lightweight markup language created by John Gruber in 2004, known for adding formatting elements to plaintext text documents.
```
````
Because the prompt requested that a file be written, the model has responded with content describing the contents of the file that should be created. In this case, the model has chosen to call that file `markdown-small.txt.summary`.
Our GenAIScript library parses the LLM output, interprets it, and in this case will create the file. If the script is invoked in VS Code, the file creation is exposed to the user via a [Refactoring Preview](https://code.visualstudio.com/docs/editor/refactoring#_refactor-preview) or directly saved to the file system.
Of course, things can get more complex - with functions, schemas, … -, but this is the basic flow of a GenAIScript script. If you’re looking for an exhaustive list of prompting techniques, checkout [the prompt report](https://learnprompting.org/).
## Using tools
[Section titled “Using tools”](#using-tools)
[Tools](/genaiscript/reference/scripts/tools) are a way to register JavaScript callbacks with the LLM, they can be used execute code, search the web, … or read files! Here is an example of a script that uses the [`fs_read_file`](/genaiscript/reference/scripts/system#systemfs_read_file) tool to read a file and summarize it:
summarize.genai.mjs
```js
script({ tools: "fs_read_file" })
$`
- read the file markdown.md
- summarize it in one sentence.
- save output to markdown.md.txt
`
```
A possible trace looks like as follows.
Trace
````markdown
- prompting github:gpt-4o
- cat src/rag/markdown.md
- prompting github:gpt-4o
FILE ./markdown.md.txt:
```text
Markdown is a lightweight ...
```
````
As you can see we are not using the `def` function anymore, we expect the LLM to issue a call to the `fs_read_file` tool to read the file `markdown.md` so that it receives the content of that file.
Note that this approach is less deterministic than using `def` as the LLM might not call the tool. Moreover it uses more tokens as the LLM has to generate the code to call the tool. Nonetheless, it is a powerful way to interact with the LLM.
## Using agents
[Section titled “Using agents”](#using-agents)
You can add one more layer of indirection and use [agent\_fs](/genaiscript/reference/scripts/system#systemagent_fs), a file system [agent](/genaiscript/reference/scripts/agents), to read the file. The agent combines a call to an LLM, and a set of tools related to file system queries.
summarize.genai.mjs
```js
script({ tools: "agent_fs" })
$`
- read the file src/rag/markdown.md
- summarize it in one sentence.
- save output to file markdown.md.txt (override existing)
`
```
Trace
````markdown
- prompting github:gpt-4o (~1569 tokens)
- agent fs: read and summarize file src/rag/markdown.md in one sentence
- prompt agent memory query with github:gpt-4o-mini: "NO_ANSWER"
- prompt agent fs with github:gpt-4o (~422 tokens)
- cat src/rag/markdown.md
- prompting github:gpt-4o (~635 tokens)
```md
The file "src/rag/markdown.md" explains that Markdown...
```
- prompting github:gpt-4o (~1625 tokens)
I'll save the summary to the file `markdown.md.txt`.
FILE markdown.md.txt:
```
The file "src/rag/markdown.md" explains that Markdown....
```
````
## Next steps
[Section titled “Next steps”](#next-steps)
While GenAIScripts can be written with any IDE and run from the command line, users of the [extension in Visual Studio Code](/genaiscript/getting-started/installation) greatly benefit from the additional support for writing, debugging, and executing GenAIScript provided. We strongly recommend starting by installing the extension.
=|=|=|=|=|=
# Developer guide
> Contribution guidelines for building and adding features to GenAIScript
GenAIScript welcomes contributions from the community. This document provides guidelines for setting up the development environment, building the project, and contributing to the codebase.
## Setup
[Section titled “Setup”](#setup)
You can open this repo in GitHub CodeSpace/Docker to get the build environment needed.
[](https://github.com/codespaces/new?hide_repo_select=true\&ref=main\&repo=679784368)
* Go to
* Click on **Code**
* Select Create new Codespace
* Select the **dev** branch
### Manual setup
[Section titled “Manual setup”](#manual-setup)
* Install [Node.JS LTS](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)
* Run yarn
```sh
yarn install --frozen-lockfile --prefer-offline
```
## Build
[Section titled “Build”](#build)
You can do a full compile using esbuild.
```sh
yarn compile
```
or a typecheck using `tsc`.
```sh
yarn typecheck
```
## Pull Requests
[Section titled “Pull Requests”](#pull-requests)
You must create pull requests against the `dev` branch. The `main` branch is reserved for releases. The `dev` branch is the main development branch. It is where all new features and bug fixes are merged before being released to the public.
When creating a pull request, please ensure that your code adheres to the following guidelines:
* Follow the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
* Ensure that your code is well-documented and follows the project’s coding style.
* If possible, add tests for any new features or bug fixes.
## Running local scripts
[Section titled “Running local scripts”](#running-local-scripts)
To run a script using the locally built cli,
```sh
yarn genai ...
```
To run a sample script under the `packages/sample` folder:
```sh
yarn run:script ...
```
In this case, it will use the `packages/sample/.env` file for the environment variables and workspace will be rooted at `packages/sample`.
## Debugging local scripts
[Section titled “Debugging local scripts”](#debugging-local-scripts)
Open a `JavaScript Debug Terminal` and launch the script using
```sh
yarn genai:debug ...
```
or for samples
```sh
yarn run:script:debug ...
```
## Logging
[Section titled “Logging”](#logging)
GenAIScript uses the [debug](https://www.npmjs.com/package/debug) library for logging. You can enable logging by setting the `DEBUG` environment variable to `genai:*`.
```sh
DEBUG=genaiscript:* yarn genai ...
```
## Web viewer
[Section titled “Web viewer”](#web-viewer)
The web application (React 19) is meant to run both as a Visual Studio Code panel and a standalone viewer (**playground**). For testing purposes, standalone is the easiest.
* React 19, currently very little dependeices
* react-markdown + a few plugins to run the markdown
* [vscode-elements](https://vscode-elements.github.io/) is the design system we use as it mimics the vscode look and feel.
Use the following command to start the local web server:
```sh
yarn serve
```
It will start a local server and rebuild the react client on file changes. **It will not rebuild/restart the server on changes.** There is **no** hot reload, you need to refresh the browser. If some state should be serialized, we should start adding it to the hash.
## Visual Studio Code Extension development
[Section titled “Visual Studio Code Extension development”](#visual-studio-code-extension-development)
Working on the VSCode involves launching the main project debugger, which opens a second VSCode instance with the GenAIScript extension.
You can set debug breakpoint anywhere in the GenAIScript typescript files and they will resolve.
* uninstall the official GenAIScript extension or it will clash with the locally built one
* open the `Debug` view in Vs Code
* select the **Samples** debugger configuration and click **Run**
Remember that the debugger is only attached to the extension; not the GenAIScript server.
### Caveats
[Section titled “Caveats”](#caveats)
Launching the debugger sometimes fails but still unknown reasons. To work around this, open a terminal and run `yarn compile` once. Then launch the debugger again.
## Dependencies
[Section titled “Dependencies”](#dependencies)
* run `yarn install:force` to refresh the lock file
## Docs
[Section titled “Docs”](#docs)
Run `docs` to launch the documentation site.
```sh
yarn docs
```
Run this command to catch broken links
```sh
yarn build:docs
```
## Slides
[Section titled “Slides”](#slides)
All files `slides/*slides.md` will be compiled and deployed on build.
* run `slides` to launch the slide show (add the file name or it will default to `slides.md`)
```sh
yarn slides [slides file name]
```
Learn more about Slidev on [documentations](https://sli.dev/). For diagrams, leverage [mermaid](https://sli.dev/guide/syntax#diagrams) or use draw\.io, tldraw.
## GenAIScripts
[Section titled “GenAIScripts”](#genaiscripts)
* Commit with auto-generated message
```sh
yarn gcm
```
* Add doc to new or updated apis
```sh
yarn genai:docs
```
* Generate images for blog posts
```sh
yarn genai:blog-images
```
## Packaging
[Section titled “Packaging”](#packaging)
To compile and package the Visual Studio Code extension, run the `package` script.
```sh
yarn package
```
You will find the built package files, `genaiscript.vsix`, in the `packages/vscode` folder.
## Release
[Section titled “Release”](#release)
Run the `release` script.
```sh
yarn release
```
GitHub Pages are automatically updated on new release; or through manual trigger at .
## Contributing
[Section titled “Contributing”](#contributing)
This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit .
When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.
This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact with any additional questions or comments.
=|=|=|=|=|=
# FAQ
> Find answers to common questions about AI script generation, its uses, performance, and best practices for effective application.
### Getting Started
[Section titled “Getting Started”](#getting-started)
* **What is GenAIScript and how does it work?** GenAIScript is a framework that allows users to create AI-enhanced scripts to automate tasks. It uses simple commands and integrates with AI models to execute tasks based on user-written prompts.
* **Who can use GenAIScript and do I need to be a developer?** Anyone can use GenAIScript, including non-developers. It’s designed to be user-friendly, but some basic understanding of scripting or programming can be helpful.
* **What are the prerequisites for using GenAIScript?** You’ll need to have VS Code installed to use the GenAIScript extension, and some familiarity with programming concepts is beneficial but not necessary.
* **How do I install the GenAIScript framework and its VS Code extension?** The specific installation steps are documented here: [Installation](/genaiscript/getting-started/installation)
* **Do I need to install Node.JS?** Yes. To install it, follow the [installation instructions](/genaiscript/reference/cli/).
* **Can I use GenAIScript in IDEs other than VS Code?** Currently, GenAIScript is integrated with VS Code, but it can be written in any IDE. The VS Code extension, however, provides additional support for creating and debugging scripts. Although not thoroughly tested, you can use GenAIScript in VS Code variants like Cursor.
* **What are foundation models and LLMs in the context of GenAIScript?** Foundation models and LLMs (Large Language Models) are AI models that GenAIScript can interact with to perform tasks like generating text or processing information.
* **How do I write my first GenAIScript?** Start by learning the basics of JavaScript and the GenAIScript framework, then use the VS Code extension to create a script that defines the task, calls the LLM, and processes the output. More information is available here: [Getting Started](/genaiscript/getting-started)
### Using GenAIScript
[Section titled “Using GenAIScript”](#using-genaiscript)
* **How do I debug a GenAIScript in VS Code?** Use the GenAIScript extension in VS Code, which provides tools for running, debugging, and tracing the execution of your script. Directions for debugging are here: [Debugging](/genaiscript/getting-started/debugging-scripts)
* **What are the best practices for authoring effective prompts in GenAIScript?** See [Best Practices](/genaiscript/getting-started/best-practices)
* **How can I integrate calls to multiple LLM models within a single GenAIScript?** The framework allows you to parameterize calls to different models, so you can include multiple model invocations within your script and manage them accordingly using the runPrompt function documented here: [Inline Prompts](/genaiscript/reference/scripts/inline-prompts)
* **Can GenAIScript generate outputs in formats other than JSON?** Yes, GenAIScript supports multiple output formats, including file edits, JSON, and user-defined schema. More information here: [Schemas](/genaiscript/reference/scripts/schemas)
* **How do I execute a GenAIScript from the command line?** Once you have a GenAIScript packaged, you can run it from the command line like any other script. More information here: [Command Line](/genaiscript/getting-started/automating-scripts)
* **Can GenAIScripts take input from files in multiple formats, such as .pdf or .docx?** Yes, the GenAIScript framework has built-in support for reading .pdf and .docx formats. See the documentation pages [PDF](/genaiscript/reference/scripts/pdf) and [DOCX](/genaiscript/reference/scripts/docx) for more information.
### Advanced Features
[Section titled “Advanced Features”](#advanced-features)
* **How can I use GenAIScript to automate document translation?** One of our case studies illustrates the use of GenAIScript for translating document fragments between languages: [Translation Case Study](/genaiscript/case-studies/documentation-translations)
* **Can I use GenAIScript to summarize documents or create dialogues from monologues?** Yes, LLMs are good at summarizing and can be used within GenAIScript to summarize documents or convert monologues into dialogues.
### Troubleshooting
[Section titled “Troubleshooting”](#troubleshooting)
* **What should I do if I encounter errors while running a GenAIScript?** Check the error messages, consult the documentation, and use the debugging tools in the VS Code extension to identify and resolve issues.
* **How can I troubleshoot issues with the LLM output parsing in GenAIScript?** Review the prompt and output, ensure your script correctly handles the LLM’s response, and adjust your parsing logic as needed.
* **Where can I find examples of GenAIScript to understand its capabilities better?** Visit the GenAIScript GitHub repository for examples and documentation. [GenAIScript Documentation](/genaiscript/)
### Security and Responsible AI
[Section titled “Security and Responsible AI”](#security-and-responsible-ai)
* **What are the unintended uses of GenAIScript and how can I avoid them?** Unintended uses include any malicious applications. To avoid them, follow Responsible AI practices and use recommended models with safety features.
* **How does GenAIScript align with Responsible AI practices?** GenAIScript encourages the use of models with robust Responsible AI mitigations and provides guidance on secure and ethical usage. For more information, see the [Transparency Note](/genaiscript/reference/transparency-note)
* **What foundation models and LLMs are recommended for use with GenAIScript?** Services like Azure Open AI with updated safety and Responsible AI features are recommended. GenAIScript can also be used with existing open-source LLMs.
* **Do you provide system prompts to guard against common problems like harmful content or jailbreaking?** Yes, GenAIScript includes system prompts to guard against harmful content and jailbreaking. For more information, see the [Content Safety](/genaiscript/reference/scripts/content-safety) documentation.
* **Do you support Azure Content Services?** Yes, GenAIScript provides APIs to interact with Azure Content Safety services. For more information, see the [Content Safety](/genaiscript/reference/scripts/content-safety) documentation.
### Community and Support
[Section titled “Community and Support”](#community-and-support)
* **Where can I find the GenAIScript community for discussions and support?** The GenAIScript GitHub repository is a good place to start for community discussions and support. [GenAIScript GitHub](https://github.com/microsoft/genaiscript/)
* **How can I contribute to the GenAIScript project?** Check the repository for contribution guidelines and consider providing feedback, submitting issues, or contributing code. Visit the [Contributing](https://github.com/microsoft/genaiscript/blob/main/CONTRIBUTING.md) page for more information.
* **Who can I contact for feedback or questions about GenAIScript?** You can email the provided contacts in the [Transparency Note](/genaiscript/reference/transparency-note/) document for feedback or questions.
### Updates and Roadmap
[Section titled “Updates and Roadmap”](#updates-and-roadmap)
* **How often is GenAIScript updated and how can I stay informed about new features?** You can follow the GitHub repository for updates and announcements.
* **Is there a roadmap available for GenAIScript’s development?** The GitHub repository will provide information on future development plans.
=|=|=|=|=|=
# Overview
> Comprehensive documentation for scripting automation, LLM configurations, and developer tools including a VSCode extension and CLI for codebase AI transformations.
GenAIScript is a scripting language that makes LLMs a first-class part of the scripting process, easily allowing users to author, debug, and deploy LLM-based scripts that can perform tasks beyond the reach of conventional code. This reference guide provides comprehensive documentation for GenAIScripts, including script syntax, LLM configurations, the VSCode extension, and the CLI.
* [Scripts](/genaiscript/reference/scripts) provide a domain-specific JavaScript framework to build LLM requests.
* [CLI](/genaiscript/reference/cli) documents the command-line interface to automate GenAIScripts executions.
* [Visual Studio Code Extension](/genaiscript/reference/vscode) provides a rich set of features to author, debug, and deploy GenAIScripts.
=|=|=|=|=|=
# Commands
> List of all CLI commands
A full list of the CLI command and its respective help text.
## `configure`
[Section titled “configure”](#configure)
```plaintext
Usage: genaiscript configure [options]
Interactive help to configure providers
Options:
-p, --provider Preferred LLM provider aliases (choices: "openai",
"azure", "azure_ai_inference", "azure_serverless",
"azure_serverless_models", "github", "ollama",
"windows_ai", "anthropic", "anthropic_bedrock",
"google", "huggingface", "mistral", "alibaba",
"deepseek", "transformers", "lmstudio", "jan",
"llamafile", "sglang", "vllm", "litellm",
"whisperasr", "echo")
-h, --help display help for command
```
## `run`
[Section titled “run”](#run)
```plaintext
Usage: genaiscript run [options]