diff --git a/docs/learn/tools.md b/docs/learn/tools.md
index d37b2a878..e3e4ce127 100644
--- a/docs/learn/tools.md
+++ b/docs/learn/tools.md
@@ -449,6 +449,15 @@ This is why the "beginner" recommendation and "advanced" recommendations call th
Mirascope provides several pre-made tools and toolkits to help you get started quickly:
+!!! warning "Dependencies Required"
+ Pre-made tools and toolkits require installing the dependencies listed in the "Dependencies" column for each tool/toolkit.
+
+ For example:
+ ```bash
+ pip install httpx # For HTTPX tool
+ pip install requests # For Requests tool
+ ```
+
### Pre-Made Tools
??? api "API Documentation"
@@ -458,12 +467,12 @@ Mirascope provides several pre-made tools and toolkits to help you get started q
- [`mirascope.tools.web.ParseURLContent`](../api/tools/web/parse_url_content.md)
- [`mirascope.tools.web.Requests`](../api/tools/web/requests.md)
-| Tool | Primary Use | Key Features | Characteristics |
-|------|-------------|--------------|-----------------|
-| [`DuckDuckGoSearch`](../api/tools/web/duckduckgo.md) | Web Searching | • Multiple query support
• Title/URL/snippet extraction
• Result count control
• Automated formatting | • Privacy-focused search
• Async support (AsyncDuckDuckGoSearch)
• Automatic filtering
• Structured results |
-| [`HTTPX`](../api/tools/web/httpx.md) | Advanced HTTP Requests | • Full HTTP method support (GET/POST/PUT/DELETE)
• Custom header support
• File upload/download
• Form data handling | • Async support (AsyncHTTPX)
• Configurable timeouts
• Comprehensive error handling
• Redirect control |
-| [`ParseURLContent`](../api/tools/web/parse_url_content.md) | Web Content Extraction | • HTML content fetching
• Main content extraction
• Element filtering
• Text normalization | • Automatic cleaning
• Configurable parser
• Timeout settings
• Error handling |
-| [`Requests`](../api/tools/web/requests.md) | Simple HTTP Requests | • Basic HTTP methods
• Simple API
• Response text retrieval
• Basic authentication | • Minimal configuration
• Intuitive interface
• Basic error handling
• Lightweight implementation |
+| Tool | Primary Use | Dependencies | Key Features | Characteristics |
+|------|-------------|--------------|--------------|-----------------|
+| [`DuckDuckGoSearch`](../api/tools/web/duckduckgo.md) | Web Searching | [`duckduckgo-search`](https://pypi.org/project/duckduckgo-search/) | • Multiple query support
• Title/URL/snippet extraction
• Result count control
• Automated formatting | • Privacy-focused search
• Async support (AsyncDuckDuckGoSearch)
• Automatic filtering
• Structured results |
+| [`HTTPX`](../api/tools/web/httpx.md) | Advanced HTTP Requests | [`httpx`](https://pypi.org/project/httpx/) | • Full HTTP method support (GET/POST/PUT/DELETE)
• Custom header support
• File upload/download
• Form data handling | • Async support (AsyncHTTPX)
• Configurable timeouts
• Comprehensive error handling
• Redirect control |
+| [`ParseURLContent`](../api/tools/web/parse_url_content.md) | Web Content Extraction | [`beautifulsoup4`](https://pypi.org/project/beautifulsoup4/), [`httpx`](https://pypi.org/project/httpx/) | • HTML content fetching
• Main content extraction
• Element filtering
• Text normalization | • Automatic cleaning
• Configurable parser
• Timeout settings
• Error handling |
+| [`Requests`](../api/tools/web/requests.md) | Simple HTTP Requests | [`requests`](https://pypi.org/project/requests/) | • Basic HTTP methods
• Simple API
• Response text retrieval
• Basic authentication | • Minimal configuration
• Intuitive interface
• Basic error handling
• Lightweight implementation |
Example using DuckDuckGoSearch:
@@ -500,10 +509,10 @@ Example using DuckDuckGoSearch:
- [`mirascope.tools.system.FileSystemToolKit`](../api/tools/system/file_system.md)
- [`mirascope.tools.system.DockerOperationToolKit`](../api/tools/system/docker_operation.md)
-| ToolKit | Primary Use | Tools and Features | Characteristics |
-|-------------------------------------------------------------|-------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------|
-| [`FileSystemToolKit`](../api/tools/system/file_system.md) | File System Operations | • ReadFile: File content reading
• WriteFile: Content writing
• ListDirectory: Directory listing
• CreateDirectory: Directory creation
• DeleteFile: File deletion | • Path traversal protection
• File size limits
• Extension validation
• Robust error handling
• Base directory isolation |
-| [`DockerOperationToolKit`](../api/tools/system/docker_operation.md) | Code & Command Execution | • ExecutePython: Python code execution with optional package installation
• ExecuteShell: Shell command execution
| • Docker container isolation
• Memory limits
• Network control
• Security restrictions
• Resource cleanup |
+| ToolKit | Primary Use | Dependencies | Tools and Features | Characteristics |
+|---------|-------------|-------------------------------------------------------------------|-------------------|-----------------|
+| [`FileSystemToolKit`](../api/tools/system/file_system.md) | File System Operations | None | • ReadFile: File content reading
• WriteFile: Content writing
• ListDirectory: Directory listing
• CreateDirectory: Directory creation
• DeleteFile: File deletion | • Path traversal protection
• File size limits
• Extension validation
• Robust error handling
• Base directory isolation |
+| [`DockerOperationToolKit`](../api/tools/system/docker_operation.md) | Code & Command Execution | [`docker`](https://pypi.org/project/docker/), [`docker engine`](https://docs.docker.com/engine/install/) | • ExecutePython: Python code execution with optional package installation
• ExecuteShell: Shell command execution | • Docker container isolation
• Memory limits
• Network control
• Security restrictions
• Resource cleanup |
Example using FileSystemToolKit:
diff --git a/mirascope/tools/__init__.py b/mirascope/tools/__init__.py
index d2e573ae9..c51e73e6c 100644
--- a/mirascope/tools/__init__.py
+++ b/mirascope/tools/__init__.py
@@ -1,12 +1,24 @@
-from .system._docker_operation import (
- DockerOperationToolKit,
- DockerOperationToolKitConfig,
-)
+from contextlib import suppress
+
from .system._file_system import FileSystemToolKit, FileSystemToolKitConfig
-from .web._duckduckgo import DuckDuckGoSearch, DuckDuckGoSearchConfig
-from .web._httpx import HTTPX, AsyncHTTPX, HTTPXConfig
-from .web._parse_url_content import ParseURLConfig, ParseURLContent
-from .web._requests import Requests, RequestsConfig
+
+with suppress(ImportError):
+ from .system._docker_operation import (
+ DockerOperationToolKit,
+ DockerOperationToolKitConfig,
+ )
+
+with suppress(ImportError):
+ from .web._duckduckgo import DuckDuckGoSearch, DuckDuckGoSearchConfig
+
+with suppress(ImportError):
+ from .web._httpx import HTTPX, AsyncHTTPX, HTTPXConfig
+
+with suppress(ImportError):
+ from .web._parse_url_content import ParseURLConfig, ParseURLContent
+
+with suppress(ImportError):
+ from .web._requests import Requests, RequestsConfig
__all__ = [
"AsyncHTTPX",
diff --git a/uv.lock b/uv.lock
index 8d2aa934d..a47350a18 100644
--- a/uv.lock
+++ b/uv.lock
@@ -3139,7 +3139,7 @@ wheels = [
[[package]]
name = "mirascope"
-version = "1.11.0"
+version = "1.11.1"
source = { editable = "." }
dependencies = [
{ name = "docstring-parser" },
@@ -3751,6 +3751,8 @@ wheels = [
{ url = "https://files.pythonhosted.org/packages/b2/07/8cbb75d6cfbe8712d8f7f6a5615f083c6e710ab916b748fbb20373ddb142/multiprocess-0.70.17-py311-none-any.whl", hash = "sha256:2884701445d0177aec5bd5f6ee0df296773e4fb65b11903b94c613fb46cfb7d1", size = 144346 },
{ url = "https://files.pythonhosted.org/packages/a4/69/d3f343a61a2f86ef10ed7865a26beda7c71554136ce187b0384b1c2c9ca3/multiprocess-0.70.17-py312-none-any.whl", hash = "sha256:2818af14c52446b9617d1b0755fa70ca2f77c28b25ed97bdaa2c69a22c47b46c", size = 147990 },
{ url = "https://files.pythonhosted.org/packages/c8/b7/2e9a4fcd871b81e1f2a812cd5c6fb52ad1e8da7bf0d7646c55eaae220484/multiprocess-0.70.17-py313-none-any.whl", hash = "sha256:20c28ca19079a6c879258103a6d60b94d4ffe2d9da07dda93fb1c8bc6243f522", size = 149843 },
+ { url = "https://files.pythonhosted.org/packages/ae/d7/fd7a092fc0ab1845a1a97ca88e61b9b7cc2e9d6fcf0ed24e9480590c2336/multiprocess-0.70.17-py38-none-any.whl", hash = "sha256:1d52f068357acd1e5bbc670b273ef8f81d57863235d9fbf9314751886e141968", size = 132635 },
+ { url = "https://files.pythonhosted.org/packages/f9/41/0618ac724b8a56254962c143759e04fa01c73b37aa69dd433f16643bd38b/multiprocess-0.70.17-py39-none-any.whl", hash = "sha256:c3feb874ba574fbccfb335980020c1ac631fbf2a3f7bee4e2042ede62558a021", size = 133359 },
]
[[package]]
@@ -4689,8 +4691,6 @@ version = "6.0.0"
source = { registry = "https://pypi.org/simple" }
sdist = { url = "https://files.pythonhosted.org/packages/18/c7/8c6872f7372eb6a6b2e4708b88419fb46b857f7a2e1892966b851cc79fc9/psutil-6.0.0.tar.gz", hash = "sha256:8faae4f310b6d969fa26ca0545338b21f73c6b15db7c4a8d934a5482faa818f2", size = 508067 }
wheels = [
- { url = "https://files.pythonhosted.org/packages/c5/66/78c9c3020f573c58101dc43a44f6855d01bbbd747e24da2f0c4491200ea3/psutil-6.0.0-cp27-none-win32.whl", hash = "sha256:02b69001f44cc73c1c5279d02b30a817e339ceb258ad75997325e0e6169d8b35", size = 249766 },
- { url = "https://files.pythonhosted.org/packages/e1/3f/2403aa9558bea4d3854b0e5e567bc3dd8e9fbc1fc4453c0aa9aafeb75467/psutil-6.0.0-cp27-none-win_amd64.whl", hash = "sha256:21f1fb635deccd510f69f485b87433460a603919b45e2a324ad65b0cc74f8fb1", size = 253024 },
{ url = "https://files.pythonhosted.org/packages/0b/37/f8da2fbd29690b3557cca414c1949f92162981920699cd62095a984983bf/psutil-6.0.0-cp36-abi3-macosx_10_9_x86_64.whl", hash = "sha256:c588a7e9b1173b6e866756dde596fd4cad94f9399daf99ad8c3258b3cb2b47a0", size = 250961 },
{ url = "https://files.pythonhosted.org/packages/35/56/72f86175e81c656a01c4401cd3b1c923f891b31fbcebe98985894176d7c9/psutil-6.0.0-cp36-abi3-manylinux_2_12_i686.manylinux2010_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:6ed2440ada7ef7d0d608f20ad89a04ec47d2d3ab7190896cd62ca5fc4fe08bf0", size = 287478 },
{ url = "https://files.pythonhosted.org/packages/19/74/f59e7e0d392bc1070e9a70e2f9190d652487ac115bb16e2eff6b22ad1d24/psutil-6.0.0-cp36-abi3-manylinux_2_12_x86_64.manylinux2010_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:5fd9a97c8e94059b0ef54a7d4baf13b405011176c3b6ff257c247cae0d560ecd", size = 290455 },