Skip to content

Commit d2df838

Browse files
dtamdtam
committed
last of docs
1 parent 27248aa commit d2df838

File tree

4 files changed

+86
-95
lines changed

4 files changed

+86
-95
lines changed

‎docs/how_to_guides/instructions.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# `Instructions` Element
22

3+
**Note**: Instructions element support has been dropped in 0.6.0 in support of [messages](./messages).
4+
35
The `<instructions></instructions>` element is passed to the LLM as secondary input. Different model may use these differently. For example, chat models may receive instructions in the system-prompt.
46

57
## 📚 Components of an Instructions Element

‎docs/how_to_guides/messages.md‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
# `Messages` Element
2+
3+
The `<messages></messages>` element contains instructions and the query that describes the high level task.
4+
5+
## 📚 Components of a Prompt Element
6+
7+
In addition to the high level task description, messages also contains the following:
8+
9+
| Component | Syntax | Description |
10+
|-------------------|--------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
11+
| Variables | `${variable_name}` | These are provided by the user at runtime, and substituted in the prompt. |
12+
| Output Schema | `${output_schema}` | This is the schema of the expected output, and is compiled based on the `output` element. For more information on how the output schema is compiled for the prompt, check out [`output` element compilation](/docs/concepts/output/#adding-compiled-output-element-to-prompt). |
13+
| Prompt Primitives | `${gr.prompt_primitive_name}` | These are pre-constructed prompts that are useful for common tasks. E.g., some primitives may contain information that helps the LLM understand the output schema better. To see the full list of prompt primitives, check out [`guardrails/constants.xml`](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/constants.xml). |
14+
15+
```xml
16+
<rail version="0.1">
17+
<messages>
18+
<message role="system">
19+
<!-- (1)! -->
20+
You are a helpful assistant only capable of communicating with valid JSON, and no other text.
21+
</message>
22+
<message role="user">
23+
<!-- (2)! -->
24+
Given the following document, answer the following questions. If the answer doesn't exist in the document, enter 'None'.
25+
26+
${document} <!-- (3)! -->
27+
28+
29+
${gr.xml_prefix_prompt} <!-- (4)! -->
30+
31+
32+
${output_schema} <!-- (5)! -->
33+
34+
35+
${gr.json_suffix_prompt} <!-- (6)! -->
36+
</message>
37+
</message>
38+
</rail>
39+
```
40+
41+
1. The instructions element contains high level background information for the LLM containing textual context and constraints.
42+
2. The prompt contains high level task information.
43+
3. The variable `${document}` is provided by the user at runtime.
44+
4. `${gr.xml_prefix_prompt}` is a prompt primitive provided by guardrails. It is equivalent to typing the following lines in the prompt: `Given below is XML that describes the information to extract from this document and the tags to extract it into.`
45+
5. `${output_schema}` is the output schema and contains information about , which is compiled based on the `output` element.
46+
6. `${gr.json_suffix_prompt}` is a prompt primitive provided by guardrails. It is equivalent to typing the following lines in the prompt:
47+
```
48+
ONLY return a valid JSON object (no other text is necessary). The JSON MUST conform to the XML format, including any types and format requests e.g. requests for lists, objects and specific types. Be correct and concise. If you are unsure anywhere, enter `null`.
49+
```
50+
51+
The messages element is made up of message elements with role attributes. Messages with the role system are intended to be system level prompt. Messages with the role assistant are intended to be messages from the llm to be repassed to itself as additional context and history. Messages with role user are input from the user and also convey history of the conversation.

‎docs/how_to_guides/prompt.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,8 @@
11
# `Prompt` Element
22

3+
4+
**Note**: Prompt element support has been dropped in 0.6.0 in support of [messages](./messages).
5+
36
The `<prompt></prompt>` element contains the query that describes the high level task.
47

58
## 📚 Components of a Prompt Element

‎docs/how_to_guides/rail.md‎

Lines changed: 30 additions & 95 deletions
Original file line numberDiff line numberDiff line change
@@ -78,15 +78,17 @@ Let's see an example of an `RAIL` specification in action:
7878
</output>
7979

8080

81-
<prompt> <!-- (2)! -->
81+
<messages> <!-- (2)! -->
82+
<message role="user">
8283
...
83-
</prompt>
84+
</message>
85+
</message>
8486

8587
</rail>
8688
```
8789

8890
1. The `output` element contains the structure of the expected output of the LLM. It contains the spec for the overall structure of the LLM output, type info for each field, and the quality criteria for each field and the corrective action to be taken in case quality criteria is not met.
89-
2. The `prompt` element contains the high level instructions that are sent to the LLM. Check out the [RAIL Prompt](#components-of-a-prompt-element) page for more details.
91+
2. The `messages` element contains the high level instructions that are sent to the LLM. Check out the [RAIL Prompt](#components-of-a-message-element) page for more details.
9092

9193
## 📖 How to use `RAIL` in Guardrails?
9294

@@ -110,125 +112,58 @@ _, validated_output, *rest = guard(
110112
1. A `Guard` object is created from a `RAIL` specification. This object manages the validation and correction of the output of the LLM, as well as the prompt that is sent to the LLM.
111113
2. Wrap the LLM API call (`openai.Completion.create`) with the `Guard` object, and add any additional arguments that you want to pass to the LLM API call. Instead of returning the raw text object, the `Guard` object will return a JSON object that is validated and corrected according to the `RAIL` specification.
112114

113-
# `Instructions` Element
115+
# `Messages` Element
114116

115-
The `<instructions></instructions>` element is passed to the LLM as secondary input. Different model may use these differently. For example, chat models may receive instructions in the system-prompt.
117+
The `<messages></messages>` element contains instructions and the query that describes the high level task.
116118

117-
## Components of an Instructions Element
119+
## 📚 Components of a Prompt Element
118120

119-
In addition to any static text describing the context of the task, instructions can also contain any of the following:
120-
121-
| Component | Syntax | Description |
122-
|-------------------|--------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
123-
| Variables | `${variable_name}` | These are provided by the user at runtime, and substituted in the instructions. |
124-
| Output Schema | `${output_schema}` | This is the schema of the expected output, and is compiled based on the `output` element. For more information on how the output schema is compiled for the instructions, check out [`output` element compilation](#adding-compiled-output-element-to-prompt) |
125-
| Prompt Primitives | `${gr.prompt_primitive_name}` | These are pre-constructed blocks of text that are useful for common tasks. E.g., some primitives may contain information that helps the LLM understand the output schema better. To see the full list of prompt primitives, check out [`guardrails/constants.xml`](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/constants.xml). |
126-
127-
128-
Here's an example of how you could compose instructions using RAIL xml:
129-
```xml
130-
<rail version="0.1">
131-
<instructions>
132-
<!-- (1)! -->
133-
You are a helpful assistant only capable of communicating with valid JSON, and no other text.
134-
135-
${gr.json_suffix_prompt_examples} <!-- (2)! -->
136-
</instructions>
137-
</rail>
138-
```
139-
140-
1. The instructions element contains high level background information for the LLM containing textual context and constraints.
141-
2. `${gr.json_suffix_prompt_examples}` is a prompt primitive provided by guardrails. It is equivalent to typing the following lines in the instructions:
142-
````
143-
ONLY return a valid JSON object (no other text is necessary), where the key of the field in JSON is the `name` attribute of the corresponding XML, and the value is of the type specified by the corresponding XML's tag. The JSON MUST conform to the XML format, including any types and format requests e.g. requests for lists, objects and specific types. Be correct and concise. If you are unsure anywhere, enter `null`.
144-
145-
Here are examples of simple (XML, JSON) pairs that show the expected behavior:
146-
- `<![CDATA[<string name='foo' format='two-words lower-case' />`]]> => `{'foo': 'example one'}`
147-
- `<![CDATA[<list name='bar'><string format='upper-case' /></list>]]>` => `{"bar": ['STRING ONE', 'STRING TWO', etc.]}`
148-
- `<![CDATA[<object name='baz'><string name="foo" format="capitalize two-words" /><integer name="index" format="1-indexed" /></object>]]>` => `{'baz': {'foo': 'Some String', 'index': 1}}`
149-
````
150-
151-
Or if you prefer Pydantic:
152-
```py
153-
# <!-- (1)! -->
154-
instructions = """You are a helpful assistant only capable of communicating with valid JSON, and no other text.
155-
156-
${gr.json_suffix_prompt_examples}""" # <!-- (2)! -->
157-
```
158-
159-
160-
1. The instructions element contains high level background information for the LLM containing textual context and constraints.
161-
2. `${gr.json_suffix_prompt_examples}` is a prompt primitive provided by guardrails. It is equivalent to typing the following lines in the instructions:
162-
````
163-
ONLY return a valid JSON object (no other text is necessary), where the key of the field in JSON is the `name` attribute of the corresponding XML, and the value is of the type specified by the corresponding XML's tag. The JSON MUST conform to the XML format, including any types and format requests e.g. requests for lists, objects and specific types. Be correct and concise. If you are unsure anywhere, enter `null`.
164-
165-
Here are examples of simple (XML, JSON) pairs that show the expected behavior:
166-
- `<![CDATA[<string name='foo' format='two-words lower-case' />`]]> => `{'foo': 'example one'}`
167-
- `<![CDATA[<list name='bar'><string format='upper-case' /></list>]]>` => `{"bar": ['STRING ONE', 'STRING TWO', etc.]}`
168-
- `<![CDATA[<object name='baz'><string name="foo" format="capitalize two-words" /><integer name="index" format="1-indexed" /></object>]]>` => `{'baz': {'foo': 'Some String', 'index': 1}}`
169-
````
170-
171-
When either of the above are compiled, it would looks like this:
172-
```
173-
You are a helpful assistant only capable of communicating with valid JSON, and no other text.
174-
175-
ONLY return a valid JSON object (no other text is necessary).
176-
The JSON MUST conform to the XML format, including any types and format requests e.g. requests for lists, objects and specific types.
177-
Be correct and concise. If you are unsure anywhere, enter `null`.
178-
179-
Here are examples of simple (XML, JSON) pairs that show the expected behavior:
180-
- `<string name='foo' format='two-words lower-case' />` => `{'foo': 'example one'}`
181-
- `<list name='bar'><string format='upper-case' /></list>` => `{"bar": ['STRING ONE', 'STRING TWO', etc.]}`
182-
- `<object name='baz'><string name="foo" format="capitalize two-words" /><integer name="index" format="1-indexed" /></object>` => `{'baz': {'foo': 'Some String', 'index': 1}}`
183-
```
184-
185-
186-
For an example of using instructions alongside a prompt see [this example for using chat models](/docs/examples/guardrails_with_chat_models).
187-
188-
# `Prompt` Element
189-
190-
The `<prompt></prompt>` element contains the query that describes the high level task.
191-
192-
## Components of a Prompt Element
193-
194-
In addition to the high level task description, the prompt also contains the following:
121+
In addition to the high level task description, messages also contains the following:
195122

196123
| Component | Syntax | Description |
197124
|-------------------|--------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
198125
| Variables | `${variable_name}` | These are provided by the user at runtime, and substituted in the prompt. |
199-
| Output Schema | `${output_schema}` | This is the schema of the expected output, and is compiled based on the `output` element. For more information on how the output schema is compiled for the prompt, check out [`output` element compilation](#adding-compiled-output-element-to-prompt). |
126+
| Output Schema | `${output_schema}` | This is the schema of the expected output, and is compiled based on the `output` element. For more information on how the output schema is compiled for the prompt, check out [`output` element compilation](/docs/concepts/output/#adding-compiled-output-element-to-prompt). |
200127
| Prompt Primitives | `${gr.prompt_primitive_name}` | These are pre-constructed prompts that are useful for common tasks. E.g., some primitives may contain information that helps the LLM understand the output schema better. To see the full list of prompt primitives, check out [`guardrails/constants.xml`](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/constants.xml). |
201128

202129
```xml
203130
<rail version="0.1">
204-
<prompt>
131+
<messages>
132+
<message role="system">
205133
<!-- (1)! -->
134+
You are a helpful assistant only capable of communicating with valid JSON, and no other text.
135+
</message>
136+
<message role="user">
137+
<!-- (2)! -->
206138
Given the following document, answer the following questions. If the answer doesn't exist in the document, enter 'None'.
207139

208-
${document} <!-- (2)! -->
209-
140+
${document} <!-- (3)! -->
210141

211-
${gr.xml_prefix_prompt} <!-- (3)! -->
212142

143+
${gr.xml_prefix_prompt} <!-- (4)! -->
213144

214-
${output_schema} <!-- (4)! -->
215145

146+
${output_schema} <!-- (5)! -->
216147

217-
${gr.json_suffix_prompt} <!-- (5)! -->
218148

219-
</prompt>
149+
${gr.json_suffix_prompt} <!-- (6)! -->
150+
</message>
151+
</message>
220152
</rail>
221153
```
222154

223-
1. The prompt contains high level task information.
224-
2. The variable `${document}` is provided by the user at runtime.
225-
3. `${gr.xml_prefix_prompt}` is a prompt primitive provided by guardrails. It is equivalent to typing the following lines in the prompt: `Given below is XML that describes the information to extract from this document and the tags to extract it into.`
226-
4. `${output_schema}` is the output schema and contains information about , which is compiled based on the `output` element.
227-
5. `${gr.json_suffix_prompt}` is a prompt primitive provided by guardrails. It is equivalent to typing the following lines in the prompt:
155+
1. The instructions element contains high level background information for the LLM containing textual context and constraints.
156+
2. The prompt contains high level task information.
157+
3. The variable `${document}` is provided by the user at runtime.
158+
4. `${gr.xml_prefix_prompt}` is a prompt primitive provided by guardrails. It is equivalent to typing the following lines in the prompt: `Given below is XML that describes the information to extract from this document and the tags to extract it into.`
159+
5. `${output_schema}` is the output schema and contains information about , which is compiled based on the `output` element.
160+
6. `${gr.json_suffix_prompt}` is a prompt primitive provided by guardrails. It is equivalent to typing the following lines in the prompt:
228161
```
229162
ONLY return a valid JSON object (no other text is necessary). The JSON MUST conform to the XML format, including any types and format requests e.g. requests for lists, objects and specific types. Be correct and concise. If you are unsure anywhere, enter `null`.
230163
```
231164

165+
The messages element is made up of message elements with role attributes. Messages with the role system are intended to be system level prompt. Messages with the role assistant are intended to be messages from the llm to be repassed to itself as additional context and history. Messages with role user are input from the user and also convey history of the conversation.
166+
232167
# `Output` Element
233168

234169
The `<output>...</output>` element of a `RAIL` spec is used to give precise specification of the expected output of the LLM. It specifies

0 commit comments

Comments
 (0)