Merge pull request #781 from PrefectHQ/model-params

Add docs on model parameters

docs/docs/audio/speech.md

@@ -95,11 +95,21 @@ ai_say('hello')
       Your browser does not support the audio element.
     </audio>
 
+## Choosing a voice
+
+Both `speak` and `@speech` accept a `voice` parameter that allows you to choose from a variety of voices. You can preview the available voices [here](https://platform.openai.com/docs/guides/text-to-speech/voice-options).
+
+```python
+
 ## Saving audio files
 
 The result of the `speak` function and `@speech` decorator is an audio stream. You can save this stream to disk like this:
 
 ```python
 audio = marvin.speak("Hello, world!")
 audio.stream_to_file("hello_world.mp3")
-```
+```
+
+
+## Model parameters
+You can pass parameters to the underlying API via the `model_kwargs` arguments of `speak` and `@speech`. These parameters are passed directly to the respective APIs, so you can use any supported parameter.

docs/docs/text/classification.md

@@ -166,6 +166,9 @@ assert issue == IssueType.BUG
 
 While convenient for certain scenarios, it's recommended to use the `classify` function for its greater flexibility and broader application range.
 
+## Model parameters
+You can pass parameters to the underlying API via the `model_kwargs` argument of `classify` or `@classifier`. These parameters are passed directly to the API, so you can use any supported parameter.
+
 ## Best practices
 
 1. **Choosing the right labels**: Opt for labels that are mutually exclusive and collectively exhaustive for your classification context. This ensures clarity and prevents overlaps in categorization.

docs/docs/text/extraction.md

@@ -152,3 +152,6 @@ marvin.cast('Mass.', to=str, instruction="The state's abbreviation")
 # MA
 ```
 
+
+## Model parameters
+You can pass parameters to the underlying API via the `model_kwargs` argument of `extract`. These parameters are passed directly to the API, so you can use any supported parameter.

docs/docs/text/functions.md

@@ -290,4 +290,8 @@ summarize_url('https://www.askmarvin.ai')
 ```
 
 ## Running a function
-Running a function is quite simple: just call it like you would any other function! The LLM will generate the output based on the function's definition and the provided inputs. Remember that no source code is generated or executed, so every call to the function will be handled by the LLM. You can use caching or other techniques to improve performance if necessary.
+Running a function is quite simple: just call it like you would any other function! The LLM will generate the output based on the function's definition and the provided inputs. Remember that no source code is generated or executed, so every call to the function will be handled by the LLM. You can use caching or other techniques to improve performance if necessary.
+
+
+## Model parameters
+You can pass parameters to the underlying API via the `model_kwargs` argument of `@fn`. These parameters are passed directly to the API, so you can use any supported parameter.

docs/docs/text/generation.md

@@ -124,6 +124,10 @@ Data generation relies even more on instructions than other Marvin tools, as the
 
 Instructions are freeform natural language and can be as general or specific as you like. The LLM will do its best to comply with any instructions you give.
 
+
+## Model parameters
+You can pass parameters to the underlying API via the `model_kwargs` argument of `generate`. These parameters are passed directly to the API, so you can use any supported parameter.
+
 ## Caching
 
 Normally, each `generate` call would be independent. For some prompts, this would mean that each call produced very similar results to other calls. That would mean that generating, say, 10 items in a single call would produce a much more varied and high-quality result than generating 10 items in 5 calls of 2 items each.
@@ -207,4 +211,4 @@ The first and second tabs both show high-quality, varied results. The third tab
             'Los Angeles',
             'Houston'
         ]
-        ```
+        ```

docs/docs/text/transformation.md

@@ -111,4 +111,7 @@ class Location(marvin.Model):
 
 Location('CHI')
 # Location(city="Chicago", state="IL")
-```
+```
+
+## Model parameters
+You can pass parameters to the underlying API via the `model_kwargs` argument of `cast` or `@model`. These parameters are passed directly to the API, so you can use any supported parameter.

docs/docs/vision/captioning.md

@@ -40,3 +40,8 @@ Marvin can use OpenAI's vision API to process images as inputs.
   </p>
 </div>
 
+
+
+
+## Model parameters
+You can pass parameters to the underlying API via the `model_kwargs` argument of `caption`. These parameters are passed directly to the API, so you can use any supported parameter.

docs/docs/vision/classification.md

@@ -55,3 +55,9 @@ The `marvin.beta.classify` function is an enhanced version of `marvin.classify`
         assert animal == 'dog'
         assert dry_or_wet == 'wet'
         ```
+
+
+
+
+## Model parameters
+You can pass parameters to the underlying API via the `model_kwargs` and `vision_model_kwargs` arguments of `classify`. These parameters are passed directly to the respective APIs, so you can use any supported parameter.

docs/docs/vision/extraction.md

@@ -48,3 +48,6 @@ The `marvin.beta.extract` function is an enhanced version of `marvin.extract` th
         ```python
         result == ["Pembroke Welsh Corgi", "Yorkshire Terrier"]
         ```    
+
+## Model parameters
+You can pass parameters to the underlying API via the `model_kwargs` and `vision_model_kwargs` arguments of `extract`. These parameters are passed directly to the respective APIs, so you can use any supported parameter.

docs/docs/vision/transformation.md

@@ -113,3 +113,6 @@ If the target type isn't self-documenting, or you want to provide additional gui
         ```python
         assert missing_items == ["eggs", "oranges"]
         ```
+
+## Model parameters
+You can pass parameters to the underlying API via the `model_kwargs` and `vision_model_kwargs` arguments of `cast`. These parameters are passed directly to the respective APIs, so you can use any supported parameter.

src/marvin/ai/audio.py

@@ -80,7 +80,12 @@ def speak(
     return response
 
 
-def speech(fn: Optional[Callable] = None, *, voice: Optional[str] = None) -> Callable:
+def speech(
+    fn: Optional[Callable] = None,
+    *,
+    voice: Optional[str] = None,
+    model_kwargs: Optional[dict] = None,
+) -> Callable:
     """
     Function decorator that generates audio from the wrapped function's return
     value. The voice used for the audio can be specified.
@@ -93,11 +98,11 @@ def speech(fn: Optional[Callable] = None, *, voice: Optional[str] = None) -> Cal
         Callable: The wrapped function.
     """
     if fn is None:
-        return partial(speech, voice=voice)
+        return partial(speech, voice=voice, model_kwargs=model_kwargs)
 
     @wraps(fn)
     def wrapper(*args, **kwargs):
         model = PythonFunction.from_function_call(fn, *args, **kwargs)
-        return speak(text=model.return_value, voice=voice)
+        return speak(text=model.return_value, voice=voice, model_kwargs=model_kwargs)
 
     return wrapper