Skip to content

Commit bd8b9af

Browse files
author
Didier Durand
committed
doc update
1 parent 2d3aee6 commit bd8b9af

File tree

2 files changed

+136
-19
lines changed

2 files changed

+136
-19
lines changed

‎README.md

+10-12
Original file line numberDiff line numberDiff line change
@@ -87,7 +87,7 @@ options:
8787
q_list_data_source_sync_jobs
8888

8989
```
90-
% python3 q_list_data_source_sync_jobs.py -h
90+
% python3 q_list_data_source_sync_jobs.py -h
9191
usage: q_list_data_source_sync_jobs.py [-h] [-a APP_ID] [-i IDX_ID] [-d DS_ID] [-v]
9292
9393
list synchronization jobs executed for a given data source of an Amazon Q application
@@ -106,8 +106,8 @@ options:
106106
for q_list_documents.py
107107

108108
```
109-
% python3 q_list_documents.py -h
110-
usage: q_list_documents.py [-h] [-app APP_ID] [-idx IDX_ID] [-j] [-incl INCLUDE] [-excl EXCLUDE] [-inv] [-v]
109+
% python3 q_list_documents.py -h
110+
usage: q_list_documents.py [-h] [-app APP_ID] [-idx IDX_ID] [-incl INCLUDE] [-excl EXCLUDE] [-inv] [-v]
111111
112112
list documents indexed by Amazon Q
113113
@@ -117,7 +117,6 @@ options:
117117
Q application id
118118
-idx IDX_ID, --idx_id IDX_ID
119119
Q index id
120-
-j, --json json format for results
121120
-incl INCLUDE, --include INCLUDE
122121
comma-separated list of status to include
123122
-excl EXCLUDE, --exclude EXCLUDE
@@ -129,8 +128,8 @@ options:
129128
for q_list_conversations.py
130129

131130
```
132-
% python3 q_list_conversations.py -h
133-
usage: q_list_conversations.py [-h] [-a APP_ID] [-u USR_ID] [-j] [-v]
131+
% python3 q_list_conversations.py -h
132+
usage: q_list_conversations.py [-h] [-a APP_ID] [-u USR_ID] [-v]
134133
135134
list documents indexed by Amazon Q
136135
@@ -140,15 +139,13 @@ options:
140139
Q application id
141140
-u USR_ID, --usr_id USR_ID
142141
Q user id
143-
-j, --json json format for results
144142
-v, --verbose verbose mode
145-
146143
```
147144
for q_chat.py
148145

149146
```
150-
% python3 q_chat.py -h
151-
usage: q_chat.py [-h] [-a APP_ID] [-u USR_ID] [-p PROMPT] [-f FILE] [-c CNV_ID] [-m MSG_ID] [-v]
147+
% python3 q_chat.py -h
148+
usage: q_chat.py [-h] [-a APP_ID] [-u USR_ID] [-p PROMPT] [-f FILE] [-c CNV_ID] [-m MSG_ID] [-d] [-v]
152149
153150
ask a question to a Q application and get answer
154151
@@ -159,11 +156,12 @@ options:
159156
-u USR_ID, --usr_id USR_ID
160157
Q index id
161158
-p PROMPT, --prompt PROMPT
162-
question prompt
163-
-f FILE, --file FILE path to attached file
159+
question prompt or path to file with list of prompts
160+
-f FILE, --file FILE path to attachment file
164161
-c CNV_ID, --cnv_id CNV_ID
165162
Q conversation id (only to continue an existing conversation)
166163
-m MSG_ID, --msg_id MSG_ID
167164
Q parent message id (only to continue an existing conversation)
165+
-d, --details full conversation details
168166
-v, --verbose verbose mode
169167
```

‎doc/q_chat.md

