RD-2370: TVEC updates (#130)

* RD-2370: Update API model to support per-token embeddings

* RD-2370: Rename option

* RD-2370: Update TVEC example

* RD-2370: Fix copyright notice on TextEmbeddingOptions

* RD-2370: Clarify documentation

Author: peblair

examples/src/main/java/com/basistech/rosette/examples/TextEmbeddingExample.java

@@ -17,6 +17,7 @@
 
 import com.basistech.rosette.api.HttpRosetteAPI;
 import com.basistech.rosette.apimodel.DocumentRequest;
+import com.basistech.rosette.apimodel.TextEmbeddingOptions;
 import com.basistech.rosette.apimodel.TextEmbeddingResponse;
 
 import java.io.IOException;
@@ -44,7 +45,9 @@ private void run() throws IOException {
         //The api object creates an http client, but to provide your own:
         //api.httpClient(CloseableHttpClient)
         // When no options, use <?>.
-        DocumentRequest<?> request = DocumentRequest.builder().content(embeddingsData).build();
+        DocumentRequest<TextEmbeddingOptions> request = DocumentRequest.<TextEmbeddingOptions>builder()
+            .content(embeddingsData)
+            .build();
         TextEmbeddingResponse response = rosetteApi.perform(HttpRosetteAPI.TEXT_EMBEDDING_SERVICE_PATH, request, TextEmbeddingResponse.class);
         System.out.println(responseToJson(response));
     }

model/src/main/java/com/basistech/rosette/apimodel/TextEmbeddingOptions.java

@@ -0,0 +1,35 @@
+/*
+* Copyright 2018 Basis Technology Corp.
+*
+* 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 com.basistech.rosette.apimodel;
+
+import com.basistech.rosette.annotations.JacksonMixin;
+import lombok.Builder;
+import lombok.Value;
+
+/**
+ * Text embedding options
+ */
+@Value
+@Builder
+@JacksonMixin
+public class TextEmbeddingOptions extends Options {
+
+    /**
+     * @return whether embeddings should be returned for each token in addition to the whole document
+     */
+    private Boolean perToken;
+
+}

model/src/main/java/com/basistech/rosette/apimodel/TextEmbeddingResponse.java

@@ -33,7 +33,17 @@
 public class TextEmbeddingResponse extends Response {
 
     /**
-     * @return the embedding vector as a list
+     * @return the document embedding vector as a list
      */
-    private final List<Double> embedding;
+    private final List<Double> documentEmbedding;
+
+    /**
+     * @return list of tokens, or {@code null}
+     */
+    private final List<String> tokens;
+
+    /**
+     * @return list of per-token embeddings, 1:1 with tokens, or {@code null}
+     */
+    private final List<List<Double>> tokenEmbeddings;
 }