Skip to content

Commit fecc51f

Browse files
jimbrigjimbrig
committed
feat(vignettes): add examples vignette for Mermaid.js diagram generation
This commit introduces a new vignette titled "Examples" that demonstrates how to use the `noclocksai` package in conjunction with the `ellmer` package to generate Mermaid.js diagrams from R code snippets. The vignette includes detailed instructions and code examples for initializing a chat with OpenAI, passing R code, and rendering the resulting diagrams. Additionally, it updates the title of the existing "noclocksai" vignette to "Getting Started" for better clarity on its content.
1 parent 0d126a8 commit fecc51f

File tree

2 files changed

+191
-2
lines changed

2 files changed

+191
-2
lines changed

‎vignettes/examples.Rmd

Lines changed: 189 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,189 @@
1+
---
2+
title: "Examples"
3+
output: rmarkdown::html_vignette
4+
vignette: >
5+
%\VignetteIndexEntry{Examples}
6+
%\VignetteEngine{knitr::rmarkdown}
7+
%\VignetteEncoding{UTF-8}
8+
---
9+
10+
```{r setup, include = FALSE}
11+
knitr::opts_chunk$set(
12+
collapse = TRUE,
13+
comment = "#>",
14+
collapse = TRUE,
15+
warning = FALSE,
16+
message = FALSE,
17+
error = FALSE,
18+
out.width = "100%"
19+
)
20+
21+
# library(noclocksai)
22+
pkgload::load_all()
23+
24+
library(ellmer)
25+
library(DiagrammeR)
26+
```
27+
28+
```{r load_cached_resources, echo=FALSE, include=FALSE}
29+
mermaid_vignette_resources <- qs2::qs_read(pkg_sys_extdata("vignettes/mermaid_vignette_resources.qs"))
30+
mermaid_code <- mermaid_vignette_resources$mermaid_code
31+
resp <- mermaid_vignette_resources$resp
32+
mermaid_workflow_code <- mermaid_vignette_resources$mermaid_workflow_code
33+
resp_workflow <- mermaid_vignette_resources$resp_workflow
34+
```
35+
36+
## Example: Mermaid.js Diagram Generation
37+
38+
This example demonstrates how to use `noclocksai`'s features that build on top of the `ellmer`
39+
package to generate a [Mermaid.js](https://mermaid-js.github.io/mermaid/#/) diagram based on a provided R code snippet.
40+
The `ellmer` package provides a simple interface to interact with the OpenAI API, allowing you to generate
41+
the diagrams based on user-provided context or code snippets.
42+
43+
`noclocksai` comes with a set of pre-defined prompts for generating Mermaid.js diagrams, making it easy to
44+
generate diagrams without having to write the prompts from scratch.
45+
46+
In this example the following steps will be taken:
47+
48+
1. Initialize a chat with OpenAI using the Mermaid.js system prompt.
49+
2. Pass an example R code snippet to the chat.
50+
3. Extract the generated Mermaid.js diagram code block from the response.
51+
4. Render the Mermaid.js diagram using the extracted code block.
52+
53+
### Prompts
54+
55+
The `noclocksai` package provides two prompts for generating Mermaid.js diagrams. These prompts can be found in the package's `prompts/mermaid/` installed directory and retrieved via the `noclocksai::pkg_sys_prompt()` utility function or directly called using the `prompt_mermaid_sys()` and `prompt_mermaid_user()` functions.
56+
57+
Expand the following sections to view the Mermaid.js system and user prompts, respectively.
58+
59+
<br>
60+
61+
<details><summary>View [Mermaid.js System Prompt](../inst/prompts/mermaid/system.prompt.md)</summary><p>
62+
63+
````markdown
64+
65+
```{r child="../inst/prompts/mermaid/system.prompt.md"}
66+
```
67+
68+
````
69+
70+
</p></details>
71+
72+
<br>
73+
74+
<details><summary>View [Mermaid.js User Prompt](../inst/prompts/mermaid/user.prompt.md)</summary><p>
75+
76+
````markdown
77+
78+
```{r child="../inst/prompts/mermaid/user.prompt.md"}
79+
```
80+
81+
````
82+
83+
</p></details>
84+
85+
### Diagram Generation Workflow
86+
87+
The following code demonstrates how to generate a Mermaid.js diagram based on a provided R code snippet
88+
using the `noclocksai` package:
89+
90+
```{r mermaid_diagram_generation_chat, eval=FALSE}
91+
# initialize a chat with OpenAI using the mermaid.js system prompt
92+
chat <- ellmer::chat_openai(
93+
system_prompt = prompt_mermaid_sys(),
94+
echo = TRUE,
95+
api_args = list(temperature = 0)
96+
)
97+
98+
# example code to pass to chat
99+
example <- "starwars |>
100+
group_by(species) |>
101+
summarise(
102+
n = n(),
103+
mass = mean(mass, na.rm = TRUE)
104+
) |>
105+
filter(
106+
n > 1,
107+
mass > 50
108+
)"
109+
110+
# send the example code to the chat
111+
resp <- chat$chat(prompt_mermaid_user(context = example))
112+
```
113+
114+
The response from the chat will contain the generated Mermaid.js diagram code block:
115+
116+
```{r mermaid_diagram_generation_chat_output, echo=FALSE}
117+
cat(resp, sep = "\n")
118+
```
119+
120+
Now that the chat has been initialized and the example R code snippet has been passed to the chat,
121+
we can extract the generated Mermaid.js diagram code block from the response using the
122+
provided utility function `extract_code()`:
123+
124+
```{r extract_mermaid_diagram_code, eval=FALSE}
125+
# extract mermaid diagram code block from response
126+
mermaid_code <- extract_code(resp, lang = "mermaid", print = TRUE)
127+
```
128+
129+
preview the extracted Mermaid.js diagram code block:
130+
131+
```{r extract_mermaid_diagram_code_output, echo=FALSE}
132+
cat(mermaid_code, sep = "\n")
133+
```
134+
135+
Then you can use this generated Mermaid.js code block to render a diagram for the example R code:
136+
137+
```{r render_mermaid_diagram, out.height="400px", fig.dim=c(6,4), fig.align="center", fig.cap="Mermaid.js Diagram for the Example R Code Snippet"}
138+
# render the mermaid diagram
139+
DiagrammeR::DiagrammeR(mermaid_code)
140+
```
141+
142+
<br>
143+
144+
The generated Mermaid.js diagram should represent the flow of the provided R code snippet.
145+
146+
### Mermaid for this Workflow
147+
148+
Let's generate a diagram for the workflow defined above:
149+
150+
```{r mermaid_workflow, eval=FALSE}
151+
workflow <- "
152+
1. Initialize a chat with OpenAI using the mermaid.js system prompt
153+
2. Pass an example R code snippet to the chat
154+
3. Extract the generated Mermaid.js diagram code block from the response
155+
4. Render the Mermaid.js diagram using the extracted code block
156+
"
157+
158+
resp <- chat$chat(prompt_mermaid_user(context = workflow))
159+
```
160+
161+
The response from the chat will contain the generated Mermaid.js diagram code block:
162+
163+
```{r mermaid_workflow_output, eval=FALSE}
164+
cat(resp_workflow, sep = "\n")
165+
```
166+
167+
Extract the generated Mermaid.js diagram code block:
168+
169+
```{r extract_mermaid_workflow_code, eval=FALSE}
170+
# extract mermaid diagram code block from response
171+
mermaid_workflow_code <- extract_code(resp, lang = "mermaid", print = TRUE)
172+
```
173+
174+
preview the extracted Mermaid.js diagram code block:
175+
176+
```{r extract_mermaid_workflow_code_output, eval=FALSE}
177+
cat(mermaid_workflow_code, sep = "\n")
178+
```
179+
180+
Render the Mermaid.js diagram for this workflow:
181+
182+
```{r render_mermaid_workflow, out.height="400px", fig.dim=c(6,4), fig.align="center", fig.cap="Mermaid.js Diagram for the Workflow of Generating a Mermaid.js Diagram"}
183+
# render the mermaid diagram
184+
DiagrammeR::DiagrammeR(mermaid_workflow_code)
185+
```
186+
187+
<br>
188+
189+
The generated Mermaid.js diagram should represent the workflow of generating a Mermaid.js diagram based on an R code snippet.

‎vignettes/noclocksai.Rmd

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
---
2-
title: "noclocksai"
2+
title: "Getting Started"
33
output: rmarkdown::html_vignette
44
vignette: >
5-
%\VignetteIndexEntry{noclocksai}
5+
%\VignetteIndexEntry{Getting Started}
66
%\VignetteEngine{knitr::rmarkdown}
77
%\VignetteEncoding{UTF-8}
88
---

0 commit comments

Comments
 (0)