Natural Language SQL Agent: Mercury + Tool Calling

This cookbook demonstrates how to build a natural language database query system using Mercury 2’s tool calling capabilities. The full loop — natural language question, SQL generation, execution, and formatted answer — completes in under 2 seconds. We walk you through how to:

Load a SQLite database (sample or your own)
Auto-detect the schema and define a SQL tool for Mercury 2
Translate natural language questions into SQL using tool calling
Execute queries and return natural language answers
Measure end-to-end latency at each step

Run the SQL Agent

Directly via Google Colab or download the .ipynb to run it locally in Jupyter

Download Sample Database

Download the sample e-commerce SQLite database to use with the notebook.

Dependencies

Install packages and import the libraries required for the Mercury 2 API and SQLite:

%pip install \
  "inceptionai" \
  "python-dotenv>=1.0.0"

import os
import json
import time
import sqlite3
from inceptionai import Inception
from dotenv import load_dotenv

API Keys

Set up your Inception Labs API key.

Create a .env file in this directory
Add your API key to the .env:
- INCEPTION_API_KEY

The key will be automatically loaded from the .env file.

# Load environment variables from .env file
load_dotenv()
INCEPTION_API_KEY = os.getenv("INCEPTION_API_KEY")

Initialize Client

Initialize the Inception (Mercury 2) client:

assert INCEPTION_API_KEY is not None, (
    "ERROR: INCEPTION_API_KEY not found. Please create a .env file and add your API key."
)

client = Inception(api_key=INCEPTION_API_KEY)
MERCURY_MODEL = "mercury-2"

Load Database

We create a small in-memory e-commerce database with three tables — customers, products, and orders. If you want to use your own SQLite database instead, replace this cell with db = sqlite3.connect("your_file.db").

# To use your own SQLite database instead, replace this cell with:
#   db = sqlite3.connect("path/to/your/database.db")

db = sqlite3.connect(":memory:")
cursor = db.cursor()
cursor.executescript("""
CREATE TABLE customers (
    id INTEGER PRIMARY KEY,
    name TEXT NOT NULL,
    email TEXT NOT NULL,
    signup_date TEXT NOT NULL
);

CREATE TABLE products (
    id INTEGER PRIMARY KEY,
    name TEXT NOT NULL,
    category TEXT NOT NULL,
    price REAL NOT NULL,
    stock INTEGER NOT NULL
);

CREATE TABLE orders (
    id INTEGER PRIMARY KEY,
    customer_id INTEGER NOT NULL,
    product_id INTEGER NOT NULL,
    quantity INTEGER NOT NULL,
    total_amount REAL NOT NULL,
    status TEXT NOT NULL,
    order_date TEXT NOT NULL,
    FOREIGN KEY (customer_id) REFERENCES customers(id),
    FOREIGN KEY (product_id) REFERENCES products(id)
);

INSERT INTO customers VALUES (1, 'Alice Johnson', '[email protected]', '2024-01-15');
INSERT INTO customers VALUES (2, 'Bob Smith', '[email protected]', '2024-02-20');
INSERT INTO customers VALUES (3, 'Sarah Lee', '[email protected]', '2024-03-10');
INSERT INTO customers VALUES (4, 'Mike Chen', '[email protected]', '2024-04-05');
INSERT INTO customers VALUES (5, 'Emma Wilson', '[email protected]', '2024-05-12');

INSERT INTO products VALUES (1, 'Wireless Headphones', 'Electronics', 79.99, 45);
INSERT INTO products VALUES (2, 'Running Shoes', 'Sports', 129.99, 30);
INSERT INTO products VALUES (3, 'Coffee Maker', 'Home & Kitchen', 49.99, 60);
INSERT INTO products VALUES (4, 'Backpack', 'Accessories', 59.99, 25);
INSERT INTO products VALUES (5, 'Yoga Mat', 'Sports', 29.99, 80);
INSERT INTO products VALUES (6, 'Desk Lamp', 'Home & Kitchen', 34.99, 55);
INSERT INTO products VALUES (7, 'Water Bottle', 'Accessories', 19.99, 100);
INSERT INTO products VALUES (8, 'Bluetooth Speaker', 'Electronics', 99.99, 35);

INSERT INTO orders VALUES (1, 1, 1, 1, 79.99, 'delivered', '2025-01-10');
INSERT INTO orders VALUES (2, 1, 3, 2, 99.98, 'delivered', '2025-01-15');
INSERT INTO orders VALUES (3, 2, 2, 1, 129.99, 'shipped', '2025-02-01');
INSERT INTO orders VALUES (4, 3, 5, 2, 59.98, 'delivered', '2025-02-10');
INSERT INTO orders VALUES (5, 3, 1, 1, 79.99, 'delivered', '2025-02-14');
INSERT INTO orders VALUES (6, 4, 8, 1, 99.99, 'pending', '2025-03-01');
INSERT INTO orders VALUES (7, 4, 4, 1, 59.99, 'pending', '2025-03-05');
INSERT INTO orders VALUES (8, 5, 6, 2, 69.98, 'shipped', '2025-03-08');
INSERT INTO orders VALUES (9, 2, 7, 3, 59.97, 'delivered', '2025-03-10');
INSERT INTO orders VALUES (10, 1, 8, 1, 99.99, 'pending', '2025-03-12');
INSERT INTO orders VALUES (11, 5, 3, 1, 49.99, 'delivered', '2025-01-20');
INSERT INTO orders VALUES (12, 3, 7, 2, 39.98, 'shipped', '2025-03-14');
""")
db.commit()

