Add docstrings and api ref for new core tools

docs/api_reference/core/audio.md

@@ -0,0 +1,2 @@
+# Audio tools
+::: marvin.core.audio

docs/api_reference/core/images.md

@@ -0,0 +1,2 @@
+# Image tools
+::: marvin.core.images

docs/api_reference/core/text.md

@@ -0,0 +1,2 @@
+# Text tools
+::: marvin.core.text

docs/static/css/mkdocstrings.css

@@ -0,0 +1,29 @@
+/* https://mkdocstrings.github.io/python/usage/customization/#style-recommendations */
+
+/* Indentation. */
+div.doc-contents:not(.first) {
+  padding-left: 25px;
+  border-left: .05rem solid var(--md-typeset-table-color);
+}
+
+/* Mark external links as such. */
+a.external::after,
+a.autorefs-external::after {
+  /* https://primer.style/octicons/arrow-up-right-24 */
+  mask-image: url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M18.25 15.5a.75.75 0 00.75-.75v-9a.75.75 0 00-.75-.75h-9a.75.75 0 000 1.5h7.19L6.22 16.72a.75.75 0 101.06 1.06L17.5 7.56v7.19c0 .414.336.75.75.75z"></path></svg>');
+  -webkit-mask-image: url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M18.25 15.5a.75.75 0 00.75-.75v-9a.75.75 0 00-.75-.75h-9a.75.75 0 000 1.5h7.19L6.22 16.72a.75.75 0 101.06 1.06L17.5 7.56v7.19c0 .414.336.75.75.75z"></path></svg>');
+  content: ' ';
+
+  display: inline-block;
+  vertical-align: middle;
+  position: relative;
+
+  height: 1em;
+  width: 1em;
+  background-color: var(--md-typeset-a-color);
+}
+
+a.external:hover::after,
+a.autorefs-external:hover::after {
+  background-color: var(--md-accent-fg-color);
+}

mkdocs.yml

@@ -18,16 +18,15 @@ nav:
   - Docs:
     - Overview: welcome/overview.md
 
+    - General purpose:
+      - AI Functions: core/function.md
 
-    - LLMs:
+    - Text and data:
       - Structured data: core/casting.md
       - Entity extraction: core/extraction.md
       - Classification: core/classification.md
       - Generating synthetic data: core/generation.md
 
-    - General purpose:
-      - Function: core/function.md
-
     - Images:
       - Generation: core/painting.md
       # - Captioning: core/function.md
@@ -44,10 +43,11 @@ nav:
     #   - GitHub Digest: examples/github_digest.md
   - API reference:
     - api_reference/index.md
-    - AI components:
-      - classifier: api_reference/components/classifier.md
-      - function: api_reference/components/functions.md
-      - model: api_reference/components/models.md
+    - Core tools:
+      - Text & Data: api_reference/core/text.md
+      - Images: api_reference/core/images.md
+      - Audio: api_reference/core/audio.md
+
     - Settings:
       - settings: api_reference/settings.md
     - Utilities:
@@ -156,4 +156,5 @@ extra:
 extra_css:
   - /static/css/global.css
   - /static/css/badges.css
-  - /static/css/custom.css
+  - /static/css/custom.css
+  - /static/css/mkdocstrings.css

src/marvin/core/audio.py

@@ -1,5 +1,5 @@
-from functools import wraps
-from typing import Callable, Literal, TypeVar
+from functools import partial, wraps
+from typing import Callable, Literal, Optional, TypeVar
 
 from openai._base_client import HttpxBinaryResponseContent
 
@@ -38,7 +38,20 @@ def speak(
     model_kwargs: dict = None,
 ):
     """
-    Use an AI to generate audio from text.
+    Generates audio from text using an AI.
+
+    This function uses an AI to generate audio from the provided text. The voice
+    used for the audio can be specified.
+
+    Args:
+        text (str): The text to generate audio from.
+        voice (Literal["alloy", "echo", "fable", "onyx", "nova", "shimmer"], optional):
+            The voice to use for the audio. Defaults to None.
+        model_kwargs (dict, optional): Additional keyword arguments for the
+            language model. Defaults to None.
+
+    Returns:
+        HttpxBinaryResponseContent: The generated audio.
     """
     model_kwargs = model_kwargs or {}
     if voice is not None:
@@ -51,15 +64,24 @@ def speak(
     return response
 
 
-def speech(fn: Callable):
+def speech(fn: Optional[Callable] = None, *, voice: Optional[str] = None) -> Callable:
     """
     Function decorator that generates audio from the wrapped function's return
-    value.
+    value. The voice used for the audio can be specified.
+
+    Args:
+        fn (Callable, optional): The function to wrap. Defaults to None.
+        voice (str, optional): The voice to use for the audio. Defaults to None.
+
+    Returns:
+        Callable: The wrapped function.
     """
+    if fn is None:
+        return partial(speech, voice=voice)
 
     @wraps(fn)
     def wrapper(*args, **kwargs):
         model = PythonFunction.from_function_call(fn, *args, **kwargs)
-        return speak(text=model.return_value)
+        return speak(text=model.return_value, voice=voice)
 
     return wrapper

src/marvin/core/images.py

@@ -40,10 +40,24 @@ def paint(
     model_kwargs: dict = None,
 ):
     """
-    Generates an image from the provided instructions and context.
+    Generates an image based on the provided instructions and context.
 
-    By default, the DALLE-3 API modifies prompts to add detail and style. To
-    disable this behavior, set `literal=True`.
+    This function uses the DALLE-3 API to generate an image based on the provided
+    instructions and context. By default, the API modifies prompts to add detail
+    and style. This behavior can be disabled by setting `literal=True`.
+
+    Args:
+        instructions (str, optional): The instructions for the image generation.
+            Defaults to None.
+        context (dict, optional): The context for the image generation. Defaults to None.
+        literal (bool, optional): Whether to disable the API's default behavior of
+            modifying prompts. Defaults to False.
+        model_kwargs (dict, optional): Additional keyword arguments for the
+            language model. Defaults to None.
+
+    Returns:
+        ImagesResponse: The response from the DALLE-3 API, which includes the
+            generated image.
     """
     response = generate_image(
         prompt_template=IMAGE_PROMPT,