Improve docs

great_ai/remote/call_remote_great_ai.py

@@ -20,6 +20,11 @@ def call_remote_great_ai(
     timeout_in_seconds: Optional[int] = 300,
     model_class: Optional[Type[T]] = None,
 ) -> Trace[T]:
+    """Communicate with a GreatAI object through an HTTP request.
+
+    Wrapper over `call_remote_great_ai_async` making it synchronous. For more info, see
+    `call_remote_great_ai_async`.
+    """
     try:
         asyncio.get_running_loop()
         raise Exception(

great_ai/remote/call_remote_great_ai_async.py

@@ -16,6 +16,23 @@ async def call_remote_great_ai_async(
     timeout_in_seconds: Optional[int] = 300,
     model_class: Optional[Type[T]] = None,
 ) -> Trace[T]:
+    """Communicate with a GreatAI object through an HTTP request.
+
+    Send a POST request using [httpx](https://www.python-httpx.org/) to implement a
+    remote call. Error-handling and retries are provided by httpx.
+
+    The return value is inflated into a Trace. If `model_class` is specified, the
+    original output is deserialised.
+
+    Args:
+        base_uri: Address of the remote instance, example: 'http://localhost:6060'
+        data: The input sent as a json to the remote instance.
+        retry_count: Retry on any HTTP communication failure.
+        timeout_in_seconds: Overall permissable max length of the request. `None` means
+            no timeout.
+        model_class: A subtype of BaseModel to be used for deserialising the `.output`
+            of the trace.
+    """
 
     if base_uri.endswith("/"):
         base_uri = base_uri[:-1]

great_ai/tracing/add_ground_truth.py

@@ -1,7 +1,7 @@
 from datetime import datetime
 from math import ceil
 from random import shuffle
-from typing import Any, Iterable, List, TypeVar, cast
+from typing import Any, Iterable, List, TypeVar, Union, cast
 from uuid import uuid4
 
 from ..constants import (
@@ -20,14 +20,14 @@ def add_ground_truth(
     inputs: Iterable[Any],
     expected_outputs: Iterable[T],
     *,
-    tags: List[str] = [],
+    tags: Union[List[str], str] = [],
     train_split_ratio: float = 1,
     test_split_ratio: float = 0,
     validation_split_ratio: float = 0
 ) -> None:
     """Add training data (with optional train-test splitting).
 
-    Add and tag datapoints, wrap them into traces. The `inputs` are available via the
+    Add and tag data-points, wrap them into traces. The `inputs` are available via the
     `.input` property, while `expected_outputs` under both the `.output` and `.feedback`
     properties.
 
@@ -46,6 +46,18 @@ def add_ground_truth(
         ...    validation_split_ratio=0.5,
         ... )
 
+        >>> add_ground_truth(
+        ...    [1, 2],
+        ...    ['odd', 'even', 'odd'],
+        ...    tags='my_tag',
+        ...    train_split_ratio=1,
+        ...    test_split_ratio=1,
+        ...    validation_split_ratio=0.5,
+        ... )
+        Traceback (most recent call last):
+            ...
+        AssertionError: The length of the inputs and expected_outputs must be equal
+
     Args:
         inputs: The inputs. (X in scikit-learn)
         expected_outputs: The ground-truth values corresponding to the inputs. (y in
@@ -63,6 +75,8 @@ def add_ground_truth(
         expected_outputs
     ), "The length of the inputs and expected_outputs must be equal"
 
+    tags = tags if isinstance(tags, list) else [tags]
+
     sum_ratio = train_split_ratio + test_split_ratio + validation_split_ratio
     assert sum_ratio > 0, "The sum of the split ratios must be a positive number"
 

great_ai/tracing/query_ground_truth.py

@@ -14,7 +14,7 @@ def query_ground_truth(
 ) -> List[Trace]:
     """Return training samples.
 
-    Combines, filters, and returns datapoints that have been either added by
+    Combines, filters, and returns data-points that have been either added by
     `add_ground_truth` or were the result of a prediction after which their trace got
     a feedback through the RESP API-s `/traces/{trace_id}/feedback` endpoint
     (end-to-end feedback).