(FEAT): Add README and implement SQL engine tool for AI agent interaction

README.md

@@ -0,0 +1,200 @@
+# Building Smart Agents: Turning Natural Language into Database Actions
+
+**Goal**: Understand how to build AI agents that can interpret natural language questions, interact with a database using SQL, and provide relevant answers.
+
+## What is This Code Doing?
+
+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:**
+
+1. Database Setup:
+
+- 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.
+
+2. Tool Creation (`sql_engine`):
+
+- 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.
+
+3. AI Agent Instantiation and Task Execution:
+
+- 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:
+
+### Step 1: Define Your Data and Environment
+
+First, you need to decide what external systems your agent will interact with. In this example, it's a database.
+
+**Set up your database (or other external system):**
+
+- 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.
+
+```python
+from sqlalchemy import create_engine, MetaData, Table, Column, String, Integer, Float
+
+engine = create_engine("sqlite:///:memory:") # In-memory database for this example
+metadata_obj = MetaData()
+
+# Define your tables
+
+receipts = Table(
+"receipts",
+metadata_obj,
+Column("receipt_id", Integer, primary_key=True),
+Column("customer_name", String(255)),
+Column("price", Float),
+Column("tip", Float),
+)
+
+# Add other tables as needed, e.g., 'waiters'
+
+metadata_obj.create_all(engine) # Create tables in the database
+
+# Insert initial data
+
+# ... (as shown in the example code)
+```
+
+### Step 2: Create Tools for Your Agent
+
+Tools are the interfaces your AI agent uses to interact with external systems. Each tool should be a Python function.
+
+- **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.
+
+```python
+from smolagents import tool
+from sqlalchemy import text # Make sure to import text for raw SQL execution
+
+`@tool`
+def sql_engine(query: str) -> str:
+"""
+Allows you to perform SQL queries on the database.
+Returns a string representation of the query results.
+
+    Available tables and their schemas:
+    Table 'receipts':
+      Columns:
+        - receipt_id: INTEGER (Primary Key)
+        - customer_name: VARCHAR(255)
+        - 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"
+    """
+    output = ""
+    with engine.connect() as con:
+        rows = con.execute(text(query)) # Use text() for raw SQL queries
+        for row in rows:
+            output += "\n" + str(row)
+    return output
+```
+
+- **Tip:** Keep the tool's output as consistent and parseable as possible. The LLM will need to interpret this string.
+
+### Step 3: Instantiate Your AI Agent
+
+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.
+
+```python
+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
+)
+```
+
+### Step 4: Give Your Agent a Task
+
+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.
+
+- **Run the agent with a prompt:**
+
+```python
+agent.run("Can you tell me the customer with the highest tip amount?")
+```
+
+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.
+
+### Step 5: Iterate and Refine
+
+Building effective agents is an iterative process.
+
+- **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.
+
+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.

text_to_sql.py

@@ -0,0 +1,130 @@
+from dotenv import load_dotenv
+
+load_dotenv()
+
+from sqlalchemy import (
+    create_engine,
+    MetaData,
+    Table,
+    Column,
+    String,
+    Integer,
+    Float,
+    insert,
+    text,  # Import text to be used in sql_engine tool
+)
+from sqlalchemy import inspect
+from smolagents import tool, CodeAgent, InferenceClientModel
+
+
+engine = create_engine("sqlite:///:memory:")
+metadata_obj = MetaData()
+
+
+def insert_rows_into_table(data_rows, target_table, engine=engine):
+    for row in data_rows:
+        stmt = insert(target_table).values(**row)
+        with engine.begin() as connection:
+            connection.execute(stmt)
+
+
+table_name = "receipts"
+# Corrected receipts table definition
+receipts = Table(
+    table_name,
+    metadata_obj,
+    Column("receipt_id", Integer, primary_key=True),
+    Column("customer_name", String(255)),  # Added customer_name column
+    Column("price", Float),
+    Column("tip", Float),
+)
+metadata_obj.create_all(engine)
+
+rows = [
+    {"receipt_id": 1, "customer_name": "Alex 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},
+]
+insert_rows_into_table(rows, receipts)
+
+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)
+
+
+@tool
+def sql_engine(query: str) -> str:
+    """
+    Allows you to perform SQL queries on the table. Returns a string representation of
+    the result. The table is named 'receipts'. It's description is as follows:
+        Columns:
+            - receipt_id: INTEGER
+            - customer_name: STRING
+            - price: FLOAT
+            - tip: FLOAT
+
+        Args:
+            query: The query to perform. This should be correct SQL.
+
+    """
+    output = ""
+    with engine.connect() as con:
+        rows = con.execute(text(query))
+        for row in rows:
+            output += "\n" + str(row)
+
+    return output
+
+
+agent = CodeAgent(
+    tools=[sql_engine],
+    model=InferenceClientModel(model_id="meta-llama/Llama-3.1-8B-Instruct"),
+)
+agent.run("Can you give me the name of the client who got the most expensive receipt?")
+
+table_name = "waiters"
+waiters = Table(
+    table_name,
+    metadata_obj,
+    Column("receipt_id", Integer, primary_key=True),
+    Column("waiter_name", String(16), primary_key=True),
+)
+metadata_obj.create_all(engine)
+
+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"},
+]
+insert_rows_into_table(rows, waiters)
+
+updated_description = """Allows you to perform SQL queries on the table. Beware that this tool's output is a string representation of the execution output.
+It can use 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
+
+agent = CodeAgent(
+    tools=[sql_engine],
+    model=InferenceClientModel(model_id="Qwen/Qwen2.5-Coder-32B-Instruct"),
+)
+
+agent.run("Which waiter got more total money from tips?")