From 95eecf9171307f7d02f5a4727fcd62e3e9af213c Mon Sep 17 00:00:00 2001
From: Ian Redpath <iredpath@basistech.com>
Date: Mon, 30 Jul 2018 16:50:02 -0400
Subject: [PATCH 1/7] RD-2360 deprecate numCategories, add singleLabel,
 scoreThreshold options for categories, add raw score to tcat response object

---
 .../rosette/apimodel/CategoriesOptions.java   | 11 ++++++
 .../rosette/apimodel/CategoriesResponse.java  |  2 +-
 .../rosette/apimodel/CategoryLabel.java       | 39 +++++++++++++++++++
 .../rosette/apimodel/SentimentResponse.java   |  2 +-
 4 files changed, 52 insertions(+), 2 deletions(-)
 create mode 100644 model/src/main/java/com/basistech/rosette/apimodel/CategoryLabel.java

diff --git a/model/src/main/java/com/basistech/rosette/apimodel/CategoriesOptions.java b/model/src/main/java/com/basistech/rosette/apimodel/CategoriesOptions.java
index 52659b503..9aae1d79b 100644
--- a/model/src/main/java/com/basistech/rosette/apimodel/CategoriesOptions.java
+++ b/model/src/main/java/com/basistech/rosette/apimodel/CategoriesOptions.java
@@ -31,8 +31,19 @@
 public class CategoriesOptions extends Options {
 
     /**
+     * @deprecated
      * @return number of categories
      */
     @Min(1)
     private final Integer numCategories;
+
+    /**
+     * @return whether or not we are in single label mode
+     */
+    private final boolean singleLabel;
+
+    /**
+     * @return the score threshold
+     */
+    private final Float scoreThreshold;
 }
diff --git a/model/src/main/java/com/basistech/rosette/apimodel/CategoriesResponse.java b/model/src/main/java/com/basistech/rosette/apimodel/CategoriesResponse.java
index 5b7bc2f1e..b7abd9590 100644
--- a/model/src/main/java/com/basistech/rosette/apimodel/CategoriesResponse.java
+++ b/model/src/main/java/com/basistech/rosette/apimodel/CategoriesResponse.java
@@ -35,5 +35,5 @@ public class CategoriesResponse extends Response {
     /**
      * @return a list of categories
      */
-    private final List<Label> categories;
+    private final List<CategoryLabel> categories;
 }
diff --git a/model/src/main/java/com/basistech/rosette/apimodel/CategoryLabel.java b/model/src/main/java/com/basistech/rosette/apimodel/CategoryLabel.java
new file mode 100644
index 000000000..9c6548be3
--- /dev/null
+++ b/model/src/main/java/com/basistech/rosette/apimodel/CategoryLabel.java
@@ -0,0 +1,39 @@
+/******************************************************************************
+ ** This data and information is proprietary to, and a valuable trade secret
+ ** of, Basis Technology Corp.  It is given in confidence by Basis Technology
+ ** and may only be used as permitted under the license agreement under which
+ ** it has been distributed, and in no other way.
+ **
+ ** Copyright (c) 2017 Basis Technology Corporation All rights reserved.
+ **
+ ** The technical data and information provided herein are provided with
+ ** `limited rights', and the computer software provided herein is provided
+ ** with `restricted rights' as those terms are defined in DAR and ASPR
+ ** 7-104.9(a).
+ ******************************************************************************/
+package com.basistech.rosette.apimodel;
+
+import com.basistech.rosette.annotations.JacksonMixin;
+import lombok.Builder;
+import lombok.Value;
+
+@Value
+@Builder
+@JacksonMixin
+public class CategoryLabel {
+
+    /**
+     * @return the label.
+     */
+    private final String label;
+
+    /**
+     * @return the confidence score  (0.0-1.0)
+     */
+    private final Double confidence;
+
+    /**
+     * @return the raw score (-INF-INF)
+     */
+    private final Double score;
+}
diff --git a/model/src/main/java/com/basistech/rosette/apimodel/SentimentResponse.java b/model/src/main/java/com/basistech/rosette/apimodel/SentimentResponse.java
index bf4ae3cf5..c070bce1d 100644
--- a/model/src/main/java/com/basistech/rosette/apimodel/SentimentResponse.java
+++ b/model/src/main/java/com/basistech/rosette/apimodel/SentimentResponse.java
@@ -30,7 +30,7 @@
 @EqualsAndHashCode
 @Builder
 @JacksonMixin
