pixeltable 0.2.12__py3-none-any.whl → 0.2.14__py3-none-any.whl

pixeltable/functions/image.py

@@ -1,5 +1,17 @@
+"""
+Pixeltable [UDFs](https://pixeltable.readme.io/docs/user-defined-functions-udfs) for `ImageType`.
+
+Example:
+```python
+import pixeltable as pxt
+
+t = pxt.get_table(...)
+t.select(t.img_col.convert('L')).collect()
+```
+"""
+
 import base64
-from typing import Optional, Tuple
+from typing import Optional
 
 import PIL.Image
 
@@ -9,9 +21,15 @@ from pixeltable.utils.code import local_public_names
 from pixeltable.exprs import Expr
 
 
-@func.udf
+@func.udf(is_method=True)
 def b64_encode(img: PIL.Image.Image, image_format: str = 'png') -> str:
-    # Encode this image as a b64-encoded png.
+    """
+    Convert image to a base64-encoded string.
+
+    Args:
+        img: image
+        image_format: image format [supported by PIL](https://pillow.readthedocs.io/en/stable/handbook/image-file-formats.html#fully-supported-formats)
+    """
     import io
 
     bytes_arr = io.BytesIO()
@@ -20,27 +38,49 @@ def b64_encode(img: PIL.Image.Image, image_format: str = 'png') -> str:
     return b64_bytes.decode('utf-8')
 
 
-@func.udf(substitute_fn=PIL.Image.alpha_composite)
+@func.udf(substitute_fn=PIL.Image.alpha_composite, is_method=True)
 def alpha_composite(im1: PIL.Image.Image, im2: PIL.Image.Image) -> PIL.Image.Image:
+    """
+    Alpha composite `im2` over `im1`.
+
+    Equivalent to [`PIL.Image.alpha_composite()`](https://pillow.readthedocs.io/en/stable/reference/Image.html#PIL.Image.alpha_composite)
+    """
     pass
 
 
-@func.udf(substitute_fn=PIL.Image.blend)
+@func.udf(substitute_fn=PIL.Image.blend, is_method=True)
 def blend(im1: PIL.Image.Image, im2: PIL.Image.Image, alpha: float) -> PIL.Image.Image:
-    pass
+    """
+    Return a new image by interpolating between two input images, using a constant alpha.
 
+    Equivalent to [`PIL.Image.blend()`](https://pillow.readthedocs.io/en/stable/reference/Image.html#PIL.Image.blend)
+    """
+    pass
 
-@func.udf(substitute_fn=PIL.Image.composite)
+@func.udf(substitute_fn=PIL.Image.composite, is_method=True)
 def composite(image1: PIL.Image.Image, image2: PIL.Image.Image, mask: PIL.Image.Image) -> PIL.Image.Image:
+    """
+    Return a composite image by blending two images using a mask.
+
+    Equivalent to [`PIL.Image.composite()`](https://pillow.readthedocs.io/en/stable/reference/Image.html#PIL.Image.composite)
+    """
     pass
 
 
 # PIL.Image.Image methods
 
-
 # Image.convert()
-@func.udf
+@func.udf(is_method=True)
 def convert(self: PIL.Image.Image, mode: str) -> PIL.Image.Image:
+    """
+    Convert the image to a different mode.
+
+    Equivalent to
+    [`PIL.Image.Image.convert()`](https://pillow.readthedocs.io/en/stable/reference/Image.html#PIL.Image.Image.convert).
+
+    Args:
+        mode: The mode to convert to. See the [Pillow documentation](https://pillow.readthedocs.io/en/stable/handbook/concepts.html#concept-modes) for a list of supported modes.
+    """
     return self.convert(mode)
 
 
@@ -52,23 +92,39 @@ def _(self: Expr, mode: str) -> ts.ColumnType:
 
 
 # Image.crop()
