Squashed 'packages/tools/' content from commit 78317b9c

git-subtree-dir: packages/tools
git-subtree-split: 78317b9c127f18bd040c1d77e3c0840cdc9a5b38

crewai_tools/tools/exa_tools/README.md

@@ -0,0 +1,30 @@
+# EXASearchTool Documentation
+
+## Description
+This tool is designed to perform a semantic search for a specified query from a text's content across the internet. It utilizes the `https://exa.ai/` API to fetch and display the most relevant search results based on the query provided by the user.
+
+## Installation
+To incorporate this tool into your project, follow the installation instructions below:
+```shell
+uv add crewai[tools] exa_py
+```
+
+## Example
+The following example demonstrates how to initialize the tool and execute a search with a given query:
+
+```python
+from crewai_tools import EXASearchTool
+
+# Initialize the tool for internet searching capabilities
+tool = EXASearchTool(api_key="your_api_key")
+```
+
+## Steps to Get Started
+To effectively use the `EXASearchTool`, follow these steps:
+
+1. **Package Installation**: Confirm that the `crewai[tools]` package is installed in your Python environment.
+2. **API Key Acquisition**: Acquire a `https://exa.ai/` API key by registering for a free account at `https://exa.ai/`.
+3. **Environment Configuration**: Store your obtained API key in an environment variable named `EXA_API_KEY` to facilitate its use by the tool.
+
+## Conclusion
+By integrating the `EXASearchTool` into Python projects, users gain the ability to conduct real-time, relevant searches across the internet directly from their applications. By adhering to the setup and usage guidelines provided, incorporating this tool into projects is streamlined and straightforward.

crewai_tools/tools/exa_tools/exa_search_tool.py

@@ -0,0 +1,108 @@
+import os
+from typing import Any, List, Optional, Type
+
+from crewai.tools import BaseTool, EnvVar
+from pydantic import BaseModel, Field
+
+try:
+    from exa_py import Exa
+
+    EXA_INSTALLED = True
+except ImportError:
+    Exa = Any
+    EXA_INSTALLED = False
+
+
+class EXABaseToolSchema(BaseModel):
+    search_query: str = Field(
+        ..., description="Mandatory search query you want to use to search the internet"
+    )
+    start_published_date: Optional[str] = Field(
+        None, description="Start date for the search"
+    )
+    end_published_date: Optional[str] = Field(
+        None, description="End date for the search"
+    )
+    include_domains: Optional[list[str]] = Field(
+        None, description="List of domains to include in the search"
+    )
+
+
+class EXASearchTool(BaseTool):
+    model_config = {"arbitrary_types_allowed": True}
+    name: str = "EXASearchTool"
+    description: str = "Search the internet using Exa"
+    args_schema: Type[BaseModel] = EXABaseToolSchema
+    client: Optional["Exa"] = None
+    content: Optional[bool] = False
+    summary: Optional[bool] = False
+    type: Optional[str] = "auto"
+    package_dependencies: List[str] = ["exa_py"]
+    api_key: Optional[str] = Field(
+        default_factory=lambda: os.getenv("EXA_API_KEY"),
+        description="API key for Exa services",
+        json_schema_extra={"required": False},
+    )
+    env_vars: List[EnvVar] = [
+        EnvVar(
+            name="EXA_API_KEY", description="API key for Exa services", required=False
+        ),
+    ]
+
+    def __init__(
+        self,
+        content: Optional[bool] = False,
+        summary: Optional[bool] = False,
+        type: Optional[str] = "auto",
+        **kwargs,
+    ):
+        super().__init__(
+            **kwargs,
+        )
+        if not EXA_INSTALLED:
+            import click
+
+            if click.confirm(
+                "You are missing the 'exa_py' package. Would you like to install it?"
+            ):
+                import subprocess
+
+                subprocess.run(["uv", "add", "exa_py"], check=True)
+
+            else:
+                raise ImportError(
+                    "You are missing the 'exa_py' package. Would you like to install it?"
+                )
+        self.client = Exa(api_key=self.api_key)
+        self.content = content
+        self.summary = summary
+        self.type = type
+
+    def _run(
+        self,
+        search_query: str,
+        start_published_date: Optional[str] = None,
+        end_published_date: Optional[str] = None,
+        include_domains: Optional[list[str]] = None,
+    ) -> Any:
+        if self.client is None:
+            raise ValueError("Client not initialized")
+
+        search_params = {
+            "type": self.type,
+        }
+
+        if start_published_date:
+            search_params["start_published_date"] = start_published_date
+        if end_published_date:
+            search_params["end_published_date"] = end_published_date
+        if include_domains:
+            search_params["include_domains"] = include_domains
+
+        if self.content:
+            results = self.client.search_and_contents(
+                search_query, summary=self.summary, **search_params
+            )
+        else:
+            results = self.client.search(search_query, **search_params)
+        return results