-public  class SentimentResponse extends Response {
+public class SentimentResponse extends Response {
 
     /**
      * @return the whole-document sentiment.

From 0f8172c416ee31b880d6099c8ba9265666f6a7e4 Mon Sep 17 00:00:00 2001
From: Ian Redpath <iredpath@basistech.com>
Date: Tue, 31 Jul 2018 09:07:01 -0400
Subject: [PATCH 2/7] RD-2360 flesh out javadoc

---
 .../com/basistech/rosette/apimodel/CategoriesOptions.java   | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/model/src/main/java/com/basistech/rosette/apimodel/CategoriesOptions.java b/model/src/main/java/com/basistech/rosette/apimodel/CategoriesOptions.java
index 9aae1d79b..60a08aac8 100644
--- a/model/src/main/java/com/basistech/rosette/apimodel/CategoriesOptions.java
+++ b/model/src/main/java/com/basistech/rosette/apimodel/CategoriesOptions.java
@@ -32,17 +32,23 @@ public class CategoriesOptions extends Options {
 
     /**
      * @deprecated
+     * users should use {@link singleLabel} to return only one result
+     * or {@link scoreThreshold} to filter results based on raw score
      * @return number of categories
      */
     @Min(1)
     private final Integer numCategories;
 
     /**
+     * Single label mode will return only the highest scoring category
+     * instead of all categories with a positive score
      * @return whether or not we are in single label mode
      */
     private final boolean singleLabel;
 
     /**
+     * threshold against the category's raw score, whose value
+     * can be any real number.
      * @return the score threshold
      */
     private final Float scoreThreshold;

From c3162e89d9e11dd0837096f6f143ce0c04054b1b Mon Sep 17 00:00:00 2001
From: Ian Redpath <iredpath@basistech.com>
Date: Tue, 31 Jul 2018 09:14:18 -0400
Subject: [PATCH 3/7] RD-2360 fix header comment

---
 .../rosette/apimodel/CategoryLabel.java       | 28 ++++++++++---------
 1 file changed, 15 insertions(+), 13 deletions(-)

diff --git a/model/src/main/java/com/basistech/rosette/apimodel/CategoryLabel.java b/model/src/main/java/com/basistech/rosette/apimodel/CategoryLabel.java
index 9c6548be3..61badbbe4 100644
--- a/model/src/main/java/com/basistech/rosette/apimodel/CategoryLabel.java
+++ b/model/src/main/java/com/basistech/rosette/apimodel/CategoryLabel.java
@@ -1,16 +1,18 @@
-/******************************************************************************
- ** This data and information is proprietary to, and a valuable trade secret
- ** of, Basis Technology Corp.  It is given in confidence by Basis Technology
- ** and may only be used as permitted under the license agreement under which
- ** it has been distributed, and in no other way.
- **
- ** Copyright (c) 2017 Basis Technology Corporation All rights reserved.
- **
- ** The technical data and information provided herein are provided with
- ** `limited rights', and the computer software provided herein is provided
- ** with `restricted rights' as those terms are defined in DAR and ASPR
- ** 7-104.9(a).
- ******************************************************************************/
+/*
+* 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;

From ef6fe16b760d89c6be464099991d783f341026e2 Mon Sep 17 00:00:00 2001
From: Ian Redpath <iredpath@basistech.com>
Date: Tue, 31 Jul 2018 16:09:23 -0400
Subject: [PATCH 4/7] RD-2360 slight javadoc change to not mention
 tcat-specific defaults

---
 .../java/com/basistech/rosette/apimodel/CategoriesOptions.java   | 1 -
 1 file changed, 1 deletion(-)

diff --git a/model/src/main/java/com/basistech/rosette/apimodel/CategoriesOptions.java b/model/src/main/java/com/basistech/rosette/apimodel/CategoriesOptions.java
index 60a08aac8..bf396ee5f 100644
--- a/model/src/main/java/com/basistech/rosette/apimodel/CategoriesOptions.java
+++ b/model/src/main/java/com/basistech/rosette/apimodel/CategoriesOptions.java
@@ -41,7 +41,6 @@ public class CategoriesOptions extends Options {
 
     /**
      * Single label mode will return only the highest scoring category
-     * instead of all categories with a positive score
      * @return whether or not we are in single label mode
      */
     private final boolean singleLabel;

From c9f20d2e47280a25976ebcea2b463efac7ded3ed Mon Sep 17 00:00:00 2001
From: Ian Redpath <iredpath@basistech.com>
Date: Tue, 31 Jul 2018 16:31:19 -0400
Subject: [PATCH 5/7] RD-2360 boolean -> Boolean

---
 .../java/com/basistech/rosette/apimodel/CategoriesOptions.java  | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/model/src/main/java/com/basistech/rosette/apimodel/CategoriesOptions.java b/model/src/main/java/com/basistech/rosette/apimodel/CategoriesOptions.java
index bf396ee5f..fd60a8840 100644
--- a/model/src/main/java/com/basistech/rosette/apimodel/CategoriesOptions.java
+++ b/model/src/main/java/com/basistech/rosette/apimodel/CategoriesOptions.java
@@ -43,7 +43,7 @@ public class CategoriesOptions extends Options {
      * Single label mode will return only the highest scoring category
      * @return whether or not we are in single label mode
      */
-    private final boolean singleLabel;
+    private final Boolean singleLabel;
 
     /**
      * threshold against the category's raw score, whose value

From b3a92d9b861b0eb0d2fc0e76af782ef15f51f3ff Mon Sep 17 00:00:00 2001
From: Ian Redpath <iredpath@basistech.com>
Date: Tue, 31 Jul 2018 17:09:26 -0400
Subject: [PATCH 6/7] RD-2360 more doc updates

---
 .../com/basistech/rosette/apimodel/CategoriesOptions.java     | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/model/src/main/java/com/basistech/rosette/apimodel/CategoriesOptions.java b/model/src/main/java/com/basistech/rosette/apimodel/CategoriesOptions.java
index fd60a8840..d24f9ae3b 100644
--- a/model/src/main/java/com/basistech/rosette/apimodel/CategoriesOptions.java
+++ b/model/src/main/java/com/basistech/rosette/apimodel/CategoriesOptions.java
@@ -32,7 +32,7 @@ public class CategoriesOptions extends Options {
 
     /**
      * @deprecated
-     * users should use {@link singleLabel} to return only one result
+     * Users should use {@link singleLabel} to return only one result
      * or {@link scoreThreshold} to filter results based on raw score
      * @return number of categories
      */
@@ -41,6 +41,8 @@ public class CategoriesOptions extends Options {
 
     /**
      * Single label mode will return only the highest scoring category
+     * If singleLabel is false, every category whose score exceeds the default
+     * (or specified) {@link scoreThreshold} value will be returned
      * @return whether or not we are in single label mode
      */
     private final Boolean singleLabel;

From d5dce1bd87bc1ff1744c80923f9f40d2d1a76410 Mon Sep 17 00:00:00 2001
From: Ian Redpath <iredpath@basistech.com>
Date: Thu, 2 Aug 2018 11:01:50 -0400
Subject: [PATCH 7/7] RD-2360 clarification on singleLabel

---
 .../java/com/basistech/rosette/apimodel/CategoriesOptions.java  | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/model/src/main/java/com/basistech/rosette/apimodel/CategoriesOptions.java b/model/src/main/java/com/basistech/rosette/apimodel/CategoriesOptions.java
index d24f9ae3b..87c5a4e9a 100644
--- a/model/src/main/java/com/basistech/rosette/apimodel/CategoriesOptions.java
+++ b/model/src/main/java/com/basistech/rosette/apimodel/CategoriesOptions.java
@@ -40,7 +40,7 @@ public class CategoriesOptions extends Options {
     private final Integer numCategories;
 
     /**
-     * Single label mode will return only the highest scoring category
+     * Single label mode will return only the highest scoring category, regardless of score
      * If singleLabel is false, every category whose score exceeds the default
      * (or specified) {@link scoreThreshold} value will be returned
      * @return whether or not we are in single label mode