Merge pull request #39 from comet-ml/CM-1592-log-asset-folder

[CM-1592] Support for logging of assets folder

Author: yaricom

.github/linters/comet-checkstyle.xml

@@ -29,11 +29,11 @@
         <property name="fileNamePattern" value="module\-info\.java$"/>
     </module>
     <!-- https://checkstyle.org/config_filters.html#SuppressionFilter -->
-    <module name="SuppressionFilter">
-        <property name="file" value="${org.checkstyle.google.suppressionfilter.config}"
-                  default="checkstyle-suppressions.xml" />
-        <property name="optional" value="true"/>
-    </module>
+<!--    <module name="SuppressionFilter">-->
+<!--        <property name="file" value="${org.checkstyle.google.suppressionfilter.config}"-->
+<!--                  default="checkstyle-suppressions.xml" />-->
+<!--        <property name="optional" value="true"/>-->
+<!--    </module>-->
 
     <!-- Checks for whitespace                               -->
     <!-- See http://checkstyle.org/config_whitespace.html -->
@@ -47,7 +47,15 @@
         <property name="ignorePattern" value="^package.*|^import.*|a href|href|http://|https://|ftp://"/>
     </module>
 
+    <module name="SuppressWarningsFilter"/>
+
     <module name="TreeWalker">
+        <module name="SuppressionCommentFilter">
+            <property name="offCommentFormat" value="@cs-\: ([\w\|]+)"/>
+            <property name="checkFormat" value="$1"/>
+        </module>
+        <module name="SuppressWarningsHolder" />
+
         <module name="OuterTypeFilename"/>
         <module name="IllegalTokenText">
             <property name="tokens" value="STRING_LITERAL, CHAR_LITERAL"/>

comet-examples/src/main/java/ml/comet/examples/OnlineExperimentExample.java

@@ -2,8 +2,13 @@
 
 import ml.comet.experiment.ExperimentBuilder;
 import ml.comet.experiment.OnlineExperiment;
+import ml.comet.experiment.context.ExperimentContext;
+import org.apache.commons.io.file.PathUtils;
 
 import java.io.IOException;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.Objects;
 
 import static ml.comet.examples.Utils.getResourceFile;
 import static ml.comet.examples.Utils.readResourceToString;
