Skip to content

Commit 1d2dfe2

Browse files
redvexredvex
committed
Update documentation
1 parent f2e6684 commit 1d2dfe2

27 files changed

+327
-87
lines changed

‎.github/workflows/update.yaml

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
name: Update version
2+
on:
3+
workflow_dispatch
4+
5+
jobs:
6+
update_and_commit:
7+
runs-on: ubuntu-latest
8+
steps:
9+
- name: Checkout Repository
10+
uses: actions/checkout@v2
11+
12+
- name: Set up Git config
13+
run: |
14+
git config user.name "github-actions[bot]"
15+
git config user.email "github-actions[bot]@users.noreply.github.com"
16+
17+
18+
19+
- name: Commit Files
20+
run: |
21+
git rebase develop
22+
git push --force

‎docs/creating_a_new_session_on_staging.md

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
# Creating a new test session on Staging
2+
3+
To create a test session on staging, head to the [action page](https://github.com/ThirdSpaceLearning/prompty_library/actions/workflows/create_session.yaml), and click "Run Workflow"
4+
![Run Worflow](../images/run_workflow_create_session.png).
5+
6+
Select:
7+
8+
- The branch related the prompt version (by default develop)
9+
- Student ID
10+
- School ID
11+
- Lesson ID
12+
13+
And click `Run Workflow`
14+
15+
The action takes a few seconds to run, but the AI tutor needs a couple of minutes to join the session.
16+
17+
To run the session, just login on staging using the pupil set in the process.

‎docs/identify_a_version.md

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# Identify a version
2+
3+
To identify a version, the easiest thing to do is to use the branch name previously created. However, it's possible to point to any version by selecting the file and click "History". The version name can be copied from Github using the copy functionality:
4+
5+
![Copy version](../images/versions.png).
6+
7+
PS. The version is an hash, something similar to (4fc35240680f444b61598db65dfcb9e3edd301e6).

‎docs/importing_existing_lesson.md

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
# Importing an existing lesson
2+
3+
Once the branch is created, head to the [action page](https://github.com/ThirdSpaceLearning/prompty_library/actions/workflows/import.yaml), and click "Run Workflow"
4+
![Run Worflow](../images/run_workflow.png).
5+
6+
Select the branch where the learning object has to be imported and type the learning objective id to import.
7+
8+
The process takes arount 15/20 seconds to import a learning objective.

‎docs/modify_a_version.md

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# Modify a version
2+
3+
To modify a version, select code and then branch
4+
![Select Branch](../images/branch.png).
5+
Then navigate to the [education/learning-objectives](../education/learning-objectives/) folder to start editing the prompt by selecting the file and click Edit.
6+
7+
To make the editor's life easier, each slide is tagged with its position.
8+
9+
It's important to notice that every single version is logged, it means, we can point Skye to use any version even if it's not immediately visible on github.

‎docs/system_prompt_files.md

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
# System Prompt
2+
3+
The system prompt is structured as following:
4+
5+
```markdown
6+
# System Interaction Guidelines
7+
8+
{tutor_persona}
9+
{pre_task_engagement}
10+
{general_tutoring_guidelines}
11+
## Important Reminders
12+
{reminders}
13+
## Current Status:
14+
{current_status}
15+
## Current Task:
16+
{current_task}
17+
## Chat Summary:
18+
{chat_summary}
19+
```
20+
21+
Each of the following prompts can include the following macros:
22+
23+
- ${config.name} - The student name
24+
- ${config.yearId} - The student year group
25+
- ${config.profile} - The student profile
26+
- ${config.teacherComment} - The student profile
27+
28+
## Tutor Persona
29+
30+
The [tutor persona](../education/tutor.md) prompt includes information about the tutor and the student.
31+
32+
## Pre Task Engagement
33+
34+
This section of the prompt scaffolds the very first interaction in a session. For example we can guide the tutor to welcome students for their very [first session](../education/first_session_with_skye.md) or having something different for [ongoing sessions](../education/ongoing_sessions_with_skye.md).
35+
36+
A few additional macro are available in this section:
37+
38+
- ${config.programme.summary} - The full list of each session learning outcome.
39+
- ${config.programme.learningObjectives} - A list of lessons to be taought during the session.
40+
- ${config.programme.lastSession.outcome} - The learning outcome for the last session.
41+
- ${config.programme.lastSession.assessmentResult} - The result of the last lesson assessment
42+
43+
## General Tutoring Guidence
44+
45+
This prompt includes a list of guidance for the tutor to use during a session. It scaffolds the tutor's behaviour across the session and it should include all the rules we want the tutor to follow.
46+
47+
## Important Reminders
48+
49+
This section of the prompt instructs the tutor about important facts regarding the student ongoing programme. For example the tutor may want to remind the student to [complete the kickoff quiz](../education/kickoff_quiz_not_completed.md) or acknowledge the fact the student has [just completed the kickOff quiz](../education/kickoff_quiz_just_completed.md).
50+
51+
A few additional macro are available in this section:
52+
53+
- ${config.assessment.completedAt} - When the student has completed the kickOff quiz.
54+
- ${config.assessment.insight} - A summary of the assessment result.
55+
- ${config.assessment.results} - The full list of questions with the student's answers.
56+
57+
## Current Status
58+
59+
The current status informs the tutor about the status of the session. It's formatted as follow:
60+
61+
```text
62+
Current Learning Objective: 1/4, Current Slide: 1/8, Current Step: 1/2
63+
```
64+
65+
The status can be refererred in other system prompts, but, generally, is used automatically the the tutor to drive its own behaviour during the session.
66+
67+
## Current Task
68+
69+
The instructions for each slide are manipulated by the system to create the current task prompt according to the following logic:
70+
71+
```pseudocode
72+
You have just said: {{utterance}}
73+
Do not repeat the question.
74+
You must respond only with "<ACK>" without any further comment and wait for the student to respond.
75+
Only after the student has responded,
76+
77+
IF (!correctAnswer)
78+
invoke the **moveToNextStep** tool using your response as a message
79+
80+
ELSE
81+
check their response against "{{correctAnswer}}"
82+
83+
IF (visualAid)
84+
Do not repeat or display this information to the student, but use it to enhance your understanding of the question: The learning slide shows {{visualAid}}.
85+
END
86+
87+
88+
IF (nextSlide)
89+
**If the answer is correct**: You must output <CORRECT> and invoke the **jumpToSlide** tool with index {{nextSlide}} and your praise for their understanding as the message.
90+
ELSE
91+
**If the answer is correct**: You must output <CORRECT> and invoke the **moveToNextStep** tool using your praise for their understanding as the message.\n
92+
END
93+
94+
IF (supportSlide)
95+
**If the answer is incorrect**: You must output <INCORRECT> and invoke the **jumpToSlide** tool with index {{supportSlide}} and a supportive message acknowledging the mistake.
96+
ELSE if (supportQuestion)
97+
**If the answer is incorrect**: You must ask {{supportQuestion}} to lead the student to the correct answer. When the student get to the right answer, invoke the **moveToNextStep** using your acknoledge as a message.
98+
ELSE
99+
**If the answer is incorrect**: You must pose guided questions to lead the student to the correct answer. When the student get to the right answer, invoke the **moveToNextStep** using your acknoledge as a message.
100+
END
101+
102+
IF (commonMisconceptions)
103+
Some examples of incorrect answers are: {{commonMisconceptions}}
104+
END
105+
106+
**if the answer is completely nonsensical**: You must advise the student to focus on the question.
107+
END
108+
```
109+
110+
The above pseudocde describe how Skye builds the current task based on the tags added to the instructions.
111+
112+
## Chat Summary
113+
114+
Chat Summary is created and updated everytime Skye move from a slide to another. Having the conversation (short memory) summarised helps with:
115+
116+
- Reduce the cost - smaller context window.
117+
- Increase the focus - the task is more prominent than the whole conversation.
118+
- Keep the context - the tutor is aware of any important facts happened in the session.

‎docs/update_a_version.md

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# Update a version
2+
3+
A version is a snapshot fixed in time. It means if others unrelated files are updated after the version is created, we need to update the version to include newly update files in the repository.
4+
5+
The Update a version action, allow to rebase automatically our version to the latest version. It means all the changes and improvements made to other files are included automatically in the selected version.
6+
7+
## Example
8+
9+
Some examples when to use the `Update version` action
10+
11+
- A new learning objective has been imported.
12+
- A learning objective has been updated.
13+
- One or more system prompt files have been updated.

‎docs/versioning.md

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
# Versioning
2+
3+
The prompt library is meant to be used to create a version of an existing lesson.
4+
To create a new branch (or version), click "New Branch" in [the branches list page](https://github.com/ThirdSpaceLearning/prompty_library/branches).
5+
6+
Make sure to not include any space in the branch name. For example a valid branch name could be: "learning-objective-2001". Another possible strategy is using the version name for a specific purpose, for example I may create a version named "spanish" to include the Spanish translations of the instructions.

‎docs/write_instructions_for_a_slide.md

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
# Write instructions for a slide
2+
3+
Each slide is formatted in markdown using the following template:
4+
5+
```markdown
6+
# Slide {n}
7+
8+
## Step {n-1}
9+
10+
{Instruction n-1}
11+
12+
## Step {n}
13+
14+
{Instruction n}
15+
16+
## Step {n+1}
17+
18+
{Instruction n+1}
19+
20+
```
21+
22+
Each step is a single unit that represent specific instructions to scaffold the LLM intelligence. To help the LLM to better understand how to perform a task using the instructions, we are using a strict format that is parsed and interpreted by the AI tutor to build the final prompt.
23+
24+
## Instruction structure
25+
26+
### Say
27+
28+
A task must start always with the tag `Say:` followed by the utterance we want the LLM to pronouce. It's important to notice that this sentence is not paraphrased by the LLM, but pronounced as is.
29+
30+
Example: `Say: What is 2+2?`
31+
32+
### Visual Aid
33+
34+
Sometimes, the question is not explicit, refering to the content of the slide itself (For example: Can you give question A a go?). In this case is paramount to explain the LLM the context of the question. The tag is optional, but it really helps the LLM to avoid hallucinations when it has to guide students when they give a wrong answer.
35+
36+
Example: `(Visual Aid: question A asks to identify the tenths in the number 4.53)
37+
38+
### Write
39+
40+
With the introduction of components, the tutor can write into the slide. The instructions are used to send directly the message to Ably to render content into the slide. The tag is optional, but is should be used when we want the tutor to interact with a slide. The format is `{value} @ {componentName}` where `componentName` is the name assigned on Figma. It's possible to add multiple instructions within the same tag, if the tutor has to use multiple components.
41+
42+
Example:
43+
44+
- Components:
45+
- `FM_a{1} @ text [The digit in the tens place is $1 and it has the value of $2]`
46+
- `FM_a{2} [The digit in the tens place is $1 and it has the value of $2]`
47+
- `(Write: 2 @ FM_a{1}, 20 @ FM_a{2})
48+
49+
### Correct Answer
50+
51+
LLMs are not great at Maths. Even the most capable LLMs struggle with simple questions. Without strict instructions, even GPT-4o can hallucinate. For this reason, we are always providing the correct answer to any question. The tag is optional, but it should always being included when the task includes a question.
52+
53+
Example: `(Correct Answer: 0.05)`
54+
55+
### Common Misconceptions
56+
57+
For the same reason we are stating the Correct Answer, sometimes, having the Common Misconception can help the LLM to avoid hallucinations. It's important to notice that LLMs work with tokens, not with numbers, it means the tokens for 0.5 (`[15, 13, 20]`) and 0.05 (`[15, 13, 2304]`) are very close and can lead, sporadicly to misinterpret a right answer for a wrong answer. The tag is optional, and it should be used only if LLM really struggle to indentify an answer as correct or incorrect.
58+
59+
Example: `(Common Misconceptions: 5, 0.5, 0.04, 0.005)`
60+
61+
### Support Slide
62+
63+
By default, when the student gets the answer wrong, we ask the LLM to pose guided questions to help the student to get to the right answer. Sometimes we want to scaffold the teaching by adding a dedicated support slide. The tag is optional, and it should be used only when we want the LLM to jump to a specific slide when the student gives a wrong answer. The tag accepts the position of the slide as a parameter.
64+
65+
Example: `(Support Slide: 4)`
66+
67+
### Support Question
68+
69+
If the instruction doesn't include a Support Slide and we want to scaffold the questions posed to the student, we can include the Support Question tag to force the LLM to pose the support questions we want, instead of the one decided by the AI. The tag is optional, and it should be used when we want the LLM to follow our directions when the student gives the wrong answer. The tag accepts a list of support questions separated by comma.
70+
71+
Example: `(Support Question: Which word helps you identify which calculation to do? The answer is 'altogether' which tells you that you need to add. Which column will change? The answer is the tenths. Which column will not change? The answer in the ones)`
72+
73+
### Next Slide
74+
75+
By default, the session flows linearly from step to step, from slide to slide, from LO to LO. We use the Next Slide tag when we want the LLM to jump to a different slide, in case of correct answer. The tag is optional, and it should be used only when we want the LLM to jump to a specific slide when the student gives the correct answer. The tag accepts the position of the slide as a parameter.
76+
77+
Example: `(Next Slide: 6)`
78+
79+
## Complete Example
80+
81+
```text
82+
# Slide 1
83+
84+
## Step 1
85+
86+
Say: How far did Terra cycle altogether? (Visual Aid: The question show 3 houses, the first and the second are connected by a line with the 7.3Km label. The second and the third are connected with a line with the 0.6Km label.)(Correct Answer: 7.9km)(Common Misconception: 7.3Km, 0.6Km)(Support Question: Which word helps you identify which calculation to do? The answer is 'altogether' which tells you that you need to add. Which column will change? The answer is the tenths. Which column will not change? The answer in the ones)(Support Slide: 4)(Next Slide: 6)
87+
```
88+
89+
## Formatting Tips
90+
91+
- Make sure to write tags using the first letter of each word in uppercase.
92+
- Do not include any space between tags.
93+
- Do not add any punctuation after the tags.

‎education/first_session.md

Lines changed: 0 additions & 2 deletions
This file was deleted.

‎education/kickoff_quiz_just_completed.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
### KickOff Quiz
2+
3+
${config.name} has completed the KickOff quiz at ${config.assessment.completed_at}.
4+
${config.assessment.insight}

‎education/kickoff_quiz_not_completed.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,3 @@
1-
## Important Reminders
1+
### KickOff Quiz
22

3-
Kickoff Quiz: Inform ${config.name} about the incomplete KickOff quiz. Stress the importance of completing it after the session to better personalize future lessons.
3+
Inform ${config.name} about the incomplete KickOff quiz. Stress the importance of completing it after the session to better personalize future lessons.

‎education/last_session_outcome.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
### Last Session Outcome
2+
3+
This is the report for the last session the studend had with you: ${config.programme.last_session}

‎education/learning-objectives/1871/17421.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ Say: Let us now repeat but for the tenths place. What is the digit in the blue t
1818

1919
## Step 5
2020

21-
Say: And what would its value then be? (Correct Answer: 0.6)
21+
Say: And what would its value then be? (Correct Answer: 0.6)
2222

2323
## Step 6
2424

‎education/learning-objectives/1921/17991.md

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -8,13 +8,10 @@ Say: Decimals can be partitioned, or split into smaller parts, in the same way t
88

99
Say: So now let us complete the part-whole model by partitioning the number into its smaller parts for b. For the first circle, what is the value of the 5 in the number? (Correct Answer: 50)
1010

11-
1211
## Step 3
1312

1413
Say: Fill in the third cicle with the number of tenths. (Correct Answer: 0.4 or 0.40)
1514

16-
1715
## Step 4
1816

1917
Say: What is the value of the hundredths? (Correct Answer: 0.02)(Support Slide: 4)
20-

‎education/learning-objectives/1966/18428.md

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,16 +5,21 @@
55
Say: In our lessons, we will try to get you speaking, reasoning and explaining out loud. We'll practice an example together so you can see how it works and practice speaking clearly and loudly enough for me to hear. Can you read the number out loud that we are trying to represent in counters? (Correct Answer: five thousand, four hundred and sixty-three)
66

77
## Step 2
8-
Say: Can you tell me how many thousand counters are missing? (Correct Answer: 4)(Visual Aid: The number five thousand, four hundred and sixty-three represented in counters but with some counters ripped out)
8+
9+
Say: Can you tell me how many thousand counters are missing? (Correct Answer: 4)(Visual Aid: The number five thousand, four hundred and sixty-three represented in counters but with some counters ripped out)
910

1011
## Step 3
12+
1113
Say: Now how many hundereds are missing? (Correct Answer: 2)
1214

1315
## Step 4
16+
1417
Say: What should we do next? (Correct Answer: Check how many ten counters are missing)
1518

1619
## Step 5
20+
1721
Say: So how many tens counters are missing then? (Correct Answer: 3)
1822

1923
## Step 6
24+
2025
Say: So what is the final step and what is the answer? (Correct Answer: Check how ones are missing and there is one missing)

‎education/learning-objectives/1969/18455.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,4 +2,4 @@
22

33
## Step 1
44

5-
Say: Today we're going to learn about rounding numbers to the nearest tenth. Can you have a go at the learning goal question? (Visual Aid: a question asking to round 2.64 to the nearest tenth) (Correct Answer: 2.6)
5+
Say: Today we're going to learn about rounding numbers to the nearest tenth. Can you have a go at the learning goal question? (Visual Aid: a question asking to round 2.64 to the nearest tenth) (Correct Answer: 2.6)

‎education/learning-objectives/1969/18456.md

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1 @@
11
# Slide 2
2-
3-

‎education/learning-objectives/1969/18457.md

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1 @@
11
# Slide 3
2-
3-

‎education/learning-objectives/1969/18458.md

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1 @@
11
# Slide 4
2-
3-

‎education/learning-objectives/1969/18459.md

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1 @@
11
# Slide 5
2-
3-

‎education/learning-objectives/1969/18460.md

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1 @@
11
# Slide 6
2-
3-

‎education/learning-objectives/1969/18461.md

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1 @@
11
# Slide 7
2-
3-

0 commit comments

Comments
 (0)