From 183f466ac4b7ed168e454737c8d46214370ad882 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jo=C3=A3o=20Moura?= Date: Sun, 11 Aug 2024 15:50:42 -0300 Subject: [PATCH] adding new docs --- docs/tools/MySQLTool.md | 56 ++++++++++++++++++++++++++++++ docs/tools/NL2SQLTool.md | 74 ++++++++++++++++++++++++++++++++++++++++ mkdocs.yml | 2 ++ 3 files changed, 132 insertions(+) create mode 100644 docs/tools/MySQLTool.md create mode 100644 docs/tools/NL2SQLTool.md diff --git a/docs/tools/MySQLTool.md b/docs/tools/MySQLTool.md new file mode 100644 index 0000000000..b31d7120b8 --- /dev/null +++ b/docs/tools/MySQLTool.md @@ -0,0 +1,56 @@ +# MySQLSearchTool + +## Description +This tool is designed to facilitate semantic searches within MySQL database tables. Leveraging the RAG (Retrieve and Generate) technology, the MySQLSearchTool provides users with an efficient means of querying database table content, specifically tailored for MySQL databases. It simplifies the process of finding relevant data through semantic search queries, making it an invaluable resource for users needing to perform advanced queries on extensive datasets within a MySQL database. + +## Installation +To install the `crewai_tools` package and utilize the MySQLSearchTool, execute the following command in your terminal: + +```shell +pip install 'crewai[tools]' +``` + +## Example +Below is an example showcasing how to use the MySQLSearchTool to conduct a semantic search on a table within a MySQL database: + +```python +from crewai_tools import MySQLSearchTool + +# Initialize the tool with the database URI and the target table name +tool = MySQLSearchTool(db_uri='mysql://user:password@localhost:3306/mydatabase', table_name='employees') + +``` + +## Arguments +The MySQLSearchTool requires the following arguments for its operation: + +- `db_uri`: A string representing the URI of the MySQL database to be queried. This argument is mandatory and must include the necessary authentication details and the location of the database. +- `table_name`: A string specifying the name of the table within the database on which the semantic search will be performed. This argument is mandatory. + +## Custom model and embeddings + +By default, the tool uses OpenAI for both embeddings and summarization. To customize the model, you can use a config dictionary as follows: + +```python +tool = MySQLSearchTool( + config=dict( + llm=dict( + provider="ollama", # or google, openai, anthropic, llama2, ... + config=dict( + model="llama2", + # temperature=0.5, + # top_p=1, + # stream=true, + ), + ), + embedder=dict( + provider="google", + config=dict( + model="models/embedding-001", + task_type="retrieval_document", + # title="Embeddings", + ), + ), + ) +) +``` diff --git a/docs/tools/NL2SQLTool.md b/docs/tools/NL2SQLTool.md new file mode 100644 index 0000000000..d0bb822719 --- /dev/null +++ b/docs/tools/NL2SQLTool.md @@ -0,0 +1,74 @@ +# NL2SQL Tool + +## Description + +This tool is used to convert natural language to SQL queries. When passsed to the agent it will generate queries and then use them to interact with the database. + +This enables multiple workflows like having an Agent to access the database fetch information based on the goal and then use the information to generate a response, report or any other output. Along with that proivdes the ability for the Agent to update the database based on its goal. + +**Attention**: Make sure that the Agent has access to a Read-Replica or that is okay for the Agent to run insert/update queries on the database. + +## Requirements + +- SqlAlchemy +- Any DB compatible library (e.g. psycopg2, mysql-connector-python) + +## Installation +Install the crewai_tools package +```shell +pip install 'crewai[tools]' +``` + +## Usage + +In order to use the NL2SQLTool, you need to pass the database URI to the tool. The URI should be in the format `dialect+driver://username:password@host:port/database`. + + +```python +from crewai_tools import NL2SQLTool + +# psycopg2 was installed to run this example with PostgreSQL +nl2sql = NL2SQLTool(db_uri="postgresql://example@localhost:5432/test_db") + +@agent +def researcher(self) -> Agent: + return Agent( + config=self.agents_config["researcher"], + allow_delegation=False, + tools=[nl2sql] + ) +``` + +## Example + +The primary task goal was: + +"Retrieve the average, maximum, and minimum monthly revenue for each city, but only include cities that have more than one user. Also, count the number of user in each city and sort the results by the average monthly revenue in descending order" + +So the Agent tried to get information from the DB, the first one is wrong so the Agent tries again and gets the correct information and passes to the next agent. + +![alt text](images/image-2.png) +![alt text](images/image-3.png) + + +The second task goal was: + +"Review the data and create a detailed report, and then create the table on the database with the fields based on the data provided. +Include information on the average, maximum, and minimum monthly revenue for each city, but only include cities that have more than one user. Also, count the number of users in each city and sort the results by the average monthly revenue in descending order." + +Now things start to get interesting, the Agent generates the SQL query to not only create the table but also insert the data into the table. And in the end the Agent still returns the final report which is exactly what was in the database. + +![alt text](images/image-4.png) +![alt text](images/image-5.png) + +![alt text](images/image-9.png) +![alt text](images/image-7.png) + + +This is a simple example of how the NL2SQLTool can be used to interact with the database and generate reports based on the data in the database. + +The Tool provides endless possibilities on the logic of the Agent and how it can interact with the database. + +``` + DB -> Agent -> ... -> Agent -> DB +``` diff --git a/mkdocs.yml b/mkdocs.yml index 207b68b228..8b7ad51746 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -170,6 +170,8 @@ nav: - JSON RAG Search: 'tools/JSONSearchTool.md' - Docx Rag Search: 'tools/DOCXSearchTool.md' - MDX RAG Search: 'tools/MDXSearchTool.md' + - MySQL Tool: 'tools/MySQLTool.md' + - NL2SQL Tool: 'tools/NL2SQL.md' - PG RAG Search: 'tools/PGSearchTool.md' - Vision Tool: 'tools/VisionTool.md' - Website RAG Search: 'tools/WebsiteSearchTool.md'