✨ add support for generated APIs (#210)

Author: sebastianMindee

docs/conf.py

@@ -54,7 +54,7 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ["_static"]
+html_static_path = []
 
 # A list of paths that contain extra files not directly related to the documentation.
 html_extra_path = ["extras"]

docs/extras/code_samples/default.txt

@@ -1,21 +1,29 @@
-import json
-import requests
+from mindee import Client, PredictResponse, product
 
-api_key = "my-api-key"
-account = "my-account"
-endpoint = "my-endpoint"
-version = "my-version"
+# Init a new client
+mindee_client = Client(api_key="my-api-key")
 
-url = f"https://api.mindee.net/v1/products/{account}/{endpoint}/v{version}/predict"
+# Add the corresponding endpoint (document). Set the account_name to "mindee" if you are using OTS.
+my_endpoint = mindee_client.create_endpoint(
+    account_name="my-account",
+    endpoint_name="my-endpoint",
+    version="my-version"
+)
 
-with open("/path/to/the/file.ext", "rb") as file_handle:
-    files = {"document": file_handle}
-    headers = {"Authorization": f"Token {api_key}"}
-    response = requests.post(url, files=files, headers=headers)
+# Load a file from disk
+input_doc = mindee_client.source_from_path("/path/to/the/file.ext")
 
-json_response = response.json()
+# Parse the file.
+# The endpoint must be specified since it cannot be determined from the class.
+result: PredictResponse = mindee_client.parse(
+    product.GeneratedV1,
+    input_doc,
+    endpoint=my_endpoint
+)
 
-if not response.ok:
-    raise RuntimeError(json_response["api_request"]["error"])
+# Print a brief summary of the parsed data
+print(result.document)
 
-print(json.dumps(json_response["document"], indent=2))
+# # Iterate over all the fields in the document
+# for field_name, field_values in result.document.inference.prediction.fields.items():
+#     print(field_name, "=", field_values)

docs/extras/code_samples/default_async.txt

@@ -1,45 +1,29 @@
-import json
-import requests
-from time import sleep
-
-api_key = "my-api-key"
-account = "my-account"
-endpoint = "my-endpoint"
-version = "my-version"
-
-url_enqueue = f"https://api.mindee.net/v1/products/{account}/{endpoint}/v{version}/predict_async"
-headers = {"Authorization": f"Token {api_key}"}
-
-with open("/path/to/the/file.ext", "rb") as file_handle:
-    files = {"document": file_handle}
-    response_enqueue = requests.post(url_enqueue, files=files, headers=headers)
-
-json_response_enqueue = response_enqueue.json()
-
-if not response_enqueue.ok:
-    raise RuntimeError(json_response_enqueue["api_request"]["error"])
-
-job_id = json_response_enqueue["job"]["id"]
-
-url_parse_queued = f"https://api.mindee.net/v1/products/{account}/{endpoint}/v{version}/documents/queue/{job_id}"
-sleep(4)
-tries = 0
-job_status = ""
-while tries < 30:
-    response_parse = requests.get(url_parse_queued, headers=headers)
-    if not response_parse.ok:
-        raise RuntimeError(json_response_enqueue["api_request"]["error"])
-    json_response_parse = response_parse.json()
-    job_status = json_response_parse["job"]["status"]
-    if job_status == "completed":
-        break
-    else:
-        print(json_response_parse["job"])
-
-    tries += 1
-    sleep(2)
-
-if job_status != "completed":
-    raise RuntimeError(f"Async parsing timed out after {tries} tries")
-
-print(json.dumps(json_response_parse["document"], indent=2))
+from mindee import Client, PredictResponse, product
+
+# Init a new client
+mindee_client = Client(api_key="my-api-key")
+
+# Add the corresponding endpoint (document). Set the account_name to "mindee" if you are using OTS.
+my_endpoint = mindee_client.create_endpoint(
+    account_name="my-account",
+    endpoint_name="my-endpoint",
+    version="my-version"
+)
+
+# Load a file from disk
+input_doc = mindee_client.source_from_path("/path/to/the/file.ext")
+
+# Parse the file.
+# The endpoint must be specified since it cannot be determined from the class.
+result: PredictResponse = mindee_client.enqueue_and_parse(
+    product.GeneratedV1,
+    input_doc,
+    endpoint=my_endpoint
+)
+
+# Print a brief summary of the parsed data
+print(result.document)
+
+# # Iterate over all the fields in the document
+# for field_name, field_values in result.document.inference.prediction.fields.items():
+#     print(field_name, "=", field_values)

docs/extras/guide/custom_v1.md

@@ -70,7 +70,7 @@ Values of `ListField`s are stored in a `ListFieldValue` structure, which is impl
 * **confidence** (`float`): the confidence score of the prediction
 * **bounding_box** (`BBox`): 4 relative vertices corrdinates of a rectangle containing the word in the document.
 * **polygon** (`Polygon`): vertices of a polygon containing the word.
-* **page_id** (`int`): the ID of the page, is `undefined` when at document-level.
+* **page_id** (`int`): the ID of the page, is `None` when at document-level.
 
 
 ### Classification Field

docs/extras/guide/generated_v1.md

@@ -0,0 +1,88 @@
+---
+title: Generated API Python
+---
+
+The Python OCR SDK supports generated APIs.
+Generated APIs can theoretically support all APIs in a catch-all generic format.
+
+# Quick-Start
+
+```python
+from mindee import Client, product
+
+# Init a new client
+mindee_client = Client(api_key="my-api-key")
+
+# Add your custom endpoint (document)
+my_endpoint = mindee_client.create_endpoint(
+    account_name="my-account",
+    endpoint_name="my-endpoint",
+    version="my-version" # Note: version should be always provided when using for OTS products
+)
+
+# Load a file from disk
+input_doc = mindee_client.source_from_path("/path/to/the/file.ext")
+
+# Parse the file.
+# The endpoint must be specified since it cannot be determined from the class.
+result = mindee_client.parse(
+    product.GeneratedV1,
+    input_doc,
+    endpoint=my_endpoint
+)
+
+# Print a brief summary of the parsed data
+print(result.document)
+
+# Iterate over all the fields in the document
+for field_name, field_values in result.document.fields.items():
+    print(field_name, "=", field_values)
+```
+
+# Generated Endpoints
+
+You may have noticed in the previous step that in order to access a custom build, you will need to provide an account and an endpoint name at the very least.
+
+Although it is optional, the version number should match the latest version of your build in most use-cases.
+If it is not set, it will default to "1".
+
+# Field Types
+
+## Generated Fields
+
+### Generated List Field
+
+A `GeneratedListField` is a special type of custom list that implements the following:
+
+- **values** (`List[Union[StringField`[GeneratedObjectField](#Generated-object-field)`]]`): the confidence score of the field prediction.
+- **page_id** (`int`): only available for some documents ATM.
+
+Since the inner contents can vary, the value isn't accessed through a property, but rather through the following functions:
+
+- **contents_list()** (`-> List[Union[str, float]]`): returns a list of values for each element.
+- **contents_string(separator=" ")** (`-> str`): returns a list of concatenated values, with an optional **separator** `str` between them.
+- ****str**()**: returns a string representation of all values, appropriate spacing.
+
+#### Generated Object Field
+
+Unrecognized structures and sometimes values of `ListField`s are stored in a `GeneratedObjectField` structure, which is implemented dynamically depending on the object's structure.
+
+No matter what, the fields will be stored in a dictionary-like structure with a `key: value` pair where `key` is a string and `value` is a nullable string. The object also contains:
+
+- **page_id** (`Optional[int]`): the ID of the page, is `None` when at document-level.
+
+# Attributes
+
+Generated builds always have access to at least two attributes:
+
+## Fields
+
+**fields** (`Dict[str`: `List[Union[`[GeneratedListField](#generated-list-field)[GeneratedObjectField](#generated-object-field), `StringField]]`):
+
+```python
+print(str(result.document.inference.prediction.fields["my-field"]))
+```
+
+# Questions?
+
+[Join our Slack](https://join.slack.com/t/mindee-community/shared_invite/zt-1jv6nawjq-FDgFcF2T5CmMmRpl9LLptw)

docs/parsing/generated.rst

@@ -0,0 +1,16 @@
+----------------
+Generated Fields
+----------------
+
+Generated Lists
+===============
+.. autoclass:: mindee.parsing.generated.generated_list
+    :members:
+
+
+Generated Objects
+=================
+.. autoclass:: mindee.parsing.generated.generated_object
+    :members:
+
+.. autofunction:: mindee.parsing.generated.is_generated_object

docs/parsing/index.rst

@@ -7,4 +7,5 @@ Parsing Utilities
     ./standard
     ./common
     ./custom
+    ./generated
 

docs/product/custom_v1.rst

@@ -0,0 +1,19 @@
+Custom V1
+---------
+
+**Sample Code:**
+
+.. literalinclude:: /extras/code_samples/custom_v1.txt
+    :language: Python
+
+.. autoclass:: mindee.product.custom.custom_v1.CustomV1
+    :members:
+    :inherited-members:
+    
+.. autoclass:: mindee.product.custom.custom_v1.CustomV1Document
+    :members:
+    :inherited-members:
+
+.. autoclass:: mindee.product.custom.custom_v1.CustomV1Page
+    :members:
+    :inherited-members:

docs/product/generated_v1.rst

@@ -0,0 +1,25 @@
+Generated V1
+------------
+
+
+**Sample Code (sync):**
+
+.. literalinclude:: /extras/code_samples/default.txt
+    :language: Python
+
+**Sample Code (async):**
+
+.. literalinclude:: /extras/code_samples/default_async.txt
+    :language: Python
+
+.. autoclass:: mindee.product.generated.generated_v1.GeneratedV1
+    :members:
+    :inherited-members:
+    
+.. autoclass:: mindee.product.generated.generated_v1.GeneratedV1Document
+    :members:
+    :inherited-members:
+
+.. autoclass:: mindee.product.generated.generated_v1.GeneratedV1Page
+    :members:
+    :inherited-members:

docs/product/international_id_v1.rst

@@ -3,7 +3,7 @@ International ID V1
 
 **Sample Code:**
 
-.. literalinclude:: /extras/code_samples/international_id_v1.txt
+.. literalinclude:: /extras/code_samples/international_id_v1_async.txt
     :language: Python
 
 .. autoclass:: mindee.product.international_id.international_id_v1.InternationalIdV1