Improve docstrings

great_ai/deploy/great_ai.py

@@ -47,6 +47,10 @@ class GreatAI(Generic[T, V]):
     Provides caching (with argument freezing), a TracingContext during execution, the
     scaffolding of HTTP endpoints using FastAPI and a dashboard using Dash.
 
+    IMPORTANT: when a request is served from cache, no new trace is created. Thus, the
+    same trace can be returned multiple times. If this is undesirable turn off caching
+    using `configure(prediction_cache_size=0)`.
+
     Supports wrapping async and synchronous functions while also maintaining correct
     typing.
 

great_ai/parameters/log_metric.py

@@ -6,6 +6,15 @@ from ..tracing import TracingContext
 
 
 def log_metric(argument_name: str, value: Any) -> None:
+    """Log a key (argument_name)-value pair that is persisted inside the trace.
+
+    The name of the function from where this is called is also stored.
+
+    Args:
+        argument_name: The key for storing the value.
+        value: Value to log. Must be JSON-serialisable.
+    """
+
     tracing_context = TracingContext.get_current_tracing_context()
     caller = inspect.stack()[1].function
     actual_name = f"metric:{caller}:{argument_name}"

great_ai/parameters/parameter.py

@@ -19,6 +19,10 @@ def parameter(
 ) -> Callable[[F], F]:
     """Control the validation and logging of function parameters.
 
+    Basically, a parameter decorator. Unfortunately, Python does not have that concept,
+    thus, it's a method decorator that expects the name of the to-be-decorated
+    parameter.
+
     Examples:
         >>> @parameter('a')
         ... def my_function(a: int):
@@ -39,7 +43,7 @@ def parameter(
         great_ai.errors.argument_validation_error.ArgumentValidationError: ...
 
     Args:
-        parameter_name: Name of parameter to consider
+        parameter_name: Name of parameter to consider.
         validate: Optional validate to run against the concrete argument.
             ArgumentValidationError is thrown when the return value is False.
         disable_logging: Do not save the value in any active TracingContext.

great_ai/remote/call_remote_great_ai_async.py

@@ -28,7 +28,7 @@ async def call_remote_great_ai_async(
         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
+        timeout_in_seconds: Overall permissible 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.

great_ai/tracing/query_ground_truth.py

@@ -16,7 +16,7 @@ def query_ground_truth(
 
     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
+    feedback through the RESP API-s `/traces/{trace_id}/feedback` endpoint
     (end-to-end feedback).
 
     Filtering can be used to only return points matching all given tags (or the single

great_ai/utilities/parallel_map/parallel_map.py

@@ -91,7 +91,7 @@ def parallel_map(
     or ignored.
 
     The new processes are forked if the OS allows it, otherwise, new Python processes
-    are bootstrapped which can incur some startup cost. Each process processes a single
+    are bootstrapped which can incur some start-sup cost. Each process processes a single
     chunk at once.
 
     Examples:

great_ai/views/trace.py

@@ -10,6 +10,23 @@ T = TypeVar("T")
 
 
 class Trace(Generic[T], HashableBaseModel):
+    """Universal structure for storing prediction traces and training data.
+
+    Attributes:
+        trace_id: UUID4 identifier for uniquely referring to a trace.
+        created: Timestamp of its (original) construction.
+        original_execution_time_ms: Wall-time elapsed while its generating
+            TracingContext was alive.
+        logged_values: Values persisted through using `@parameter` or `log_metric()`.
+        models: Marks left by each encountered `@use_model` decorated function.
+        exception: Exception description if any was encountered.
+        output: Return value of the function wrapped by GreatAI.
+        feedback: Feedback obtained using the REST API of `add_ground_truth`.
+        tags: Tags used for filtering traces. Contains the name of the original
+            function, value of `ENVIRONMENT`, its split if has any, and either
+            `ground_truth` or `online` depending on the origin of the Trace.
+    """
+
     trace_id: str
     created: str
     original_execution_time_ms: float