docs/api/routes/feedback.md

Feedback Routes Documentation

This document describes the API endpoints available for managing user feedback on AI-generated messages in the Auto-Analyst backend.

Base URL

All feedback-related endpoints are prefixed with /feedback.

Endpoints

Create or Update Message Feedback

Creates new feedback or updates existing feedback for a specific message.

Endpoint: POST /feedback/message/{message_id}

Path Parameters:

• message_id: ID of the message to provide feedback for

Request Body:

{
    "rating": 5,                           // Required: Star rating (1-5)
    "model_name": "gpt-4o-mini",          // Optional: Model used for the message
    "model_provider": "openai",           // Optional: Provider of the model
    "temperature": 0.7,                   // Optional: Temperature setting
    "max_tokens": 6000                    // Optional: Max tokens setting
}

Response:

{
    "feedback_id": 123,
    "message_id": 456,
    "rating": 5,
    "feedback_comment": null,
    "model_name": "gpt-4o-mini",
    "model_provider": "openai",
    "temperature": 0.7,
    "max_tokens": 6000,
    "created_at": "2023-05-01T12:00:00Z",
    "updated_at": "2023-05-01T12:00:00Z"
}

Error Responses:

• 404 Not Found: Message with specified ID not found
• 500 Internal Server Error: Failed to create/update feedback

Get Message Feedback

Retrieves feedback for a specific message.

Endpoint: GET /feedback/message/{message_id}

Path Parameters:

• message_id: ID of the message to get feedback for

Response:

{
    "feedback_id": 123,
    "message_id": 456,
    "rating": 5,
    "feedback_comment": null,
    "model_name": "gpt-4o-mini",
    "model_provider": "openai",
    "temperature": 0.7,
    "max_tokens": 6000,
    "created_at": "2023-05-01T12:00:00Z",
    "updated_at": "2023-05-01T12:00:00Z"
}

Error Responses:

• 404 Not Found: No feedback found for the specified message
• 500 Internal Server Error: Failed to retrieve feedback

Get Chat Feedback

Retrieves all feedback for messages in a specific chat.

Endpoint: GET /feedback/chat/{chat_id}

Path Parameters:

• chat_id: ID of the chat to get feedback for

Response:

[
    {
        "feedback_id": 123,
        "message_id": 456,
        "rating": 5,
        "feedback_comment": null,
        "model_name": "gpt-4o-mini",
        "model_provider": "openai",
        "temperature": 0.7,
        "max_tokens": 6000,
        "created_at": "2023-05-01T12:00:00Z",
        "updated_at": "2023-05-01T12:00:00Z"
    }
]

Note: Returns an empty array if no feedback exists for the chat.

Error Responses:

• 500 Internal Server Error: Failed to retrieve chat feedback

Feedback Features

Rating System

• Scale: 1-5 star rating system
• Required: Rating is the only required field for feedback
• Purpose: Allows users to rate the quality of AI responses

Model Context Tracking

The system optionally tracks:

• Model Name: The specific AI model used (e.g., "gpt-4o-mini")
• Model Provider: The provider of the model (e.g., "openai", "anthropic")
• Temperature: The creativity/randomness setting used
• Max Tokens: The maximum response length setting

Update Behavior

• Upsert Operation: The POST endpoint either creates new feedback or updates existing feedback
• Partial Updates: When updating, only provided fields are modified
• Timestamp Tracking: Both creation and update timestamps are maintained

Data Management

Database Operations

• Atomic Operations: Feedback creation/updates are handled in database transactions
• Referential Integrity: Feedback is linked to specific messages via foreign keys
• Soft Handling: Missing optional fields are handled gracefully

Error Handling

• Comprehensive Logging: All operations are logged for debugging
• User-Friendly Messages: Error responses provide clear information
• Transaction Safety: Failed operations are rolled back to maintain data consistency

Usage Patterns

Typical Workflow

1. User receives an AI-generated message
2. User provides rating (1-5 stars) via the frontend
3. Frontend calls POST /feedback/message/{message_id} with rating and model context
4. System stores or updates the feedback
5. Feedback can be retrieved later for analytics or user review

Analytics Integration

Feedback data is used by the analytics system to:

• Track model performance across different configurations
• Identify patterns in user satisfaction
• Generate insights for model optimization