Feedback API for custom applications

PhariaAssistant provides a comprehensive feedback system to help you collect and manage user feedback for your custom applications. The system includes four REST API endpoints for creating, updating, retrieving, and deleting feedback entries:

• POST /feedback - Create a new feedback entry
• GET /feedback - Retrieve feedback entries based on filter criteria
• DELETE /feedback/{feedback_id} - Remove a feedback entry
• PATCH /feedback/{feedback_id} - Update an existing feedback entry

For detailed API specifications, refer to your Assistant installation's API documentation at https://pharia-assistant.<your.pharia-ai.domain.com>/api/docs.

Note: The GET and DELETE endpoints require Assistant admin permissions.

The feedback system is designed to support multiple feedback entries for the same trace id. For instance, this could allow you to supply multiple types of feedback for the same result:

1. Rating Feedback: Implement a thumbs up/down rating system where:

   • Initial ratings can be created using the POST endpoint
   • Rating changes could then be updated using the PATCH endpoint

2. Content Feedback: Capture both original and edited versions of generated content:

   • Store the original result and any user edits as separate feedback entries
   • This data can be valuable for scenarios like Reinforcement Learning from Human Feedback (RLHF)

By creating separate feedback entries for different types of feedback, you can maintain clear distinctions between various feedback categories while preserving the relationship to the original result.

Tutorial: Using the Feedback API Endpoints

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 (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 various 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"
}

Common Use Cases

1. 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"}
  }'

2. 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"
    }
  ]
}