-@func.udf(substitute_fn=PIL.Image.Image.crop, param_types=[ts.ImageType(), ts.ArrayType((4,), dtype=ts.IntType())])
-def crop(self: PIL.Image.Image, box: Tuple[int, int, int, int]) -> PIL.Image.Image:
+@func.udf(substitute_fn=PIL.Image.Image.crop, param_types=[ts.ImageType(), ts.ArrayType((4,), dtype=ts.IntType())], is_method=True)
+def crop(self: PIL.Image.Image, box: tuple[int, int, int, int]) -> PIL.Image.Image:
+    """
+    Return a rectangular region from the image. The box is a 4-tuple defining the left, upper, right, and lower pixel
+    coordinates.
+
+    Equivalent to
+    [`PIL.Image.Image.crop()`](https://pillow.readthedocs.io/en/stable/reference/Image.html#PIL.Image.Image.crop)
+    """
     pass
 
 
 @crop.conditional_return_type
-def _(self: Expr, box: Tuple[int, int, int, int]) -> ts.ColumnType:
+def _(self: Expr, box: tuple[int, int, int, int]) -> ts.ColumnType:
     input_type = self.col_type
     assert isinstance(input_type, ts.ImageType)
-    if isinstance(box, list) and all(isinstance(x, int) for x in box):
+    if (isinstance(box, list) or isinstance(box, tuple)) and len(box) == 4 and all(isinstance(x, int) for x in box):
         return ts.ImageType(size=(box[2] - box[0], box[3] - box[1]), mode=input_type.mode, nullable=input_type.nullable)
     return ts.ImageType(mode=input_type.mode, nullable=input_type.nullable)  # we can't compute the size statically
 
 
 # Image.getchannel()
-@func.udf(substitute_fn=PIL.Image.Image.getchannel)
+@func.udf(substitute_fn=PIL.Image.Image.getchannel, is_method=True)
 def getchannel(self: PIL.Image.Image, channel: int) -> PIL.Image.Image:
+    """
+    Return an L-mode image containing a single channel of the original image.
+
+    Equivalent to
+    [`PIL.Image.Image.getchannel()`](https://pillow.readthedocs.io/en/stable/reference/Image.html#PIL.Image.Image.getchannel)
+
+    Args:
+        channel: The channel to extract. This is a 0-based index.
+    """
     pass
 
 
@@ -80,31 +136,64 @@ def _(self: Expr) -> ts.ColumnType:
 
 
 # Image.resize()
-@func.udf(param_types=[ts.ImageType(), ts.ArrayType((2,), dtype=ts.IntType())])
-def resize(self: PIL.Image.Image, size: Tuple[int, int]) -> PIL.Image.Image:
+@func.udf(param_types=[ts.ImageType(), ts.ArrayType((2,), dtype=ts.IntType())], is_method=True)
+def resize(self: PIL.Image.Image, size: tuple[int, int]) -> PIL.Image.Image:
+    """
+    Return a resized copy of the image. The size parameter is a tuple containing the width and height of the new image.
+
+    Equivalent to
+    [`PIL.Image.Image.resize()`](https://pillow.readthedocs.io/en/stable/reference/Image.html#PIL.Image.Image.resize)
+    """
     return self.resize(size)
 
 
 @resize.conditional_return_type
-def _(self: Expr, size: Tuple[int, int]) -> ts.ColumnType:
+def _(self: Expr, size: tuple[int, int]) -> ts.ColumnType:
     input_type = self.col_type
     assert isinstance(input_type, ts.ImageType)
     return ts.ImageType(size=size, mode=input_type.mode, nullable=input_type.nullable)
 
 
 # Image.rotate()
-@func.udf
+@func.udf(is_method=True)
 def rotate(self: PIL.Image.Image, angle: int) -> PIL.Image.Image:
+    """
+    Return a copy of the image rotated by the given angle.
+
+    Equivalent to
+    [`PIL.Image.Image.rotate()`](https://pillow.readthedocs.io/en/stable/reference/Image.html#PIL.Image.Image.rotate)
+
+    Args:
+        angle: The angle to rotate the image, in degrees. Positive angles are counter-clockwise.
+    """
     return self.rotate(angle)
 
 
-@func.udf(substitute_fn=PIL.Image.Image.effect_spread)
+@func.udf(substitute_fn=PIL.Image.Image.effect_spread, is_method=True)
 def effect_spread(self: PIL.Image.Image, distance: int) -> PIL.Image.Image:
+    """
+    Randomly spread pixels in an image.
+
+    Equivalent to
+    [`PIL.Image.Image.effect_spread()`](https://pillow.readthedocs.io/en/stable/reference/Image.html#PIL.Image.Image.effect_spread)
+
+    Args:
+        distance: The distance to spread pixels.
+    """
     pass
 
 
