(FEAT): Revise README to enhance tutorial clarity and detail on AI agent development with SQL interaction

README.md

@@ -1,138 +1,128 @@
-# Building Smart Agents: Turning Natural Language into Database Actions
+# Unlocking Database Intelligence with AI Agents: A `smolagents` Tutorial
 
-**Goal**: Understand how to build AI agents that can interpret natural language questions, interact with a database using SQL, and provide relevant answers.
+[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)
 
-## What is This Code Doing?
+This guide explores how to develop an intelligent agent using the `smolagents` framework, specifically enabling it to interact with a SQL database.
 
-At its core, this Python script demonstrates how to create a simple AI agent that can understand questions posed in plain English and then generate and execute SQL queries to retrieve answers from a database. It sets up a simulated scenario with receipts and waiters tables in an in-memory SQLite database, populates them with sample data, and then tasks two different AI models (via `CodeAgent`) to answer questions about this data.
+---
 
-**Specifically, the code performs the following actions:**
+## Beyond Simple Text-to-SQL: The Agent Advantage
 
-1. Database Setup:
+Why opt for an advanced agent system instead of a straightforward text-to-SQL pipeline?
 
-- Initializes an in-memory SQLite database using `SQLAlchemy`.
-- Defines two database tables: receipts (with columns for receipt_id, customer_name, price, tip) and waiters (with receipt_id, waiter_name).
-- Populates these tables with sample data.
+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.
 
-2. Tool Creation (`sql_engine`):
+👉 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.
 
-- It defines a Python function called `sql_engine` which is decorated as a `@tool`. This means the AI agent can "call" this function to perform specific actions.
-- The `sql_engine` tool takes a SQL query string as input, executes it against the database, and returns the results as a string. Crucially, the tool's description is vital, as it tells the AI agent how and when to use it, including the available tables and their columns.
+Let's dive into building such an agent! 💪
 
-3. AI Agent Instantiation and Task Execution:
+First, ensure all necessary libraries are installed by running the command below:
 
