init

1 files changed, 119 insertions, 0 deletions

diff --git a/docs/specifications.md b/docs/specifications.md
new file mode 100644
index 0000000..ec5c81f
--- /dev/null
+++ b/docs/specifications.md
@@ -0,0 +1,119 @@
+# Check Image Deduplication API
+
+- Draft April 13, 2019  
+- Specs from "VFRAME - SHARED Image Matching - Checkpoint Spec 2019APR.odt"
+
+
+The VFRAME/Check image deduplication API will provide capabilities to determine if a query image matches any of prior submitted query images. 
+
+Functional Requirements:
+
+- provide matching results for at least 10,000 image requests submitted per day
+- provide scalable capacity for sustained usage of at least one year
+- provide an authenticated API service to match a query image to all previously submitted query images and receive a match result
+
+
+## Use Case Scenario
+
+User story:
+- Audience member sends image to a number on WhatsApp (or generically, user adds an image to Check). - Handled by Smooch.
+    • Image is ingested into Check. - Handled by Smooch & Check.
+    • Image is matched against existing images in Check.
+        ◦ MVP:
+            ▪ detect near-identical matches that are different sizes, resolutions.
+        ◦ Assess for feasibility:
+            ▪ find same meme images used for different claims
+            ▪ find same claims using different meme images
+            ▪ find same images (not memes) with different text
+            ▪ find same images + text in different physical files
+    • Image is automatically related to any matching images in Check.
+    • Analyst can confirm matches and dissociate any false matches. - Handled in Check
+    • Audience member receives the verification result for any matching images with existing final-status. - Handled in Check, Smooch, and WA Business API
+    
+    
+## Out of Scope
+
+- Video matching
+- Machine vision or content analysis
+- Indian-language OCR (though OCR models/ libraries should be easily integrated)
+- User-in-the-loop machine learning for improvement of matching algorithms
+    
+    
+
+## Example Requests
+
+Example response for a successful image upload with no match:
+
+`check.vframe.io/v1/match/`
+
+```
+{
+ "success": True,
+ "match": False,
+ "closest_matches":
+ 	[
+ 		{
+ 			"sha256: "cf80cd8aed482d5d1527d7dc72fceff84e6326592848447d2dc0b0e87dfc9a90",
+ 			"score": 2
+ 		},
+ 		{
+ 			"sha256: "156350ca18fa04545c4192432860c7efe9ddba18ea6e40e4da81bb7097a7166f",
+ 			"score": 3
+ 		}
+	]
+"
+```
+ 			 
+
+Example response for a successful image upload with a match:
+
+`check.vframe.io/v1/match/`
+
+```
+{
+ "success": True,
+ "match": True,
+ "match":
+	{
+		"sha256: "eadc688cd557ee351fa9b718e87a6e8dfb9c9fce69e9944c71c0f58f8b972632",
+		"score": 0
+	},
+ "close_matches":
+ 	[
+ 		{
+ 			"sha256: "cf80cd8aed482d5d1527d7dc72fceff84e6326592848447d2dc0b0e87dfc9a90",
+ 			"score": 2
+ 		},
+ 		{
+ 			"sha256: "156350ca18fa04545c4192432860c7efe9ddba18ea6e40e4da81bb7097a7166f",
+ 			"score": 2
+ 		}
+	]
+"
+```
+
+Get match, but with more permissive threshold
+
+`check.vframe.io/v1/match/threshold/3/`
+
+```
+{
+ "success": True,
+ "match": True,
+ "matches":
+	{
+		"sha256: "eadc688cd557ee351fa9b718e87a6e8dfb9c9fce69e9944c71c0f58f8b972632",
+		"score": 0
+	},
+ "closest_matches":
+ 	[
+ 		{
+ 			"sha256: "cf80cd8aed482d5d1527d7dc72fceff84e6326592848447d2dc0b0e87dfc9a90",
+ 			"score": 3
+ 		},
+ 		{
+ 			"sha256: "156350ca18fa04545c4192432860c7efe9ddba18ea6e40e4da81bb7097a7166f",
+ 			"score": 3
+ 		}
+	]
+"
\ No newline at end of file