Adds the experimentalapi client class to the docs (#228)

* Adds the experimentalapi client class to the docs

* Update src/groundlight/experimental_api.py

Co-authored-by: Sunil Kumar <[email protected]>

---------

Co-authored-by: Sunil Kumar <[email protected]>

Makefile

@@ -22,7 +22,7 @@ generate: install-generator  ## Generate the SDK from our public openapi spec
 		-o ./generated \
 		--additional-properties=packageName=groundlight_openapi_client
 # strict-nullable makes nullable fields Optional in the generated Pydantic classes: https://github.com/koxudaxi/datamodel-code-generator/issues/327
-	poetry run datamodel-codegen  --input spec/public-api.yaml --output generated/model.py --strict-nullable
+	poetry run datamodel-codegen  --input spec/public-api.yaml --output generated/model.py --strict-nullable --use-schema-description
 	poetry run black .
 
 PYTEST=poetry run pytest -v

generated/model.py

@@ -1,6 +1,6 @@
 # generated by datamodel-codegen:
 #   filename:  public-api.yaml
-#   timestamp: 2024-07-12T20:41:35+00:00
+#   timestamp: 2024-07-19T21:02:15+00:00
 
 from __future__ import annotations
 
@@ -12,6 +12,11 @@
 
 
 class ChannelEnum(Enum):
+    """
+    * `EMAIL` - EMAIL
+    * `TEXT` - TEXT
+    """
+
     EMAIL = "EMAIL"
     TEXT = "TEXT"
 
@@ -25,6 +30,11 @@ class ImageQueryTypeEnum(Enum):
 
 
 class ModeEnum(Enum):
+    """
+    * `BINARY` - BINARY
+    * `COUNT` - COUNT
+    """
+
     BINARY = "BINARY"
     COUNT = "COUNT"
 
@@ -44,13 +54,28 @@ class ResultTypeEnum(Enum):
 
 
 class SnoozeTimeUnitEnum(Enum):
+    """
+    * `DAYS` - DAYS
+    * `HOURS` - HOURS
+    * `MINUTES` - MINUTES
+    * `SECONDS` - SECONDS
+    """
+
     DAYS = "DAYS"
     HOURS = "HOURS"
     MINUTES = "MINUTES"
     SECONDS = "SECONDS"
 
 
 class VerbEnum(Enum):
+    """
+    * `ANSWERED_CONSECUTIVELY` - ANSWERED_CONSECUTIVELY
+    * `ANSWERED_WITHIN_TIME` - ANSWERED_WITHIN_TIME
+    * `CHANGED_TO` - CHANGED_TO
+    * `NO_CHANGE` - NO_CHANGE
+    * `NO_QUERIES` - NO_QUERIES
+    """
+
     ANSWERED_CONSECUTIVELY = "ANSWERED_CONSECUTIVELY"
     ANSWERED_WITHIN_TIME = "ANSWERED_WITHIN_TIME"
     CHANGED_TO = "CHANGED_TO"
@@ -81,6 +106,11 @@ class ActionRequest(BaseModel):
 
 
 class AllNotes(BaseModel):
+    """
+    Serializes all notes for a given detector, grouped by type as listed in UserProfile.NoteCategoryChoices
+    The fields must match whats in USERPROFILE.NoteCategoryChoices
+    """
+
     CUSTOMER: List[Note]
     GL: List[Note]
 
@@ -96,6 +126,10 @@ class ConditionRequest(BaseModel):
 
 
 class Detector(BaseModel):
+    """
+    Spec for serializing a detector object in the public API.
+    """
+
     id: str = Field(..., description="A unique ID for this object.")
     type: DetectorTypeEnum = Field(..., description="The type of this object.")
     created_at: datetime = Field(..., description="When this detector was created.")
@@ -117,6 +151,10 @@ class Detector(BaseModel):
 
 
 class DetectorCreationInputRequest(BaseModel):
+    """
+    Helper serializer for validating POST /detectors input.
+    """
+
     name: constr(min_length=1, max_length=200) = Field(..., description="A short, descriptive name for the detector.")
     query: constr(min_length=1, max_length=300) = Field(..., description="A question about the image.")
     group_name: Optional[constr(min_length=1, max_length=100)] = Field(
@@ -148,6 +186,10 @@ class DetectorCreationInputRequest(BaseModel):
 
 
 class ImageQuery(BaseModel):
+    """
+    Spec for serializing a image-query object in the public API.
+    """
+
     metadata: Optional[Dict[str, Any]] = Field(..., description="Metadata about the image query.")
     id: str = Field(..., description="A unique ID for this object.")
     type: ImageQueryTypeEnum = Field(..., description="The type of this object.")

sphinx_docs/models.rst

@@ -5,6 +5,9 @@ SDK Client
    :members:
    :special-members: __init__
 
+.. autoclass:: groundlight.ExperimentalApi
+   :members:
+   :special-members: __init__
 
 API Response Objects
 =====================
@@ -19,4 +22,10 @@ API Response Objects
     :model-show-json: True
 
 .. autopydantic_model:: model.PaginatedImageQueryList
+    :model-show-json: True
+
+.. autopydantic_model:: model.Rule
+    :model-show-json: True
+
+.. autopydantic_model:: model.PaginatedRuleList
     :model-show-json: True

src/groundlight/experimental_api.py

@@ -26,6 +26,11 @@
 
 class ExperimentalApi(Groundlight):
     def __init__(self, endpoint: Union[str, None] = None, api_token: Union[str, None] = None):
+        """
+        Constructs an experimental groundlight client. The experimental client inherits all the functionality of the
+        base groundlight client, but also includes additional functionality that is still in development. Experimental
+        functionality is subject to change.
+        """
         super().__init__(endpoint=endpoint, api_token=api_token)
         self.actions_api = ActionsApi(self.api_client)
         self.images_api = ImageQueriesApi(self.api_client)