-- It creates instances of `CodeAgent` using different Large Language Models (LLMs) like meta-llama/Llama-3.1-8B-Instruct and Qwen/Qwen2.5-Coder-32B-Instruct.
-- Each agent is provided with the `sql_engine` tool, giving it the capability to interact with the database.
-- The agents are then given natural language prompts, such as "Can you give me the name of the client who got the most expensive receipt?" or "Which waiter got more total money from tips?".
-
-4. Problem Solving and Self-Correction:
-
-- The output shows how the first agent (Llama-3.1) iteratively attempts to solve the problem. When its initial SQL generation or result parsing fails, it analyzes the error messages (e.g., "syntax error," "could not convert string to float") and revises its approach in subsequent steps. This demonstrates a form of self-correction.
-- The second agent (Qwen2.5) successfully performs a SQL JOIN operation and then processes the results in Python to find the answer.
-
-## How Does This Code Work? (The Mechanics of an AI Agent)
-
-This code leverages the power of Large Language Models (LLMs) combined with tool-use capabilities to create an AI agent. Here's the "how":
-
-1. **The LLM as the "Brain":** The `CodeAgent` uses an LLM (like Llama-3.1 or Qwen2.5) as its core reasoning engine. The LLM's extensive training on vast amounts of text enables it to:
-
-- Understand natural language prompts (e.g., "most expensive receipt").
-- Generate code (in this case, SQL queries and Python logic for parsing/calculation) to achieve a goal.
-- Reason about execution errors and potentially self-correct its generated code.
-
-2. **Tools as "Hands" or "Senses":** The `@tool` decorator from smolagents (or similar frameworks) allows the LLM to interact with the external world beyond just generating text.
-
-- The `sql_engine` function acts as a specialized tool that encapsulates the logic for database interaction.s
-- When the LLM determines that a database query is needed to answer a user's question, it "calls" the `sql_engine` tool, generating the appropriate SQL query string as an argument.
-- The LLM relies heavily on the description attribute of the tool. This description tells the LLM what the tool does, what arguments it expects, and importantly, the schema of the database it can query. A clear and accurate description is paramount for the agent to use the tool correctly.
-
-3. **The Agentic Loop:** The `CodeAgent` operates in a loop:
-
-- It receives a prompt.
-- It uses the LLM to think about the problem and decide if a tool is needed.
-- If a tool is needed, the LLM generates the code (e.g., sql_engine("SELECT ...")) to use it.
-- This generated code is then executed.
-- The output of the code (e.g., database results, error messages) is fed back to the LLM.
-- The LLM then uses this feedback to either refine its approach (self-correction), generate more code, or formulate a final answer.
-
-4. **SQLAlchemy for Database Abstraction:**
-
-- `SQLAlchemy` is used here to define the database schema (tables and columns) in a Pythonic way. This makes it easier to manage the database structure programmatically.
-- It also provides an Object Relational Mapper (ORM) and a SQL Expression Language, which simplifies executing SQL queries and handling database connections (though in our sql_engine tool, we're directly using raw SQL for simplicity).
-
-## Why Is This Approach Useful for AI Agents?
-
-This method of combining LLMs with tools is a powerful paradigm for building sophisticated AI agents for several key reasons:
-
-- **Extending LLM Capabilities:** LLMs are great at text understanding and generation, but they don't inherently "know" how to interact with a database, browse the internet, or perform complex calculations. Tools provide these external capabilities, essentially giving the LLM "skills" beyond just language.
-- **Grounding in Factual Data:** By providing a sql_engine tool, the LLM can access up-to-date and specific information stored in a database, preventing hallucinations and ensuring factual accuracy, which LLMs alone sometimes struggle with.
-- **Complex Task Execution:** Agents can break down complex problems into smaller steps, using different tools as needed. For example, in the second question, the agent first used SQL to fetch raw data and then used Python code (generated by the LLM) to perform an aggregation.
-- **Reduced Development Effort:** Instead of hand-coding every possible interaction or query, you define the tools and let the LLM figure out how to use them to achieve the desired outcome from natural language. This abstracts away much of the conditional logic usually required in traditional programming.
-- **Adaptability and Flexibility:** If your database schema changes, you primarily update the tool's description. The LLM, given the updated description, can often adapt its SQL generation without needing extensive code changes.
-- **Self-Correction and Robustness:** The ability of the agent to analyze `Execution logs` and correct its own errors makes the system more robust and capable of handling unexpected issues.
-
-## How to Create Your Own AI Agents (Step-by-Step Tutorial)
-
-Let's break down the process of creating an AI agent similar to the one demonstrated:
+```bash
+!pip install smolagents python-dotenv sqlalchemy --upgrade -q
+```
 
-### Step 1: Define Your Data and Environment
+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.
 
-First, you need to decide what external systems your agent will interact with. In this example, it's a database.
+```python
+from dotenv import load_dotenv
+load_dotenv()
+```
 
-**Set up your database (or other external system):**
+### Step 1: Database Initialization
 
-- Decide on your database type (e.g., SQLite, PostgreSQL, MySQL).
-- Use a library like SQLAlchemy to define your database schema (tables, columns, data types, primary keys).
-- Populate your database with initial data.
+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
+from sqlalchemy import (
+    create_engine,
+    MetaData,
+    Table,
+    Column,
+    String,
+    Integer,
+    Float,
+    insert,
+    inspect,
+    text, # Essential for executing raw SQL expressions
+)
 
-engine = create_engine("sqlite:///:memory:") # In-memory database for this example
+# Establish an in-memory SQLite database connection
+engine = create_engine("sqlite:///:memory:")
 metadata_obj = MetaData()
 
-# Define your tables
+# 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(
-"receipts",
-metadata_obj,
-Column("receipt_id", Integer, primary_key=True),
-Column("customer_name", String(255)),
-Column("price", Float),
-Column("tip", Float),
+    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)
+```
 
-# Add other tables as needed, e.g., 'waiters'
+### Step 2: Crafting the Agent's Database Tool
 
-metadata_obj.create_all(engine) # Create tables in the database
+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.
 
-# Insert initial data
+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.
 
-# ... (as shown in the example code)
+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)
 ```
 
-### Step 2: Create Tools for Your Agent
+```
+Columns:
+  - receipt_id: INTEGER
+  - customer_name: VARCHAR(255)
+  - price: FLOAT
+  - tip: FLOAT
+```
 
-Tools are the interfaces your AI agent uses to interact with external systems. Each tool should be a Python function.
+Now, we'll construct our `sql_engine` tool. Key elements include:
 