-@func.udf(substitute_fn=PIL.Image.Image.transpose)
+@func.udf(substitute_fn=PIL.Image.Image.transpose, is_method=True)
 def transpose(self: PIL.Image.Image, method: int) -> PIL.Image.Image:
+    """
+    Transpose the image.
+
+    Equivalent to
+    [`PIL.Image.Image.transpose()`](https://pillow.readthedocs.io/en/stable/reference/Image.html#PIL.Image.Image.transpose)
+
+    Args:
+        method: The transpose method. See the [Pillow documentation](https://pillow.readthedocs.io/en/stable/reference/Image.html#PIL.Image.Image.transpose) for a list of supported methods.
+    """
     pass
 
 
@@ -115,53 +204,128 @@ def _(self: Expr) -> ts.ColumnType:
     return self.col_type
 
 
-@func.udf(substitute_fn=PIL.Image.Image.entropy)
+@func.udf(substitute_fn=PIL.Image.Image.entropy, is_method=True)
 def entropy(self: PIL.Image.Image, mask: Optional[PIL.Image.Image] = None, extrema: Optional[list] = None) -> float:
+    """
+    Returns the entropy of the image, optionally using a mask and extrema.
+
+    Equivalent to
+    [`PIL.Image.Image.entropy()`](https://pillow.readthedocs.io/en/stable/reference/Image.html#PIL.Image.Image.entropy)
+
+    Args:
+        mask: An optional mask image.
+        extrema: An optional list of extrema.
+    """
     pass
 
 
-@func.udf(substitute_fn=PIL.Image.Image.getbands)
-def getbands(self: PIL.Image.Image) -> Tuple[str]:
+@func.udf(substitute_fn=PIL.Image.Image.getbands, is_method=True)
+def getbands(self: PIL.Image.Image) -> tuple[str]:
+    """
+    Return a tuple containing the names of the image bands.
+
+    Equivalent to
+    [`PIL.Image.Image.getbands()`](https://pillow.readthedocs.io/en/stable/reference/Image.html#PIL.Image.Image.getbands)
+    """
     pass
 
 
-@func.udf(substitute_fn=PIL.Image.Image.getbbox)
-def getbbox(self: PIL.Image.Image) -> Tuple[int, int, int, int]:
+@func.udf(substitute_fn=PIL.Image.Image.getbbox, is_method=True)
+def getbbox(self: PIL.Image.Image, *, alpha_only: bool = True) -> tuple[int, int, int, int]:
+    """
+    Return a bounding box for the non-zero regions of the image.
+
+    Equivalent to [`PIL.Image.Image.getbbox()`](https://pillow.readthedocs.io/en/stable/reference/Image.html#PIL.Image.Image.getbbox)
+
+    Args:
+        alpha_only: If `True`, and the image has an alpha channel, trim transparent pixels. Otherwise, trim pixels when all channels are zero.
+    """
     pass
 
 
-@func.udf(substitute_fn=PIL.Image.Image.getcolors)
-def getcolors(self: PIL.Image.Image, maxcolors: int) -> Tuple[Tuple[int, int, int], int]:
+@func.udf(substitute_fn=PIL.Image.Image.getcolors, is_method=True)
+def getcolors(self: PIL.Image.Image, maxcolors: int = 256) -> tuple[tuple[int, int, int], int]:
+    """
+    Return a list of colors used in the image, up to a maximum of `maxcolors`.
+
+    Equivalent to
+    [`PIL.Image.Image.getcolors()`](https://pillow.readthedocs.io/en/stable/reference/Image.html#PIL.Image.Image.getcolors)
+
+    Args:
+        maxcolors: The maximum number of colors to return.
+    """
     pass
 
 
-@func.udf(substitute_fn=PIL.Image.Image.getextrema)
-def getextrema(self: PIL.Image.Image) -> Tuple[int, int]:
+@func.udf(substitute_fn=PIL.Image.Image.getextrema, is_method=True)
+def getextrema(self: PIL.Image.Image) -> tuple[int, int]:
+    """
+    Return a 2-tuple containing the minimum and maximum pixel values of the image.
+
+    Equivalent to
+    [`PIL.Image.Image.getextrema()`](https://pillow.readthedocs.io/en/stable/reference/Image.html#PIL.Image.Image.getextrema)
+    """
     pass
 
 