Inspect Schema

We introspect the schema directly from the database, so the tool calling setup automatically adapts to whatever tables are loaded:

cursor.execute("SELECT sql FROM sqlite_master WHERE type='table' AND sql IS NOT NULL")
DB_SCHEMA = "\n\n".join(row[0] for row in cursor.fetchall())

print("Detected schema:")
print(DB_SCHEMA)

Define the SQL Tool

We define a single tool — run_sql_query — that Mercury 2 can call to execute SQL against our database. The tool description includes the auto-detected schema so Mercury knows what tables and columns are available:

tools = [
    {
        "type": "function",
        "function": {
            "name": "run_sql_query",
            "description": f"Execute a read-only SQL query against the SQLite database. Schema:\n{DB_SCHEMA}",
            "parameters": {
                "type": "object",
                "properties": {
                    "query": {
                        "type": "string",
                        "description": "The SQL SELECT query to execute",
                    }
                },
                "required": ["query"],
            },
        },
    }
]


def run_sql_query(query: str) -> str:
    """Execute a SQL query and return results as a formatted string."""
    try:
        cursor.execute(query)
        columns = [desc[0] for desc in cursor.description] if cursor.description else []
        rows = cursor.fetchall()
        if not rows:
            return "No results found."
        result = " | ".join(columns) + "\n"
        result += "-" * len(result) + "\n"
        for row in rows:
            result += " | ".join(str(val) for val in row) + "\n"
        return result
    except Exception as e:
        return f"SQL Error: {e}"


tool_functions = {"run_sql_query": run_sql_query}

Query Helper

This function handles the full tool-calling loop:

Send the user’s natural language question to Mercury 2 with the tool definition
Mercury generates a run_sql_query tool call with SQL
We execute the SQL and send results back to Mercury
Mercury returns a natural language answer

We time each step to show the latency breakdown.

def ask_database(question: str) -> dict:
    """
    Full tool-calling loop: question -> Mercury tool call -> SQL exec -> Mercury answer.
    Returns timing breakdown and the final answer.
    """
    messages = [{"role": "user", "content": question}]

    # Step 1: Mercury generates a tool call
    t0 = time.time()
    response = client.chat.completions.create(
        model=MERCURY_MODEL,
        messages=messages,
        tools=tools,
    )
    t1 = time.time()

    assistant_message = response.choices[0].message
    tool_call = assistant_message.tool_calls[0]
    function_name = tool_call.function.name
    function_args = json.loads(tool_call.function.arguments)

    print(f"Generated SQL: {function_args['query']}")

    # Step 2: Execute the SQL
    t2 = time.time()
    result = tool_functions[function_name](**function_args)
    t3 = time.time()

    print(f"Query result:\n{result}")

    # Step 3: Send tool result back to Mercury for a natural language answer
    messages.append(assistant_message.model_dump(exclude_none=True))
    messages.append(
        {
            "role": "tool",
            "tool_call_id": tool_call.id,
            "content": result,
        }
    )

    t4 = time.time()
    response = client.chat.completions.create(
        model=MERCURY_MODEL,
        messages=messages,
    )
    t5 = time.time()

    final_answer = response.choices[0].message.content

    timing = {
        "tool_call_generation": round(t1 - t0, 3),
        "sql_execution": round(t3 - t2, 3),
        "answer_generation": round(t5 - t4, 3),
        "total": round(t5 - t0, 3),
    }

    return {"answer": final_answer, "sql": function_args["query"], "timing": timing}

