Add giphy tool [PHI-2206] (#1565)

## Description

This adds the GiphyTools and examples of how to search gifs as an agent.

## Type of change

Please check the options that are relevant:

- [ ] Bug fix (non-breaking change which fixes an issue)
- [x] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to not work as expected)
- [ ] Model update
- [ ] Infrastructure change

## Checklist

- [x] My code follows Phidata's style guidelines and best practices
- [x] I have performed a self-review of my code
- [x] I have added docstrings and comments for complex logic
- [x] My changes generate no new warnings or errors
- [x] I have added cookbook examples for my new addition (if needed)
- [x] I have updated requirements.txt/pyproject.toml (if needed)
- [x] I have verified my changes in a clean environment

---------

Co-authored-by: Dirk Brand <[email protected]>

.gitignore

@@ -47,3 +47,5 @@ agents.db
 data.db
 
 .ipynb_checkpoints
+
+*.db

cookbook/playground/multimodal_agent.py

@@ -9,6 +9,7 @@
 from phi.agent import Agent
 from phi.model.openai import OpenAIChat
 from phi.tools.dalle import Dalle
+from phi.tools.giphy import GiphyTools
 from phi.tools.models_labs import ModelsLabs
 from phi.model.response import FileType
 from phi.playground import Playground, serve_playground_app
@@ -85,8 +86,24 @@
     storage=SqlAgentStorage(table_name="fal_agent", db_file=image_agent_storage_file),
 )
 
+gif_agent = Agent(
+    name="Gif Generator Agent",
+    model=OpenAIChat(id="gpt-4o"),
+    tools=[GiphyTools()],
+    description="You are an AI agent that can generate gifs using Giphy.",
+    instructions=[
+        "When the user asks you to create a gif, come up with the appropriate Giphy query and use the `search_gifs` tool to find the appropriate gif.",
+        "Don't return the URL, only describe what you created.",
+    ],
+    markdown=True,
+    debug_mode=True,
+    add_history_to_messages=True,
+    add_datetime_to_instructions=True,
+    storage=SqlAgentStorage(table_name="gif_agent", db_file=image_agent_storage_file),
+)
+
 
-app = Playground(agents=[image_agent, ml_gif_agent, ml_video_agent, fal_agent]).get_app(use_async=False)
+app = Playground(agents=[image_agent, ml_gif_agent, ml_video_agent, fal_agent, gif_agent]).get_app(use_async=False)
 
 if __name__ == "__main__":
     serve_playground_app("multimodal_agent:app", reload=True)

cookbook/tools/giphy_tool.py

@@ -0,0 +1,19 @@
+from phi.agent import Agent
+from phi.model.openai import OpenAIChat
+from phi.tools.giphy import GiphyTools
+
+"""Create an agent specialized in creating gifs using Giphy """
+
+gif_agent = Agent(
+    name="Gif Generator Agent",
+    model=OpenAIChat(id="gpt-4o"),
+    tools=[GiphyTools(limit=5)],
+    description="You are an AI agent that can generate gifs using Giphy.",
+    instructions=[
+        "When the user asks you to create a gif, come up with the appropriate Giphy query and use the `search_gifs` tool to find the appropriate gif.",
+    ],
+    debug_mode=True,
+    show_tool_calls=True,
+)
+
+gif_agent.print_response("I want a gif to send to a friend for their birthday.")

phi/model/content.py

@@ -14,5 +14,6 @@ class Video(BaseModel):
 class Image(BaseModel):
     id: str
     url: str
+    alt_text: Optional[str] = None
     original_prompt: Optional[str] = None
     revised_prompt: Optional[str] = None

phi/tools/giphy.py

@@ -0,0 +1,71 @@
+import os
+import uuid
+from typing import Optional
+
+import httpx
+
+from phi.agent import Agent
+from phi.model.content import Image
+from phi.tools import Toolkit
+from phi.utils.log import logger
+
+
+class GiphyTools(Toolkit):
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        limit: int = 1,
+    ):
+        super().__init__(name="giphy_tools")
+
+        self.api_key = api_key or os.getenv("GIPHY_API_KEY")
+        if not self.api_key:
+            logger.error("No Giphy API key provided")
+
+        self.limit: int = limit
+
+        self.register(self.search_gifs)
+
+    def search_gifs(self, agent: Agent, query: str) -> str:
+        """Find a GIPHY gif
+
+        Args:
+            query (str): A text description of the required gif.
+
+        Returns:
+            result (str): A string containing urls of GIFs found
+        """
+
+        base_url = "https://api.giphy.com/v1/gifs/search"
+        params = {
+            "api_key": self.api_key,
+            "q": query,
+            "limit": self.limit,
+        }
+
+        try:
+            response = httpx.get(base_url, params=params)
+            response.raise_for_status()
+
+            # Extract the GIF URLs
+            data = response.json()
+            gif_urls = []
+            for gif in data.get("data", []):
+                images = gif.get("images", {})
+                original_image = images["original"]
+
+                media_id = str(uuid.uuid4())
+                gif_url = original_image["url"]
+                alt_text = gif["alt_text"]
+                gif_urls.append(gif_url)
+
+                agent.add_image(Image(id=media_id, url=gif_url, alt_text=alt_text, revised_prompt=query))
+
+            return f"These are the found gifs {gif_urls}"
+
+        except httpx.HTTPStatusError as e:
+            logger.error(f"HTTP error occurred: {e.response.status_code} - {e.response.text}")
+        except Exception as e:
+            logger.error(f"An error occurred: {e}")
+
+        return "No gifs found"