Metadata-Version: 2.4
Name: sqlalchemy-llm-agent
Version: 0.1.3
Summary: Sqlalchemy nl2sql agent
Home-page: https://github.com/org/sqlalchemy-llm-agent
License: MIT License
        
        Copyright (c) 2025 Lari
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in
        all copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
        THE SOFTWARE.
        
Project-URL: Homepage, https://github.com/laricko/sqlalchemy-llm-agent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: langchain[openai]>=1.0.5
Requires-Dist: sqlalchemy>=2.0.44
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# 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 whether work within cli or build quick administrative panel.

## Features
- **Only read operations** - Gives agent only to use safe sqlqueries.
- **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.

```python
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 or ["*"]
    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.

## Command-line usage
You can also run ad-hoc queries directly from a terminal with the bundled CLI. Create a Python
config file that exposes a `sqlalchemy_llm_agent_config` variable:

```python
# config.py
from sqlalchemy import create_engine, inspect
from sqlalchemy_llm_agent import SqlalchemyAgentConfig

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

sqlalchemy_llm_agent_config = SqlalchemyAgentConfig(
    api_key="sk-openai-123",
    tables=["payments"],
    inspector=inspector,
    engine=engine,
)
```

Then invoke the CLI by pointing it to the config file and passing the natural-language query:

```
sqlalchemy_llm_agent --config ./config.py "Give me success payments"
```

The command prints the resulting rows as formatted JSON, making it easy to script around or
inspect responses interactively.