-- **Define a Python function for your tool:** This function should encapsulate the logic for a specific action (e.g., querying the database, making an API call, reading a file).
-- **Decorate it with `@tool`:** This tells the smolagents framework that this function is an agent tool.
-- **Provide a clear and detailed docstring:** This docstring is crucial. The LLM will read this description to understand what the tool does, its parameters, and what information it provides. Include:
-- A high-level explanation of the tool's purpose.
-- A detailed description of the data it can access or modify (e.g., table schemas, API endpoints).
-- Examples if necessary.
+- 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
-from sqlalchemy import text # Make sure to import text for raw SQL execution
 
-`@tool`
+@tool
 def sql_engine(query: str) -> str:
-"""
-Allows you to perform SQL queries on the database.
-Returns a string representation of the query results.
+    """
+    Enables execution of SQL queries against the database.
+    Outputs the query results as a formatted string.
 
-    Available tables and their schemas:
+    Known tables and their column structures:
     Table 'receipts':
       Columns:
         - receipt_id: INTEGER (Primary Key)
@@ -140,61 +130,125 @@ Returns a string representation of the query results.
         - price: FLOAT
         - tip: FLOAT
 
-    Table 'waiters':
-      Columns:
-        - receipt_id: INTEGER (Primary Key)
-        - waiter_name: VARCHAR(16) (Primary Key)
-
     Args:
-        query: The SQL query string to execute. This should be correct SQL.
-               Example: "SELECT customer_name FROM receipts WHERE price > 10.0"
+        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:
-        rows = con.execute(text(query)) # Use text() for raw SQL queries
+        # Utilize text() to safely execute raw SQL within SQLAlchemy
+        rows = con.execute(text(query))
         for row in rows:
-            output += "\n" + str(row)
+            output += "\n" + str(row) # Converts each row of results into a string representation
     return output
 ```
 
-- **Tip:** Keep the tool's output as consistent and parseable as possible. The LLM will need to interpret this string.
+### Step 3: Assembling the AI Agent
 
-### Step 3: Instantiate Your 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.
 
-Now, you bring everything together by creating your `CodeAgent` and providing it with the necessary components.
-
-- **Choose your LLM:** Select a suitable language model. Different models have different capabilities and cost implications.
-- **Initialize `CodeAgent`:** Pass your list of tools and your chosen LLM.
+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
+from smolagents import CodeAgent, InferenceClientModel
 
-agent = `CodeAgent`(
-tools=[sql_engine], # Provide the list of tools your agent can use
-model=InferenceClientModel(model_id="meta-llama/Llama-3.1-8B-Instruct"), # Or another model
+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: Give Your Agent a Task
+### 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.
 
-Once your agent is set up, you can give it natural language prompts, and it will attempt to solve them using its tools and reasoning.
+To achieve this, we'll define a second table, `waiters`, which records the names of waiters associated with each `receipt_id`.
 
-- **Run the agent with a prompt:**
+```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
-agent.run("Can you tell me the customer with the highest tip amount?")
+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)
 ```
 
-The agent will then go through its loop: interpret the question, decide if sql_engine is needed, generate SQL, execute it, process results, and formulate an answer.
+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?")
+```
 
-### Step 5: Iterate and Refine
+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!
 
-Building effective agents is an iterative process.
+This tutorial covered several key concepts:
 
-- **Review Agent Output and Execution logs:** Pay close attention to the `Execution logs`. If the agent fails, analyze the error messages to understand why.
-- **Improve Tool Descriptions:** Often, agents fail because the tool's description isn't clear enough, or doesn't provide all the necessary context (e.g., table schemas, data types). Make your tool descriptions as precise and comprehensive as possible.
-- **Refine Prompts:** Sometimes, rephrasing the initial prompt can help the agent understand the task better.
-- **Consider Model Choice:** Different LLMs excel at different tasks. If one model struggles, experimenting with another might yield better results.
-- **Handle Complex Output Parsing:** As seen in the example, parsing the string output from tools can be tricky. The agent might need to generate additional Python code to properly extract information from the tool's raw string output.
+- **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.
 
-By following these steps, you can start building powerful AI agents that can automate tasks, answer questions, and interact with various systems using natural language, making them incredibly versatile for many applications.
+✅ You are now equipped to start building your own advanced text-to-SQL systems! ✨