Add comprehensive tutorial on building a Text-to-SQL AI agent with `smolagents`

README.md

@@ -1,40 +1,91 @@
-# Unlocking Database Intelligence with AI Agents: A `smolagents` Tutorial
+---
+title: { { "Create a Text to SQL AI Agent" } }
+emoji: { { 😊 } }
+colorFrom: { { blue } }
+colorTo: { { purple } }
+---
 
-[Open In Colab](https://colab.research.google.com/github/huggingface/smolagents/blob/main/notebooks/text_to_sql.ipynb)
-[Open In Studio Lab](https://studiolab.sagemaker.aws/import/github/huggingface/smolagents/blob/main/notebooks/text_to_sql.ipynb)
+Here's a `README.md` file outlining your Text-to-SQL agent project:
 
-This guide explores how to develop an intelligent agent using the `smolagents` framework, specifically enabling it to interact with a SQL database.
+## Intelligent Text-to-SQL Agent with `smolagents`
 
----
+This project demonstrates building a robust Text-to-SQL AI agent using the `smolagents` framework, capable of translating natural language queries into SQL, executing them, and intelligently processing the results, including handling complex scenarios like table joins.
+
+## Table of Contents
+
+- [Intelligent Text-to-SQL Agent with `smolagents`](#intelligent-text-to-sql-agent-with-smolagents)
+- [Table of Contents](#table-of-contents)
+- [Why an AI Agent for Text-to-SQL?](#why-an-ai-agent-for-text-to-sql)
+- [Features](#features)
+- [Installation](#installation)
+  - [Instantiating the Agent (Single Table)](#instantiating-the-agent-single-table)
+  - [Querying the Agent: Single Table](#querying-the-agent-single-table)
+  - [Extending for Table Joins](#extending-for-table-joins)
+  - [Querying the Agent: Multi-Table](#querying-the-agent-multi-table)
+- [How it Works](#how-it-works)
+- [Key Concepts Demonstrated](#key-concepts-demonstrated)
+- [Contributing](#contributing)
+- [License](#license)
 
-## Beyond Simple Text-to-SQL: The Agent Advantage
+## Why an AI Agent for Text-to-SQL?
 
-Why opt for an advanced agent system instead of a straightforward text-to-SQL pipeline?
+Traditional Text-to-SQL pipelines often suffer from brittleness:
 
-Traditional text-to-SQL solutions are often quite rigid. A direct translation from natural language to a database query can easily lead to syntactical errors, causing the database to reject the query. More insidiously, a query might execute without error but produce entirely incorrect or irrelevant results, providing no indication of its inaccuracy. This "silent failure" can be detrimental for critical applications.
+- **Syntactic Errors:** Generated SQL queries might be invalid, leading to execution failures.
+- **Semantic Errors:** Even if syntactically correct, queries can produce incorrect or irrelevant results without explicit error messages, leading to silent failures and potentially misleading information.
 
-👉 An agent-based system, conversely, possesses the crucial capability to **critically evaluate outputs and execution logs**. It can identify when a query has failed or yielded unexpected results, and then iteratively refine its strategy or reformulate the query. This inherent capacity for self-correction significantly boosts performance and reliability.
+**An agent-based system overcomes these limitations by:**
 
-Let's dive into building such an agent! 💪
+- **Critical Inspection:** Analyzing query outputs and execution logs.
+- **Self-Correction:** Identifying errors or suboptimal results and iteratively refining the SQL query or subsequent processing steps.
+- **Enhanced Robustness:** Providing a more reliable and intelligent way to interact with databases from natural language.
 
-First, ensure all necessary libraries are installed by running the command below:
+## Features
+
+- **Natural Language to SQL:** Translates user questions into executable SQL queries.
+- **Database Interaction:** Executes SQL queries against an in-memory SQLite database.
+- **Intelligent Parsing:** Processes and extracts relevant information from SQL query results.
+- **Self-Correction:** Learns from execution errors and refines its approach.
+- **Multi-Table Querying:** Supports questions requiring joins across multiple tables.
+- **LLM Flexibility:** Integrates with various Large Language Models (LLMs) via `smolagents`.
+
+## Installation
+
+To get started, clone this repository and install the required dependencies:
 
 ```bash
-!pip install smolagents python-dotenv sqlalchemy --upgrade -q
+git clone https://github.com/your-username/text-to-sql-agent.git
+cd text-to-sql-agent
+pip install smolagents python-dotenv sqlalchemy --upgrade -q
 ```
 
-To enable interaction with Large Language Models (LLMs) via inference providers, you'll need an authentication token, such as an `HF_TOKEN` from Hugging Face. We'll use `python-dotenv` to load this from your environment variables.
+`````
 
-```python
-from dotenv import load_dotenv
-load_dotenv()
+**Note:** To interact with Large Language Models via inference providers (e.g., Hugging Face Inference API), you'll need a valid authentication token set as an environment variable, typically `HF_TOKEN`.
+
+## Project Structure
+
+The core logic of this project is encapsulated in `text_to_sql.py`.
+
+```text
+.
+├── README.md
+└── text_to_sql.py
 ```
 
-### Step 1: Database Initialization
+## Usage
+
+This section walks through the `text_to_sql.py` script, explaining each part of building and using the agent.
 
-We begin by setting up our in-memory SQLite database using `SQLAlchemy`. This involves defining our table structures and populating them with initial data.
+### Setup and Dependencies
+
+First, load your environment variables, including your LLM token.
 
 ```python
+# text_to_sql.py
+from dotenv import load_dotenv
+load_dotenv()
+
 from sqlalchemy import (
     create_engine,
     MetaData,
@@ -45,77 +96,72 @@ from sqlalchemy import (
     Float,
     insert,
     inspect,
-    text, # Essential for executing raw SQL expressions
+    text,
 )
+from smolagents import tool, CodeAgent, InferenceClientModel
+
+# ... (rest of the code)
+```
 
-# Establish an in-memory SQLite database connection
+### Database Initialization
+
+We set up an in-memory SQLite database using SQLAlchemy, defining `receipts` and `waiters` tables and populating them with sample data.
+
+````python
+# text_to_sql.py
 engine = create_engine("sqlite:///:memory:")
 metadata_obj = MetaData()
 
-# Utility function for bulk data insertion
 def insert_rows_into_table(rows, table, engine=engine):
     for row in rows:
         stmt = insert(table).values(**row)
         with engine.begin() as connection:
             connection.execute(stmt)
 
-# Define the 'receipts' table schema
-table_name = "receipts"
+# Define the 'receipts' table
 receipts = Table(
-    table_name,
+    "receipts",
     metadata_obj,
-    Column("receipt_id", Integer, primary_key=True), # Unique identifier for each transaction
-    Column("customer_name", String(255)), # Full name of the patron
-    Column("price", Float), # Total cost of the receipt
-    Column("tip", Float), # Gratuity amount
+    Column("receipt_id", Integer, primary_key=True),
+    Column("customer_name", String(255)), # Adjusted from String(16) for longer names
+    Column("price", Float),
+    Column("tip", Float),
 )
-# Create the defined table within our database
 metadata_obj.create_all(engine)
 
-# Sample transaction data
+# Sample data for 'receipts'
 rows = [
     {"receipt_id": 1, "customer_name": "Alan Payne", "price": 12.06, "tip": 1.20},
     {"receipt_id": 2, "customer_name": "Alex Mason", "price": 23.86, "tip": 0.24},
     {"receipt_id": 3, "customer_name": "Woodrow Wilson", "price": 53.43, "tip": 5.43},
     {"receipt_id": 4, "customer_name": "Margaret James", "price": 21.11, "tip": 1.00},
 ]
-# Populate the 'receipts' table
 insert_rows_into_table(rows, receipts)
-```
-
-### Step 2: Crafting the Agent's Database Tool
 
-For an AI agent to interact with a database, it requires specialized **tools**. Our `sql_engine` function will serve as this tool, allowing the agent to execute SQL queries.
-
-The tool's docstring plays a critical role, as its content (the `description` attribute) is presented to the LLM by the agent system. This description guides the LLM on _how_ and _when_ to utilize the tool, including details about available tables and their column structures.
-
-First, let's extract the schema details for our `receipts` table:
-
-```python
+# Print table schema (for LLM context)
 inspector = inspect(engine)
 columns_info = [(col["name"], col["type"]) for col in inspector.get_columns("receipts")]
-
 table_description = "Columns:\n" + "\n".join([f"  - {name}: {col_type}" for name, col_type in columns_info])
-print(table_description)
-```
+print(table_description)```
+
+**Output:**
+`````
 
-```
 Columns:
-  - receipt_id: INTEGER
-  - customer_name: VARCHAR(255)
-  - price: FLOAT
-  - tip: FLOAT
-```
 
-Now, we'll construct our `sql_engine` tool. Key elements include:
+- receipt_id: INTEGER
+- customer_name: VARCHAR(255)
+- price: FLOAT
+- tip: FLOAT
 
-- The `@tool` decorator from `smolagents` to designate it as an agent capability.
-- A comprehensive docstring, complete with an `Args:` section, to inform the LLM about the tool's purpose and expected inputs.
-- Type hints for both input and output parameters, enhancing clarity and guiding the LLM's code generation.
+````
 
-```python
-from smolagents import tool
+### Creating the SQL Tool
 
+The `sql_engine` function acts as the agent's interface to the database. Its detailed docstring provides the LLM with crucial information about its functionality and the database schema.
+
+```python
+# text_to_sql.py
 @tool
 def sql_engine(query: str) -> str:
     """
@@ -136,105 +182,100 @@ def sql_engine(query: str) -> str:
     """
     output = ""
     with engine.connect() as con:
-        # Utilize text() to safely execute raw SQL within SQLAlchemy
         rows = con.execute(text(query))
         for row in rows:
-            output += "\n" + str(row) # Converts each row of results into a string representation
+            output += "\n" + str(row)
     return output
-```
-
-### Step 3: Assembling the AI Agent
+````
 
-With our database and tool ready, we now instantiate the `CodeAgent`. This is `smolagents’` flagship agent class, designed to generate and execute code, and to iteratively refine its actions based on the ReAct (Reasoning + Acting) framework.
+### Instantiating the Agent (Single Table)
 
-The `model` parameter links our agent to a Large Language Model. `InferenceClientModel` facilitates access to LLMs via Hugging Face's Inference API, supporting both Serverless and Dedicated endpoints. Alternatively, you could integrate other proprietary LLM APIs.
+We create a `CodeAgent` and provide it with the `sql_engine` tool and an LLM (e.g., `meta-llama/Llama-3.1-8B-Instruct`).
 
 ```python
-from smolagents import CodeAgent, InferenceClientModel
-
+# text_to_sql.py
 agent = CodeAgent(
-    tools=[sql_engine], # Provide the 'sql_engine' tool to our agent
-    model=InferenceClientModel(model_id="meta-llama/Llama-3.1-8B-Instruct"), # Selecting our LLM
+    tools=[sql_engine],
+    model=InferenceClientModel(model_id="meta-llama/Llama-3.1-8B-Instruct"),
 )
 ```
 
-### Step 4: Posing a Query to the Agent
+### Querying the Agent: Single Table
 
-Our agent is now configured. Let's challenge it with a natural language question. The agent will then leverage its LLM and `sql_engine` tool to find the answer.
+Now, we can ask the agent a question and observe its problem-solving process, including self-correction.
 
 ```python
+# text_to_sql.py
 agent.run("Can you give me the name of the client who got the most expensive receipt?")
 ```
 
-**Understanding the Agent's Iterative Solution Process:**
+**Expected Agent Output (summarized):**
+The agent will attempt several SQL queries, potentially encountering syntax errors or parsing issues with the raw string output from `sql_engine`. Through iterative self-correction, it will eventually generate and execute `SELECT MAX(price), customer_name FROM receipts ORDER BY price DESC LIMIT 1`, parse the result `(53.43, 'Woodrow Wilson')`, and identify 'Woodrow Wilson'.
 
-The `CodeAgent` employs a self-correcting, cyclical approach:
+### Extending for Table Joins
 
-1. **Intent Comprehension:** The LLM interprets the request, identifying the need to find the "most expensive receipt."
-2. **Tool Selection:** It recognizes that the `sql_engine` tool is necessary for database interaction.
-3. **Initial Code Generation:** The agent generates its first attempt at a SQL query (e.g., `SELECT MAX(price) FROM receipts`) to get the maximum price. It then tries to use this result in a follow-up query.
-4. **Execution and Feedback:** The `sql_engine` executes the query. However, the output is a string like `\n(53.43,)`. If the agent naively tries to embed this string directly into another SQL query (e.g., `WHERE price = (53.43,)`), it will encounter a `syntax error`.
-5. **Adaptive Self-Correction:** Upon receiving an `OperationalError` (e.g., "syntax error" or "could not convert string to float"), the LLM analyzes the error. It understands that the string-formatted output needs to be correctly parsed into a numeric type before being used in subsequent SQL or Python logic. Previous attempts might fail due to unexpected characters (like newlines) or incorrect string manipulation.
-6. **Refined Strategy:** Learning from its previous attempts, the agent eventually generates a more efficient, consolidated SQL query: `SELECT MAX(price), customer_name FROM receipts ORDER BY price DESC LIMIT 1`. This effectively retrieves both the highest price and the corresponding customer name in a single database call.
-7. **Result Parsing and Finalization:** Finally, the LLM generates Python code to accurately parse the `\n(53.43, 'Woodrow Wilson')` string output from the `sql_engine`, extracting the customer name. It then provides the `final_answer`.
-
-This continuous cycle of **reasoning, acting via tools, observing outcomes (including errors), and self-correction** is fundamental to the robustness and adaptability of agent-based systems.
-
----
-
-### Level 2: Inter-Table Queries (Table Joins)
-
-Let's elevate the complexity! Our goal now is to enable the agent to handle questions that require combining data from multiple tables using SQL joins.
-
-To achieve this, we'll define a second table, `waiters`, which records the names of waiters associated with each `receipt_id`.
+To handle more complex queries, we add a `waiters` table and update the `sql_engine` tool's description to include its schema.
 
 ```python
-# Define the 'waiters' table schema
-table_name = "waiters"
+# text_to_sql.py
+# Define the 'waiters' table
 waiters = Table(
-    table_name,
+    "waiters",
     metadata_obj,
-    Column("receipt_id", Integer, primary_key=True), # Links to 'receipts' table
-    Column("waiter_name", String(16), primary_key=True), # Name of the assigned waiter
+    Column("receipt_id", Integer, primary_key=True),
+    Column("waiter_name", String(16), primary_key=True),
 )
-# Create the 'waiters' table in the database
 metadata_obj.create_all(engine)
 
-# Sample data for the 'waiters' table
+# Sample data for 'waiters'
 rows = [
     {"receipt_id": 1, "waiter_name": "Corey Johnson"},
     {"receipt_id": 2, "waiter_name": "Michael Watts"},
     {"receipt_id": 3, "waiter_name": "Michael Watts"},
     {"receipt_id": 4, "waiter_name": "Margaret James"},
 ]
-# Populate the 'waiters' table
 insert_rows_into_table(rows, waiters)
-```
-
-With the introduction of a new table, it's crucial to **update the `sql_engine` tool's description**. This ensures the LLM is aware of the `waiters` table and its schema, allowing it to construct queries that span both tables.
 
-```python
+# Update the tool's description to include the new table
 updated_description = """This tool allows performing SQL queries on the database, returning results as a string.
 It can access the following tables:"""
 
 inspector = inspect(engine)
 for table in ["receipts", "waiters"]:
     columns_info = [(col["name"], col["type"]) for col in inspector.get_columns(table)]
-
     table_description = f"Table '{table}':\n"
-
     table_description += "  Columns:\n" + "\n".join([f"    - {name}: {col_type}" for name, col_type in columns_info])
     updated_description += "\n\n" + table_description
 
 print(updated_description)
+sql_engine.description = updated_description # Update the tool's description
 ```
 
-For more intricate requests like this, switching to a more powerful LLM can significantly enhance the agent's reasoning capabilities. Here, we'll upgrade to `Qwen/Qwen2.5-Coder-32B-Instruct`.
+**Output:**
 
-```python
-# Assign the updated description to the tool
-sql_engine.description = updated_description
+```
+This tool allows performing SQL queries on the database, returning results as a string.
+It can access the following tables:
+
+Table 'receipts':
+  Columns:
+    - receipt_id: INTEGER
+    - customer_name: VARCHAR(255)
+    - price: FLOAT
+    - tip: FLOAT
+
+Table 'waiters':
+  Columns:
+    - receipt_id: INTEGER
+    - waiter_name: VARCHAR(16)
+```
+
+### Querying the Agent: Multi-Table
+
+We switch to a more powerful LLM (`Qwen/Qwen2.5-Coder-32B-Instruct`) for this harder task.
 
+```python
+# text_to_sql.py
 agent = CodeAgent(
     tools=[sql_engine],
     model=InferenceClientModel(model_id="Qwen/Qwen2.5-Coder-32B-Instruct"),
@@ -243,12 +284,33 @@ agent = CodeAgent(
 agent.run("Which waiter received the highest total amount in tips?")
 ```
 
-The agent successfully addresses this challenge, often directly formulating the correct SQL query involving a `JOIN` operation, and then performing the necessary calculations in Python. The simplicity of setup versus the complexity of the task handled demonstrates the power of this agentic approach!
+**Expected Agent Output (summarized):**
+The agent will formulate a SQL query to join `waiters` and `receipts` tables (e.g., `SELECT w.waiter_name, r.tip FROM waiters w JOIN receipts r ON w.receipt_id = r.receipt_id`). It will then process the results in Python to sum tips per waiter and identify "Michael Watts" as having the highest total tips.
+
+## How it Works
+
+The `smolagents` `CodeAgent` operates on the **ReAct (Reasoning + Acting)** framework:
+
+1. **Reasoning (LLM as Brain):** A Large Language Model (e.g., Llama-3.1, Qwen2.5) interprets the natural language prompt and decides on a course of action.
+2. **Acting (Tools as Hands):** If an external interaction is needed (like querying a database), the LLM generates Python code to call a registered `@tool` (e.g., `sql_engine("...")`). The tool's `docstring` (description) is critical for the LLM to understand its capabilities.
+3. **Observation & Feedback:** The generated code is executed. The output (e.g., database results, error messages) is fed back to the LLM.
+4. **Self-Correction & Iteration:** The LLM analyzes the feedback. If there's an error or the result is unsatisfactory, it refines its reasoning and generates new code, iterating until the task is complete or deemed unfeasible.
+
+This iterative process allows the agent to solve complex problems and recover from errors, making it more robust than traditional direct translation methods.
+
+## Key Concepts Demonstrated
+
+- **Agentic Frameworks:** Using `smolagents` to orchestrate LLM interactions and tool use.
+- **Tool Creation:** Defining custom Python functions as tools for agents, complete with detailed descriptions.
+- **Dynamic Tool Descriptions:** Updating tool information to reflect changes in available data (e.g., new database tables).
+- **LLM Integration:** Leveraging various LLMs for different levels of reasoning complexity.
+- **SQLAlchemy:** Programmatically interacting with databases in Python.
+- **ReAct Paradigm:** The iterative cycle of reasoning, acting, and observation that enables self-correction.
+
+## Contributing
 
-This tutorial covered several key concepts:
+Feel free to open issues or submit pull requests if you have suggestions or improvements!
 
-- **Constructing custom tools** for agents.
-- **Dynamically updating a tool's description** to reflect changes in available data or functionalities.
-- **Leveraging stronger LLMs** to empower an agent's reasoning for more complex tasks.
+## License
 
-✅ You are now equipped to start building your own advanced text-to-SQL systems! ✨
+This project is open-sourced under the MIT License. See the `LICENSE` file for more details.

TUTORIAL.md

@@ -0,0 +1,254 @@
+# Unlocking Database Intelligence with AI Agents: A `smolagents` Tutorial
+
+[Open In Colab](https://colab.research.google.com/github/huggingface/smolagents/blob/main/notebooks/text_to_sql.ipynb)
+[Open In Studio Lab](https://studiolab.sagemaker.aws/import/github/huggingface/smolagents/blob/main/notebooks/text_to_sql.ipynb)
+
+This guide explores how to develop an intelligent agent using the `smolagents` framework, specifically enabling it to interact with a SQL database.
+
+---
+
+## Beyond Simple Text-to-SQL: The Agent Advantage
+
+Why opt for an advanced agent system instead of a straightforward text-to-SQL pipeline?
+
+Traditional text-to-SQL solutions are often quite rigid. A direct translation from natural language to a database query can easily lead to syntactical errors, causing the database to reject the query. More insidiously, a query might execute without error but produce entirely incorrect or irrelevant results, providing no indication of its inaccuracy. This "silent failure" can be detrimental for critical applications.
+
+👉 An agent-based system, conversely, possesses the crucial capability to **critically evaluate outputs and execution logs**. It can identify when a query has failed or yielded unexpected results, and then iteratively refine its strategy or reformulate the query. This inherent capacity for self-correction significantly boosts performance and reliability.
+
+Let's dive into building such an agent! 💪
+
+First, ensure all necessary libraries are installed by running the command below:
+
+```bash
+!pip install smolagents python-dotenv sqlalchemy --upgrade -q
+```
+
+To enable interaction with Large Language Models (LLMs) via inference providers, you'll need an authentication token, such as an `HF_TOKEN` from Hugging Face. We'll use `python-dotenv` to load this from your environment variables.
+
+```python
+from dotenv import load_dotenv
+load_dotenv()
+```
+
+### Step 1: Database Initialization
+
+We begin by setting up our in-memory SQLite database using `SQLAlchemy`. This involves defining our table structures and populating them with initial data.
+
+```python
+from sqlalchemy import (
+    create_engine,
+    MetaData,
+    Table,
+    Column,
+    String,
+    Integer,
+    Float,
+    insert,
+    inspect,
+    text, # Essential for executing raw SQL expressions
+)
+
+# Establish an in-memory SQLite database connection
+engine = create_engine("sqlite:///:memory:")
+metadata_obj = MetaData()
+
+# Utility function for bulk data insertion
+def insert_rows_into_table(rows, table, engine=engine):
+    for row in rows:
+        stmt = insert(table).values(**row)
+        with engine.begin() as connection:
+            connection.execute(stmt)
+
+# Define the 'receipts' table schema
+table_name = "receipts"
+receipts = Table(
+    table_name,
+    metadata_obj,
+    Column("receipt_id", Integer, primary_key=True), # Unique identifier for each transaction
+    Column("customer_name", String(255)), # Full name of the patron
+    Column("price", Float), # Total cost of the receipt
+    Column("tip", Float), # Gratuity amount
+)
+# Create the defined table within our database
+metadata_obj.create_all(engine)
+
+# Sample transaction data
+rows = [
+    {"receipt_id": 1, "customer_name": "Alan Payne", "price": 12.06, "tip": 1.20},
+    {"receipt_id": 2, "customer_name": "Alex Mason", "price": 23.86, "tip": 0.24},
+    {"receipt_id": 3, "customer_name": "Woodrow Wilson", "price": 53.43, "tip": 5.43},
+    {"receipt_id": 4, "customer_name": "Margaret James", "price": 21.11, "tip": 1.00},
+]
+# Populate the 'receipts' table
+insert_rows_into_table(rows, receipts)
+```
+
+### Step 2: Crafting the Agent's Database Tool
+
+For an AI agent to interact with a database, it requires specialized **tools**. Our `sql_engine` function will serve as this tool, allowing the agent to execute SQL queries.
+
+The tool's docstring plays a critical role, as its content (the `description` attribute) is presented to the LLM by the agent system. This description guides the LLM on _how_ and _when_ to utilize the tool, including details about available tables and their column structures.
+
+First, let's extract the schema details for our `receipts` table:
+
+```python
+inspector = inspect(engine)
+columns_info = [(col["name"], col["type"]) for col in inspector.get_columns("receipts")]
+
+table_description = "Columns:\n" + "\n".join([f"  - {name}: {col_type}" for name, col_type in columns_info])
+print(table_description)
+```
+
+```
+Columns:
+  - receipt_id: INTEGER
+  - customer_name: VARCHAR(255)
+  - price: FLOAT
+  - tip: FLOAT
+```
+
+Now, we'll construct our `sql_engine` tool. Key elements include:
+
+- The `@tool` decorator from `smolagents` to designate it as an agent capability.
+- A comprehensive docstring, complete with an `Args:` section, to inform the LLM about the tool's purpose and expected inputs.
+- Type hints for both input and output parameters, enhancing clarity and guiding the LLM's code generation.
+
+```python
+from smolagents import tool
+
+@tool
+def sql_engine(query: str) -> str:
+    """
+    Enables execution of SQL queries against the database.
+    Outputs the query results as a formatted string.
+
+    Known tables and their column structures:
+    Table 'receipts':
+      Columns:
+        - receipt_id: INTEGER (Primary Key)
+        - customer_name: VARCHAR(255)
+        - price: FLOAT
+        - tip: FLOAT
+
+    Args:
+        query: The precise SQL query string to be executed.
+               Example: "SELECT customer_name FROM receipts WHERE price > 10.0;"
+    """
+    output = ""
+    with engine.connect() as con:
+        # Utilize text() to safely execute raw SQL within SQLAlchemy
+        rows = con.execute(text(query))
+        for row in rows:
+            output += "\n" + str(row) # Converts each row of results into a string representation
+    return output
+```
+
+### Step 3: Assembling the AI Agent
+
+With our database and tool ready, we now instantiate the `CodeAgent`. This is `smolagents’` flagship agent class, designed to generate and execute code, and to iteratively refine its actions based on the ReAct (Reasoning + Acting) framework.
+
+The `model` parameter links our agent to a Large Language Model. `InferenceClientModel` facilitates access to LLMs via Hugging Face's Inference API, supporting both Serverless and Dedicated endpoints. Alternatively, you could integrate other proprietary LLM APIs.
+
+```python
+from smolagents import CodeAgent, InferenceClientModel
+
+agent = CodeAgent(
+    tools=[sql_engine], # Provide the 'sql_engine' tool to our agent
+    model=InferenceClientModel(model_id="meta-llama/Llama-3.1-8B-Instruct"), # Selecting our LLM
+)
+```
+
+### Step 4: Posing a Query to the Agent
+
+Our agent is now configured. Let's challenge it with a natural language question. The agent will then leverage its LLM and `sql_engine` tool to find the answer.
+
+```python
+agent.run("Can you give me the name of the client who got the most expensive receipt?")
+```
+
+**Understanding the Agent's Iterative Solution Process:**
+
+The `CodeAgent` employs a self-correcting, cyclical approach:
+
+1. **Intent Comprehension:** The LLM interprets the request, identifying the need to find the "most expensive receipt."
+2. **Tool Selection:** It recognizes that the `sql_engine` tool is necessary for database interaction.
+3. **Initial Code Generation:** The agent generates its first attempt at a SQL query (e.g., `SELECT MAX(price) FROM receipts`) to get the maximum price. It then tries to use this result in a follow-up query.
+4. **Execution and Feedback:** The `sql_engine` executes the query. However, the output is a string like `\n(53.43,)`. If the agent naively tries to embed this string directly into another SQL query (e.g., `WHERE price = (53.43,)`), it will encounter a `syntax error`.
+5. **Adaptive Self-Correction:** Upon receiving an `OperationalError` (e.g., "syntax error" or "could not convert string to float"), the LLM analyzes the error. It understands that the string-formatted output needs to be correctly parsed into a numeric type before being used in subsequent SQL or Python logic. Previous attempts might fail due to unexpected characters (like newlines) or incorrect string manipulation.
+6. **Refined Strategy:** Learning from its previous attempts, the agent eventually generates a more efficient, consolidated SQL query: `SELECT MAX(price), customer_name FROM receipts ORDER BY price DESC LIMIT 1`. This effectively retrieves both the highest price and the corresponding customer name in a single database call.
+7. **Result Parsing and Finalization:** Finally, the LLM generates Python code to accurately parse the `\n(53.43, 'Woodrow Wilson')` string output from the `sql_engine`, extracting the customer name. It then provides the `final_answer`.
+
+This continuous cycle of **reasoning, acting via tools, observing outcomes (including errors), and self-correction** is fundamental to the robustness and adaptability of agent-based systems.
+
+---
+
+### Level 2: Inter-Table Queries (Table Joins)
+
+Let's elevate the complexity! Our goal now is to enable the agent to handle questions that require combining data from multiple tables using SQL joins.
+
+To achieve this, we'll define a second table, `waiters`, which records the names of waiters associated with each `receipt_id`.
+
+```python
+# Define the 'waiters' table schema
+table_name = "waiters"
+waiters = Table(
+    table_name,
+    metadata_obj,
+    Column("receipt_id", Integer, primary_key=True), # Links to 'receipts' table
+    Column("waiter_name", String(16), primary_key=True), # Name of the assigned waiter
+)
+# Create the 'waiters' table in the database
+metadata_obj.create_all(engine)
+
+# Sample data for the 'waiters' table
+rows = [
+    {"receipt_id": 1, "waiter_name": "Corey Johnson"},
+    {"receipt_id": 2, "waiter_name": "Michael Watts"},
+    {"receipt_id": 3, "waiter_name": "Michael Watts"},
+    {"receipt_id": 4, "waiter_name": "Margaret James"},
+]
+# Populate the 'waiters' table
+insert_rows_into_table(rows, waiters)
+```
+
+With the introduction of a new table, it's crucial to **update the `sql_engine` tool's description**. This ensures the LLM is aware of the `waiters` table and its schema, allowing it to construct queries that span both tables.
+
+```python
+updated_description = """This tool allows performing SQL queries on the database, returning results as a string.
+It can access the following tables:"""
+
+inspector = inspect(engine)
+for table in ["receipts", "waiters"]:
+    columns_info = [(col["name"], col["type"]) for col in inspector.get_columns(table)]
+
+    table_description = f"Table '{table}':\n"
+
+    table_description += "  Columns:\n" + "\n".join([f"    - {name}: {col_type}" for name, col_type in columns_info])
+    updated_description += "\n\n" + table_description
+
+print(updated_description)
+```
+
+For more intricate requests like this, switching to a more powerful LLM can significantly enhance the agent's reasoning capabilities. Here, we'll upgrade to `Qwen/Qwen2.5-Coder-32B-Instruct`.
+
+```python
+# Assign the updated description to the tool
+sql_engine.description = updated_description
+
+agent = CodeAgent(
+    tools=[sql_engine],
+    model=InferenceClientModel(model_id="Qwen/Qwen2.5-Coder-32B-Instruct"),
+)
+
+agent.run("Which waiter received the highest total amount in tips?")
+```
+
+The agent successfully addresses this challenge, often directly formulating the correct SQL query involving a `JOIN` operation, and then performing the necessary calculations in Python. The simplicity of setup versus the complexity of the task handled demonstrates the power of this agentic approach!
+
+This tutorial covered several key concepts:
+
+- **Constructing custom tools** for agents.
+- **Dynamically updating a tool's description** to reflect changes in available data or functionalities.
+- **Leveraging stronger LLMs** to empower an agent's reasoning for more complex tasks.
+
+✅ You are now equipped to start building your own advanced text-to-SQL systems! ✨