net.myrrix.online.RescorerProvider Maven / Gradle / Ivy
/*
* Copyright Myrrix Ltd
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package net.myrrix.online;
import org.apache.mahout.cf.taste.recommender.IDRescorer;
import org.apache.mahout.cf.taste.recommender.Rescorer;
import org.apache.mahout.common.LongPair;
import net.myrrix.common.MyrrixRecommender;
/**
* Implementations of this interface provide, optionally, objects that can be used to modify and influence
* the results of:
*
*
* - {@link ServerRecommender#recommend(long, int)}
* - {@link ServerRecommender#recommendToMany(long[], int, boolean, IDRescorer)}
* - {@link ServerRecommender#recommendToAnonymous(long[], int, IDRescorer)}
* - {@link ServerRecommender#mostSimilarItems(long, int, Rescorer)}
*
*
* It is a means to inject business logic into the results of {@link ServerRecommender}.
*
* Implementations of this class are factories. An implementation creates and configures an {@link IDRescorer}
* rescoring object and returns it for use in the context of one
* {@link ServerRecommender#recommend(long, int, IDRescorer)} method call. (A {@code Rescorer<LongPair>}
* is used for {@link ServerRecommender#mostSimilarItems(long, int, Rescorer)} since it operates on item ID
* pairs, but is otherwise analogous.) The {@link IDRescorer} then filters the candidates
* recommendations or most similar items by item ID ({@link IDRescorer#isFiltered(long)})
* or modifies the scores of item candidates that are not filtered ({@link IDRescorer#rescore(long, double)})
* based on the item ID and original score.
*
* The factory methods, like {@link #getRecommendRescorer(long[], MyrrixRecommender, String...)}, take optional
* {@code String} arguments. These are passed from the REST API, as a {@code String}, from URL parameter
* {@code rescorerParams}. The implementation may need this information to initialize its rescoring
* logic for the request. For example, the argument may be the user's current location, used to filter
* results by location.
*
* For example, a request containing {@code ...?rescorerParams=xxx,yyy,zzz} will result in an {@code args}
* parameter with one elements, {@code xxx,yyy,zzz}. A request containing
* {@code ...?rescorerParams=xxx&...rescorerParams=yyy&...rescorerParams=zzz...} will result in an
* {@code args} parameter with 3 elements, {@code xxx}, {@code yyy}, {@code zzz}.
*
* @author Sean Owen
* @since 1.0
* @see MultiRescorer
* @see net.myrrix.online.candidate.CandidateFilter
*/
public interface RescorerProvider {
/**
* @param userIDs user(s) for which recommendations are being made, which may be needed in the rescoring logic.
* @param recommender the recommender instance that is rescoring results
* @param args arguments, if any, that should be used when making the {@link IDRescorer}. This is additional
* information from the request that may be necessary to its logic, like current location. What it means
* is up to the implementation.
* @return {@link IDRescorer} to use with {@link ServerRecommender#recommend(long, int, IDRescorer)}
* or {@code null} if none should be used. The resulting {@link IDRescorer} will be passed each candidate
* item ID to {@link IDRescorer#isFiltered(long)}, and each non-filtered candidate with its original score
* to {@link IDRescorer#rescore(long, double)}
*/
IDRescorer getRecommendRescorer(long[] userIDs, MyrrixRecommender recommender, String... args);
/**
* @param itemIDs items that the anonymous user is associated to
* @param recommender the recommender instance that is rescoring results
* @param args arguments, if any, that should be used when making the {@link IDRescorer}. This is additional
* information from the request that may be necessary to its logic, like current location. What it means
* is up to the implementation.
* @return {@link IDRescorer} to use with {@link ServerRecommender#recommendToAnonymous(long[], int, IDRescorer)}
* or {@code null} if none should be used. The resulting {@link IDRescorer} will be passed each candidate
* item ID to {@link IDRescorer#isFiltered(long)}, and each non-filtered candidate with its original score
* to {@link IDRescorer#rescore(long, double)}
*/
IDRescorer getRecommendToAnonymousRescorer(long[] itemIDs, MyrrixRecommender recommender, String... args);
/**
* @param recommender the recommender instance that is rescoring results
* @param args arguments, if any, that should be used when making the {@link IDRescorer}. This is additional
* information from the request that may be necessary to its logic, like current location. What it means
* is up to the implementation.
* @return {@link IDRescorer} to use with {@link ServerRecommender#mostPopularItems(int, IDRescorer)}
* or {@code null} if none should be used.
*/
IDRescorer getMostPopularItemsRescorer(MyrrixRecommender recommender, String... args);
/**
* @param recommender the recommender instance that is rescoring results
* @param args arguments, if any, that should be used when making the {@link IDRescorer}. This is additional
* information from the request that may be necessary to its logic, like current location. What it means
* is up to the implementation.
* @return {@link Rescorer} to use with {@link ServerRecommender#mostSimilarItems(long[], int, Rescorer)}
* or {@code null} if none should be used. The {@link Rescorer} will be passed, to its
* {@link Rescorer#isFiltered(Object)} method, a {@link LongPair} containing the candidate item ID
* as its first element, and the item ID passed in the user query as its second element.
* Each non-filtered {@link LongPair} is passed with its original score to
* {@link Rescorer#rescore(Object, double)}
*/
Rescorer getMostSimilarItemsRescorer(MyrrixRecommender recommender, String... args);
}