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 },