MS-764 Replace tiers with confidence bands

build.gradle

@@ -19,9 +19,9 @@ repositories {
     mavenCentral()
 }
 
-project.version = "2025.1.1-SNAPSHOT"
+project.version = "2025.1.2-SNAPSHOT"
 ext {
-    VERSION_CODE = 20250101
+    VERSION_CODE = 20250102
 }
 
 android {

src/main/java/com/simprints/libsimprints/Tier.kt

@@ -1,6 +1,6 @@
 package com.simprints.libsimprints
 
-@Deprecated("Use contracts.data.Tier instead")
+@Deprecated("Replaced by contracts.data.ConfidenceBand")
 enum class Tier {
     TIER_1,
     TIER_2,

src/main/java/com/simprints/libsimprints/contracts/VersionsList.kt

@@ -12,5 +12,5 @@ object VersionsList {
      * The new API uses JSON as marshalling format instead of parcelable to make
      * adding and removing data fields simpler.
      */
-    const val INITIAL_REWORK = 20240801
+    const val INITIAL_REWORK = 20250102
 }

src/main/java/com/simprints/libsimprints/contracts/data/ConfidenceBand.kt

@@ -0,0 +1,17 @@
+package com.simprints.libsimprints.contracts.data
+
+/**
+ * Qualifies how good is the specific confidence score based
+ * on the decision policy in the project configuration.
+ *
+ * HIGH -   highly likely (near 100% confidence) to be a match
+ * MEDIUM - possible match but not 100% likely a match
+ * LOW -    not a match
+ * NONE -   fallback value when matching was not possible
+ */
+enum class ConfidenceBand {
+    HIGH,
+    MEDIUM,
+    LOW,
+    NONE,
+}

src/main/java/com/simprints/libsimprints/contracts/data/Identification.kt

@@ -5,14 +5,14 @@ import org.json.JSONArray
 /**
  * This constructor creates a new identification
  *
- * @param guid       Global unique id of the verified person
- * @param confidence An int containing the (matching) confidence
- * @param tier       The tier score derived from the confidence
+ * @param guid           Global unique id of the verified person
+ * @param confidence     An int containing the (matching) confidence
+ * @param confidenceBand Confidence qualifier based on the project's configuration
  */
 data class Identification(
     val guid: String,
     val confidence: Float,
-    val tier: Tier,
+    val confidenceBand: ConfidenceBand,
 ) : Comparable<Identification> {
     override fun compareTo(other: Identification): Int = when {
         confidence == other.confidence -> 0
@@ -22,22 +22,22 @@ data class Identification(
 
     companion object {
         private const val KEY_GUID = "guid"
-        private const val KEY_TIER = "tier"
         private const val KEY_CONFIDENCE = "confidence"
+        private const val KEY_CONFIDENCE_BAND = "confidenceBand"
 
         fun List<Identification>.toJson(): String = map { id ->
             id.asJsonObject { json ->
                 json.put(KEY_GUID, id.guid)
-                json.put(KEY_TIER, id.tier.name)
+                json.put(KEY_CONFIDENCE_BAND, id.confidenceBand.name)
                 json.put(KEY_CONFIDENCE, id.confidence)
             }
         }.let { JSONArray(it) }.toString()
 
         fun fromJson(jsonString: String): List<Identification>? = fromJsonArrayString(jsonString) { json ->
             val guid = json.getString(KEY_GUID)
-            val tier = json.getString(KEY_TIER).let { Tier.valueOf(it) }
             val confidence = json.getDouble(KEY_CONFIDENCE).toFloat()
-            Identification(guid, confidence, tier)
+            val band = json.getString(KEY_CONFIDENCE_BAND).let { ConfidenceBand.valueOf(it) }
+            Identification(guid, confidence, band)
         }
     }
 }

src/main/java/com/simprints/libsimprints/contracts/data/Verification.kt

@@ -5,34 +5,34 @@ package com.simprints.libsimprints.contracts.data
  *
  * @param guid       Global unique id of the verified person
  * @param confidence An int containing the (matching) confidence
- * @param tier       The tier score derived from the confidence
+ * @param confidenceBand Confidence qualifier based on the project's configuration
  */
 data class Verification(
     val guid: String,
     val confidence: Float,
-    val tier: Tier,
+    val confidenceBand: ConfidenceBand,
     val isSuccess: Boolean,
 ) {
     fun toJson(): String = asJsonObject {
         it.put(KEY_GUID, guid)
-        it.put(KEY_TIER, tier.name)
+        it.put(KEY_CONFIDENCE_BAND, confidenceBand.name)
         it.put(KEY_CONFIDENCE, confidence)
         it.put(KEY_IS_SUCCESS, isSuccess)
     }.toString()
 
     companion object {
         private const val KEY_GUID = "guid"
-        private const val KEY_TIER = "tier"
         private const val KEY_CONFIDENCE = "confidence"
+        private const val KEY_CONFIDENCE_BAND = "confidenceBand"
         private const val KEY_IS_SUCCESS = "isSuccess"
 
         fun fromJson(jsonString: String): Verification? = fromJsonString(jsonString) { json ->
             val guid = json.getString(KEY_GUID)
-            val tier = json.getString(KEY_TIER).let { Tier.valueOf(it) }
             val confidence = json.getDouble(KEY_CONFIDENCE).toFloat()
+            val band = json.getString(KEY_CONFIDENCE_BAND).let { ConfidenceBand.valueOf(it) }
             val isSuccess = json.getBoolean(KEY_IS_SUCCESS)
 
-            Verification(guid, confidence, tier, isSuccess)
+            Verification(guid, confidence, band, isSuccess)
         }
     }
 }

src/test/java/com/simprints/libsimprints/contracts/SimprintsResponseTest.kt

@@ -3,11 +3,11 @@ package com.simprints.libsimprints.contracts
 import android.content.Intent
 import androidx.test.ext.junit.runners.AndroidJUnit4
 import com.simprints.libsimprints.Constants
+import com.simprints.libsimprints.contracts.data.ConfidenceBand
 import com.simprints.libsimprints.contracts.data.Enrolment
 import com.simprints.libsimprints.contracts.data.Identification
 import com.simprints.libsimprints.contracts.data.Identification.Companion.toJson
 import com.simprints.libsimprints.contracts.data.RefusalForm
-import com.simprints.libsimprints.contracts.data.Tier
 import com.simprints.libsimprints.contracts.data.Verification
 import org.junit.Assert.assertEquals
 import org.junit.Assert.assertNotNull
@@ -83,7 +83,7 @@ class SimprintsResponseTest {
     fun `correctly parses identification intent`() {
         val intent = Intent().putExtra(
             Constants.SIMPRINTS_IDENTIFICATIONS,
-            listOf(Identification("guid", 42f, Tier.TIER_1)).toJson(),
+            listOf(Identification("guid", 42f, ConfidenceBand.HIGH)).toJson(),
         )
         val result = SimprintsResponse.fromIntent(intent, Constants.SIMPRINTS_OK)
 
@@ -98,7 +98,7 @@ class SimprintsResponseTest {
     fun `correctly parses verification intent`() {
         val intent = Intent().putExtra(
             Constants.SIMPRINTS_VERIFICATION,
-            Verification("guid", 42f, Tier.TIER_1, true).toJson(),
+            Verification("guid", 42f, ConfidenceBand.HIGH, true).toJson(),
         )
         val result = SimprintsResponse.fromIntent(intent, Constants.SIMPRINTS_OK)
 

src/test/java/com/simprints/libsimprints/contracts/data/IdentificationTest.kt

@@ -11,11 +11,10 @@ class IdentificationTest {
     @Test
     fun `test enrolment parcelling`() {
         val expected = listOf(
-            Identification("case1", 99f, Tier.TIER_1),
-            Identification("case2", 70f, Tier.TIER_2),
-            Identification("case3", 50f, Tier.TIER_3),
-            Identification("case4", 30f, Tier.TIER_4),
-            Identification("case5", 10f, Tier.TIER_5),
+            Identification("case1", 99f, ConfidenceBand.HIGH),
+            Identification("case2", 70f, ConfidenceBand.MEDIUM),
+            Identification("case3", 50f, ConfidenceBand.LOW),
+            Identification("case4", 30f, ConfidenceBand.NONE),
         )
         val actual = Identification.fromJson(expected.toJson())
 

src/test/java/com/simprints/libsimprints/contracts/data/VerificationTest.kt

@@ -9,7 +9,7 @@ import org.junit.runner.RunWith
 class VerificationTest {
     @Test
     fun `test verification parcelling`() {
-        val expected = Verification("case-id", 42f, Tier.TIER_4, false)
+        val expected = Verification("case-id", 42f, ConfidenceBand.HIGH, false)
         val actual = Verification.fromJson(expected.toJson())
 
         Assert.assertEquals(expected, actual)