Feedback and score attribution
Message ratings, human review and automated scores have distinct producers and update paths. Preserve source attribution and reconcile stored results independently of delayed analytics projections.
Message rating and analytics projection
| Property | Contract |
|---|---|
| Eligible messages | Only ROLE_ASSISTANT messages can be rated. |
ratedMessage.feedback | Complete feedback list across raters. |
isUpdate | True when the caller replaced their previous rating on the message. |
| Evaluation projection | Asynchronous ingestion can produce SCORE_SOURCE_USER analytics. This copy can be delayed, absent or stale and is separate from the stored message rating. |
Reading and withdrawing message feedback
| Operation | Feedback behavior |
|---|---|
| Get conversation state | Returns assistant-message feedback with the message history. |
| Send a message | Ignores supplied feedback; it is not a feedback-write path. |
| Rate a message | Creates or replaces the caller's own rating. |
| Delete a message rating | Removes only the caller's entry and preserves other raters. An absent rating is an idempotent success; omitted removed means false. |
Score sources
| Source | Producer or interpretation |
|---|---|
SCORE_SOURCE_USER | Feedback from an end user, projected through the message-rating path. |
SCORE_SOURCE_HUMAN | A human reviewer's annotation. |
SCORE_SOURCE_JUDGE | An automated judge result. |
SCORE_SOURCE_EVAL | A managed evaluator result reported by the evaluation provider. |
SCORE_SOURCE_HARNESS | A harness or other API-based score producer. |
Keep these populations separate when aggregating. Equal numeric scales do not make end-user sentiment, reviewer assessment and automated measurements interchangeable. Use the supported source filter and retain the provider's sourceLabel when exact upstream attribution matters.
Reviewer assessment belongs in the evaluation review path, separate from end-user message feedback and its product behavior. Declared source values alone do not establish that every source is supported for public writes; see supported score writes.
Supported score writes and configuration
| Write concern | Current contract |
|---|---|
| Qualified score values and targets | Use numeric or boolean values on trace targets. Categorical/text values and observation/session/dataset-run writes are not supported by the qualified write path, even though the enum vocabulary names them. |
| Human-review source | Use SCORE_SOURCE_HUMAN. A missing configId for this source returns HTTP 400. Create its score configuration first. |
| Rater attribution | Derived from verified caller context, not a body field. |
| Score configuration retirement | Archive with isArchived; retrieve archived configurations with includeArchived when needed for historical scores. |
The platform derives a score ID from target, rater and score name. Repeat scoring across days is not qualified as replacement of the earlier provider record. Serialize review actions and reconcile the stored result; a stable ID alone does not guarantee duplicate-free ingestion or event ordering.