Changing detector_id to detector. Userguide updates (#12)

BREAKING CHANGE.  `detector_id` is no long accepted as a named arg.  Must use `detector` instead, which can now be an id string or a detector object.

* Adding section on edge to User Guide.

* Adding a partial `get_or_create_detector` method to SDK.

* Doesn't fail silently if pagination would be needed.

* submit_image_query can accept a detector or a detector_id

* Consolidating the code samples into a single snippet.

* format udpates

* Wordsmithing the user guide.

* Improving interface and docs based on feedback.

* Moving exception handling to bottom of userguide.

* Ooops taking out jpeg_from_numpy which isn't supposed to be on this branch.  Bad merge.

* Changing tests to pass `detector` instead of `detector_id`

Author: robotrapta

.gitignore

@@ -163,3 +163,5 @@ cython_debug/
 poetry.lock
 
 node_modules/
+
+*.swp

README.md

@@ -12,37 +12,13 @@ $ pip install groundlight
 $ poetry add groundlight
 ```
 
-### Basic Usage
+### Usage
 
-To access the API, you need an API token. You can create one on the [groundlight website](https://app.groundlight.ai/reef/my-account/api-tokens). Then, you're ready to use the SDK!
-
-```Python
-from groundlight import Groundlight
-
-# Load the API client. This defaults to the prod endpoint,
-# but you can specify a different endpoint like so:
-# gl = Groundlight(endpoint="https://device.integ.groundlight.ai/device-api")
-gl = Groundlight(api_token="<YOUR_API_TOKEN>")
-
-# Create a detector
-detector = gl.create_detector(name="Dog", query="Is it a dog?")
-
-# (Or, create a detector with a specific named ML config from https://github.com/positronix-ai/zuuul/blob/main/pysrc/predictor_config/binary_classification_predictors.yaml)
-# detector = gl.create_detector(name="Dog", query="Is it a dog?", config_name="b4mu11-mlp")
-
-# Call an API method (e.g., retrieve a list of detectors)
-detectors = gl.list_detectors()
-```
-
-(Alternatively, you can use the token by setting the `GROUNDLIGHT_API_TOKEN` environment variable.)
-
-### What API methods are available?
-
-Check out the [User Guide](UserGuide.md)!
+For instructions on using the SDK see the public [User Guide](UserGuide.md).
 
 For more details, see the [Groundlight](src/groundlight/client.py)
-class. This SDK closely follows the methods in our [API
-Docs](https://app.groundlight.ai/reef/admin/api-docs).
+class. This SDK closely follows the methods in our [API 
+Docs](https://app.groundlight.ai/reef/admin/public-api-docs/).
 
 ## Development
 

UserGuide.md

@@ -1,10 +1,32 @@
-# User Guide
+# Groundlight Python SDK
 
-`groundlight` is a python SDK for working with the Groundlight API. You can send image queries and receive predictions powered by a mixture of machine learning models and human labelers in-the-loop.
+Groundlight makes it simple to understand images.  You can easily create computer vision detectors just by describing what you want to know using natural language.
 
-*Note: The SDK is currently in "alpha" phase.*
+How does it work?  Your images are first analyzed by machine learning (ML) models which are automatically trained on your data.  If those models have high enough confidence, that's your answer.  But if the models are unsure, then the images are progressively escalated to more resource-intensive analysis methods up to real-time human review.  So what you get is a computer vision system that starts working right away without even needing to first gather and label a dataset.  At first it will operate with high latency, because people need to review the image queries.  But over time, the ML systems will learn and improve so queries come back faster with higher confidence.
 
-## Pre-reqs
+*Note: The SDK is currently in "beta" phase.  Interfaces are subject to change in future versions.*
+
+
+## Simple Example
+
+How to build a computer vision system in 5 lines of python code:
+
+```Python
+from groundlight import Groundlight
+gl = Groundlight()
+
+# Create a new detector: use natural language to describe what you want to understand
+detector = gl.create_detector(name="door", query="Is the door open?")
+
+# Send an image to the detector
+image_query = gl.submit_image_query(detector=detector, image="path/to/filename.jpeg")
+
+# Show the results
+print(f"The answer is {image_query.result}")
+```
+
+
+## Getting Started
 
 1. Install the `groundlight` sdk.
 
@@ -13,32 +35,42 @@
     ```
 
 1. To access the API, you need an API token. You can create one on the
-   [groundlight website](https://app.groundlight.ai/reef/my-account/api-tokens).
+   [groundlight web app](https://app.groundlight.ai/reef/my-account/api-tokens).
 
-1. Use the `Groundlight` client!
+The API token should be stored securely.  You can use it directly in your code to initialize the SDK like:
 
-    ```Python
-    from groundlight import Groundlight
-    gl = Groundlight(api_token="<YOUR_API_TOKEN>")
-    ```
+```python
+gl = Groundlight(api_token="<YOUR_API_TOKEN>")
+```
 
-    The API token should be stored securely - do not commit it to version control! Alternatively, you can use the token by setting the `GROUNDLIGHT_API_TOKEN` environment variable.
+which is an easy way to get started, but is NOT a best practice.  Please do not commit your API Token to version control!  Instead we recommend setting the `GROUNDLIGHT_API_TOKEN` environment variable outside your code so that the SDK can find it automatically.
+
+```bash
+$ export GROUNDLIGHT_API_TOKEN=api_2asdfkjEXAMPLE
+$ python glapp.py
+```
 
-## Basics
 
-#### Create a new detector
+## Using Groundlight on the edge
+
+Starting your model evaluations at the edge reduces latency, cost, network bandwidth, and energy. Once you have downloaded and installed your Groundlight edge models, you can configure the Groundlight SDK to use your edge environment by configuring the 'endpoint' to point at your local environment as such:
 
 ```Python
-detector = gl.create_detector(name="Dog", query="Is it a dog?")
+from groundlight import Groundlight
+gl = Groundlight(endpoint="http://localhost:6717")
 ```
 
-#### Retrieve a detector
+(Edge model download is not yet generally available.)
+
+## Advanced
+
+### Retrieve an existing detector
 
 ```Python
 detector = gl.get_detector(id="YOUR_DETECTOR_ID")
 ```
 
-#### List your detectors
+### List your detectors
 
 ```Python
 # Defaults to 10 results per page
@@ -48,21 +80,15 @@ detectors = gl.list_detectors()
 detectors = gl.list_detectors(page=3, page_size=25)
 ```
 
-#### Submit an image query
-
-```Python
-image_query = gl.submit_image_query(detector_id="YOUR_DETECTOR_ID", image="path/to/filename.jpeg")
-```
-
-#### Retrieve an image query
+### Retrieve an image query
 
 In practice, you may want to check for a new result on your query. For example, after a cloud reviewer labels your query. For example, you can use the `image_query.id` after the above `submit_image_query()` call.
 
 ```Python
 image_query = gl.get_image_query(id="YOUR_IMAGE_QUERY_ID")
 ```
 
-#### List your previous image queries
+### List your previous image queries
 
 ```Python
 # Defaults to 10 results per page
@@ -72,8 +98,6 @@ image_queries = gl.list_image_queries()
 image_queries = gl.list_image_queries(page=3, page_size=25)
 ```
 
-## Advanced
-
 ### Handling HTTP errors
 
 If there is an HTTP error during an API call, it will raise an `ApiException`. You can access different metadata from that exception:
@@ -92,3 +116,4 @@ except ApiException as e:
     print(e.reason)
     print(e.status)
 ```
+

pyproject.toml

@@ -1,10 +1,10 @@
 [tool.poetry]
 name = "groundlight"
-version = "0.4.0"
+version = "0.5.0"
 license = "MIT"
 readme = "UserGuide.md"
 homepage = "https://groundlight.ai"
-description = "Call the Groundlight API from python"
+description = "Build computer vision systems from natural language with Groundlight"
 authors = ["Groundlight AI <[email protected]>"]
 packages = [
     { include = "**/*.py", from = "src" },

src/groundlight/client.py

@@ -1,6 +1,6 @@
 import os
 from io import BufferedReader, BytesIO
-from typing import Union
+from typing import Optional, Union
 
 from model import Detector, ImageQuery, PaginatedDetectorList, PaginatedImageQueryList
 from openapi_client import ApiClient, Configuration
@@ -61,6 +61,17 @@ def get_detector(self, id: str) -> Detector:
         obj = self.detectors_api.get_detector(id=id)
         return Detector.parse_obj(obj.to_dict())
 
+    def get_detector_by_name(self, name: str) -> Optional[Detector]:
+        #TODO: Do this on server.
+        detector_list = self.list_detectors(page_size=100)
+        for d in detector_list.results:
+            if d.name == name:
+                return d
+        if detector_list.next:
+            #TODO: paginate
+            raise RuntimeError("You have too many detectors to use get_detector_by_name")
+        return None
+
     def list_detectors(self, page: int = 1, page_size: int = 10) -> PaginatedDetectorList:
         obj = self.detectors_api.list_detectors(page=page, page_size=page_size)
         return PaginatedDetectorList.parse_obj(obj.to_dict())
@@ -69,6 +80,19 @@ def create_detector(self, name: str, query: str, config_name: str = None) -> Det
         obj = self.detectors_api.create_detector(DetectorCreationInput(name=name, query=query, config_name=config_name))
         return Detector.parse_obj(obj.to_dict())
 
+    def get_or_create_detector(self, name: str, query: str, config_name: str = None) -> Detector:
+        """Tries to look up the detector by name.  If a detector with that name and query exists, return it.
+        Otherwise, create a detector with the specified query and config.
+        """
+        existing_detector = self.get_detector_by_name(name)
+        if existing_detector:
+            if existing_detector.query == query:
+                return existing_detector
+            else:
+                raise ValueError(f"Found existing detector with {name=} (id={existing_detector.id}) but the queries don't match")
+                
+        return self.create_detector(name, query, config_name)
+
     def get_image_query(self, id: str) -> ImageQuery:
         obj = self.image_queries_api.get_image_query(id=id)
         return ImageQuery.parse_obj(obj.to_dict())
@@ -77,7 +101,21 @@ def list_image_queries(self, page: int = 1, page_size: int = 10) -> PaginatedIma
         obj = self.image_queries_api.list_image_queries(page=page, page_size=page_size)
         return PaginatedImageQueryList.parse_obj(obj.to_dict())
 
-    def submit_image_query(self, detector_id: str, image: Union[str, bytes, BytesIO]) -> ImageQuery:
+    def submit_image_query(self, 
+            image: Union[str, bytes, BytesIO, BufferedReader],
+            detector: Union[Detector, str],
+        ) -> ImageQuery:
+        """Evaluates an image with Groundlight.
+        :param image: The image, in several possible formats:
+            - a filename (string) of a jpeg file
+            - a byte array or BytesIO with jpeg bytes
+            - a numpy array in the 0-255 range (gets converted to jpeg)
+        :param detector: the Detector object, or string id of a detector like `det_12345`
+        """
+        if isinstance(detector, Detector):
+            detector_id = detector.id
+        else:
+            detector_id = detector
         image_bytesio: Union[BytesIO, BufferedReader]
         if isinstance(image, str):
             # Assume it is a filename

test/integration/test_groundlight.py

@@ -21,7 +21,7 @@ def detector(gl: Groundlight) -> Detector:
 
 @pytest.fixture
 def image_query(gl: Groundlight, detector: Detector) -> ImageQuery:
-    return gl.submit_image_query(detector_id=detector.id, image="test/assets/dog.jpeg")
+    return gl.submit_image_query(detector=detector.id, image="test/assets/dog.jpeg")
 
 
 # @pytest.mark.skip(reason="We don't want to create a million detectors")
@@ -58,7 +58,7 @@ def test_get_detector(gl: Groundlight, detector: Detector):
 
 # @pytest.mark.skip(reason="We don't want to create a million detectors and image_queries")
 def test_submit_image_query(gl: Groundlight, detector: Detector):
-    _image_query = gl.submit_image_query(detector_id=detector.id, image="test/assets/dog.jpeg")
+    _image_query = gl.submit_image_query(detector=detector.id, image="test/assets/dog.jpeg")
     assert str(_image_query)
     assert isinstance(_image_query, ImageQuery)