started tutorial page

docs/.vscode/settings.json

@@ -0,0 +1,6 @@
+{
+    "cSpell.words": [
+        "genaiscript",
+        "openai"
+    ]
+}

docs/src/content/docs/getting-started/your-first-genai-script.mdx

@@ -1,15 +1,14 @@
 ---
 title: Your first GenAI script
 sidebar:
-  order: 3
+    order: 3
 description: Learn how to create and execute your initial GenAI script to
-  automate interactions with language models.
+    automate interactions with language models.
 keywords: GenAI script creation, language model automation, script execution,
-  LLM prompt generation, genaisrc setup
+    LLM prompt generation, genaisrc setup
 genaiscript:
-  model: openai:gpt-3.5-turbo
-  files: src/samples/markdown.md
-
+    model: openai:gpt-3.5-turbo
+    files: src/samples/markdown.md
 ---
 
 import { Tabs, TabItem } from "@astrojs/starlight/components"
@@ -52,7 +51,8 @@ The resulting file will be placed in the `genaisrc` folder in your project.
 The execution of the GenAIScript generates a prompt (and more)
 that gets sent to the LLM model.
 
-The ` $``...`` ` template string function formats and write the string to the prompt; which gets sent to the LLM.
+The ` $``...`` ` template string function formats and write the string to the prompt;
+which gets sent to the LLM.
 
 ```js title="poem.genai.js" system=false assistant=true
 $`Write a one sentence poem.`
@@ -63,30 +63,23 @@ $`Write a one sentence poem.`
 <details>
 <summary>👤 user</summary>
 
-
 ```markdown wrap
 Write a one sentence poem.
 ```
 
-
 </details>
 
-
 <details open>
 <summary>🤖 assistant</summary>
 
-
 ```markdown wrap
 Roses bloom, hearts swoon, under the silver moon.
 ```
 
-
 </details>
 
 {/* genaiscript output end */}
 
-
-
 ## the Context
 
 GenAIScript exposes the context through the `env` variable. The context is implicitly defined by the location you start executing the script.
@@ -104,32 +97,30 @@ def("FILES", env.files)
 <details open>
 <summary>👤 user</summary>
 
-
 ``````markdown wrap
 FILES:
-`````md file="src/samples/markdown.md"
+
+```md file="src/samples/markdown.md"
 ---
 title: What is Markdown? - Understanding Markdown Syntax
 description: Learn about Markdown, a lightweight markup language for formatting plain text, its syntax, and how it differs from WYSIWYG editors.
 keywords: Markdown, markup language, formatting, plain text, syntax
 sidebar: mydoc_sidebar
 ---
+
 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. 
+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.
 
 Using Markdown is different than using a WYSIWYG editor. In an application like Microsoft Word, you click buttons to format words and phrases, and the changes are visible immediately. Markdown isn’t like that. When you create a Markdown-formatted file, you add Markdown syntax to the text to indicate which words and phrases should look different.
 
 For example, to denote a heading, you add a number sign before it (e.g., # Heading One). Or to make a phrase bold, you add two asterisks before and after it (e.g., **this text is bold**). It may take a while to get used to seeing Markdown syntax in your text, especially if you’re accustomed to WYSIWYG applications. The screenshot below shows a Markdown file displayed in the Visual Studio Code text editor....
-`````
+```
 ``````
 
-
 </details>
 
 {/* genaiscript output end */}
 
-
-
 ## the Task
 
 The `$` function is used to build the prompt text, it renders and writes the text to the prompt
@@ -146,36 +137,34 @@ Review the documents in FILE and report the 2 most important issues.`
 <details>
 <summary>👤 user</summary>
 
-
 ``````markdown wrap
 FILES:
-`````md file="src/samples/markdown.md"
+
+```md file="src/samples/markdown.md"
 ---
 title: What is Markdown? - Understanding Markdown Syntax
 description: Learn about Markdown, a lightweight markup language for formatting plain text, its syntax, and how it differs from WYSIWYG editors.
 keywords: Markdown, markup language, formatting, plain text, syntax
 sidebar: mydoc_sidebar
 ---
