diff --git a/README.md b/README.md index 9ca0d36f2..818b75bbf 100644 --- a/README.md +++ b/README.md @@ -1,101 +1,132 @@ -## Getting started +
-When setting up agents you can provide tools for them to use. Here you will find ready-to-use tools as well as simple helpers for you to create your own tools. +![Logo of crewAI, two people rowing on a boat](./assets/crewai_logo.png) -In order to create a new tool, you have to pick one of the available strategies. +
+ +# **crewAI Tools** +This document provides a comprehensive guide for setting up sophisticated tools for [crewAI](https://github.com/joaomdmoura/crewai) agents, facilitating the creation of bespoke tooling to empower your AI solutions. + +In the realm of CrewAI agents, tools are pivotal for enhancing functionality. This guide outlines the steps to equip your agents with an arsenal of ready-to-use tools and the methodology to craft your own. + +
+ +

+ +[Homepage](https://www.crewai.io/) | [Documentation](https://docs.crewai.com/) | [Chat with Docs](https://chatg.pt/DWjSBZn) | [Examples](https://github.com/joaomdmoura/crewai-examples) | [Discord](https://discord.com/invite/X4JWnZnxPb) + +

+ +
+ +## Table of contents + +- [Creating Your Tools](#creating-your-tools) + - [Subclassing `BaseTool`](#subclassing-basetool) + - [Functional Tool Creation](#functional-tool-creation) + - [Utilizing the `tool` Decorator](#utilizing-the-tool-decorator) +- [Contribution Guidelines](#contribution-guidelines) +- [Development Setup](#development-setup) + +## Creating Your Tools + +Tools are always expect to return strings, as they are meant to be used by the agents to generate responses. + +There are three ways to create tools for crewAI agents: +- [Subclassing `BaseTool`](#subclassing-basetool) +- [Creating a tool from a function or lambda](#functional-tool-creation) +- [Using the `tool` decorator](#utilizing-the-tool-decorator) ### Subclassing `BaseTool` ```python -class MyTool(BaseTool): - name: str = "Knowledge base" - description: str = "A knowledge base with all the requirements for the project." +class MyCustomTool(BaseTool): + name: str = "Name of my tool" + description: str = "Clear description for what this tool is useful for, you agent will need this information to use it." - def _run(self, question) -> str: - return ( - tbl.search(embed_func([question])[0]).limit(3).to_pandas()["text"].tolist() - ) + def _run(self, argument) -> str: + # Implementation goes here + pass ``` -As you can see, all you need to do is to create a new class that inherits from `BaseTool`, define `name` and `description` fields, as well as implement the `_run` method. +Define a new class inheriting from `BaseTool`, specifying `name`, `description`, and the `_run` method for operational logic. -### Create tool from a function or lambda +### Functional Tool Creation ```python my_tool = Tool( - name="Knowledge base", - description="A knowledge base with all the requirements for the project.", - func=lambda question: tbl.search(embed_func([question])[0]) - .limit(3) - .to_pandas()["text"] - .tolist(), + name="Name of my tool" + description="Clear description for what this tool is useful for, you agent will need this information to use it.", + func=lambda argument: # Your function logic here ) ``` -Here's it's a bit simpler, as you don't have to subclass. Simply create a `Tool` object with the three required fields and you are good to go. +For a simpler approach, create a `Tool` object directly with the required attributes and a functional logic. -### Use the `tool` decorator. +### Utilizing the `tool` Decorator ```python -@tool("Knowledge base") +@tool("Name of my tool") def my_tool(question: str) -> str: - """A knowledge base with all the requirements for the project.""" - return tbl.search(embed_func([question])[0]).limit(3).to_pandas()["text"].tolist() + """Clear description for what this tool is useful for, you agent will need this information to use it.""" + # Function logic here ``` -By using the decorator you can easily wrap simple functions as tools. If you don't provide a name, the function name is going to be used. However, the docstring is required. +The `tool` decorator simplifies the process, transforming functions into tools with minimal overhead. -If you are using a linter you may see issues when passing your decorated tool in `tools` parameters that expect a list of `BaseTool`. If that's the case, you can use the `as_tool` helper. +## Contribution Guidelines +We eagerly welcome contributions to enrich this toolset. To contribute: -## Contribution +1. **Fork the Repository:** Begin with forking the repository to your GitHub account. +2. **Feature Branch:** Create a new branch in your fork for the feature or improvement. +3. **Implement Your Feature:** Add your contribution to the new branch. +4. **Pull Request:** Submit a pull request from your feature branch to the main repository. -This repo is open-source and we welcome contributions. If you're looking to contribute, please: +Your contributions are greatly appreciated and will help enhance this project. -- Fork the repository. -- Create a new branch for your feature. -- Add your feature or improvement. -- Send a pull request. -- We appreciate your input! +## **Development Setup** -### Installing Dependencies +**Installing Dependencies:** ```bash poetry install ``` -### Virtual Env +**Activating Virtual Environment:** ```bash poetry shell ``` -### Pre-commit hooks +**Setting Up Pre-commit Hooks:** ```bash pre-commit install ``` -### Running Tests +**Running Tests:** ```bash poetry run pytest ``` -### Running static type checks +**Static Type Checking:** ```bash poetry run pyright ``` -### Packaging +**Packaging:** ```bash poetry build ``` -### Installing Locally +**Local Installation:** ```bash pip install dist/*.tar.gz ``` + +Thank you for your interest in enhancing the capabilities of AI agents through advanced tooling. Your contributions make a significant impact. \ No newline at end of file diff --git a/src/crewai_tools/__init__.py b/src/crewai_tools/__init__.py index 1aea157ad..09d10d88f 100644 --- a/src/crewai_tools/__init__.py +++ b/src/crewai_tools/__init__.py @@ -1 +1 @@ -from .base_tool import BaseTool, Tool, as_tool, tool +from .tools.base_tool import BaseTool, Tool, as_tool, tool diff --git a/src/crewai_tools/adapters/embedchain_adapter.py b/src/crewai_tools/adapters/embedchain_adapter.py index 8ef1d2a11..cdb7f1d5a 100644 --- a/src/crewai_tools/adapters/embedchain_adapter.py +++ b/src/crewai_tools/adapters/embedchain_adapter.py @@ -1,6 +1,6 @@ from embedchain import App -from crewai_tools.rag_tool import Adapter +from crewai_tools.tools.rag.rag_tool import Adapter class EmbedchainAdapter(Adapter): diff --git a/src/crewai_tools/adapters/lancedb_adapter.py b/src/crewai_tools/adapters/lancedb_adapter.py index 630ce972e..c612d475c 100644 --- a/src/crewai_tools/adapters/lancedb_adapter.py +++ b/src/crewai_tools/adapters/lancedb_adapter.py @@ -7,7 +7,7 @@ from lancedb.table import Table as LanceDBTable from openai import Client as OpenAIClient from pydantic import Field, PrivateAttr -from crewai_tools.rag_tool import Adapter +from crewai_tools.tools.rag.rag_tool import Adapter def _default_embedding_function(): diff --git a/src/crewai_tools/base_tool.py b/src/crewai_tools/tools/base_tool.py similarity index 100% rename from src/crewai_tools/base_tool.py rename to src/crewai_tools/tools/base_tool.py diff --git a/src/crewai_tools/tools/rag/__init__.py b/src/crewai_tools/tools/rag/__init__.py new file mode 100644 index 000000000..e69de29bb diff --git a/src/crewai_tools/rag_tool.py b/src/crewai_tools/tools/rag/rag_tool.py similarity index 97% rename from src/crewai_tools/rag_tool.py rename to src/crewai_tools/tools/rag/rag_tool.py index 222cf529d..5ef616795 100644 --- a/src/crewai_tools/rag_tool.py +++ b/src/crewai_tools/tools/rag/rag_tool.py @@ -3,7 +3,7 @@ from typing import Any from pydantic import BaseModel, ConfigDict -from crewai_tools.base_tool import BaseTool +from crewai_tools.tools.base_tool import BaseTool class Adapter(BaseModel, ABC): diff --git a/tests/rag_tool_test.py b/tests/tools/rag/rag_tool_test.py similarity index 88% rename from tests/rag_tool_test.py rename to tests/tools/rag/rag_tool_test.py index 8d441d341..a059c60a2 100644 --- a/tests/rag_tool_test.py +++ b/tests/tools/rag/rag_tool_test.py @@ -1,4 +1,4 @@ -from crewai_tools.rag_tool import Adapter, RagTool +from crewai_tools.tools.rag.rag_tool import Adapter, RagTool class MockAdapter(Adapter):