feat: add UrlArtifact, ImageUrlArtifact (#1913)

Closes #1359

Author: collindutter

docs/griptape-framework/data/artifacts.md

@@ -23,6 +23,14 @@ When `BlobArtifact`s are returned from Tools, they will be stored in [Task Memor
 
 [ImageArtifact](../../reference/griptape/artifacts/image_artifact.md)s store image data. This includes binary image data along with metadata such as MIME type and dimensions. They are a subclass of [BlobArtifacts](#blob).
 
+### Url
+
+[UrlArtifact](../../reference/griptape/artifacts/url_artifact.md)s store URLs pointing to resources.
+
+### Image Url
+
+[ImageUrlArtifact](../../reference/griptape/artifacts/image_url_artifact.md)s store URLs pointing to images. They are a subclass of [UrlArtifact](#url).
+
 ### Audio
 
 [AudioArtifact](../../reference/griptape/artifacts/audio_artifact.md)s store audio content. This includes binary audio data and metadata such as format, and duration. They are a subclass of [BlobArtifacts](#blob).

griptape/artifacts/__init__.py

@@ -4,9 +4,11 @@
 from .text_artifact import TextArtifact
 from .json_artifact import JsonArtifact
 from .blob_artifact import BlobArtifact
+from .url_artifact import UrlArtifact
 from .boolean_artifact import BooleanArtifact
 from .list_artifact import ListArtifact
 from .image_artifact import ImageArtifact
+from .image_url_artifact import ImageUrlArtifact
 from .audio_artifact import AudioArtifact
 from .action_artifact import ActionArtifact
 from .generic_artifact import GenericArtifact
@@ -18,10 +20,12 @@
     "AudioArtifact",
     "BaseArtifact",
     "BlobArtifact",
+    "UrlArtifact",
     "BooleanArtifact",
     "ErrorArtifact",
     "GenericArtifact",
     "ImageArtifact",
+    "ImageUrlArtifact",
     "InfoArtifact",
     "JsonArtifact",
     "ListArtifact",

griptape/artifacts/audio_artifact.py

@@ -29,7 +29,7 @@ def __attrs_post_init__(self) -> None:
     def mime_type(self) -> str:
         return f"audio/{self.format}"
 
-    def to_bytes(self) -> bytes:
+    def to_bytes(self, **kwargs) -> bytes:
         return self.value
 
     def to_text(self) -> str:

griptape/artifacts/base_artifact.py

@@ -49,7 +49,7 @@ def __bool__(self) -> bool:
     def __len__(self) -> int:
         return len(self.value)
 
-    def to_bytes(self) -> bytes:
+    def to_bytes(self, **kwargs) -> bytes:
         return self.to_text().encode(encoding=self.encoding, errors=self.encoding_error_handler)
 
     @abstractmethod

griptape/artifacts/blob_artifact.py

@@ -28,7 +28,7 @@ def base64(self) -> str:
     def mime_type(self) -> str:
         return "application/octet-stream"
 
-    def to_bytes(self) -> bytes:
+    def to_bytes(self, **kwargs) -> bytes:
         return self.value
 
     def to_text(self) -> str:

griptape/artifacts/image_artifact.py

@@ -33,7 +33,7 @@ def __attrs_post_init__(self) -> None:
     def mime_type(self) -> str:
         return f"image/{self.format}"
 
-    def to_bytes(self) -> bytes:
+    def to_bytes(self, **kwargs) -> bytes:
         return self.value
 
     def to_text(self) -> str:

griptape/artifacts/image_url_artifact.py

@@ -0,0 +1,9 @@
+from griptape.artifacts.url_artifact import UrlArtifact
+
+
+class ImageUrlArtifact(UrlArtifact):
+    """Stores a url to an image.
+
+    Attributes:
+        value: The url.
+    """

griptape/artifacts/url_artifact.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+import requests
+from attrs import define, field
+
+from griptape.artifacts import BaseArtifact
+
+
+@define
+class UrlArtifact(BaseArtifact):
+    """Stores a url.
+
+    Attributes:
+        value: The url.
+    """
+
+    value: str = field(metadata={"serializable": True})
+
+    def to_bytes(self, *, headers: dict | None = None, **kwargs) -> bytes:
+        """Fetches the content of the URL and returns it as bytes.
+
+        Args:
+            headers: Optional headers to include in the request.
+            **kwargs: Additional keyword arguments, not used.
+
+        Returns:
+            bytes: The content of the URL as bytes.
+
+        """
+        response = requests.get(self.value, headers=headers)
+        response.raise_for_status()
+
+        return response.content
+
+    def to_text(self) -> str:
+        """Returns the URL as is."""
+        return self.value

tests/unit/artifacts/test_image_url_artifact.py

@@ -0,0 +1,8 @@
+from griptape.artifacts import ImageUrlArtifact
+
+
+class TestImageUrlArtifact:
+    def test_init(self):
+        assert ImageUrlArtifact(
+            value="some url",
+        )

tests/unit/artifacts/test_url_artifact.py

@@ -0,0 +1,46 @@
+from unittest.mock import Mock
+
+import pytest
+
+from griptape.artifacts import BaseArtifact, UrlArtifact
+
+
+class TestUrlArtifact:
+    @pytest.fixture()
+    def url_artifact(self):
+        return UrlArtifact(
+            value="some url",
+        )
+
+    @pytest.fixture(autouse=True)
+    def mock_get(self, mocker):
+        mock_response = Mock(content=b"some binary data", status_code=200)
+
+        return mocker.patch("requests.get", return_value=mock_response)
+
+    def test_to_text(self, url_artifact: UrlArtifact):
+        assert url_artifact.to_text() == "some url"
+
+    def test_to_dict(self, url_artifact: UrlArtifact):
+        image_dict = url_artifact.to_dict()
+
+        assert image_dict["value"] == "some url"
+
+    def test_deserialization(self, url_artifact):
+        artifact_dict = url_artifact.to_dict()
+        deserialized_artifact = BaseArtifact.from_dict(artifact_dict)
+
+        assert isinstance(deserialized_artifact, UrlArtifact)
+
+        assert deserialized_artifact.value == "some url"
+
+    @pytest.mark.parametrize(
+        "headers",
+        [
+            None,
+            {},
+            {"Authorization": "Bearer some_token"},
+        ],
+    )
+    def test_to_bytes(self, url_artifact, headers):
+        assert url_artifact.to_bytes(headers=headers) == b"some binary data"