first commit

Author: Tim Huff

pyproject.toml

@@ -9,7 +9,7 @@ packages = [
     {include = "**/*.py", from = "src"},
 ]
 readme = "README.md"
-version = "0.27.0"
+version = "0.28.0"
 
 [tool.poetry.dependencies]
 # For certifi, use ">=" instead of "^" since it upgrades its "major version" every year, not really following semver

src/groundlight/cli.py

@@ -1,17 +1,33 @@
+import logging
+import sys
+from enum import Enum
 from functools import wraps
-from typing import Union
+from typing import Any, Union
 
 import typer
 from typing_extensions import get_origin
 
-from groundlight import Groundlight
+from groundlight import ExperimentalApi, Groundlight
 from groundlight.client import ApiTokenError
 
+logger = logging.getLogger("groundlight.sdk")
+
 cli_app = typer.Typer(
     no_args_is_help=True,
     context_settings={"help_option_names": ["-h", "--help"], "max_content_width": 800},
 )
 
+experimental_app = typer.Typer(
+    no_args_is_help=True,
+    help="Experimental commands — may change or be removed without notice.",
+    context_settings={"help_option_names": ["-h", "--help"], "max_content_width": 800},
+)
+cli_app.add_typer(experimental_app, name="experimental")
+cli_app.add_typer(experimental_app, name="exp")
+
+
+_CLI_PRIMITIVE_TYPES = (str, int, float, bool)
+
 
 def is_cli_supported_type(annotation):
     """
@@ -21,15 +37,45 @@ def is_cli_supported_type(annotation):
     return annotation in (int, float, bool)
 
 
-def class_func_to_cli(method):
+def is_cli_representable(annotation) -> bool:
+    """Returns True if the annotation is a type Typer can natively represent as a CLI argument.
+
+    Primitive scalar types, Enum subclasses, and Union types (handled separately) are considered
+    representable. Complex types like dict, list, bytes, and custom model classes are not.
+    """
+    if annotation in _CLI_PRIMITIVE_TYPES:
+        return True
+    if isinstance(annotation, type) and issubclass(annotation, Enum):
+        return True
+    if get_origin(annotation) is Union:
+        return True
+    return False
+
+
+def _format_result(result: Any) -> str:
+    """Format a method return value for CLI output.
+
+    Pydantic models are serialized to indented JSON. Everything else falls back to str().
+    """
+    try:
+        return result.model_dump_json(indent=2)
+    except AttributeError:
+        return str(result)
+
+
+def class_func_to_cli(method, is_experimental: bool = False):
     """
-    Given the class method, create a method with the identical signature to provide the help documentation and
-    but only instantiates the class when the method is actually called.
+    Given a class method, return a wrapper function with the same signature that Typer can
+    register as a CLI command. The wrapper instantiates ExperimentalApi at call time (which
+    also provides all stable Groundlight methods via inheritance), so a single instantiation
+    path serves both stable and experimental commands.
+
+    If is_experimental is True, a warning is printed to stderr before the method runs.
     """
 
-    # We create a fake class and fake method so we have the correct annotations for typer to use
-    # When we wrap the fake method, we only use the fake method's name to access the real method
-    # and attach it to a Groundlight instance that we create at function call time
+    # We create a fake class and fake method so we have the correct annotations for typer to use.
+    # When we wrap the fake method, we only use the fake method's name to look up and call the
+    # real method on an ExperimentalApi instance created at call time.
     class FakeClass:
         pass
 
@@ -38,14 +84,22 @@ class FakeClass:
 
     @wraps(fake_method)
     def wrapper(*args, **kwargs):
-        gl = Groundlight()
-        gl_method = vars(Groundlight)[fake_method.__name__]
-        gl_bound_method = gl_method.__get__(gl, Groundlight)  # pylint: disable=all
-        print(gl_bound_method(*args, **kwargs))  # this is where we output to the console
+        if is_experimental:
+            print(
+                f"Warning: '{fake_method.__name__}' is an experimental command and may change without notice.",
+                file=sys.stderr,
+            )
+        gl = ExperimentalApi()
+        bound_method = getattr(gl, fake_method.__name__)
+        result = bound_method(*args, **kwargs)
+        if result is not None:
+            print(_format_result(result))
 
     # not recommended practice to directly change annotations, but gets around Typer not supporting Union types
     cli_unsupported_params = []
     for name, annotation in method.__annotations__.items():
+        if name == "return":
+            continue
         if get_origin(annotation) is Union:
             # If we can submit a string, we take the string from the cli
             if str in annotation.__args__:
@@ -60,6 +114,11 @@ def wrapper(*args, **kwargs):
                         break
                 if not found_supported_type:
                     cli_unsupported_params.append(name)
+        elif is_experimental and not is_cli_representable(annotation):
+            # For experimental methods only: proactively flag non-Union types that Typer cannot
+            # represent (e.g. dict, list, custom models) so the caller can skip them gracefully
+            # before Typer raises a deferred RuntimeError at cli_app() invocation time.
+            cli_unsupported_params.append(name)
     # Ideally we could just not list the unsupported params, but it doesn't seem natively supported by Typer
     # and requires more metaprogamming than makes sense at the moment. For now, we require methods to support str
     for param in cli_unsupported_params:
@@ -72,12 +131,24 @@ def wrapper(*args, **kwargs):
 
 
 def groundlight():
+    """Entry point for the groundlight CLI."""
     try:
-        # For each method in the Groundlight class, create a function that can be called from the command line
+        stable_names = {n for n, m in vars(Groundlight).items() if callable(m) and not n.startswith("_")}
+
         for name, method in vars(Groundlight).items():
             if callable(method) and not name.startswith("_"):
                 cli_func = class_func_to_cli(method)
                 cli_app.command()(cli_func)
+
+        for name, method in vars(ExperimentalApi).items():
+            if not callable(method) or name.startswith("_") or name in stable_names:
+                continue
+            try:
+                cli_func = class_func_to_cli(method, is_experimental=True)
+                experimental_app.command()(cli_func)
+            except Exception as e:  # pylint: disable=broad-except
+                logger.debug("Skipping experimental CLI command '%s': %s", name, e)
+
         cli_app()
     except ApiTokenError as e:
         print(e)