feat(chat): 👍/👎 feedback on assistant messages — closes chat↔eval loop

Foundation for the closed feedback loop the system has been missing.
Every assistant message can now be rated by the viewer; the rating
lives on the chat_messages row itself (rating: -1/0/+1 +
rating_comment). When user-auth lands this can move to a join table
without changing the API surface — the rating semantic is the same
either way.

Migration 033 adds two nullable-on-display, non-null-on-storage
columns. ORM model updated. ChatMessageResponse exposes the rating so
already-rated messages show their state when conversation history
loads.

API: PUT /chat/conversations/{cid}/messages/{mid}/rating accepts
{rating: -1|0|1, comment?: str}. Setting rating to 0 also clears the
comment (so the two never disagree). Validates the message belongs to
the conversation; bumps conversation.updated_at so sort order
reflects the activity.

UI: small 👍 / 👎 buttons in the assistant message header, next to
Copy and Delete. Click toggles the rating (clicking the active one
clears it). Optimistic local update so the click feels instant; on
API failure we revert and show a toast. Buttons only appear for
assistant messages — user messages stay clean.

This commit deliberately stops at "rating is captured and visible".
The next step (promoting +1 messages into qa_eval gold samples and
surfacing -1 ones for admin review) is a separate piece that can
work on whatever feedback accumulates here.

Author: loglux

app/api/v1/chat.py

@@ -26,6 +26,7 @@
     ConversationSettings,
     ConversationSummary,
     ConversationTitleUpdate,
+    MessageRatingUpdate,
     SourceChunk,
 )
 from app.services.chat_titles import build_conversation_title
@@ -764,6 +765,8 @@ async def get_conversation_messages(
                 model=msg.model,
                 use_self_check=msg.use_self_check,
                 prompt_version_id=msg.prompt_version_id,
+                rating=msg.rating,
+                rating_comment=msg.rating_comment,
                 timestamp=msg.created_at,
                 message_index=msg.message_index,
             )
@@ -772,6 +775,77 @@ async def get_conversation_messages(
     return response_messages
 
 
+@router.put(
+    "/conversations/{conversation_id}/messages/{message_id}/rating",
+    response_model=ChatMessageResponse,
+)
+async def set_message_rating(
+    conversation_id: UUID,
+    message_id: UUID,
+    payload: MessageRatingUpdate,
+    db: AsyncSession = Depends(get_db),
+    user_id: Optional[UUID] = Depends(get_current_user_id),
+):
+    """
+    Set or clear a 👍/👎 rating on a stored chat message.
+
+    Ratings are the chat → eval bridge: thumbs-up messages can later be
+    promoted into the qa_eval gold corpus and thumbs-down ones surfaced
+    for review. A rating of 0 clears any previous rating and its comment.
+    User-role messages can also be rated (e.g. to flag a confusing
+    question) — we do not restrict by role here.
+    """
+    convo_query = select(ConversationModel).where(
+        ConversationModel.id == conversation_id,
+        ConversationModel.is_deleted == False,
+    )
+    conversation = (await db.execute(convo_query)).scalar_one_or_none()
+    if not conversation:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Conversation {conversation_id} not found",
+        )
+
+    msg_query = select(ChatMessageModel).where(
+        ChatMessageModel.id == message_id,
+        ChatMessageModel.conversation_id == conversation_id,
+    )
+    message = (await db.execute(msg_query)).scalar_one_or_none()
+    if not message:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Message {message_id} not found",
+        )
+
+    message.rating = payload.rating
+    # Clearing the rating also clears any stale comment so the two
+    # never disagree.
+    message.rating_comment = payload.comment if payload.rating != 0 else None
+    conversation.updated_at = utcnow()
+
+    sources_payload: Optional[list[SourceChunk]] = None
+    if message.sources_json:
+        try:
+            raw_sources = json.loads(message.sources_json)
+            sources_payload = [SourceChunk(**source) for source in raw_sources]
+        except Exception:
+            sources_payload = None
+
+    return ChatMessageResponse(
+        id=message.id,
+        role=message.role,
+        content=message.content,
+        sources=sources_payload,
+        model=message.model,
+        use_self_check=message.use_self_check,
+        prompt_version_id=message.prompt_version_id,
+        rating=message.rating,
+        rating_comment=message.rating_comment,
+        timestamp=message.created_at,
+        message_index=message.message_index,
+    )
+
+
 @router.delete(
     "/conversations/{conversation_id}/messages/{message_id}",
     response_model=ChatDeleteResponse,

app/db/migrations/versions/033_add_message_feedback.py

@@ -0,0 +1,50 @@
+"""Add feedback (thumbs rating + comment) to chat messages.
+
+Closes the chat ↔ eval loop foundation: every assistant message can be
+rated by the viewer, so real-world successful Q&A pairs can later be
+promoted into the qa_eval gold corpus and bad ones flagged for review.
+
+The rating is stored on the message itself rather than in a separate
+table because in the current MVP there is no per-user data — each
+conversation has one effective rater. When multi-user auth lands, this
+can move to a join table without changing the API surface.
+
+Revision ID: 033
+Revises: 032
+Create Date: 2026-05-16
+"""
+
+import sqlalchemy as sa
+from alembic import op
+
+revision = "033"
+down_revision = "032"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "chat_messages",
+        sa.Column(
+            "rating",
+            sa.SmallInteger(),
+            nullable=False,
+            server_default="0",
+            comment="-1 = thumbs down, 0 = no rating, +1 = thumbs up",
+        ),
+    )
+    op.add_column(
+        "chat_messages",
+        sa.Column(
+            "rating_comment",
+            sa.Text(),
+            nullable=True,
+            comment="Optional free-text feedback attached to the rating",
+        ),
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("chat_messages", "rating_comment")
+    op.drop_column("chat_messages", "rating")

app/models/database.py

@@ -407,6 +407,23 @@ class ChatMessage(Base):
     )
     message_index: Mapped[int] = mapped_column(Integer, nullable=False)
 
