Track explanation that is generated by LLM when making ratings.. (Could also be done by humans ;-) )

app/controllers/api/v1/books_controller.rb

@@ -9,13 +9,15 @@ class BooksController < Api::ApiController
       before_action :set_book, only: [ :show, :update, :destroy ]
       before_action :check_book, only: [ :show, :update, :destroy ]
 
-      def_param_group :book do
-        param :name, String
-        param :show_rank, [ true, false ]
-        param :support_implicit_judgements, [ true, false ]
-        param :owner_id, Integer
-        param :scorer_id, Integer
-        param :selection_strategy_id, Integer
+      def_param_group :book_params do
+        param :book, Hash, required: true do
+          param :name, String
+          param :show_rank, [ true, false ]
+          param :support_implicit_judgements, [ true, false ]
+          param :owner_id, Integer
+          param :scorer_id, Integer
+          param :selection_strategy_id, Integer
+        end
       end
 
       api :GET, '/api/books',
@@ -84,7 +86,7 @@ def show
       # rubocop:enable Metrics/BlockLength
 
       api :POST, '/api/books', 'Create a new book.'
-      param_group :book
+      param_group :book_params
       def create
         @book = Book.new(book_params)
         team = Team.find_by(id: params[:book][:team_id])
@@ -99,7 +101,7 @@ def create
       api :PUT, '/api/books/:book_id', 'Update a given book.'
       param :id, :number,
             desc: 'The ID of the requested book.', required: true
-      param_group :book
+      param_group :book_params
       def update
         update_params = book_params
         if @book.update update_params

app/controllers/api/v1/cases_controller.rb

@@ -8,10 +8,12 @@ class CasesController < Api::ApiController
       before_action :case_with_all_the_bells_whistles, only: [ :show ]
       before_action :check_case, only: [ :show, :update, :destroy ]
 
-      def_param_group :case do
-        param :case_name, String
-        param :scorer_id, Integer
-        param :archived, [ true, false ]
+      def_param_group :case_params do
+        param :case, Hash, required: true do
+          param :case_name, String
+          param :scorer_id, Integer
+          param :archived, [ true, false ]
+        end
       end
 
       # Spiking out can we make an API public?
@@ -78,7 +80,7 @@ def show
       # rubocop:enable Metrics/AbcSize
 
       api :POST, '/api/cases', 'Create a new case.'
-      param_group :case
+      param_group :case_params
       def create
         @case = current_user.cases.build case_params
 
@@ -95,7 +97,7 @@ def create
       api :PUT, '/api/cases/:case_id', 'Update a given case.'
       param :id, :number,
             desc: 'The ID of the requested case.', required: true
-      param_group :case
+      param_group :case_params
       def update
         update_params = case_params
         update_params[:scorer_id] = Scorer.system_default_scorer.id if default_scorer_removed? update_params

app/controllers/api/v1/judgements_controller.rb

@@ -8,11 +8,25 @@ class JudgementsController < Api::ApiController
       before_action :set_judgement,   only: [ :show, :update, :destroy ]
       before_action :check_judgement, only: [ :show, :update, :destroy ]
 
-      def_param_group :judgement do
-        param :rating, Float
-        param :judge_later, [ true, false ]
-        param :unrateable, [ true, false ]
-        param :user_id, String
+      def_param_group :judgement_params do
+        param :judgement, Hash, required: true do
+          param :user_id, Integer
+          param :rating, Float
+          param :judge_later, [ true, false ]
+          param :unrateable, [ true, false ]
+          param :explanation, String
+        end
+      end
+
+      def_param_group :create_judgement_params do
+        param :judgement, Hash, required: true do
+          param :query_doc_pair_id, Integer
+          param :user_id, Integer
+          param :rating, Float
+          param :judge_later, [ true, false ]
+          param :unrateable, [ true, false ]
+          param :explanation, String
+        end
       end
 
       api :GET, '/api/books/:book_id/judgements',
@@ -38,18 +52,17 @@ def show
       end
 
       # rubocop:disable Metrics/AbcSize
-      api :POST, '/api/books/:book_id/query_doc_pair/:query_doc_pair_id/judgements/', 'Create a new judgement.'
-      param :query_doc_pair_id, :number,
-            desc: 'The ID of the requested query doc pair.', required: true
+      api :POST, '/api/books/:book_id/judgements/', 'Create a new judgement.'
       param :book_id, :number,
             desc: 'The ID of the requested book.', required: true
-      param_group :judgement
+      param_group :create_judgement_params
       def create
         # @judgement = @book.judgements.build judgement_params
         @judgement = @book.judgements.find_or_create_by query_doc_pair_id: params[:judgement][:query_doc_pair_id],
                                                         user_id:           params[:judgement][:user]
 
         @judgement.rating = params[:judgement][:rating] unless params[:judgement][:rating].nil?
