sqlalchemy-llm-agent 0.1.1

Sqlalchemy nl2sql agent

SQLAlchemy LLM Agent

sqlalchemy-llm-agent packages a small, batteries-included LangChain agent that can inspect SQLAlchemy schemas and run ad-hoc SQL queries generated by an LLM. It is helpful when you want to expose a controlled subset of your database to an LLM-powered assistant without wiring up all of the boilerplate yourself.

Features

• Table-aware prompts – the agent automatically enumerates the tables available to it and bakes them into its system prompt so the LLM understands the data surface area it can use.
• Schema inspection tool – provides a LangChain tool that reads table metadata via sqlalchemy.inspect so the LLM can learn column names and types before writing SQL.
• Query execution tool – safely executes generated SQL statements through your SQLAlchemy Engine and returns rows as dictionaries for further processing.
• Config-driven access control – restrict the agent to a whitelist of tables by name or give it access to every table in the database via the special "*" entry.

Installation

pip install sqlalchemy-llm-agent

Quickstart

Below is a minimal end-to-end example that shows how to configure and call the agent. This example assumes you already have a SQLAlchemy Engine and have run inspect(engine) to produce an inspector object.

from sqlalchemy import create_engine, inspect
from sqlalchemy_llm_agent import SqlalchemyAgent, SqlalchemyAgentConfig

engine = create_engine("postgresql+psycopg://user:pass@localhost:5432/mydb")
inspector = inspect(engine)

config = SqlalchemyAgentConfig(
    api_key="sk-openai-123",  # Replace with your actual OpenAI API key
    model="gpt-5",            # Optional, defaults to gpt-5
    tables=["users", "orders"],  # Limit the agent to just these tables
    row_limit=100,
    inspector=inspector,
    engine=engine,
)

agent = SqlalchemyAgent(config)
result_rows = agent.query("List the five most recent orders including user email")
for row in result_rows:
    print(row)

The agent will automatically:

1. Inspect the users and orders tables to learn their columns.
2. Generate a SQL query using the configured LLM (gpt-5 by default).
3. Execute the query through your SQLAlchemy engine and return the results as a list of dictionaries.

You now have a reusable component that can power chatbots, dashboards, or internal tools that need natural-language access to relational data.