Merge pull request #802 from PrefectHQ/async-utils

async first utils and expose sync versions

Author: zzstoatzz

docs/docs/text/classification.md

@@ -174,4 +174,17 @@ You can pass parameters to the underlying API via the `model_kwargs` argument of
 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.
 2. **Effective use of instructions**: Provide clear, concise, and contextually relevant instructions. This enhances the accuracy of the classification, especially in ambiguous or complex cases.
 3. **Iterative testing and refinement**: Continuously test and refine your classification criteria and instructions based on real-world feedback. This iterative process helps in fine-tuning the classification logic for better results.
-4. **Prefer `classify()` over `@classifier`**: `classify()` is more versatile and adaptable for a wide range of scenarios. It should be the primary tool for classification tasks in Marvin.
+4. **Prefer `classify()` over `@classifier`**: `classify()` is more versatile and adaptable for a wide range of scenarios. It should be the primary tool for classification tasks in Marvin.
+
+## Async support
+
+If you are using Marvin in an async environment, you can use `classify_async`:
+
+```python
+result = await marvin.classify_async(
+    "The app crashes when I try to upload a file.", 
+    labels=["bug", "feature request", "inquiry"]
+) 
+
+assert result == "bug"
+```

docs/docs/text/extraction.md

@@ -155,3 +155,16 @@ marvin.cast('Mass.', to=str, instructions="The state's abbreviation")
 
 ## 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.
+
+## Async support
+If you are using Marvin in an async environment, you can use `extract_async`:
+  
+```python
+result = await marvin.extract_async(
+    "I drove from New York to California.",
+    target=str,
+    instructions="2-letter state codes",
+) 
+
+assert result == ["NY", "CA"]
+```

docs/docs/text/functions.md

@@ -295,3 +295,16 @@ Running a function is quite simple: just call it like you would any other functi
 
 ## 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.
+
+## Async support
+Async functions can be decorated just like regular functions. The result is still async and must be awaited.  
+
+```python
+@marvin.fn
+async def list_fruit(n: int) -> list[str]:
+    """
+    Returns a list of `n` fruit.
+    """
+
+await list_fruit(n=3)
+```

docs/docs/text/generation.md

@@ -212,3 +212,15 @@ The first and second tabs both show high-quality, varied results. The third tab
             'Houston'
         ]
         ```
+
+## Async support
+If you are using Marvin in an async environment, you can use `generate_async`:
+  
+```python
+cat_names = await marvin.generate_async(
+    n=4, 
+    instructions="names for cats inspired by Chance the Rapper"
+)
+
+# ['Chancey', 'Rappurr', 'Lyric', 'Chano']
+```

docs/docs/text/transformation.md

@@ -115,3 +115,12 @@ Location('CHI')
 
 ## 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.
+
+## Async support
+If you are using `marvin` in an async environment, you can use `cast_async`:
+
+```python
+result = await marvin.cast_async("one", int) 
+
+assert result == 1
+```

docs/docs/vision/captioning.md

@@ -45,3 +45,13 @@ Marvin can use OpenAI's vision API to process images as inputs.
 
 ## 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.
+
+
+
+## Async support
+
+If you are using Marvin in an async environment, you can use `caption_async`:
+
+```python
+caption = await marvin.beta.caption_async(image=Path('/path/to/marvin.png'))
+```

docs/docs/vision/classification.md

@@ -60,4 +60,18 @@ The `marvin.beta.classify` function is an enhanced version of `marvin.classify`
 
 
 ## 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.
+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.
+
+
+## Async support
+
+If you are using Marvin in an async environment, you can use `classify_async`:
+
+```python
+result = await marvin.beta.classify_async(
+    "The app crashes when I try to upload a file.", 
+    labels=["bug", "feature request", "inquiry"]
+) 
+
+assert result == "bug"
+```

docs/docs/vision/extraction.md

@@ -51,3 +51,17 @@ The `marvin.beta.extract` function is an enhanced version of `marvin.extract` th
 
 ## 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.
+
+
+## Async support
+If you are using Marvin in an async environment, you can use `extract_async`:
+  
+```python
+result = await marvin.beta.extract_async(
+    "I drove from New York to California.",
+    target=str,
+    instructions="2-letter state codes",
+) 
+
+assert result == ["NY", "CA"]
+```

docs/docs/vision/transformation.md

@@ -115,4 +115,13 @@ If the target type isn't self-documenting, or you want to provide additional gui
         ```
 
 ## 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.
+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.
+
+## Async support
+If you are using `marvin` in an async environment, you can use `cast_async`:
+
+```python
+result = await marvin.beta.cast_async("one", int) 
+
+assert result == 1
+```

src/marvin/__init__.py

@@ -1,6 +1,19 @@
 from .settings import settings
 
-from .ai.text import fn, cast, extract, classify, classifier, generate, model, Model
+from .ai.text import (
+    fn,
+    cast,
+    cast_async,
+    extract,
+    extract_async,
+    classify,
+    classify_async,
+    classifier,
+    generate,
+    generate_async,
+    model,
+    Model,
+)
 from .ai.images import paint, image
 from .ai.audio import speak, speech
 from . import beta
@@ -15,11 +28,15 @@
     # --- text ---
     "Model",
     "cast",
+    "cast_async",
     "classify",
+    "classify_async",
     "classifier",
     "extract",
+    "extract_async",
     "fn",
     "generate",
+    "generate_async",
     "model",
     # --- images ---
     "image",