@@ -22,21 +27,19 @@
  */
 public class OnlineExperimentExample {
 
+    private static final String CHART_IMAGE_FILE = "chart.png";
+    private static final String MODEL_FILE = "model.hd5";
+    private static final String HTML_REPORT_FILE = "report.html";
+    private static final String GRAPH_JSON_FILE = "graph.json";
+    private static final String CODE_FILE = "code_sample.py";
+
     /**
      * The main entry point to the example.
      *
      * @param args the command line arguments if any.
      */
     public static void main(String[] args) {
-        OnlineExperimentExample main = new OnlineExperimentExample();
-        try {
-            main.run();
-        } catch (IOException e) {
-            e.printStackTrace();
-        }
-    }
 
-    private void run() throws IOException {
         //this will take configs from /comet-java-sdk/comet-examples/src/main/resources/application.conf
         //be sure you have set up apiKey, project, workspace in defaults.conf before you start!
 
@@ -48,6 +51,16 @@ private void run() throws IOException {
         //you can use a default builder or just inject params
         //OnlineExperiment experiment = ExperimentBuilder.OnlineExperiment().builder();
 
+        try {
+            OnlineExperimentExample.run(experiment);
+        } catch (IOException e) {
+            e.printStackTrace();
+        } finally {
+            experiment.end();
+        }
+    }
+
+    private static void run(OnlineExperiment experiment) throws IOException {
         experiment.setExperimentName("Java-SDK 2.0.2");
         experiment.nextStep();
 
@@ -68,20 +81,33 @@ private void run() throws IOException {
         experiment.logParameter("batch_size", "500");
         experiment.logParameter("learning_rate", 12);
 
-        experiment.uploadAsset(getResourceFile("chart.png"), "amazing chart.png", false);
-        experiment.uploadAsset(getResourceFile("model.hd5"), false);
+        experiment.uploadAsset(getResourceFile(CHART_IMAGE_FILE), "amazing chart.png", false);
+        experiment.uploadAsset(getResourceFile(MODEL_FILE), false,
+                ExperimentContext.builder().withContext("train").build());
+
+        experiment.nextStep();
+
+        // upload assets from folder
+        Path assetDir = copyResourcesToTmpDir();
+        experiment.logAssetFolder(assetDir.toFile(), true, true);
 
         experiment.logOther("Parameter", 4);
 
         System.out.println("Epoch 1/20");
         System.out.println("- loss: 0.7858 - acc: 0.7759 - val_loss: 0.3416 - val_acc: 0.9026");
 
-        experiment.logGraph(readResourceToString("graph.json"));
+        experiment.logGraph(readResourceToString(GRAPH_JSON_FILE));
+
+        experiment.logCode(getResourceFile(CODE_FILE),
+                ExperimentContext.builder().withContext("test").build());
 
         System.out.println("===== Experiment completed ====");
 
         // will close connection, if not called connection will close on jvm exit
         experiment.end();
+
+        // remove tmp directory
+        PathUtils.deleteDirectory(assetDir);
     }
 
     private static void generateCharts(OnlineExperiment experiment) {
@@ -108,4 +134,20 @@ private static long getUpdatedEpochValue(OnlineExperiment experiment) {
         return experiment.getEpoch() + experiment.getStep() / 5;
     }
 
+    private static Path copyResourcesToTmpDir() throws IOException {
+        Path root = Files.createTempDirectory("onlineExperimentExample");
+        PathUtils.copyFileToDirectory(
+                Objects.requireNonNull(getResourceFile(CHART_IMAGE_FILE)).toPath(), root);
+        PathUtils.copyFileToDirectory(
+                Objects.requireNonNull(getResourceFile(MODEL_FILE)).toPath(), root);
+        Files.createTempFile(root, "empty_file", ".txt");
+
+        Path subDir = Files.createTempDirectory(root, "subDir");
+        PathUtils.copyFileToDirectory(
+                Objects.requireNonNull(getResourceFile(HTML_REPORT_FILE)).toPath(), subDir);
+        PathUtils.copyFileToDirectory(
+                Objects.requireNonNull(getResourceFile(GRAPH_JSON_FILE)).toPath(), subDir);
+
+        return root;
+    }
 }

comet-examples/src/main/resources/code_sample.py

@@ -0,0 +1 @@
+# some code goes here

comet-java-client/pom.xml

@@ -49,6 +49,11 @@
 			<artifactId>commons-lang3</artifactId>
 			<version>3.12.0</version>
 		</dependency>
+		<dependency>
+			<groupId>commons-io</groupId>
+			<artifactId>commons-io</artifactId>
+			<version>2.11.0</version>
+		</dependency>
 		<dependency>
 			<groupId>com.typesafe</groupId>
 			<artifactId>config</artifactId>

comet-java-client/src/main/java/ml/comet/experiment/ApiExperiment.java

@@ -1,24 +1,7 @@
 package ml.comet.experiment;
 
-import lombok.NonNull;
-import lombok.experimental.UtilityClass;
-import ml.comet.experiment.builder.ApiExperimentBuilder;
-import ml.comet.experiment.impl.ApiExperimentImpl;
-
 /**
- * This is stub to support backward compatibility.
- *
- * @deprecated It would be replaced in the future with new experiment creation API.
+ * The {@code ApiExperiment} can be used to synchronously read/update data of your Comet.ml experiment.
  */
-@UtilityClass
-public final class ApiExperiment {
-    /**
-     * Returns builder to create {@link Experiment} instance.
-     *
-     * @param experimentKey the unique identifier of the existing experiment.
-     * @return the initialized ApiExperiment instance.
-     */
-    public static ApiExperimentBuilder builder(@NonNull final String experimentKey) {
-        return ApiExperimentImpl.builder(experimentKey);
-    }
+public interface ApiExperiment extends Experiment {
 }

comet-java-client/src/main/java/ml/comet/experiment/ApiExperimentImpl.java

@@ -0,0 +1,23 @@
+package ml.comet.experiment;
+
+import lombok.NonNull;
+import lombok.experimental.UtilityClass;
+import ml.comet.experiment.builder.ApiExperimentBuilder;
+
+/**
+ * This is stub to support backward compatibility.
+ *
+ * @deprecated It would be replaced in the future with new experiment creation API.
+ */
+@UtilityClass
+public final class ApiExperimentImpl {
+    /**
+     * Returns builder to create {@link Experiment} instance.
+     *
+     * @param experimentKey the unique identifier of the existing experiment.
+     * @return the initialized ApiExperiment instance.
+     */
+    public static ApiExperimentBuilder builder(@NonNull final String experimentKey) {
+        return ml.comet.experiment.impl.ApiExperimentImpl.builder(experimentKey);
+    }
+}

comet-java-client/src/main/java/ml/comet/experiment/Experiment.java

@@ -1,6 +1,7 @@
 package ml.comet.experiment;
 
-import ml.comet.experiment.impl.constants.AssetType;
+import ml.comet.experiment.context.ExperimentContext;
+import ml.comet.experiment.impl.asset.AssetType;
 import ml.comet.experiment.model.ExperimentAssetLink;
 import ml.comet.experiment.model.ExperimentMetadataRest;
 import ml.comet.experiment.model.GitMetadata;
@@ -140,11 +141,22 @@ public interface Experiment {
     /**
      * Send logs to Comet.
      *
-     * @param line   Text to be logged
-     * @param offset Offset describes the place for current text to be inserted
-     * @param stderr the flag to indicate if this is StdErr message.
+     * @param line    Text to be logged
+     * @param offset  Offset describes the place for current text to be inserted
+     * @param stderr  the flag to indicate if this is StdErr message.
+     * @param context the context to be associated with the parameter.
      */
-    void logLine(String line, long offset, boolean stderr);
+    void logLine(String line, long offset, boolean stderr, String context);
+
+    /**
+     * Logs a metric with Comet. For running experiment updates current step to one from param!
+     * Metrics are generally values that change from step to step.
+     *
+     * @param metricName  The name for the metric to be logged
+     * @param metricValue The new value for the metric.  If the values for a metric are plottable we will plot them.
+     * @param context     the context to be associated with the metric.
+     */
+    void logMetric(String metricName, Object metricValue, ExperimentContext context);
 
     /**
      * Logs a metric with Comet. For running experiment updates current step to one from param!
@@ -153,18 +165,27 @@ public interface Experiment {
      * @param metricName  The name for the metric to be logged
      * @param metricValue The new value for the metric.  If the values for a metric are plottable we will plot them
      * @param step        The current step for this metric, this will set the given step for this experiment
-     * @param epoch       The current epoch for this metric, this will set the given epoch for this experiment
+     * @param epoch       The current epoch for this metric, this will set the given epoch for this experiment.
      */
     void logMetric(String metricName, Object metricValue, long step, long epoch);
 
+    /**
+     * Logs a param with Comet. For running experiment updates current step to one from param!
+     * Params should be set at the start of the experiment.
+     *
+     * @param parameterName The name of the param being logged
+     * @param paramValue    The value for the param being logged
+     * @param context       the context to be associated with the parameter.
+     */
+    void logParameter(String parameterName, Object paramValue, ExperimentContext context);
 
     /**
      * Logs a param with Comet. For running experiment updates current step to one from param!
      * Params should be set at the start of the experiment.
      *
      * @param parameterName The name of the param being logged
      * @param paramValue    The value for the param being logged
-     * @param step          The current step for this metric, this will set the given step for this experiment
+     * @param step          The current step for this metric, this will set the given step for this experiment.
      */
     void logParameter(String parameterName, Object paramValue, long step);
 
@@ -214,6 +235,15 @@ public interface Experiment {
      */
     void logEndTime(long endTimeMillis);
 
+    /**
+     * Allows you to report code for the experiment.
+     *
+     * @param code     Code to be sent to Comet
+     * @param fileName Name of source file to be displayed on UI 'code' tab
+     * @param context  the context to be associated with the asset.
+     */
+    void logCode(String code, String fileName, ExperimentContext context);
+
     /**
      * Allows you to report code for the experiment.
      *
@@ -222,6 +252,14 @@ public interface Experiment {
      */
     void logCode(String code, String fileName);
 
+    /**
+     * Allows you to report code for the experiment.
+     *
+     * @param file    Asset with source code to be sent
+     * @param context the context to be associated with the asset.
+     */
+    void logCode(File file, ExperimentContext context);
+
     /**
      * Allows you to report code for the experiment.
      *
@@ -236,11 +274,41 @@ public interface Experiment {
      * @param asset     The asset to be stored
      * @param fileName  The file name under which the asset should be stored in Comet. E.g. "someFile.txt"
      * @param overwrite Whether to overwrite files of the same name in Comet
-     * @param step      the step to be associated with asset
-     * @param epoch     the epoch to be associated with asset
+     * @param context   the context to be associated with the asset.
+     */
+    void uploadAsset(File asset, String fileName, boolean overwrite, ExperimentContext context);
+
+    /**
+     * Upload an asset to be associated with the experiment, for example the trained weights of a neural net.
+     * For running experiment updates current step to one from param!
+     *
+     * @param asset     The asset to be stored
+     * @param fileName  The file name under which the asset should be stored in Comet. E.g. "someFile.txt"
+     * @param overwrite Whether to overwrite files of the same name in Comet
+     * @param step      the step to be associated with the asset
+     * @param epoch     the epoch to be associated with the asset
      */
     void uploadAsset(File asset, String fileName, boolean overwrite, long step, long epoch);
 
+    /**
+     * Upload an asset to be associated with the experiment, for example the trained weights of a neural net.
+     * For running experiment updates current step to one from param!
+     *
+     * @param asset     The file asset to be stored. The name of the file will be used as assets identifier on Comet.
+     * @param overwrite Whether to overwrite files of the same name in Comet
+     * @param context   the context to be associated with the asset.
+     */
+    void uploadAsset(File asset, boolean overwrite, ExperimentContext context);
+
+    /**
+     * Upload an asset to be associated with the experiment, for example the trained weights of a neural net.
+     * For running experiment updates current step to one from param!
+     *
+     * @param asset     The file asset to be stored. The name of the file will be used as assets identifier on Comet.
+     * @param overwrite Whether to overwrite files of the same name in Comet
+     * @param step      the step to be associated with the asset
+     * @param epoch     the epoch to be associated with the asset
+     */
     void uploadAsset(File asset, boolean overwrite, long step, long epoch);
 
     /**

comet-java-client/src/main/java/ml/comet/experiment/ExperimentBuilder.java

@@ -1,7 +1,9 @@
 package ml.comet.experiment;
 
 import lombok.experimental.UtilityClass;
+import ml.comet.experiment.builder.ApiExperimentBuilder;
 import ml.comet.experiment.builder.OnlineExperimentBuilder;
+import ml.comet.experiment.impl.ApiExperimentImpl;
 import ml.comet.experiment.impl.OnlineExperimentImpl;
 
 /**
@@ -23,7 +25,19 @@ public class ExperimentBuilder {
      *
      * @return the instance of the {@link OnlineExperimentBuilder}.
      */
+    @SuppressWarnings({"MethodName"})
     public static OnlineExperimentBuilder OnlineExperiment() {
         return OnlineExperimentImpl.builder();
     }
+
+    /**
+     * The factory to create instance of the {@link ApiExperimentBuilder} which can be used
+     * to configure and create fully initialized instance of the {@link ApiExperiment}.
+     *
+     * @return the initialized instance of the {@link ApiExperimentBuilder}.
+     */
+    @SuppressWarnings({"MethodName"})
+    public static ApiExperimentBuilder ApiExperiment() {
+        return ApiExperimentImpl.builder();
+    }
 }