diff --git a/docs/source/index.md b/docs/source/index.md index 7c9f0c3..712fec6 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -46,7 +46,7 @@ def setup(opts): else: return little_model() -inputs = { 'noise_vector': vector(length=128) } +inputs = { 'noise_vector': vector(length=128, description='A random seed.') } outputs = { 'image': image(width=512, height=512) } # The @runway.command() decorator is used to create interfaces to call functions @@ -54,7 +54,7 @@ outputs = { 'image': image(width=512, height=512) } # your model. Each command creates an HTTP route that the Runway app will use # to communicate with your model (e.g. POST /generate). Multiple commands # can be defined for the same model. -@runway.command('generate', inputs=inputs, outputs=outputs) +@runway.command('generate', inputs=inputs, outputs=outputs, description='Generate an image.') def generate(model, input_args): # Functions wrapped by @runway.command() receive two arguments: # 1. Whatever is returned by a function wrapped by @runway.setup(), diff --git a/examples/docs_code_snippets/runway_module_command.py b/examples/docs_code_snippets/runway_module_command.py index c1dd56b..bdb9b92 100644 --- a/examples/docs_code_snippets/runway_module_command.py +++ b/examples/docs_code_snippets/runway_module_command.py @@ -7,7 +7,7 @@ def setup(): return model() sample_inputs= { - "z": vector(length=512), + "z": vector(length=512, description="The seed used to generate an output image."), "category": category(choices=["day", "night"]) } @@ -15,12 +15,21 @@ def setup(): "image": image(width=1024, height=1024) } -@runway.command("sample", inputs=sample_inputs, outputs=sample_outputs) +# Descriptions are used to document each data type and `@runway.command()`; Their values appear +# in the app as tooltips. Writing detailed descriptions for each model option goes a long way +# towards helping users learn how to interact with your model. Write descriptions as full +# sentences. +sample_description = "Generate a new image based on a z-vector and an output style: Day or night." +@runway.command("sample", + inputs=sample_inputs, + outputs=sample_outputs, + description=sample_description) def sample(model, inputs): # The parameters passed to a function decorated by @runway.command() are: - # 1. The return value of a function wrapped by @runway.setup(), usually a model + # 1. The return value of a function wrapped by @runway.setup(), usually a model. # 2. The inputs sent with the HTTP request to the / endpoint, # as defined by the inputs keyword argument delivered to @runway.command(). img = model.sample(z=inputs["z"], category=inputs["category"]) + # `img` can be a PIL or numpy image. It will be encoded as a base64 URI string + # automatically by @runway.command(). return { "image": img } - diff --git a/examples/docs_code_snippets/runway_module_setup.py b/examples/docs_code_snippets/runway_module_setup.py index f228a14..1bb74d0 100644 --- a/examples/docs_code_snippets/runway_module_setup.py +++ b/examples/docs_code_snippets/runway_module_setup.py @@ -2,8 +2,15 @@ from runway.data_types import category from your_code import model -options = {"network_size": category(choices=[64, 128, 256, 512], default=256)} +# Descriptions are used to document each data type; Their values appear in the app as +# tooltips. Writing detailed descriptions for each model option goes a long way towards +# helping users learn how to interact with your model. Write descriptions as full sentences. +network_size_description = "The size of the network. A larger number will result in" \ + "better accuracy at the expense of increased latency." +options = { + "network_size": category(choices=[64, 128, 256, 512], default=256, description=network_size_description) +} @runway.setup(options=options) def setup(opts): print("Setup ran, and the network size is {}".format(opts["network_size"])) - return model(network_size=opts["network_size"]) \ No newline at end of file + return model(network_size=opts["network_size"]) diff --git a/runway/model.py b/runway/model.py index acf334a..a8ed7e7 100644 --- a/runway/model.py +++ b/runway/model.py @@ -185,7 +185,11 @@ def setup(self, decorated_fn=None, options=None): from runway.data_types import category from your_code import model - options = {"network_size": category(choices=[64, 128, 256, 512], default=256)} + # Descriptions are used to document each data type; Their values appear in the app as + # tooltips. Writing detailed descriptions for each model option goes a long way towards + # helping users learn how to interact with your model. Write descriptions as full sentences. + network_size_description = "The size of the network. A larger number will result in better accuracy at the expense of increased latency." + options = { "network_size": category(choices=[64, 128, 256, 512], default=256, description=network_size_description) } @runway.setup(options=options) def setup(opts): print("Setup ran, and the network size is {}".format(opts["network_size"])) @@ -241,7 +245,7 @@ def setup(): return model() sample_inputs= { - "z": vector(length=512), + "z": vector(length=512, description="The seed used to generate an output image."), "category": category(choices=["day", "night"]) } @@ -249,7 +253,15 @@ def setup(): "image": image(width=1024, height=1024) } - @runway.command("sample", inputs=sample_inputs, outputs=sample_outputs) + # Descriptions are used to document each data type and `@runway.command()`; Their values appear + # in the app as tooltips. Writing detailed descriptions for each model option goes a long way + # towards helping users learn how to interact with your model. Write descriptions as full + # sentences. + sample_description = "Generate a new image based on a z-vector and an output style: Day or night." + @runway.command("sample", + inputs=sample_inputs, + outputs=sample_outputs, + description=sample_description) def sample(model, inputs): # The parameters passed to a function decorated by @runway.command() are: # 1. The return value of a function wrapped by @runway.setup(), usually a model. @@ -260,6 +272,13 @@ def sample(model, inputs): # automatically by @runway.command(). return { "image": img } + .. note:: + All ``@runway.command()`` decorators accept a ``description`` keyword argument + that can be used to describe what the command does. Descriptions appear as + tooltips in the app and help users learn what the command does. It's best + practice to write full-sentence descriptions for each of your input variables + and commands. + :param name: The name of the command. This name is used to create the HTTP route associated with the command (i.e. a name of "generate_text" will generate a ``/generate_text`` @@ -277,7 +296,7 @@ def sample(model, inputs): :param description: A text description of what this command does. If this parameter is present its value will be rendered as a tooltip in Runway. Defaults to None. - :type description: string + :type description: string, optional :raises Exception: An exception if there isn't at least one key value pair for both inputs and outputs dictionaries :return: A decorated function