agno 0.1.2__py3-none-any.whl → 2.3.13__py3-none-any.whl

agno/tools/exa.py

@@ -1,24 +1,64 @@
 import json
+from concurrent.futures import ThreadPoolExecutor, TimeoutError
 from os import getenv
-from typing import Any, Dict, List, Optional
+from typing import Any, Dict, List, Literal, Optional
 
 from agno.tools import Toolkit
-from agno.utils.log import logger
+from agno.utils.log import log_debug, log_info, logger
 
 try:
     from exa_py import Exa
+    from exa_py.api import SearchResponse
 except ImportError:
     raise ImportError("`exa_py` not installed. Please install using `pip install exa_py`")
 
 
 class ExaTools(Toolkit):
+    """
+    ExaTools is a toolkit for interfacing with the Exa web search engine, providing
+    functionalities to perform categorized searches and retrieve structured results.
+
+    Args:
+        enable_search (bool): Enable search functionality. Default is True.
+        enable_get_contents (bool): Enable get contents functionality. Default is True.
+        enable_find_similar (bool): Enable find similar functionality. Default is True.
+        enable_answer (bool): Enable answer generation. Default is True.
+        enable_research (bool): Enable research tool functionality. Default is False.
+        all (bool): Enable all tools. Overrides individual flags when True. Default is False.
+        text (bool): Retrieve text content from results. Default is True.
+        text_length_limit (int): Max length of text content per result. Default is 1000.
+        highlights (bool): Include highlighted snippets. Deprecated since it was removed in the Exa API. It will be removed from Agno in a future release.
+        api_key (Optional[str]): Exa API key. Retrieved from `EXA_API_KEY` env variable if not provided.
+        num_results (Optional[int]): Default number of search results. Overrides individual searches if set.
+        start_crawl_date (Optional[str]): Include results crawled on/after this date (`YYYY-MM-DD`).
+        end_crawl_date (Optional[str]): Include results crawled on/before this date (`YYYY-MM-DD`).
+        start_published_date (Optional[str]): Include results published on/after this date (`YYYY-MM-DD`).
+        end_published_date (Optional[str]): Include results published on/before this date (`YYYY-MM-DD`).
+        use_autoprompt (Optional[bool]): Enable autoprompt features in queries. Deprecated since it was removed in the Exa API. It will be removed from Agno in a future release.
+        type (Optional[str]): Specify content type (e.g., article, blog, video).
+        category (Optional[str]): Filter results by category. Options are "company", "research paper", "news", "pdf", "github", "tweet", "personal site", "linkedin profile", "financial report".
+        include_domains (Optional[List[str]]): Restrict results to these domains.
+        exclude_domains (Optional[List[str]]): Exclude results from these domains.
+        show_results (bool): Log search results for debugging. Default is False.
+        model (Optional[str]): The search model to use. Options are 'exa' or 'exa-pro'.
+        timeout (int): Maximum time in seconds to wait for API responses. Default is 30 seconds.
+    """
+
     def __init__(
         self,
+        enable_search: bool = True,
+        enable_get_contents: bool = True,
+        enable_find_similar: bool = True,
+        enable_answer: bool = True,
+        enable_research: bool = False,
+        all: bool = False,
         text: bool = True,
         text_length_limit: int = 1000,
-        highlights: bool = True,
+        highlights: Optional[bool] = None,  # Deprecated
+        summary: bool = False,
         api_key: Optional[str] = None,
         num_results: Optional[int] = None,
+        livecrawl: str = "always",
         start_crawl_date: Optional[str] = None,
         end_crawl_date: Optional[str] = None,
         start_published_date: Optional[str] = None,
@@ -27,88 +67,330 @@ class ExaTools(Toolkit):
         type: Optional[str] = None,
         category: Optional[str] = None,
         include_domains: Optional[List[str]] = None,
+        exclude_domains: Optional[List[str]] = None,
         show_results: bool = False,
+        model: Optional[str] = None,
+        timeout: int = 30,
+        research_model: Literal["exa-research", "exa-research-pro"] = "exa-research",
+        **kwargs,
     ):
-        super().__init__(name="exa")
-
         self.api_key = api_key or getenv("EXA_API_KEY")
         if not self.api_key:
             logger.error("EXA_API_KEY not set. Please set the EXA_API_KEY environment variable.")
 