+
 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. 
+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.
 
 Using Markdown is different than using a WYSIWYG editor. In an application like Microsoft Word, you click buttons to format words and phrases, and the changes are visible immediately. Markdown isn’t like that. When you create a Markdown-formatted file, you add Markdown syntax to the text to indicate which words and phrases should look different.
 
 For example, to denote a heading, you add a number sign before it (e.g., # Heading One). Or to make a phrase bold, you add two asterisks before and after it (e.g., **this text is bold**). It may take a while to get used to seeing Markdown syntax in your text, especially if you’re accustomed to WYSIWYG applications. The screenshot below shows a Markdown file displayed in the Visual Studio Code text editor....
-`````
+```
 
 You are an expert technical writer and proofreader.
 Review the documents in FILE and report the 2 most important issues.
 ``````
 
-
 </details>
 
-
 <details open>
 <summary>🤖 assistant</summary>
 
-
 ```markdown wrap
 I reviewed the document in "src/samples/markdown.md" and found the following two important issues:
 
@@ -186,13 +175,10 @@ I reviewed the document in "src/samples/markdown.md" and found the following two
 These are the two most important issues that need to be addressed in the document.
 ```
 
-
 </details>
 
 {/* genaiscript output end */}
 
-
-
 ## the Metadata
 
 You can add a call to the `script` function to provides metadata about the script
@@ -219,36 +205,34 @@ Review the documents in FILE and report the 2 most important issues.`
 <details>
 <summary>👤 user</summary>
 
-
 ``````markdown wrap
 FILES:
-`````md file="src/samples/markdown.md"
+
+```md file="src/samples/markdown.md"
 ---
 title: What is Markdown? - Understanding Markdown Syntax
 description: Learn about Markdown, a lightweight markup language for formatting plain text, its syntax, and how it differs from WYSIWYG editors.
 keywords: Markdown, markup language, formatting, plain text, syntax
 sidebar: mydoc_sidebar
 ---
+
 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. 
+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.
 
 Using Markdown is different than using a WYSIWYG editor. In an application like Microsoft Word, you click buttons to format words and phrases, and the changes are visible immediately. Markdown isn’t like that. When you create a Markdown-formatted file, you add Markdown syntax to the text to indicate which words and phrases should look different.
 
 For example, to denote a heading, you add a number sign before it (e.g., # Heading One). Or to make a phrase bold, you add two asterisks before and after it (e.g., **this text is bold**). It may take a while to get used to seeing Markdown syntax in your text, especially if you’re accustomed to WYSIWYG applications. The screenshot below shows a Markdown file displayed in the Visual Studio Code text editor....
-`````
+```
 
 You are an expert technical writer and proofreader.
 Review the documents in FILE and report the 2 most important issues.
 ``````
 
-
 </details>
 
-
 <details open>
 <summary>🤖 assistant</summary>
 
-
 ```markdown wrap
 File src/samples/markdown.md:
 
@@ -259,18 +243,16 @@ File src/samples/markdown.md:
 These are the two most important issues in the document.
 ```
 
-
 </details>
 
 {/* genaiscript output end */}
 
-
-
 The `title`, `description`, and `group` properties are used to display the script in the UI
 and can be helpful when the user is searching for a script.
 
 ![The quickpick entry for the snippet above](../../../assets/vscode-select-script.png)
 
 ## Next steps
 
-[Run your script](/genaiscript/getting-started/running-scripts) from Visual Studio Code.
+-   Follow the [Prompt As Code guide](/genaiscript/guides/prompt-as-code) to dive deeper in programmatically generating prompts
+-   [Run your script](/genaiscript/getting-started/running-scripts) from Visual Studio Code.

docs/src/content/docs/guides/prompt-as-code.md

@@ -0,0 +1,115 @@
+---
+title: Prompt As Code
+description: Tutorial on using GenAIScript runtime and syntax to assemble prompts
+sidebar:
+  order: 0
+genaiscript:
+  files: src/samples/markdown.md
+  model: openai:gpt-3.50-turbo
+---
+
+This page is a tutorial on creating prompt with GenAIScript. It is designed to be opened
+in Visual Studio Code as a Notebook.
+
+1. Follow the steps in [installation](/genaiscript/getting-started/installation) and
+[configuration](/genaiscript/getting-started/configuration) to set up your environment.
+
+2. Right click on this file and select **Open With...**, then **GenAIScript Markdown Notebook**
+to edit this file as a Notebook.
+
+## About GenAIScript Markdown Notebooks
+
+The [GenAIScript Markdown Notebook](/genaiscript/reference/scripts/notebook) will parse the markdown document into a Notebook view and use Visual Studio Code's support to provide a rich editing experience. It should work with any markdown file as long as the code fence use "```".
+
+- Each **JavaScript** code block is an self-contained GenAIScript that can be executed individually. The results are attached to each code block and saved in the markdown file.
+- This is a stateless kernel, so the variables are not shared between code blocks.
+- Other languages are not supported in this notebook and simply ignored.
+
+## Prompt as code
+
+GenAIScript lets you write prompts as a JavaScript program. GenAIScript runs your program; generate chat messages; then handles the remaining interaction with the LLM API.
+
+Let's start with a simple hello world program.
+
+```js
+$`Say "hello!" in emojis`
+```
+
+<!-- genaiscript output start -->
+
+<details>
+<summary>👤 user</summary>
+
+
+```markdown wrap
+Say "hello!" in emojis
+```
+
+
+</details>
+
+
+<details open>
+<summary>🤖 assistant </summary>
+
+
+```markdown wrap
+👋😃!
+```
+
+
+</details>
+
+<!-- genaiscript output end -->
+
+
+
+The `$` function formats the strings and write them to the user message. This user message is added to the chat messages and sent to the LLM API. Under the snippet, you can review both the **user** message (that our program generated) and the **assistant** (LLM) response.
+
+You can run the code block by clicking the **Execute Cell** button on the top left corner of the code block. It will be default try to use the `openai:gpt-3.5-turbo` LLM. If you need to use a different model, update the `model` field in the front matter at the start of the document. There are many options documented in [configuration](/genaiscript/getting-started/configuration).
+
+Once the execution is done, you will also an additional **trace** entry that allows you to dive in the internal details of the GenAIScript execution. This is very helpful to diagnose issues with your prompts. The trace can be quite large so it is not serialized in the markdown file.
+
+You can sequence multiple `$` calls to append text to the user message. You can also inner expression to generate dynamic content.
+
+```js
+// let's give 3 tasks to the LLM
+// to get 3 different outputs
+for(let i = 1; i <= 3; i++)
+  $`- Say "hello!" in ${i} emojis.`
+$`Respond with a markdown list`
+```
+
+<!-- genaiscript output start -->
+
+<details>
+<summary>👤 user</summary>
+
+
+```markdown wrap
+- Say "hello!" in 1 emojis.
+- Say "hello!" in 2 emojis.
+- Say "hello!" in 3 emojis.
+Respond with a markdown list
+```
+
+
+</details>
+
+
+<details open>
+<summary>🤖 assistant </summary>
+
+
+```markdown wrap
+- 👋
+- 👋😊
+- 👋✨😃
+```
+
+
+</details>
+
+<!-- genaiscript output end -->
+
+

packages/vscode/src/docsnotebook.ts

@@ -229,13 +229,13 @@ function activateNotebookExecutor(state: ExtensionState) {
                         ]),
                         new vscode.NotebookCellOutput([
                             vscode.NotebookCellOutputItem.text(
-                                details(
+                                /*details(
                                     "env.vars.output",
                                     fenceMD(
                                         YAMLStringify(clean(output)),
                                         "yaml"
                                     )
-                                ) + details("trace", trace),
+                                ) + */ details("trace", trace),
                                 MARKDOWN_MIME_TYPE
                             ),
                         ]),