Tutorial: Collecting user feedback

This tutorial demonstrates how to interact with the feedback system using practical examples. All examples use curl commands, but you can adapt them to your preferred HTTP client or programming language.


Prerequisites

Before you begin, ensure you have: - A valid authentication token for your PhariaAssistant installation. - Admin privileges; these are required for GET and DELETE operations. - Your PhariaAssistant domain URL.

Replace <your.pharia-ai.domain.com> with your actual domain and <YOUR_AUTH_TOKEN> with your authentication token in the examples below.

Creating feedback entries (POST)

The POST endpoint allows any authenticated user to create new feedback entries.

Example 1: Creating a simple rating feedback

curl -X POST "https://pharia-assistant.<your.pharia-ai.domain.com>/api/feedback" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_AUTH_TOKEN>" \
  -d '{
    "trace_id": "123e4567-e89b-12d3-a456-426614174000",
    "app_id": "987fcdeb-51a2-43d1-9f12-345678901234",
    "app_version": "v1.2.0",
    "feedback": {
      "type": "rating",
      "value": 5,
      "comment": "Excellent response quality!"
    }
  }'

Example 2: Creating content feedback with user edits

curl -X POST "https://pharia-assistant.<your.pharia-ai.domain.com>/api/feedback" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_AUTH_TOKEN>" \
  -d '{
    "trace_id": "123e4567-e89b-12d3-a456-426614174000",
    "app_id": "987fcdeb-51a2-43d1-9f12-345678901234",
    "app_version": "v1.2.0",
    "feedback": {
      "type": "content_edit",
      "original_text": "The capital of France is Paris.",
      "edited_text": "The capital of France is Paris, known for its rich history and culture.",
      "edit_reason": "Added more context"
    }
  }'

Response

{
  "feedback_id": "456e7890-f12b-34c5-d678-901234567890"
}

Retrieving feedback entries (GET)

The GET endpoint requires admin permissions and supports filtering options.

Example 1: Retrieve all feedback (limited by system constraints)

curl -X GET "https://pharia-assistant.<your.pharia-ai.domain.com>/api/feedback" \
  -H "Authorization: Bearer <YOUR_ADMIN_TOKEN>"

Example 2: Filter by specific trace ID

curl -X GET "https://pharia-assistant.<your.pharia-ai.domain.com>/api/feedback?trace_id=123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer <YOUR_ADMIN_TOKEN>"

Example 3: Filter by app ID and time range

curl -X GET "https://pharia-assistant.<your.pharia-ai.domain.com>/api/feedback?app_id=987fcdeb-51a2-43d1-9f12-345678901234&start_time=2024-01-01T00:00:00&end_time=2024-12-31T23:59:59" \
  -H "Authorization: Bearer <YOUR_ADMIN_TOKEN>"

Example 4: Retrieve specific feedback entry

curl -X GET "https://pharia-assistant.<your.pharia-ai.domain.com>/api/feedback?feedback_id=456e7890-f12b-34c5-d678-901234567890" \
  -H "Authorization: Bearer <YOUR_ADMIN_TOKEN>"

Response

[
  {
    "feedback_id": "456e7890-f12b-34c5-d678-901234567890",
    "trace_id": "123e4567-e89b-12d3-a456-426614174000",
    "app_id": "987fcdeb-51a2-43d1-9f12-345678901234",
    "creation_date": "2024-01-15T10:30:00.123456",
    "api_version": "v1.0.0",
    "ui_version": "v1.0.0",
    "app_version": "v1.2.0",
    "feedback": {
      "type": "rating",
      "value": 5,
      "comment": "Excellent response quality!"
    }
  }
]

Updating feedback entries (PATCH)

The PATCH endpoint allows any authenticated user to update existing feedback entries.

Example: Update a rating from thumbs up to thumbs down

curl -X PATCH "https://pharia-assistant.<your.pharia-ai.domain.com>/api/feedback/456e7890-f12b-34c5-d678-901234567890" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_AUTH_TOKEN>" \
  -d '{
    "feedback": {
      "type": "rating",
      "value": 1,
      "comment": "Actually, the response was not helpful",
      "updated_reason": "Changed mind after further review"
    }
  }'

Response

{
  "message": "Feedback updated successfully"
}

Deleting feedback entries (DELETE)

The DELETE endpoint requires admin permissions and permanently removes feedback entries.

Example: Delete a specific feedback entry

curl -X DELETE "https://pharia-assistant.<your.pharia-ai.domain.com>/api/feedback/456e7890-f12b-34c5-d678-901234567890" \
  -H "Authorization: Bearer <YOUR_ADMIN_TOKEN>"

Response

{
  "message": "Feedback deleted successfully"
}

Typical use cases

Implementing a rating system

# Initial thumbs up
curl -X POST "https://pharia-assistant.<your.pharia-ai.domain.com>/api/feedback" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_AUTH_TOKEN>" \
  -d '{
    "trace_id": "trace-123",
    "app_id": "app-456",
    "app_version": "v1.0.0",
    "feedback": {"rating": "thumbs_up"}
  }'

# User changes to thumbs down - update the same feedback
curl -X PATCH "https://pharia-assistant.<your.pharia-ai.domain.com>/api/feedback/<feedback_id>" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_AUTH_TOKEN>" \
  -d '{
    "feedback": {"rating": "thumbs_down", "change_reason": "reconsidered"}
  }'

Collecting user edits for RLHF

# Store original AI response
curl -X POST "https://pharia-assistant.<your.pharia-ai.domain.com>/api/feedback" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_AUTH_TOKEN>" \
  -d '{
    "trace_id": "trace-789",
    "app_id": "app-456",
    "app_version": "v1.0.0",
    "feedback": {
      "type": "original_response",
      "content": "AI generated text here..."
    }
  }'

# Store user's edited version
curl -X POST "https://pharia-assistant.<your.pharia-ai.domain.com>/api/feedback" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_AUTH_TOKEN>" \
  -d '{
    "trace_id": "trace-789",
    "app_id": "app-456",
    "app_version": "v1.0.0",
    "feedback": {
      "type": "user_edit",
      "content": "User improved text here...",
      "edit_type": "improvement"
    }
  }'

Error handling

HTTP status codes and their meanings

  • 200: Success

  • 401: Unauthorized - Check your authentication token

  • 404: Feedback not found - Verify the feedback ID exists

  • 413: Too many results - Add more specific filters to your GET request

  • 422: Validation error - Check your request format and required fields

  • 500: Internal server error - Check the API logs

Example validation error response

{
  "detail": [
    {
      "loc": ["body", "trace_id"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}