+        self.exa = Exa(self.api_key)
         self.show_results = show_results
+        self.timeout = timeout
 
         self.text: bool = text
         self.text_length_limit: int = text_length_limit
-        self.highlights: bool = highlights
+
+        if highlights:
+            import warnings
+
+            warnings.warn(
+                "The 'highlights' parameter is deprecated since it was removed in the Exa API. It will be removed from Agno in a future release.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+        if use_autoprompt:
+            import warnings
+
+            warnings.warn(
+                "The 'use_autoprompt' parameter is deprecated since it was removed in the Exa API. It will be removed from Agno in a future release.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+
+        self.summary: bool = summary
         self.num_results: Optional[int] = num_results
+        self.livecrawl: str = livecrawl
         self.start_crawl_date: Optional[str] = start_crawl_date
         self.end_crawl_date: Optional[str] = end_crawl_date
         self.start_published_date: Optional[str] = start_published_date
         self.end_published_date: Optional[str] = end_published_date
-        self.use_autoprompt: Optional[bool] = use_autoprompt
         self.type: Optional[str] = type
-        self.include_domains: Optional[List[str]] = include_domains
         self.category: Optional[str] = category
+        self.include_domains: Optional[List[str]] = include_domains
+        self.exclude_domains: Optional[List[str]] = exclude_domains
+        self.model: Optional[str] = model
+        self.research_model: Literal["exa-research", "exa-research-pro"] = research_model
+
+        tools: List[Any] = []
+        if all or enable_search:
+            tools.append(self.search_exa)
+        if all or enable_get_contents:
+            tools.append(self.get_contents)
+        if all or enable_find_similar:
+            tools.append(self.find_similar)
+        if all or enable_answer:
+            tools.append(self.exa_answer)
+        if all or enable_research:
+            tools.append(self.research)
+
+        super().__init__(name="exa", tools=tools, **kwargs)
+
+    def _execute_with_timeout(self, func, *args, **kwargs):
+        """Execute a function with a timeout using a temporary ThreadPoolExecutor."""
+        with ThreadPoolExecutor(max_workers=1) as executor:
+            future = executor.submit(func, *args, **kwargs)
+            try:
+                return future.result(timeout=self.timeout)
+            except TimeoutError:
+                raise TimeoutError(f"Operation timed out after {self.timeout} seconds")
+            except Exception as e:
+                raise e
 
-        self.register(self.search_exa)
+    def _parse_results(self, exa_results: SearchResponse) -> str:
+        exa_results_parsed = []
+        for result in exa_results.results:
+            result_dict = {"url": result.url}
+            if result.title:
+                result_dict["title"] = result.title
+            if result.author and result.author != "":
+                result_dict["author"] = result.author
+            if result.published_date:
+                result_dict["published_date"] = result.published_date
+            if result.text:
+                _text = result.text
+                if self.text_length_limit:
+                    _text = _text[: self.text_length_limit]
+                result_dict["text"] = _text
+            exa_results_parsed.append(result_dict)
+        return json.dumps(exa_results_parsed, indent=4, ensure_ascii=False)
 
-    def search_exa(self, query: str, num_results: int = 5) -> str:
+    def search_exa(self, query: str, num_results: int = 5, category: Optional[str] = None) -> str:
         """Use this function to search Exa (a web search engine) for a query.
 
         Args:
             query (str): The query to search for.
             num_results (int): Number of results to return. Defaults to 5.
+            category (Optional[str]): The category to filter search results.
+                Options are "company", "research paper", "news", "pdf", "github",
+                "tweet", "personal site", "linkedin profile", "financial report".
 
         Returns:
             str: The search results in JSON format.
         """
-        if not self.api_key:
-            return "Please set the EXA_API_KEY"
-
         try:
-            exa = Exa(self.api_key)
-            logger.info(f"Searching exa for: {query}")
+            if self.show_results:
+                log_info(f"Searching exa for: {query}")
             search_kwargs: Dict[str, Any] = {
                 "text": self.text,
-                "highlights": self.highlights,
+                "summary": self.summary,
                 "num_results": self.num_results or num_results,
                 "start_crawl_date": self.start_crawl_date,
                 "end_crawl_date": self.end_crawl_date,
                 "start_published_date": self.start_published_date,
                 "end_published_date": self.end_published_date,
-                "use_autoprompt": self.use_autoprompt,
                 "type": self.type,
-                "category": self.category,
+                "category": self.category or category,  # Prefer a user-set category
                 "include_domains": self.include_domains,
+                "exclude_domains": self.exclude_domains,
             }
             # Clean up the kwargs
             search_kwargs = {k: v for k, v in search_kwargs.items() if v is not None}
-            exa_results = exa.search_and_contents(query, **search_kwargs)
-            exa_results_parsed = []
-            for result in exa_results.results:
-                result_dict = {"url": result.url}
-                if result.title:
-                    result_dict["title"] = result.title
-                if result.author and result.author != "":
-                    result_dict["author"] = result.author
-                if result.published_date:
-                    result_dict["published_date"] = result.published_date
-                if result.text:
-                    _text = result.text
-                    if self.text_length_limit:
-                        _text = _text[: self.text_length_limit]
-                    result_dict["text"] = _text
-                if self.highlights:
-                    try:
-                        if result.highlights:  # type: ignore
-                            result_dict["highlights"] = result.highlights  # type: ignore
-                    except Exception as e:
-                        logger.debug(f"Failed to get highlights {e}")
-                exa_results_parsed.append(result_dict)
-            parsed_results = json.dumps(exa_results_parsed, indent=4)
+
+            # Execute search with timeout
+            exa_results = self._execute_with_timeout(self.exa.search_and_contents, query, **search_kwargs)
+
+            parsed_results = self._parse_results(exa_results)
+            # Extract search results
             if self.show_results:
-                logger.info(parsed_results)
+                log_info(parsed_results)
             return parsed_results
+        except TimeoutError as e:
+            logger.error(f"Search timed out after {self.timeout} seconds")
+            return f"Error: {str(e)}"
         except Exception as e:
             logger.error(f"Failed to search exa {e}")
             return f"Error: {e}"
+
+    def get_contents(self, urls: list[str]) -> str:
+        """
+        Retrieve detailed content from specific URLs using the Exa API.
+
+        Args:
+            urls (list(str)): A list of URLs from which to fetch content.
+
+        Returns:
+            str: The search results in JSON format.
+        """
+
+        query_kwargs: Dict[str, Any] = {
+            "text": self.text,
+            "summary": self.summary,
+        }
+
+        try:
+            if self.show_results:
+                log_info(f"Fetching contents for URLs: {urls}")
+
+            # Execute get_contents with timeout
+            exa_results = self._execute_with_timeout(self.exa.get_contents, urls=urls, **query_kwargs)
+
+            parsed_results = self._parse_results(exa_results)
+            if self.show_results:
+                log_info(parsed_results)
+
+            return parsed_results
+        except TimeoutError as e:
+            logger.error(f"Get contents timed out after {self.timeout} seconds")
+            return f"Error: {str(e)}"
+        except Exception as e:
+            logger.error(f"Failed to get contents from Exa: {e}")
+            return f"Error: {e}"
+
+    def find_similar(self, url: str, num_results: int = 5) -> str:
+        """
+        Find similar links to a given URL using the Exa API.
+
+        Args:
+            url (str): The URL for which to find similar links.
+            num_results (int, optional): The number of similar links to return. Defaults to 5.
+
+        Returns:
+            str: The search results in JSON format.
+        """
+
+        query_kwargs: Dict[str, Any] = {
+            "text": self.text,
+            "summary": self.summary,
+            "include_domains": self.include_domains,
+            "exclude_domains": self.exclude_domains,
+            "start_crawl_date": self.start_crawl_date,
+            "end_crawl_date": self.end_crawl_date,
+            "start_published_date": self.start_published_date,
+            "end_published_date": self.end_published_date,
+            "num_results": self.num_results or num_results,
+        }
+
+        try:
+            if self.show_results:
+                log_info(f"Finding similar links to: {url}")
+
+            # Execute find_similar with timeout
+            exa_results = self._execute_with_timeout(self.exa.find_similar_and_contents, url=url, **query_kwargs)
+
+            parsed_results = self._parse_results(exa_results)
+            if self.show_results:
+                log_info(parsed_results)
+
+            return parsed_results
+        except TimeoutError as e:
+            logger.error(f"Find similar timed out after {self.timeout} seconds")
+            return f"Error: {str(e)}"
+        except Exception as e:
+            logger.error(f"Failed to get similar links from Exa: {e}")
+            return f"Error: {e}"
+
+    def exa_answer(self, query: str, text: bool = False) -> str:
+        """
+        Get an LLM answer to a question informed by Exa search results.
+
+        Args:
+            query (str): The question or query to answer.
+            text (bool): Include full text from citation. Default is False.
+        Returns:
+            str: The answer results in JSON format with both generated answer and sources.
+        """
+
+        if self.model and self.model not in ["exa", "exa-pro"]:
+            raise ValueError("Model must be either 'exa' or 'exa-pro'")
+        try:
+            if self.show_results:
+                log_info(f"Generating answer for query: {query}")
+            answer_kwargs: Dict[str, Any] = {
+                "model": self.model,
+                "text": text,
+            }
+            answer_kwargs = {k: v for k, v in answer_kwargs.items() if v is not None}
+
+            # Execute answer with timeout
+            answer = self._execute_with_timeout(self.exa.answer, query=query, **answer_kwargs)
+
+            result = {
+                "answer": answer.answer,  # type: ignore
+                "citations": [
+                    {
+                        "id": citation.id,
+                        "url": citation.url,
+                        "title": citation.title,
+                        "published_date": citation.published_date,
+                        "author": citation.author,
+                        "text": citation.text if text else None,
+                    }
+                    for citation in answer.citations  # type: ignore
+                ],
+            }
+            if self.show_results:
+                log_info(json.dumps(result))
+
+            return json.dumps(result, indent=4)
+
+        except TimeoutError as e:
+            logger.error(f"Answer generation timed out after {self.timeout} seconds")
+            return f"Error: {str(e)}"
+        except Exception as e:
+            logger.error(f"Failed to get answer from Exa: {e}")
+            return f"Error: {e}"
+
+    def research(
+        self,
+        instructions: str,
+        output_schema: Optional[Dict[str, Any]] = None,
+    ) -> str:
+        """
+        Perform deep research on a topic.
+
+        Args:
+            instructions (str): Research instructions.
+            output_schema (Optional[Dict[str, Any]]): JSON schema for structured output. If not provided, the API will auto-infer an appropriate schema.
+        Returns:
+            str: JSON formatted research results including data and citations.
+        """
+        try:
+            log_debug(f"Creating research task with instructions: {instructions}")
+            log_debug(f"Output schema: {output_schema}")
+
+            task_kwargs: Dict[str, Any] = {
+                "instructions": instructions,
+                "model": self.research_model,
+            }
+
+            if output_schema is not None:
+                task_kwargs["output_schema"] = output_schema
+            else:
+                task_kwargs["output_infer_schema"] = True
+
+            task_result = self._execute_with_timeout(self.exa.research.create_task, **task_kwargs)  # type: ignore
+            task_id = task_result.id
+
+            if self.show_results:
+                log_info(f"Research task created with ID: {task_id}")
+
+            # Step 2: Poll until complete (using default polling settings)
+            task = self.exa.research.poll_task(task_id)  # type: ignore
+
+            # Step 3: Format and return results
+            result: Dict[str, Any] = {"data": task.data, "citations": {}}
+
+            # Process citations by field
+            for field, sources in task.citations.items():
+                result["citations"][field] = [
+                    {"url": source.url, "title": source.title, "id": source.id} for source in sources
+                ]
+
+            if self.show_results:
+                log_info("Research completed successfully")
+
+            return json.dumps(result, indent=4)
+
+        except TimeoutError:
+            error_msg = "Research task timed out"
+            logger.error(error_msg)
+            return json.dumps({"error": error_msg}, indent=4)
+        except Exception as e:
+            error_msg = f"Research failed: {str(e)}"
+            logger.error(error_msg)
+            return json.dumps({"error": error_msg}, indent=4)

agno/tools/fal.py

@@ -3,13 +3,15 @@ pip install fal-client
 """
 
 from os import getenv
-from typing import Optional
+from typing import Optional, Union
 from uuid import uuid4
 
 from agno.agent import Agent
-from agno.media import ImageArtifact, VideoArtifact
+from agno.media import Image, Video
+from agno.team.team import Team
 from agno.tools import Toolkit
-from agno.utils.log import logger
+from agno.tools.function import ToolResult
+from agno.utils.log import log_info, logger
 
 try:
     import fal_client  # type: ignore
@@ -22,32 +24,41 @@ class FalTools(Toolkit):
         self,
         api_key: Optional[str] = None,
         model: str = "fal-ai/hunyuan-video",
+        enable_generate_media: bool = True,
+        enable_image_to_image: bool = False,
+        all: bool = False,
+        **kwargs,
     ):
-        super().__init__(name="fal")
-
-        self.api_key = api_key or getenv("FAL_KEY")
+        self.api_key = api_key or getenv("FAL_API_KEY")
         if not self.api_key:
-            logger.error("FAL_KEY not set. Please set the FAL_KEY environment variable.")
+            logger.error("FAL_API_KEY not set. Please set the FAL_API_KEY environment variable.")
         self.model = model
         self.seen_logs: set[str] = set()
-        self.register(self.generate_media)
+
+        tools = []
+        if all or enable_generate_media:
+            tools.append(self.generate_media)
+        if all or enable_image_to_image:
+            tools.append(self.image_to_image)
+
+        super().__init__(name="fal-tools", tools=tools, **kwargs)
 
     def on_queue_update(self, update):
         if isinstance(update, fal_client.InProgress) and update.logs:
             for log in update.logs:
                 message = log["message"]
                 if message not in self.seen_logs:
-                    logger.info(message)
+                    log_info(message)
                     self.seen_logs.add(message)
 
-    def generate_media(self, agent: Agent, prompt: str) -> str:
+    def generate_media(self, agent: Union[Agent, Team], prompt: str) -> ToolResult:
         """
         Use this function to run a model with a given prompt.
 
         Args:
             prompt (str): A text description of the task.
         Returns:
-            str: Return the result of the model.
+            ToolResult: Contains the generated media and success message.
         """
         try:
             result = fal_client.subscribe(
@@ -61,32 +72,27 @@ class FalTools(Toolkit):
 
             if "image" in result:
                 url = result.get("image", {}).get("url", "")
-                agent.add_image(
-                    ImageArtifact(
-                        id=media_id,
-                        url=url,
-                    )
+                image_artifact = Image(
+                    id=media_id,
+                    url=url,
                 )
-                media_type = "image"
+                return ToolResult(content=f"Image generated successfully at {url}", images=[image_artifact])
             elif "video" in result:
                 url = result.get("video", {}).get("url", "")
-                agent.add_video(
-                    VideoArtifact(
-                        id=media_id,
-                        url=url,
-                    )
+                video_artifact = Video(
+                    id=media_id,
+                    url=url,
                 )
-                media_type = "video"
+                return ToolResult(content=f"Video generated successfully at {url}", videos=[video_artifact])
             else:
                 logger.error(f"Unsupported type in result: {result}")
-                return f"Unsupported type in result: {result}"
+                return ToolResult(content=f"Unsupported type in result: {result}")
 
-            return f"{media_type.capitalize()} generated successfully at {url}"
         except Exception as e:
             logger.error(f"Failed to run model: {e}")
-            return f"Error: {e}"
+            return ToolResult(content=f"Error: {e}")
 
-    def image_to_image(self, agent: Agent, prompt: str, image_url: Optional[str] = None) -> str:
+    def image_to_image(self, agent: Union[Agent, Team], prompt: str, image_url: Optional[str] = None) -> ToolResult:
         """
         Use this function to transform an input image based on a text prompt using the Fal AI image-to-image model.
         The model takes an existing image and generates a new version modified according to your prompt.
@@ -97,7 +103,7 @@ class FalTools(Toolkit):
             image_url (str): The URL of the image to use for the generation.
 
         Returns:
-            str: Return the result of the model.
+            ToolResult: Contains the generated image and success message.
         """
 
         try:
@@ -109,15 +115,13 @@ class FalTools(Toolkit):
             )
             url = result.get("images", [{}])[0].get("url", "")
             media_id = str(uuid4())
-            agent.add_image(
-                ImageArtifact(
-                    id=media_id,
-                    url=url,
-                )
+            image_artifact = Image(
+                id=media_id,
+                url=url,
             )
 
-            return f"Image generated successfully at {url}"
+            return ToolResult(content=f"Image generated successfully at {url}", images=[image_artifact])
 
         except Exception as e:
             logger.error(f"Failed to generate image: {e}")
-            return f"Error: {e}"
+            return ToolResult(content=f"Error: {e}")