-@func.udf(substitute_fn=PIL.Image.Image.getpalette)
-def getpalette(self: PIL.Image.Image, mode: Optional[str] = None) -> Tuple[int]:
+@func.udf(substitute_fn=PIL.Image.Image.getpalette, is_method=True)
+def getpalette(self: PIL.Image.Image, mode: Optional[str] = None) -> tuple[int]:
+    """
+    Return the palette of the image, optionally converting it to a different mode.
+
+    Equivalent to
+    [`PIL.Image.Image.getpalette()`](https://pillow.readthedocs.io/en/stable/reference/Image.html#PIL.Image.Image.getpalette)
+
+    Args:
+        mode: The mode to convert the palette to.
+    """
     pass
 
 
-@func.udf(param_types=[ts.ImageType(), ts.ArrayType((2,), dtype=ts.IntType())])
-def getpixel(self: PIL.Image.Image, xy: tuple[int, int]) -> Tuple[int]:
+@func.udf(param_types=[ts.ImageType(), ts.ArrayType((2,), dtype=ts.IntType())], is_method=True)
+def getpixel(self: PIL.Image.Image, xy: tuple[int, int]) -> tuple[int]:
+    """
+    Return the pixel value at the given position. The position `xy` is a tuple containing the x and y coordinates.
+
+    Equivalent to
+    [`PIL.Image.Image.getpixel()`](https://pillow.readthedocs.io/en/stable/reference/Image.html#PIL.Image.Image.getpixel)
+
+    Args:
+        xy: The coordinates, given as (x, y).
+    """
     # `xy` will be a list; `tuple(xy)` is necessary for pillow 9 compatibility
     return self.getpixel(tuple(xy))
 
 
-@func.udf(substitute_fn=PIL.Image.Image.getprojection)
-def getprojection(self: PIL.Image.Image) -> Tuple[int]:
+@func.udf(substitute_fn=PIL.Image.Image.getprojection, is_method=True)
+def getprojection(self: PIL.Image.Image) -> tuple[int]:
+    """
+    Return two sequences representing the horizontal and vertical projection of the image.
+
+    Equivalent to
+    [`PIL.Image.Image.getprojection()`](https://pillow.readthedocs.io/en/stable/reference/Image.html#PIL.Image.Image.getprojection)
+    """
     pass
 
 
-@func.udf(substitute_fn=PIL.Image.Image.histogram)
-def histogram(self: PIL.Image.Image, mask: PIL.Image.Image, extrema: Optional[list] = None) -> Tuple[int]:
+@func.udf(substitute_fn=PIL.Image.Image.histogram, is_method=True)
+def histogram(
+        self: PIL.Image.Image, mask: Optional[PIL.Image.Image] = None, extrema: Optional[list] = None
+) -> list[int]:
+    """
+    Return a histogram for the image.
+
+    Equivalent to
+    [`PIL.Image.Image.histogram()`](https://pillow.readthedocs.io/en/stable/reference/Image.html#PIL.Image.Image.histogram)
+
+    Args:
+        mask: An optional mask image.
+        extrema: An optional list of extrema.
+    """
     pass
 
 
