docs: add usage examples to docstrings of multimodal components (#340)

* docs: add usage examples to docstrings of multimodal components

* fix errors

Author: anakin87

haystack_experimental/components/converters/image/document_to_image.py

@@ -34,7 +34,7 @@ class DocumentToImageContent:
     - A supported image format (MIME type must be one of the supported image types)
     - For PDF files, a `page_number` key specifying which page to extract
 
-    Usage example:
+    ### Usage example
         ```python
         from haystack import Document
         from haystack_experimental.components.image_converters.document_to_image import DocumentToImageContent

haystack_experimental/components/converters/image/file_to_image.py

@@ -31,6 +31,24 @@
 class ImageFileToImageContent:
     """
     Converts image files to ImageContent objects.
+
+    ### Usage example
+    ```python
+    from haystack_experimental.components.converters.image import ImageFileToImageContent
+
+    converter = ImageFileToImageContent()
+
+    sources = ["image.jpg", "another_image.png"]
+
+    image_contents = converter.run(sources=sources)["image_contents"]
+    print(image_contents)
+
+    # [ImageContent(base64_image='...',
+    #               mime_type='image/jpeg',
+    #               detail=None,
+    #               meta={'file_path': 'image.jpg'}),
+    #  ...]
+    ```
     """
 
     def __init__(

haystack_experimental/components/converters/image/image_to_document.py

@@ -23,6 +23,23 @@ class ImageFileToDocument:
 
     It does **not** extract any content from the image files, instead it creates `Document` objects with `None` as
     their content and attaches metadata such as file path and any user-provided values.
+
+    ### Usage example
+    ```python
+    from haystack_experimental.components.converters.image import ImageFileToDocument
+
+    converter = ImageFileToDocument()
+
+    sources = ["image.jpg", "another_image.png"]
+
+    result = converter.run(sources=sources)
+    documents = result["documents"]
+
+    print(documents)
+
+    # [Document(id=..., meta: {'file_path': 'image.jpg'}),
+    # Document(id=..., meta: {'file_path': 'another_image.png'})]
+    ```
     """
 
     def __init__(self, *, store_full_path: bool = False):

haystack_experimental/components/converters/image/pdf_to_image.py

@@ -24,6 +24,24 @@
 class PDFToImageContent:
     """
     Converts PDF files to ImageContent objects.
+
+    ### Usage example
+    ```python
+    from haystack_experimental.components.converters.image import PDFToImageContent
+
+    converter = PDFToImageContent()
+
+    sources = ["file.pdf", "another_file.pdf"]
+
+    image_contents = converter.run(sources=sources)["image_contents"]
+    print(image_contents)
+
+    # [ImageContent(base64_image='...',
+    #               mime_type='application/pdf',
+    #               detail=None,
+    #               meta={'file_path': 'file.pdf', 'page_number': 1}),
+    #  ...]
+    ```
     """
 
     def __init__(

haystack_experimental/components/embedders/image/sentence_transformers_doc_image_embedder.py

@@ -33,6 +33,31 @@ class SentenceTransformersDocumentImageEmbedder:
     A component for computing Document embeddings based on images using Sentence Transformers models.
 
     The embedding of each Document is stored in the `embedding` field of the Document.
+
+    ### Usage example
+    ```python
+    from haystack import Document
+    from haystack_experimental.components.embedders.image import SentenceTransformersDocumentImageEmbedder
+
+    embedder = SentenceTransformersDocumentImageEmbedder(model="sentence-transformers/clip-ViT-B-32")
+    embedder.warm_up()
+
+    documents = [
+        Document(content="A photo of a cat", meta={"file_path": "cat.jpg"}),
+        Document(content="A photo of a dog", meta={"file_path": "dog.jpg"}),
+    ]
+
+    result = embedder.run(documents=documents)
+    documents_with_embeddings = result["documents"]
+    print(documents_with_embeddings)
+
+    # [Document(id=...,
+    #           content='A photo of a cat',
+    #           meta={'file_path': 'cat.jpg',
+    #                 'embedding_source': {'type': 'image', 'file_path_meta_field': 'file_path'}},
+    #           embedding=vector of size 512),
+    #  ...]
+    ```
     """
 
     def __init__(

haystack_experimental/components/generators/chat/amazon_bedrock.py

@@ -39,6 +39,23 @@
     class AmazonBedrockChatGenerator:
         """
         Experimental version of AmazonBedrockChatGenerator that allows multimodal chat messages.
+
+        ### Usage example
+        ```python
+        from haystack_experimental.components.generators.chat import AmazonBedrockChatGenerator
+        from haystack_experimental.dataclasses import ChatMessage, ImageContent
+
+        generator = AmazonBedrockChatGenerator(model="anthropic.claude-3-5-sonnet-20240620-v1:0")
+
+        image_content = ImageContent.from_file_path(file_path="apple.jpg")
+
+        message = ChatMessage.from_user(content_parts=["Describe the image using 10 words at most.", image_content])
+
+        response = generator.run(messages=[message])["replies"][0].text
+
+        print(response)
+        # The image shows a red apple.
+        ```
         """
 
         def __init__(  # pylint: disable=too-many-positional-arguments

haystack_experimental/components/generators/chat/openai.py

@@ -16,6 +16,23 @@
 class OpenAIChatGenerator(haystack.components.generators.chat.openai.OpenAIChatGenerator):
     """
     Experimental version of OpenAIChatGenerator that allows multimodal chat messages.
+
+    ### Usage example
+    ```python
+    from haystack_experimental.components.generators.chat import OpenAIChatGenerator
+    from haystack_experimental.dataclasses import ChatMessage, ImageContent
+
+    generator = OpenAIChatGenerator(model="gpt-4o-mini")
+
+    image_content = ImageContent.from_file_path(file_path="apple.jpg")
+
+    message = ChatMessage.from_user(content_parts=["Please describe the image using 5 words at most.", image_content])
+
+    response = generator.run(messages=[message])["replies"][0].text
+
+    print(response)
+    # Red apple on straw background.
+    ```
     """
 
     pass

haystack_experimental/components/query/query_expander.py

@@ -61,7 +61,7 @@ class QueryExpander:
     {"queries": ["expanded query 1", "expanded query 2", "expanded query 3"]}
     ```
 
-    Usage example:
+    ### Usage example
 
     ```python
     from haystack.components.generators.chat.openai import OpenAIChatGenerator