+    # Feedback signal: -1 thumbs down, 0 unrated, +1 thumbs up. Optional
+    # free-text comment for the rater. Closes the chat ↔ eval loop:
+    # later, +1 rated assistant messages can be promoted into the
+    # qa_samples gold corpus and -1 ones surfaced for review.
+    rating: Mapped[int] = mapped_column(
+        sa.SmallInteger,
+        default=0,
+        nullable=False,
+        server_default="0",
+        comment="-1 = thumbs down, 0 = no rating, +1 = thumbs up",
+    )
+    rating_comment: Mapped[Optional[str]] = mapped_column(
+        Text,
+        nullable=True,
+        comment="Optional free-text feedback attached to the rating",
+    )
+
     created_at: Mapped[datetime] = mapped_column(DateTime, default=utcnow, nullable=False)
 
     conversation: Mapped["Conversation"] = relationship("Conversation", back_populates="messages")

app/models/schemas.py

@@ -454,10 +454,25 @@ class ChatMessageResponse(BaseModel):
         default=None, description="Whether self-check was applied"
     )
     prompt_version_id: Optional[UUID] = Field(default=None, description="Prompt version used")
+    rating: int = Field(default=0, description="-1 thumbs down, 0 unrated, +1 thumbs up")
+    rating_comment: Optional[str] = Field(
+        default=None, description="Optional free-text feedback attached to the rating"
+    )
     timestamp: datetime
     message_index: int
 
 
+class MessageRatingUpdate(BaseModel):
+    """Payload for setting a 👍/👎 rating on a chat message."""
+
+    rating: int = Field(
+        ..., ge=-1, le=1, description="-1 thumbs down, 0 clears rating, +1 thumbs up"
+    )
+    comment: Optional[str] = Field(
+        default=None, max_length=2000, description="Optional free-text feedback (max 2000 chars)"
+    )
+
+
 class ConversationSummary(BaseModel):
     """Conversation list item."""
 

frontend/src/components/chat/MessageBubble.tsx

@@ -11,9 +11,10 @@ interface MessageBubbleProps {
   onDelete?: () => void
   showPromptVersion?: boolean
   sourceAnchorPrefix?: string
+  onRate?: (messageId: string, rating: -1 | 0 | 1) => void | Promise<void>
 }
 