+        @judgement.explanation = params[:judgement][:explanation] unless params[:judgement][:explanation].nil?
 
         if params[:judgement][:user_id]
           user = User.find(params[:judgement][:user_id])
@@ -71,7 +84,7 @@ def create
             desc: 'The ID of the requested query doc pair.', required: true
       param :id, :number,
             desc: 'The ID of the requested judgement.', required: true
-      param_group :judgement
+      param_group :judgement_params
       def update
         update_params = judgement_params
         if @judgement.update update_params
@@ -96,7 +109,7 @@ def destroy
       private
 
       def judgement_params
-        params.require(:judgement).permit(:rating, :unrateable, :query_doc_pair_id, :user_id)
+        params.require(:judgement).permit(:rating, :unrateable, :query_doc_pair_id, :user_id, :explanation)
       end
 
       def set_judgement

app/controllers/api/v1/query_doc_pairs_controller.rb

@@ -8,15 +8,17 @@ class QueryDocPairsController < Api::ApiController
       before_action :set_query_doc_pair,   only: [ :show, :update, :destroy ]
       before_action :check_query_doc_pair, only: [ :show, :update, :destroy ]
 
-      def_param_group :query_doc_pair do
-        param :query_text, String
-        param :doc_id, String
-        param :document_fields, String
-        param :information_need, String
-        param :notes, String
-        param :options, String
-        param :position, Integer
-        param :selection_strategy_id, Integer
+      def_param_group :query_doc_pair_params do
+        param :query_doc_pair, Hash, required: true do
+          param :query_text, String
+          param :doc_id, String
+          param :document_fields, String
+          param :information_need, String
+          param :notes, String
+          param :options, String
+          param :position, Integer
+          param :selection_strategy_id, Integer
+        end
       end
 
       api :GET, '/api/books/:book_id/query_doc_pairs',
@@ -30,7 +32,7 @@ def index
       end
 
       api :GET, '/api/books/:book_id/query_doc_pair/:id',
-          'Show the book with the given ID.'
+          'Show the query document pair with the given ID.'
       param :book_id, :number,
             desc: 'The ID of the requested book.', required: true
       param :id, :number,
@@ -39,20 +41,31 @@ def show
         respond_with @query_doc_pair
       end
 
+      api :GET, '/api/books/:book_id/query_doc_pair/to_be_judged/:judge_id',
+          'Mostly randomly selects a query doc pair that needs to be judged, or none if they have all been judged.'
+      param :book_id, :number,
+            desc: 'The ID of the requested book.', required: true
+      param :judge_id, :number,
+            desc: 'The ID of the judge that doing the evaluating.', required: true
+      def to_be_judged
+        judge = User.find(params[:judge_id])
+        @query_doc_pair = SelectionStrategy.random_query_doc_based_on_strategy(@book, judge)
+
+        if @query_doc_pair
+          respond_with @query_doc_pair
+        else
+          head :no_content
+        end
+      end
+
       api :POST, '/api/books/:book_id/query_doc_pair', 'Create a new query document pair.'
       param :book_id, :number,
             desc: 'The ID of the requested book.', required: true
-      param_group :query_doc_pair
+      param_group :query_doc_pair_params
       def create
         @query_doc_pair = @book.query_doc_pairs.find_or_create_by query_text: params[:query_doc_pair][:query_text],
                                                                   doc_id:     params[:query_doc_pair][:doc_id]
 
-        # @query_doc_pair.position = params[:query_doc_pair][:position] unless params[:query_doc_pair][:position].nil?
-        # unless params[:query_doc_pair][:document_fields].nil?
-        #  @query_doc_pair.document_fields = params[:query_doc_pair][:document_fields]
-        # end
-        # if @query_doc_pair.save
-
         update_params = query_doc_pair_params
         if @query_doc_pair.update update_params
           respond_with @query_doc_pair
@@ -66,7 +79,7 @@ def create
             desc: 'The ID of the requested book.', required: true
       param :id, :number,
             desc: 'The ID of the requested query document pair.', required: true
-      param_group :query_doc_pair
+      param_group :query_doc_pair_params
       def update
         update_params = query_doc_pair_params
         if @query_doc_pair.update update_params

app/controllers/api/v1/team_members_controller.rb

@@ -7,6 +7,10 @@ class TeamMembersController < Api::ApiController
       before_action :set_team,          only: [ :index, :create, :destroy, :invite ]
       before_action :check_team,        only: [ :index, :create, :destroy, :invite ]
 
+      def_param_group :invite_user_params do
+        param :id, String, desc: 'Oddly enough this is the email address of the person to invite'
+      end
+
       def index
         @members = @team.members
         respond_with @members
