Skip to content

annotate

annotate asks several named questions about every line of its input at once. Each question uses one of the other functions, such as decide, choose or score, and annotate prints the line's number and then each answer as name=answer.

Terminal window
thinkthen annotate questions.json messages.txt

Output

1	refund=true	topic=billing	urgency=0.05
2	refund=false	topic=shipping	urgency=0.14
3	refund=true	topic=billing	urgency=0.45

Each line holds three answers: whether the message asks for a refund, what it is about, and how urgent it is from 0 to 1. The questions live in a file. Each has a name, a function, and that function's question and choices or levels:

questions.json
questions.json
{
"questions": {
"refund": {
"function": "decide",
"question": "Does the customer request a refund?"
},
"topic": {
"function": "choose",
"question": "What is the message about?",
"choices": ["billing", "shipping", "other"]
},
"urgency": {
"function": "score",
"question": "How urgent is the request?",
"levels": ["routine", "urgent"]
}
}
}
messages.txt
Please refund my order.
Where is my parcel?
I was charged twice for one invoice.

A question in the file takes the same bars as its function. Here the refund question gets a low bar of 0.2 and a high bar of 0.8:

questions.json
{
"questions": {
"refund": {
"function": "decide",
"question": "Does the customer request a refund?",
"threshold": {"low": 0.2, "high": 0.8}
},
"topic": {
"function": "choose",
"question": "What is the message about?",
"choices": ["billing", "shipping", "other"]
},
"urgency": {
"function": "score",
"question": "How urgent is the request?",
"levels": ["routine", "urgent"]
}
}
}
Terminal window
thinkthen annotate questions.json messages.txt

Output

1	refund=true	topic=billing	urgency=0.05
2	refund=false	topic=shipping	urgency=0.14
3	refund=unsure	topic=billing	urgency=0.45

Line 3, the double charge, is not sure on refund, while its other answers stand. Send not sure to a person. Never treat it as a no.

See why

--json prints the details of every answer. This jq keeps two for the refund question.

Terminal window
thinkthen annotate --json questions.json messages.txt |
jq -c '.answer.refund | {status, probability}'

Output

{"status":"answered","probability":0.99}
{"status":"answered","probability":0.03}
{"status":"unsure","probability":0.7}

The double charge has 0.7, between the bars, so its refund answer is not sure. JSON output lists every field.

Add an answer column for each question to a CSV file

Section titled “Add an answer column for each question to a CSV file”
Add an answer column for each question to a CSV file
questions.json
{
"field": "/text",
"questions": {
"refund": {
"function": "decide",
"question": "Does the customer request a refund?"
},
"topic": {
"function": "choose",
"question": "What is the message about?",
"choices": ["billing", "shipping", "other"]
},
"urgency": {
"function": "score",
"question": "How urgent is the request?",
"levels": ["routine", "urgent"]
}
}
}
messages.csv
id,text
a1,Please refund my order.
a2,Where is my parcel?
a3,I was charged twice for one invoice.
Terminal window
thinkthen annotate --column text \
--from csv questions.json < messages.csv

Output

id,text,refund,topic,urgency
a1,Please refund my order.,TRUE,billing,0.05
a2,Where is my parcel?,FALSE,shipping,0.14
a3,I was charged twice for one invoice.,TRUE,billing,0.45

--column names the column to read. annotate adds one column per question, named after it. File types covers TSV, Excel and other files, and Toolboxes covers the questions file.

Options
OptionWhat it does
<TOOLBOX>Toolbox path or saved entry name
[FILE]...Input files; default: standard input
--name <NAME>Optional execution identity
--text <TEXT>Judge this text instead of reading input
--column <COLUMN>Field column; repeat; replaces a saved pointer
--details [=<DETAILS>]Add status, probability, error, detail and source columns
--in-place [=<IN-PLACE>]Replace source with backup
--into <INTO>Answer field for JSON Lines; column for tables
--output <OUTPUT>Destination path
--sheet <SHEET>Worksheet

Shared options

If annotate can't answer a line, it prints an error and exits with code 2, 4, 5 or 6. Troubleshooting lists each error and its fix.

In code: Python · TypeScript · Go · Java · Kotlin · C# · R · Ruby · Rust · Swift · Zig · C · C++ · DuckDB · SQLite · PostgreSQL

Next: Triage a support inbox puts these answers to work on a whole inbox.