From 60ce0b504d2a40bfce613decf54a8108b8589a91 Mon Sep 17 00:00:00 2001
From: rschoene <rene.schoene@tu-dresden.de>
Date: Thu, 2 May 2019 12:44:13 +0200
Subject: [PATCH] Begin with new learner interface.

---
 .../api/MachineLearningDecoder.java           | 28 +++++++++++
 .../api/MachineLearningEncoder.java           | 48 +++++++++++++++++++
 .../api/MachineLearningResult.java            | 25 ++++++++++
 3 files changed, 101 insertions(+)
 create mode 100644 feedbackloop.api/src/main/java/de/tudresden/inf/st/eraser/feedbackloop/api/MachineLearningDecoder.java
 create mode 100644 feedbackloop.api/src/main/java/de/tudresden/inf/st/eraser/feedbackloop/api/MachineLearningEncoder.java
 create mode 100644 feedbackloop.api/src/main/java/de/tudresden/inf/st/eraser/feedbackloop/api/MachineLearningResult.java

diff --git a/feedbackloop.api/src/main/java/de/tudresden/inf/st/eraser/feedbackloop/api/MachineLearningDecoder.java b/feedbackloop.api/src/main/java/de/tudresden/inf/st/eraser/feedbackloop/api/MachineLearningDecoder.java
new file mode 100644
index 00000000..2c29aa28
--- /dev/null
+++ b/feedbackloop.api/src/main/java/de/tudresden/inf/st/eraser/feedbackloop/api/MachineLearningDecoder.java
@@ -0,0 +1,28 @@
+package de.tudresden.inf.st.eraser.feedbackloop.api;
+
+import java.time.Instant;
+
+/**
+ * This interface represents the connection from a machine learning model back to the knowledge base.
+ * It decodes the output of the machine learning model and outputs the result of the classification.
+ *
+ * @author rschoene - Initial contribution
+ */
+@SuppressWarnings("unused")
+public interface MachineLearningDecoder {
+
+  /**
+   * Execute the machine learning model and returns the classification result.
+   * @return the result of the classification
+   */
+  MachineLearningResult classify();
+
+  // less important
+
+  /**
+   * Returns the time when the model was last updated, i.e., when the last training was completed.
+   * @return the time when the model was last updated, or <code>null</code> if the model was not trained yet
+   */
+  Instant lastModelUpdate();
+
+}
diff --git a/feedbackloop.api/src/main/java/de/tudresden/inf/st/eraser/feedbackloop/api/MachineLearningEncoder.java b/feedbackloop.api/src/main/java/de/tudresden/inf/st/eraser/feedbackloop/api/MachineLearningEncoder.java
new file mode 100644
index 00000000..dff85f27
--- /dev/null
+++ b/feedbackloop.api/src/main/java/de/tudresden/inf/st/eraser/feedbackloop/api/MachineLearningEncoder.java
@@ -0,0 +1,48 @@
+package de.tudresden.inf.st.eraser.feedbackloop.api;
+
+import de.tudresden.inf.st.eraser.jastadd.model.Item;
+import de.tudresden.inf.st.eraser.jastadd.model.Root;
+
+import java.util.List;
+
+/**
+ * This interface represents the connection from knowledge base to one machine learning model.
+ * It takes information from the knowledge base, and encodes them to a representation that is readable both for
+ * the used technique and the purpose of the machine learning model.
+ *
+ * @author rschoene - Initial contribution
+ */
+@SuppressWarnings("unused")
+public interface MachineLearningEncoder {
+
+  /**
+   * Update when new data is available.
+   * @param model        The underlying model
+   * @param changedItems A list of items whose state has changed
+   */
+  void newData(Root model, List<Item> changedItems);
+
+  // to be discussed, in which form this is specified
+
+  /**
+   * Get the items that this model is supposed to change.
+   * @return the list of targeted items
+   */
+  List<Item> getTargets();
+
+  // to be discussed, in which form this is specified
+
+  /**
+   * Get the items which are relevant for the decision making of this model.
+   * @return the list of items relevant for decision making
+   */
+  List<Item> getRelevantItems();
+
+  // to be discussed, if this is necessary
+
+  /**
+   * Explicit hint for this model to start/trigger training. The model might ignore this hint.
+   */
+  void triggerTraining();
+
+}
diff --git a/feedbackloop.api/src/main/java/de/tudresden/inf/st/eraser/feedbackloop/api/MachineLearningResult.java b/feedbackloop.api/src/main/java/de/tudresden/inf/st/eraser/feedbackloop/api/MachineLearningResult.java
new file mode 100644
index 00000000..d57ccc81
--- /dev/null
+++ b/feedbackloop.api/src/main/java/de/tudresden/inf/st/eraser/feedbackloop/api/MachineLearningResult.java
@@ -0,0 +1,25 @@
+package de.tudresden.inf.st.eraser.feedbackloop.api;
+
+import de.tudresden.inf.st.eraser.jastadd.model.ItemPreference;
+
+import java.util.List;
+
+/**
+ * Representation of a classification result using a MachineLearningModel.
+ *
+ * @author rschoene - Initial contribution
+ */
+@SuppressWarnings("unused")
+public interface MachineLearningResult {
+
+  // Object rawClass();
+
+  // double rawConfidence();
+
+  // can be used for both activity and preferences
+  /**
+   * Get the result as a list of item preferences, i.e., new states to be set for those items.
+   * @return the classification result as item preferences
+   */
+  List<ItemPreference> getPreferences();
+}
-- 
GitLab