-@func.udf(substitute_fn=PIL.Image.Image.quantize)
+@func.udf(substitute_fn=PIL.Image.Image.quantize, is_method=True)
 def quantize(
     self: PIL.Image.Image,
     colors: int = 256,
@@ -170,14 +334,52 @@ def quantize(
     palette: Optional[int] = None,
     dither: int = PIL.Image.Dither.FLOYDSTEINBERG,
 ) -> PIL.Image.Image:
+    """
+     Convert the image to 'P' mode with the specified number of colors.
+
+     Equivalent to
+     [`PIL.Image.Image.quantize()`](https://pillow.readthedocs.io/en/stable/reference/Image.html#PIL.Image.Image.quantize)
+
+    Args:
+        colors: The number of colors to quantize to.
+        method: The quantization method. See the [Pillow documentation](https://pillow.readthedocs.io/en/stable/reference/Image.html#PIL.Image.Image.quantize) for a list of supported methods.
+        kmeans: The number of k-means clusters to use.
+        palette: The palette to use.
+        dither: The dithering method. See the [Pillow documentation](https://pillow.readthedocs.io/en/stable/reference/Image.html#PIL.Image.Image.quantize) for a list of supported methods.
+     """
     pass
 
 
-@func.udf(substitute_fn=PIL.Image.Image.reduce)
-def reduce(self: PIL.Image.Image, factor: int, box: Optional[Tuple[int]] = None) -> PIL.Image.Image:
+@func.udf(substitute_fn=PIL.Image.Image.reduce, is_method=True)
+def reduce(self: PIL.Image.Image, factor: int, box: Optional[tuple[int]] = None) -> PIL.Image.Image:
+    """
+    Reduce the image by the given factor.
+
+    Equivalent to
+    [`PIL.Image.Image.reduce()`](https://pillow.readthedocs.io/en/stable/reference/Image.html#PIL.Image.Image.reduce)
+
+    Args:
+        factor: The reduction factor.
+        box: An optional 4-tuple of ints providing the source image region to be reduced. The values must be within (0, 0, width, height) rectangle. If omitted or None, the entire source is used.
+    """
     pass
 
 
+@func.udf(is_property=True)
+def width(self: PIL.Image.Image) -> int:
+    return self.width
+
+
+@func.udf(is_property=True)
+def height(self: PIL.Image.Image) -> int:
+    return self.height
+
+
+@func.udf(is_property=True)
+def mode(self: PIL.Image.Image) -> str:
+    return self.mode
+
+
 __all__ = local_public_names(__name__)
 
 

pixeltable/functions/openai.py

@@ -1,3 +1,10 @@
+"""
+Pixeltable [UDFs](https://pixeltable.readme.io/docs/user-defined-functions-udfs)
+that wrap various endpoints from the OpenAI API. In order to use them, you must
+first `pip install openai` and configure your OpenAI credentials, as described in
+the [Working with OpenAI](https://pixeltable.readme.io/docs/working-with-openai) tutorial.
+"""
+
 import base64
 import io
 import pathlib
@@ -51,6 +58,33 @@ def _retry(fn: Callable) -> Callable:
 def speech(
     input: str, *, model: str, voice: str, response_format: Optional[str] = None, speed: Optional[float] = None
 ) -> str:
+    """
+    Generates audio from the input text.
+
+    Equivalent to the OpenAI `audio/speech` API endpoint.
+    For additional details, see: [https://platform.openai.com/docs/guides/text-to-speech](https://platform.openai.com/docs/guides/text-to-speech)
+
+    __Requirements:__
+
+    - `pip install openai`
+
+    Args:
+        input: The text to synthesize into speech.
+        model: The model to use for speech synthesis.
+        voice: The voice profile to use for speech synthesis. Supported options include:
+            `alloy`, `echo`, `fable`, `onyx`, `nova`, and `shimmer`.
+
+    For details on the other parameters, see: [https://platform.openai.com/docs/api-reference/audio/createSpeech](https://platform.openai.com/docs/api-reference/audio/createSpeech)
+
+    Returns:
+        An audio file containing the synthesized speech.
+
+    Examples:
+        Add a computed column that applies the model `tts-1` to an existing Pixeltable column `tbl.text`
+        of the table `tbl`:
+
+        >>> tbl['audio'] = speech(tbl.text, model='tts-1', voice='nova')
+    """
     content = _retry(_openai_client().audio.speech.create)(
         input=input, model=model, voice=voice, response_format=_opt(response_format), speed=_opt(speed)
     )
@@ -77,6 +111,31 @@ def transcriptions(
     prompt: Optional[str] = None,
     temperature: Optional[float] = None,
 ) -> dict:
+    """
+    Transcribes audio into the input language.
+
+    Equivalent to the OpenAI `audio/transcriptions` API endpoint.
+    For additional details, see: [https://platform.openai.com/docs/guides/speech-to-text](https://platform.openai.com/docs/guides/speech-to-text)
+
+    __Requirements:__
+
+    - `pip install openai`
+
+    Args:
+        audio: The audio to transcribe.
+        model: The model to use for speech transcription.
+
+    For details on the other parameters, see: [https://platform.openai.com/docs/api-reference/audio/createTranscription](https://platform.openai.com/docs/api-reference/audio/createTranscription)
+
+    Returns:
+        A dictionary containing the transcription and other metadata.
+
+    Examples:
+        Add a computed column that applies the model `whisper-1` to an existing Pixeltable column `tbl.audio`
+        of the table `tbl`:
+
+        >>> tbl['transcription'] = transcriptions(tbl.audio, model='whisper-1', language='en')
+    """
     file = pathlib.Path(audio)
     transcription = _retry(_openai_client().audio.transcriptions.create)(
         file=file, model=model, language=_opt(language), prompt=_opt(prompt), temperature=_opt(temperature)
@@ -86,6 +145,31 @@ def transcriptions(
 
 @pxt.udf(param_types=[ts.AudioType(), ts.StringType(), ts.StringType(nullable=True), ts.FloatType(nullable=True)])
 def translations(audio: str, *, model: str, prompt: Optional[str] = None, temperature: Optional[float] = None) -> dict:
+    """
+    Translates audio into English.
+
+    Equivalent to the OpenAI `audio/translations` API endpoint.
+    For additional details, see: [https://platform.openai.com/docs/guides/speech-to-text](https://platform.openai.com/docs/guides/speech-to-text)
+
+    __Requirements:__
+
+    - `pip install openai`
+
+    Args:
+        audio: The audio to translate.
+        model: The model to use for speech transcription and translation.
+
+    For details on the other parameters, see: [https://platform.openai.com/docs/api-reference/audio/createTranslation](https://platform.openai.com/docs/api-reference/audio/createTranslation)
+
+    Returns:
+        A dictionary containing the translation and other metadata.
+
+    Examples:
+        Add a computed column that applies the model `whisper-1` to an existing Pixeltable column `tbl.audio`
+        of the table `tbl`:
+
+        >>> tbl['translation'] = translations(tbl.audio, model='whisper-1', language='en')
+    """
     file = pathlib.Path(audio)
     translation = _retry(_openai_client().audio.translations.create)(
         file=file, model=model, prompt=_opt(prompt), temperature=_opt(temperature)
@@ -118,6 +202,35 @@ def chat_completions(
     tool_choice: Optional[dict] = None,
     user: Optional[str] = None,
 ) -> dict:
+    """
+    Creates a model response for the given chat conversation.
+
+    Equivalent to the OpenAI `chat/completions` API endpoint.
+    For additional details, see: [https://platform.openai.com/docs/guides/chat-completions](https://platform.openai.com/docs/guides/chat-completions)
+
+    __Requirements:__
+
+    - `pip install openai`
+
+    Args:
+        messages: A list of messages to use for chat completion, as described in the OpenAI API documentation.
+        model: The model to use for chat completion.
+
+    For details on the other parameters, see: [https://platform.openai.com/docs/api-reference/chat](https://platform.openai.com/docs/api-reference/chat)
+
+    Returns:
+        A dictionary containing the response and other metadata.
+
+    Examples:
+        Add a computed column that applies the model `gpt-4o-mini` to an existing Pixeltable column `tbl.prompt`
+        of the table `tbl`:
+
+        >>> messages = [
+                {'role': 'system', 'content': 'You are a helpful assistant.'},
+                {'role': 'user', 'content': tbl.prompt}
+            ]
+            tbl['response'] = chat_completions(messages, model='gpt-4o-mini')
+    """
     result = _retry(_openai_client().chat.completions.create)(
         messages=messages,
         model=model,
@@ -142,6 +255,30 @@ def chat_completions(
 
 @pxt.udf
 def vision(prompt: str, image: PIL.Image.Image, *, model: str) -> str:
+    """
+    Analyzes an image with the OpenAI vision capability. This is a convenience function that takes an image and
+    prompt, and constructs a chat completion request that utilizes OpenAI vision.
+
+    For additional details, see: [https://platform.openai.com/docs/guides/vision](https://platform.openai.com/docs/guides/vision)
+
+    __Requirements:__
+
+    - `pip install openai`
+
+    Args:
+        prompt: A prompt for the OpenAI vision request.
+        image: The image to analyze.
+        model: The model to use for OpenAI vision.
+
+    Returns:
+        The response from the OpenAI vision API.
+
+    Examples:
+        Add a computed column that applies the model `gpt-4o-mini` to an existing Pixeltable column `tbl.image`
+        of the table `tbl`:
+
+        >>> tbl['response'] = vision("What's in this image?", tbl.image, model='gpt-4o-mini')
+    """
     # TODO(aaron-siegel): Decompose CPU/GPU ops into separate functions
     bytes_arr = io.BytesIO()
     image.save(bytes_arr, format='png')
@@ -174,6 +311,33 @@ _embedding_dimensions_cache: dict[str, int] = {
 def embeddings(
     input: Batch[str], *, model: str, dimensions: Optional[int] = None, user: Optional[str] = None
 ) -> Batch[np.ndarray]:
+    """
+    Creates an embedding vector representing the input text.
+
+    Equivalent to the OpenAI `embeddings` API endpoint.
+    For additional details, see: [https://platform.openai.com/docs/guides/embeddings](https://platform.openai.com/docs/guides/embeddings)
+
+    __Requirements:__
+
+    - `pip install openai`
+
+    Args:
+        input: The text to embed.
+        model: The model to use for the embedding.
+        dimensions: The vector length of the embedding. If not specified, Pixeltable will use
+            a default value based on the model.
+
+    For details on the other parameters, see: [https://platform.openai.com/docs/api-reference/embeddings](https://platform.openai.com/docs/api-reference/embeddings)
+
+    Returns:
+        An array representing the application of the given embedding to `input`.
+
+    Examples:
+        Add a computed column that applies the model `text-embedding-3-small` to an existing
+        Pixeltable column `tbl.text` of the table `tbl`:
+
+        >>> tbl['embed'] = embeddings(tbl.text, model='text-embedding-3-small')
+    """
     result = _retry(_openai_client().embeddings.create)(
         input=input, model=model, dimensions=_opt(dimensions), user=_opt(user), encoding_format='float'
     )
@@ -204,6 +368,31 @@ def image_generations(
     style: Optional[str] = None,
     user: Optional[str] = None,
 ) -> PIL.Image.Image:
+    """
+    Creates an image given a prompt.
+
+    Equivalent to the OpenAI `images/generations` API endpoint.
+    For additional details, see: [https://platform.openai.com/docs/guides/images](https://platform.openai.com/docs/guides/images)
+
+    __Requirements:__
+
+    - `pip install openai`
+
+    Args:
+        prompt: Prompt for the image.
+        model: The model to use for the generations.
+
+    For details on the other parameters, see: [https://platform.openai.com/docs/api-reference/images/create](https://platform.openai.com/docs/api-reference/images/create)
+
+    Returns:
+        The generated image.
+
+    Examples:
+        Add a computed column that applies the model `dall-e-2` to an existing
+        Pixeltable column `tbl.text` of the table `tbl`:
+
+        >>> tbl['gen_image'] = image_generations(tbl.text, model='dall-e-2')
+    """
     # TODO(aaron-siegel): Decompose CPU/GPU ops into separate functions
     result = _retry(_openai_client().images.generate)(
         prompt=prompt,
@@ -241,6 +430,31 @@ def _(size: Optional[str] = None) -> ts.ImageType:
 
 @pxt.udf
 def moderations(input: str, *, model: Optional[str] = None) -> dict:
+    """
+    Classifies if text is potentially harmful.
+
+    Equivalent to the OpenAI `moderations` API endpoint.
+    For additional details, see: [https://platform.openai.com/docs/guides/moderation](https://platform.openai.com/docs/guides/moderation)
+
+    __Requirements:__
+
+    - `pip install openai`
+
+    Args:
+        input: Text to analyze with the moderations model.
+        model: The model to use for moderations.
+
+    For details on the other parameters, see: [https://platform.openai.com/docs/api-reference/moderations](https://platform.openai.com/docs/api-reference/moderations)
+
+    Returns:
+        Details of the moderations results.
+
+    Examples:
+        Add a computed column that applies the model `text-moderation-stable` to an existing
+        Pixeltable column `tbl.input` of the table `tbl`:
+
+        >>> tbl['moderations'] = moderations(tbl.text, model='text-moderation-stable')
+    """
     result = _retry(_openai_client().moderations.create)(input=input, model=_opt(model))
     return result.dict()