@@ -31,6 +35,8 @@ def create
       end
 
       # rubocop:disable Layout/LineLength
+      api :POST, '/api/teams/:team_id/members/invite', 'Invite someone to join a team.  Creates a shell user account and adds them to the team.'
+      param_group :invite_user_params
       def invite
         unless signup_enabled?
           render json: { error: 'Signups are disabled!' }, status: :not_found

app/controllers/api/v1/users_controller.rb

@@ -5,6 +5,12 @@ module V1
     class UsersController < Api::ApiController
       before_action :set_user, except: [ :index ]
 
+      api :GET, '/api/users',
+          'List the users.'
+      error :code => 401, :desc => 'Unauthorized'
+      param :prefix, String,
+            :desc     => 'Filters down the list to users whose email addresses or name start with the prefix.',
+            :required => false
       def index
         @users = []
         if params[:prefix]
@@ -15,6 +21,10 @@ def index
         respond_with @users
       end
 
+      api :GET, '/api/users/:id',
+          'Show the user with the given ID.'
+      param :id, :number,
+            desc: 'The ID of the requested user.', required: true
       def show
         respond_with @user
       end

app/controllers/judgements_controller.rb

@@ -36,9 +36,10 @@ def new
     if @query_doc_pair.nil? # no more query doc pairs to be judged!
       redirect_to book_path(@book)
     else
-      if @query_doc_pair
-        @query = Query.joins(:case).where(case: { book_id: @query_doc_pair.book.id }).has_information_need.where(query_text: @query_doc_pair.query_text).first
-      end
+      # NO LONGER USED
+      # if @query_doc_pair
+      #   @query = Query.joins(:case).where(case: { book_id: @query_doc_pair.book.id }).has_information_need.where(query_text: @query_doc_pair.query_text).first
+      # end
       @judgement = Judgement.new(query_doc_pair: @query_doc_pair, user: @current_user, updated_at: Time.zone.now)
       @previous_judgement = @judgement.previous_judgement_made # unless @judgement.new_record?
       if (track_judging[:counter] % 50).zero? # It's party time!
@@ -93,6 +94,7 @@ def create
 
   def unrateable
     @judgement = Judgement.find_or_initialize_by(query_doc_pair_id: params[:query_doc_pair_id], user: current_user)
+    @judgement.update(judgement_params)
 
     @judgement.mark_unrateable!
     UpdateCaseRatingsJob.perform_later @judgement.query_doc_pair
@@ -132,6 +134,6 @@ def set_judgement
   end
 
   def judgement_params
-    params.require(:judgement).permit(:user_id, :rating, :query_doc_pair_id, :unrateable)
+    params.require(:judgement).permit(:user_id, :rating, :query_doc_pair_id, :unrateable, :explanation)
   end
 end

app/models/judgement.rb

@@ -5,6 +5,7 @@
 # Table name: judgements
 #
 #  id                :bigint           not null, primary key
+#  explanation       :text(65535)
 #  judge_later       :boolean          default(FALSE)
 #  rating            :float(24)
 #  unrateable        :boolean          default(FALSE)

app/views/api/v1/export/books/_judgements.json.jbuilder

@@ -4,3 +4,4 @@ json.rating         judgement.rating
 json.unrateable     judgement.unrateable
 json.judge_later    judgement.judge_later
 json.user_email     judgement.user.email if judgement.user
+json.explanation    judgement.explanation

app/views/api/v1/judgements/_judgement.json.jbuilder

@@ -5,3 +5,4 @@ json.query_doc_pair_id judgement.query_doc_pair_id
 json.unrateable judgement.unrateable
 json.judge_later judgement.judge_later
 json.user_id judgement.user_id
+json.explanation judgement.explanation

app/views/books/edit.html.erb

@@ -31,7 +31,7 @@
           <h5 class="mb-1">
             <%= check_box('book_ids', book.id, class: 'form-check-input me-1', disabled: book.rated_query_doc_pairs.empty?) %>
             <label for="book_ids_<%= book.id %>" class="form-check-label stretched">
-            <%= book.name %>
+            <%= book_title(book) %>
             </label>
           </h5>
           <label for="book_ids_<%= book.id %>" class="form-check-label stretched">

app/views/books/index.html.erb

@@ -38,7 +38,7 @@
     <% @books.each do |book| %>
       <tr>
         <td><%= book.id %> </td>
-        <td><%= link_to book.name, book_path(book) %></td>
+        <td><%= link_to book_title(book), book_path(book) %></td>
         <td><%= book.teams.pluck(:name).join(',') %></td>
         <td><%= book.scorer.name %> </td>
         <td><%= book.selection_strategy.name %> </td>