diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs
index a09f5d0edd..aefa0a8927 100644
--- a/docs/astro.config.mjs
+++ b/docs/astro.config.mjs
@@ -2,6 +2,7 @@ import { defineConfig, passthroughImageService } from "astro/config"
import starlight from "@astrojs/starlight"
import starlightBlog from "starlight-blog"
import rehypeMermaid from "rehype-mermaid"
+import starlightLinksValidator from "starlight-links-validator"
// https://astro.build/config
export default defineConfig({
@@ -39,6 +40,7 @@ export default defineConfig({
},
},
}),
+ //starlightLinksValidator(),
],
components: {
Head: "./src/components/Head.astro",
diff --git a/docs/package.json b/docs/package.json
index cd58322844..1818199353 100644
--- a/docs/package.json
+++ b/docs/package.json
@@ -21,10 +21,12 @@
"dependencies": {},
"devDependencies": {
"@astrojs/check": "^0.9.4",
- "@astrojs/starlight": "^0.29.2",
- "astro": "^4.16.16",
+ "@astrojs/starlight": "^0.30.1",
+ "astro": "^5.0.5",
"rehype-mermaid": "^3.0.0",
- "starlight-blog": "^0.15.0",
+ "starlight-blog": "^0.16.0",
+ "starlight-links-validator": "^0.13.4",
+ "starlight-package-managers": "^0.8.1",
"typescript": "5.7.2",
"zx": "^8.2.4"
}
diff --git a/docs/src/components/GenAIScriptCli.astro b/docs/src/components/GenAIScriptCli.astro
new file mode 100644
index 0000000000..46e6fb6da6
--- /dev/null
+++ b/docs/src/components/GenAIScriptCli.astro
@@ -0,0 +1,15 @@
+---
+import { PackageManagers } from "starlight-package-managers"
+interface Props {
+ args: string
+ comment: string
+}
+const { args, comment } = Astro.props
+---
+
diff --git a/docs/src/content/config.ts b/docs/src/content.config.ts
similarity index 81%
rename from docs/src/content/config.ts
rename to docs/src/content.config.ts
index 8ed1e371a7..18846d55c7 100644
--- a/docs/src/content/config.ts
+++ b/docs/src/content.config.ts
@@ -1,9 +1,11 @@
import { defineCollection } from "astro:content"
+import { docsLoader } from "@astrojs/starlight/loaders"
import { docsSchema } from "@astrojs/starlight/schema"
import { blogSchema } from "starlight-blog/schema"
export const collections = {
docs: defineCollection({
+ loader: docsLoader(),
schema: docsSchema({
extend: (context) => blogSchema(context),
}),
diff --git a/docs/src/content/docs/blog/node-api.md b/docs/src/content/docs/blog/node-api.mdx
similarity index 93%
rename from docs/src/content/docs/blog/node-api.md
rename to docs/src/content/docs/blog/node-api.mdx
index 91560b403e..3d16df54f6 100644
--- a/docs/src/content/docs/blog/node-api.md
+++ b/docs/src/content/docs/blog/node-api.mdx
@@ -6,6 +6,7 @@ authors:
tags: ["sdk", "automation", "dev", "api"]
description: Learn about the new API to call genaiscript for other typescript scripts.
---
+import { PackageManagers } from 'starlight-package-managers'
A long standing feature request has been to run GenAIScript programmatically from other scripts. We are happy to announce that we have released a Node.JS API for GenAIScript. This API allows you to call GenAIScript from other TypeScript scripts (v1.83+).
@@ -15,9 +16,7 @@ A long standing feature request has been to run GenAIScript programmatically fro
You'll want to add [genaiscript](https://www.npmjs.com/package/genaiscript) as a (dev) dependency to your project.
-```sh
-npm install -D genaiscript
-```
+
## The `run` API
diff --git a/docs/src/content/docs/case-studies/blocks-localization.mdx b/docs/src/content/docs/case-studies/blocks-localization.mdx
index 05c1dd9ed3..b1bcc8987e 100644
--- a/docs/src/content/docs/case-studies/blocks-localization.mdx
+++ b/docs/src/content/docs/case-studies/blocks-localization.mdx
@@ -10,7 +10,7 @@ import { Code } from "@astrojs/starlight/components"
import stringsJson from "../../../../../packages/sample/src/makecode/jacdac-buzzer-strings.json?raw"
import scriptSource from "../../../../../packages/sample/src/makecode/makecode-loc.genai.js?raw"
-This is another instance of using the LLM to produce translation of natural strings with an embedded DSL, similarly to the [Documentation Translation](./documentation-translations.mdx) guide.
+This is another instance of using the LLM to produce translation of natural strings with an embedded DSL, similarly to the [Documentation Translation](/genaiscript/case-studies/documentation-translations.mdx) guide.
[MakeCode](https://makecode.com) uses a [microformat](https://makecode.com/defining-blocks) to define the shape of coding blocks.
When translating the format strings, it is critical to converse the properties of the blocks, such as the number of arguments,
diff --git a/docs/src/content/docs/getting-started/index.md b/docs/src/content/docs/getting-started/index.mdx
similarity index 94%
rename from docs/src/content/docs/getting-started/index.md
rename to docs/src/content/docs/getting-started/index.mdx
index a4b89c07e3..7fcdb3e390 100644
--- a/docs/src/content/docs/getting-started/index.md
+++ b/docs/src/content/docs/getting-started/index.mdx
@@ -15,6 +15,8 @@ genaiscript:
files: src/samples/markdown-small.txt
---
+import GenAIScriptCli from "../../../components/GenAIScriptCli.astro"
+
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.
@@ -49,13 +51,11 @@ So the final JSON payload sent to the LLM server might look more like this:
```
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.
+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.
-```sh wrap
-npx --yes genaiscript run poem
-```
+
Here is an example output for this prompt (shortened) that got returned by OpenAI gpt-4o.
@@ -93,11 +93,13 @@ and we use `def` to include it in the prompt as a `prompt variable`. We then "re
````markdown wrap title="prompt"
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.
````
@@ -126,9 +128,7 @@ $`Summarize FILE in one sentence.`
And now apply it to a bunch of files
-```sh
-npx --yes genaiscript run summarize **/*.md
-```
+
## Processing outputs
@@ -148,6 +148,7 @@ the GenAIScript runtime interprets based on what the prompt requested from the m
````markdown wrap
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.
```
@@ -180,21 +181,22 @@ $`
`
```
-A possible trace looks like as follows.
+A possible trace looks like as follows.
Trace
-`````markdown
+````markdown
- prompting github:gpt-4o
- cat src/rag/markdown.md
- prompting github:gpt-4o
FILE ./markdown.md.txt:
+
```text
Markdown is a lightweight ...
```
-`````
+````
@@ -219,13 +221,13 @@ $`
Trace
-`````markdown
+````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)
+- 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...
@@ -236,10 +238,12 @@ The file "src/rag/markdown.md" explains that Markdown...
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
diff --git a/docs/src/content/docs/guides/issue-reviewer.mdx b/docs/src/content/docs/guides/issue-reviewer.mdx
index 60132a80ea..b14eb5f185 100644
--- a/docs/src/content/docs/guides/issue-reviewer.mdx
+++ b/docs/src/content/docs/guides/issue-reviewer.mdx
@@ -6,7 +6,7 @@ description: Learn how to automate reviewing issues with a script.
keywords: pull request automation, code review, GitHub Actions, GenAIScript reviewer, PR feedback
---
import { Code } from '@astrojs/starlight/components';
-import importedCode from "../../../../../packages/sample/genaisrc/issue-reviewer.genai?raw"
+import importedCode from "../../../../../packages/sample/genaisrc/issue-reviewer.genai.mjs?raw"
This guide shows how to automate reviewing issues
with a GenAIScript that provides feedback and code analysis in GitHub Actions.
diff --git a/docs/src/content/docs/reference/cli/api.mdx b/docs/src/content/docs/reference/cli/api.mdx
index 179e3a71e7..7af59b8184 100644
--- a/docs/src/content/docs/reference/cli/api.mdx
+++ b/docs/src/content/docs/reference/cli/api.mdx
@@ -5,29 +5,13 @@ sidebar:
---
import { Tabs, TabItem } from "@astrojs/starlight/components"
+import { PackageManagers } from 'starlight-package-managers'
This page describes how to import and use the [cli](/genaiscript/reference/cli) as an API in your Node.JS application.
Assuming you have have added the cli as a dependency in your project, you can import the cli as follows:
-
-
-
-```sh
-npm install -D genaiscript
-```
-
-
-
-
-
-```sh
-yarn add -D genaiscript
-```
-
-
-
-
+
The API can be imported using imports from **"genaiscript/api"**.
diff --git a/docs/src/content/docs/reference/cli/index.mdx b/docs/src/content/docs/reference/cli/index.mdx
index 45ac7892b3..39b5f78a1b 100644
--- a/docs/src/content/docs/reference/cli/index.mdx
+++ b/docs/src/content/docs/reference/cli/index.mdx
@@ -9,15 +9,13 @@ keywords: GenAIScript CLI, Node.js automation, AI scripting, command line interf
import { Steps } from "@astrojs/starlight/components"
import { Tabs, TabItem } from "@astrojs/starlight/components"
import DirectoryLinks from "../../../../components/DirectoryLinks.astro"
+import GenAIScriptCli from "../../../../components/GenAIScriptCli.astro"
+import { PackageManagers } from "starlight-package-managers"
The GenAIScript CLI **`genaiscript`** runs GenAIScript scripts
outside of Visual Studio and in your [automation](/genaiscript/getting-starting/automating-scripts).
-```sh
-npx --yes genaiscript ...
-```
-
-where `--yes` skips the confirmation prompt to install the package.
+
## Prerequisites
@@ -29,22 +27,7 @@ The CLI is a Node.JS package hosted on [npm](https://www.npmjs.com/package/genai
- Install locally as a `devDependency` in your project.
-
-
-
-```sh
-npm install -D genaiscript
-```
-
-
-
-
-```sh
-yarn add -D genaiscript
-```
-
-
-
+
- Install it globally.
diff --git a/docs/src/content/docs/reference/scripts/content-safety.mdx b/docs/src/content/docs/reference/scripts/content-safety.mdx
index 8c8b60cc89..52199de3f6 100644
--- a/docs/src/content/docs/reference/scripts/content-safety.mdx
+++ b/docs/src/content/docs/reference/scripts/content-safety.mdx
@@ -12,15 +12,15 @@ GenAIScript has multiple built-in safety features to protect the system from mal
The following safety prompts are included by default when running a prompt, unless the system option is configured:
-- [system.safety_harmful_content](../system#systemsafety_harmful_content), safety prompt against Harmful Content: Hate and Fairness, Sexual, Violence, Self-Harm. See https://learn.microsoft.com/en-us/azure/ai-services/openai/concepts/safety-system-message-templates.
-- [system.safety_jailbreak](../system#systemsafety_jailbreak), safety script to ignore prompting instructions in code sections, which are created by the `def` function.
-- [system.safety_protected_material](../system#systemsafety_protected_material) safety prompt against Protected material. See https://learn.microsoft.com/en-us/azure/ai-services/openai/concepts/safety-system-message-templates
+- [system.safety_harmful_content](/genaiscript/reference/script/system#systemsafety_harmful_content), safety prompt against Harmful Content: Hate and Fairness, Sexual, Violence, Self-Harm. See https://learn.microsoft.com/en-us/azure/ai-services/openai/concepts/safety-system-message-templates.
+- [system.safety_jailbreak](/genaiscript/reference/script/system#systemsafety_jailbreak), safety script to ignore prompting instructions in code sections, which are created by the `def` function.
+- [system.safety_protected_material](/genaiscript/reference/script/system#systemsafety_protected_material) safety prompt against Protected material. See https://learn.microsoft.com/en-us/azure/ai-services/openai/concepts/safety-system-message-templates
Other system scripts can be added to the prompt by using the `system` option.
-- [system.safety_ungrounded_content_summarization](../system#systemsafety_ungrounded_content_summarization) safety prompt against ungrounded content in summarization
-- [system.safety_canary_word](../system#systemsafety_canary_word) safety prompt against prompt leaks.
-- [system.safety_validate_harmful_content](../system#systemsafety_validate_harmful_content) runs the `detectHarmfulContent` method to validate the output of the prompt.
+- [system.safety_ungrounded_content_summarization](/genaiscript/reference/script/system#systemsafety_ungrounded_content_summarization) safety prompt against ungrounded content in summarization
+- [system.safety_canary_word](/genaiscript/reference/script/system#systemsafety_canary_word) safety prompt against prompt leaks.
+- [system.safety_validate_harmful_content](/genaiscript/reference/script/system#systemsafety_validate_harmful_content) runs the `detectHarmfulContent` method to validate the output of the prompt.
## Azure AI Content Safety services
diff --git a/docs/src/content/docs/reference/scripts/github.md b/docs/src/content/docs/reference/scripts/github.mdx
similarity index 97%
rename from docs/src/content/docs/reference/scripts/github.md
rename to docs/src/content/docs/reference/scripts/github.mdx
index 9b4e33c38f..41a675061f 100644
--- a/docs/src/content/docs/reference/scripts/github.md
+++ b/docs/src/content/docs/reference/scripts/github.mdx
@@ -4,6 +4,7 @@ description: Support for querying GitHub
sidebar:
order: 50
---
+import { PackageManagers } from 'starlight-package-managers'
The `github` module provides several helper functions to query GitHub, along with the connection information for more advanced usage.
@@ -148,9 +149,7 @@ const { client }: { client: Octokit } = await github.api()
Install octokit in your list of packages:
-```sh
-npm install -D octokit
-```
+
## Working on a different repository
diff --git a/docs/src/content/docs/reference/scripts/mcp-tools.mdx b/docs/src/content/docs/reference/scripts/mcp-tools.mdx
index d93423b011..3fb8ed788d 100644
--- a/docs/src/content/docs/reference/scripts/mcp-tools.mdx
+++ b/docs/src/content/docs/reference/scripts/mcp-tools.mdx
@@ -46,7 +46,7 @@ The tool identifier will be `server_toolname` to avoid clashes.
Servers are started when rendering the prompt and stopped once the chat session is completed.
-This means that if you define servers in an [inline prompt](/genaiscript/reference/prompts/inline),
+This means that if you define servers in an [inline prompt](/genaiscript/reference/scripts/inline-prompts),
the server will be started/stopped for each inline prompt.
## Finding servers
diff --git a/docs/src/content/docs/reference/scripts/tools.mdx b/docs/src/content/docs/reference/scripts/tools.mdx
index 4b2f28505e..c1cecb3fca 100644
--- a/docs/src/content/docs/reference/scripts/tools.mdx
+++ b/docs/src/content/docs/reference/scripts/tools.mdx
@@ -15,7 +15,7 @@ You can register **tools** (also known as **functions**) that the LLM may decide
See [OpenAI functions](https://platform.openai.com/docs/guides/function-calling), [Ollama tools](https://ollama.com/blog/tool-support),
or [Anthropic tool use](https://docs.anthropic.com/en/docs/build-with-claude/tool-use).
-Not all LLM models support tools, in those cases, GenAIScript also support a fallback mechanism to implement tool call through system prompts (see [Ad Hoc Tools](#adhoctools)).
+Not all LLM models support tools, in those cases, GenAIScript also support a fallback mechanism to implement tool call through system prompts (see [Fallback Tools](#fallbacktools)).
## `defTool`
@@ -62,7 +62,7 @@ This example uses the `current_weather` tool to get the weather for Brussels.
### Math tool example
-This example uses the [math expression evaluator](/genaiscript/reference/scripts/math)
+This example uses the math expression evaluator
to evaluate a math expression.