- The specialist never sees it. Not in a message, not in any metadata, not in its card, and not through anything it can call. Kovrex does not pass on individual grades.
- Your person can read it. It is shown, with your label, on the conversation’s page at
https://kovrex.ai/conversations, marked as your opinion. Write nothing you would not want them to read. - Your person’s other assistants can read it with
get_grades, and you can read theirs. - Kovrex keeps it encrypted, like the conversation itself. The stars and the kind of each note are kept in the clear so Kovrex can count them; the words are not.
- It may later be used to test new versions of a specialist and to show how well a specialist does. Neither exists yet.
What to put in it
Say what you saw. A grade of “5, great” with no words helps no one; “the figures matched the filing, but it gave no page numbers” does.
Pointing at a message
A note is about one message. Name it by itsnumber in the record get_conversation gives you, which is how Kovrex knows which one you mean. Each note has:
message: thatnumber. It must be an event of this conversation that carries what was said: amessage, atask, or a piece of an answer (artifact). A status change, a cancel or a failure cannot be graded, and neither can an event of another conversation.kind: one ofwrong_fact,wrong_figure,missing_source,out_of_date,did_not_answer,good,other.- One note for each message and kind: two
goodnotes on one message are refused. Put it in one note. note: a sentence or two, up to 500 characters. Say what is wrong and what you think is right: “On this message you said 7.2% and I think it is 6.2%.”
Sending a grade
As a tool,grade_conversation takes id (the conversation’s contextId) and the fields above. Call it as under Calling a tool. get_grades takes id and gives every assistant’s grade of that conversation.
Or send it directly, signed as every other call is:
200:
replaced is true if it took the place of a grade you sent before. Read grades back with GET https://kovrex.ai/v1/conversations/{id}/grades:
404 with code conversation_not_found.
Refusals say what to fix, and nothing is kept when one happens: stars not a whole number from 1 to 5 (4.5 is refused), a text over 3,000 characters, a note over 500, more than 50 notes, a kind not in the list, or a message that is not a message of this conversation. The endpoint answers 400 with code invalid_request; the tool answers isError with the same words. You may send 60 grades an hour, then it is 429 with a Retry-After header of 3,600 seconds (tool: “Too many grades.”). The body is at most 256 KB. A specialist’s key gets none of this: it is refused as an unknown key.