+126-7
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,36 @@
11
## q_chat
2-
the q_chat script allows you to chat with the Amazon Q assistant from the command line.
3-
The question prompt is sent to the Q application (defined by its id) and a json structure is returned.
4-
It is also possible to attach a file to the chat question.
2+
3+
* [Description](#description)
4+
* [Usage](#usage)
5+
* [Help and Security](#help-and-security)
6+
7+
### Description
8+
9+
The q_chat script allows to chat with the Amazon Q assistant from the command line. For example, to be
10+
more efficient when creating some new prompt or when testing Q responses with some questions archived in a
11+
text file. The question prompt is sent to the Q application (defined by its id) under the chosen user name
12+
and a json structure is
13+
returned.
14+
15+
16+
It is also possible to attach a file to the chat question as part of the prompt (see example below asking for a
17+
summarization of a poem)
518

619
If you don't provide a conversation id, Amazon Q will assume that you start a new conversation with him.
7-
If you provide a conversation id (obtained from a previous exchange in field "conversationId") and the
20+
If you provide a conversation id - as obtained from a previous exchange in field "conversationId - and the
821
message id - as last returned systemMessageId" (see example below) - of last the assistant response, Q will
9-
assume that you continue this conversation and restore the context of this precedent conversation to
10-
continue the chat based on the conversation context.
22+
assume that you continue this conversation and restore the [LLM context window](https://klu.ai/glossary/context-window)
23+
of this precedent conversation to continue the chat based on this LLM context.
24+
25+
The q_chat script allows you to run conversations with Q. You have to provide a text file with 1 prompt per line.
26+
Prompts that are part of same conversation will be chained by prefix 'c:' at beginning of line. See example in
27+
[sample file](/data/prompt_list.txt)
1128

1229
This script is based on the [boto3("qbusiness").chat_sync() API](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/qbusiness/client/chat_sync.html) provided by the Amazon Q service. The userid should be one of
1330
the user created in the Q application as per documentation.
1431

15-
### Usage
32+
### Usage
33+
1634
Use with a simple text prompt
1735

1836
```
@@ -68,4 +86,105 @@ of "systemMessageId", which is last message in conversation flow.
6886
"systemMessageId": "7f66a7b5-cf35-4385-a9d9-6b479a185bba",
6987
"userMessageId": "d51cd11f-1e62-4d93-9560-6c63c7d6d5bc"
7088
}
89+
```
90+
91+
Use with a list of prompts, 3 of then in a conversation + 1 isolated proopt, resulting in 2 distinct
92+
conversations:
93+
94+
```
95+
% python3 q_chat.py -a <your-app-id> -u sammy -p ../data/prompt_list.txt
96+
[
97+
{
98+
"conversationId": "a86bc9f6-2ace-4535-8634-3be3660e9ab8",
99+
"startTime": "2024-02-28 11:21:11.105000+01:00",
100+
"title": "what is a cat?",
101+
"messages": [
102+
{
103+
"body": "There's no single right answer as to whether a cat or dog is better as a pet - it depends on individual preferences and lifestyle. Here are a few factors to consider when deciding: \n\n- Care requirements - Dogs generally need more exercise and attention than cats. Cats can be left alone for longer periods. \n\n- Living space - Dogs need more room to play and exercise. Cats are more adaptable to small living spaces. \n\n- Affection levels - Dogs are often more interactive and eager to please. Cats can be more independent but will seek attention on their terms. \n\n- Allergies - Dogs tend to cause more pet dander allergies than cats. Hypoallergenic breeds exist for both. \n\n- Training - Dogs are more trainable but require consistency. Cats don't always respond to commands but can be litter trained. \n\n- Costs - Dogs often have higher food, medical and supplies costs over their lifetime. But upfront costs are similar. \n\n- Personality match - Consider your lifestyle and whether you prefer an energetic canine companion or a more solitary feline friend. \n\nI'd recommend considering your needs, researching breeds, and seeing how different pets interact in shelters before deciding. Both cats and dogs can make wonderful pets for the right owners.",
104+
"messageId": "c5103006-ada3-4ce1-b240-b1587d1a201b",
105+
"time": "2024-02-28 11:21:28.577000+01:00",
106+
"type": "SYSTEM"
107+
},
108+
{
109+
"attachments": [],
110+
"body": "c:should I prefer a cat or dog?",
111+
"messageId": "776c7117-4ac8-4b85-a4c7-b9ef78bf0050",
112+
"time": "2024-02-28 11:21:21.124000+01:00",
113+
"type": "USER"
114+
},
115+
{
116+
"body": "A dog is a domesticated carnivorous mammal. It is commonly kept as a household pet and comes in a variety of sizes, coat colors and patterns. Dogs have sharp teeth, keen senses of smell and hearing, and a strong sense of loyalty to their human owners. They are trainable animals that can be taught basic commands and tasks. Dogs communicate through body language, vocalizations like barking and whining, and facial expressions. They seek affection from humans and enjoy activities like walking, playing fetch and going to the park. Dogs make devoted companions while also serving important roles like assistance, protection, detection and rescue work.",
117+
"messageId": "e231cb45-1aa4-46a2-a86d-91f8f4723987",
118+
"time": "2024-02-28 11:21:20.787000+01:00",
119+
"type": "SYSTEM"
120+
},
121+
{
122+
"attachments": [],
123+
"body": "c:what is a dog?",
124+
"messageId": "d7a340ce-dcf1-4e1d-9f87-9234078b778d",
125+
"time": "2024-02-28 11:21:16.386000+01:00",
126+
"type": "USER"
127+
},
128+
{
129+
"body": "A cat is a small domesticated carnivorous mammal. It is commonly kept as a household pet and comes in a variety of sizes, coat colors and patterns. Cats have sharp retractable claws, keen eyesight in low light and a strong sense of smell. They are agile hunters known for catching mice and other small animals. Cats communicate through vocalizations like meowing, purring and hissing. They are intelligent, playful animals that seek affection from their human owners. Cats make loving companions while also helping control rodent populations in homes and farms.",
130+
"messageId": "7e72e6bb-237b-4235-8f37-90ce9c180ea8",
131+
"time": "2024-02-28 11:21:15.977000+01:00",
132+
"type": "SYSTEM"
133+
},
134+
{
135+
"attachments": [],
136+
"body": "what is a cat?",
137+
"messageId": "8799e878-4005-4f7b-b65c-44c25a27f25c",
138+
"time": "2024-02-28 11:21:11.105000+01:00",
139+
"type": "USER"
140+
}
141+
]
142+
},
143+
{
144+
"conversationId": "e5bbba10-d5b9-42c2-bb11-f3112e62a56c",
145+
"startTime": "2024-02-28 11:21:28.950000+01:00",
146+
"title": "what is Amazon?",
147+
"messages": [
148+
{
149+
"body": "Amazon is an American multinational technology company based in Seattle, Washington, that focuses on e-commerce, cloud computing, digital streaming, and artificial intelligence. It is one of the Big Five companies in the U.S. information technology industry, along with Google, Apple, Microsoft, and Facebook. Amazon was founded by Jeff Bezos in 1994 and started as an online marketplace for books but has since expanded to sell a wide variety of products and services primarily through its Amazon.com and Amazon Prime subscription programs. Amazon is also a major provider of cloud computing services through Amazon Web Services, which powers many large websites and applications.",
150+
"messageId": "ba7536b6-0f89-441f-b080-12edf134b98e",
151+
"time": "2024-02-28 11:21:33.135000+01:00",
152+
"type": "SYSTEM"
153+
},
154+
{
155+
"attachments": [],
156+
"body": "what is Amazon?",
157+
"messageId": "139477bf-2fe0-4d94-93d0-e837a1e4d171",
158+
"time": "2024-02-28 11:21:28.950000+01:00",
159+
"type": "USER"
160+
}
161+
]
162+
}
163+
]
164+
```
165+
### Help and Security
166+
167+
To properly set up the security definitions in AWS account for use of this script, see [README](/)
168+
169+
```
170+
% python3 q_chat.py -h
171+
usage: q_chat.py [-h] [-a APP_ID] [-u USR_ID] [-p PROMPT] [-f FILE] [-c CNV_ID] [-m MSG_ID] [-d] [-v]
172+
173+
ask a question to a Q application and get answer
174+
175+
options:
176+
-h, --help show this help message and exit
177+
-a APP_ID, --app_id APP_ID
178+
Q application id
179+
-u USR_ID, --usr_id USR_ID
180+
Q index id
181+
-p PROMPT, --prompt PROMPT
182+
question prompt or path to file with list of prompts
183+
-f FILE, --file FILE path to attachment file
184+
-c CNV_ID, --cnv_id CNV_ID
185+
Q conversation id (only to continue an existing conversation)
186+
-m MSG_ID, --msg_id MSG_ID
187+
Q parent message id (only to continue an existing conversation)
188+
-d, --details full conversation details
189+
-v, --verbose verbose mode
71190
```

0 commit comments

Comments
 (0)