Natural Language Database Queries

Let’s run several queries and measure the full round-trip latency. Each query goes through: NL question, SQL generation, execution, and NL answer.

Query 1: Aggregation

“Who are the top 3 customers by total spending?”

result = ask_database("Who are the top 3 customers by total spending?")
print(f"\nAnswer: {result['answer']}")
print(f"\nLatency breakdown:")
for step, duration in result["timing"].items():
    print(f"  {step}: {duration}s")

Query 2: Filtering

“Which orders are still pending?”

result = ask_database("Which orders are still pending?")
print(f"\nAnswer: {result['answer']}")
print(f"\nLatency breakdown:")
for step, duration in result["timing"].items():
    print(f"  {step}: {duration}s")

Query 3: Join + Lookup

“Show me all orders placed by Sarah Lee.”

result = ask_database("Show me all orders placed by Sarah Lee.")
print(f"\nAnswer: {result['answer']}")
print(f"\nLatency breakdown:")
for step, duration in result["timing"].items():
    print(f"  {step}: {duration}s")

Query 4: Analytics

“What is the most popular product category by number of items sold?”

result = ask_database("What is the most popular product category by number of items sold?")
print(f"\nAnswer: {result['answer']}")
print(f"\nLatency breakdown:")
for step, duration in result["timing"].items():
    print(f"  {step}: {duration}s")

Query 5: Revenue

“What’s our total revenue from delivered orders?”

result = ask_database("What's our total revenue from delivered orders?")
print(f"\nAnswer: {result['answer']}")
print(f"\nLatency breakdown:")
for step, duration in result["timing"].items():
    print(f"  {step}: {duration}s")

Latency Summary

Mercury 2’s diffusion-based architecture generates tokens ~5x faster than traditional autoregressive LLMs. In the queries above, the full tool-calling loop — understanding the question, generating SQL, executing it, and summarizing results in natural language — consistently completes in around 1-2 seconds. SQL execution itself is near-instant; the time is spent on two Mercury inference calls (tool call generation + answer generation), each typically under 1 second. This makes Mercury 2 fast enough to power real-time, interactive database assistants where users expect instant answers to ad-hoc questions — no waiting, no loading spinners.

Getting Started

API reference

Capabilities

Resources

Support

Natural Language SQL Agent: Mercury + Tool Calling

Run the SQL Agent

Download Sample Database

Dependencies

API Keys

Initialize Client

Load Database

Inspect Schema

Define the SQL Tool

Query Helper

Natural Language Database Queries

Query 1: Aggregation

Query 2: Filtering

Query 3: Join + Lookup

Query 4: Analytics

Query 5: Revenue

Latency Summary

Run the SQL Agent

Download Sample Database

​Dependencies

​API Keys

​Initialize Client

​Load Database

​Inspect Schema

​Define the SQL Tool

​Query Helper

​Natural Language Database Queries

​Query 1: Aggregation

​Query 2: Filtering

​Query 3: Join + Lookup

​Query 4: Analytics

​Query 5: Revenue

​Latency Summary

Dependencies

API Keys

Initialize Client

Load Database

Inspect Schema

Define the SQL Tool

Query Helper

Natural Language Database Queries

Query 1: Aggregation

Query 2: Filtering

Query 3: Join + Lookup

Query 4: Analytics

Query 5: Revenue

Latency Summary