-export function MessageBubble({ message, onDelete, showPromptVersion, sourceAnchorPrefix }: MessageBubbleProps) {
+export function MessageBubble({ message, onDelete, showPromptVersion, sourceAnchorPrefix, onRate }: MessageBubbleProps) {
   const isUser = message.role === 'user'
   const timestamp = new Date(message.timestamp).toLocaleTimeString('en-US', {
     hour: '2-digit',
@@ -100,6 +101,36 @@ export function MessageBubble({ message, onDelete, showPromptVersion, sourceAnch
             <span className="text-xs opacity-50">{timestamp}</span>
           </div>
           <div className="flex items-center gap-2">
+            {!isUser && onRate && message.id && (
+              <>
+                <button
+                  type="button"
+                  onClick={() => onRate(message.id!, message.rating === 1 ? 0 : 1)}
+                  className={`text-base leading-none transition-colors ${
+                    message.rating === 1
+                      ? 'text-emerald-400'
+                      : 'text-gray-500 hover:text-emerald-300'
+                  }`}
+                  aria-label={message.rating === 1 ? 'Clear thumbs up' : 'Thumbs up'}
+                  title="Helpful answer — promote to gold corpus"
+                >
+                  👍
+                </button>
+                <button
+                  type="button"
+                  onClick={() => onRate(message.id!, message.rating === -1 ? 0 : -1)}
+                  className={`text-base leading-none transition-colors ${
+                    message.rating === -1
+                      ? 'text-rose-400'
+                      : 'text-gray-500 hover:text-rose-300'
+                  }`}
+                  aria-label={message.rating === -1 ? 'Clear thumbs down' : 'Thumbs down'}
+                  title="Bad answer — flag for review"
+                >
+                  👎
+                </button>
+              </>
+            )}
             {onDelete && (
               <button
                 type="button"

frontend/src/hooks/useChat.ts

@@ -111,6 +111,8 @@ export function useChat(kbId: string) {
           model: msg.model,
           use_self_check: msg.use_self_check,
           prompt_version_id: msg.prompt_version_id,
+          rating: msg.rating ?? 0,
+          rating_comment: msg.rating_comment ?? null,
         })))
       } catch (e) {
         console.error('Failed to load conversation history:', e)
@@ -356,6 +358,38 @@ export function useChat(kbId: string) {
     }
   }, [refreshConversations])
 
+  const rateMessage = useCallback(
+    async (messageId: string, rating: -1 | 0 | 1) => {
+      if (!conversationId) return
+      // Optimistic local update — the click feels instant and the API call
+      // either confirms or reverts.
+      const previous = messages.find((m) => m.id === messageId)?.rating ?? 0
+      setMessages((prev) =>
+        prev.map((m) => (m.id === messageId ? { ...m, rating } : m))
+      )
+      try {
+        const updated = await apiClient.rateMessage(conversationId, messageId, rating)
+        setMessages((prev) =>
+          prev.map((m) =>
+            m.id === messageId
+              ? { ...m, rating: updated.rating ?? 0, rating_comment: updated.rating_comment ?? null }
+              : m
+          )
+        )
+      } catch (e) {
+        // Revert on failure.
+        setMessages((prev) =>
+          prev.map((m) => (m.id === messageId ? { ...m, rating: previous } : m))
+        )
+        console.error('Failed to set message rating:', e)
+        toast.error('Failed to save rating', {
+          description: e instanceof Error ? e.message : undefined,
+        })
+      }
+    },
+    [conversationId, messages]
+  )
+
   return {
     conversations,
     conversationsLoading,
@@ -369,6 +403,7 @@ export function useChat(kbId: string) {
     deleteConversation,
     renameConversation,
     selectConversation,
+    rateMessage,
     conversationId,
   }
 }

frontend/src/pages/ChatPage.tsx

@@ -146,6 +146,7 @@ export function ChatPage() {
     deleteConversation,
     renameConversation,
     selectConversation,
+    rateMessage,
     conversationId,
   } = useChat(id!)
 
@@ -1100,6 +1101,7 @@ export function ChatPage() {
                           onDelete={handleDelete}
                           showPromptVersion={showPromptVersions}
                           sourceAnchorPrefix={sourceAnchorPrefix}
+                          onRate={rateMessage}
                         />
                       {message.sources && message.sources.length > 0 && (
                         <details className="mt-4 space-y-2">

frontend/src/services/api.ts

@@ -611,6 +611,19 @@ class APIClient {
     return response.data
   }
 
+  async rateMessage(
+    conversationId: string,
+    messageId: string,
+    rating: -1 | 0 | 1,
+    comment?: string | null
+  ): Promise<ChatMessageResponse> {
+    const response = await this.client.put<ChatMessageResponse>(
+      `/chat/conversations/${conversationId}/messages/${messageId}/rating`,
+      { rating, comment: comment ?? null }
+    )
+    return response.data
+  }
+
   async getConversation(conversationId: string): Promise<ConversationDetail> {
     const response = await this.client.get<ConversationDetail>(
       `/chat/conversations/${conversationId}`

frontend/src/types/index.ts

@@ -273,6 +273,8 @@ export interface ChatMessage {
   use_conversation_history?: boolean
   conversation_history_limit?: number
   prompt_version_id?: string | null
+  rating?: number
+  rating_comment?: string | null
 }
 
 export interface SourceChunk {
@@ -404,6 +406,8 @@ export interface ChatMessageResponse {
   model?: string
   use_self_check?: boolean
   prompt_version_id?: string | null
+  rating?: number
+  rating_comment?: string | null
 }
 
 export interface AppSettings {