Metadata-Version: 2.4
Name: sauceql
Version: 0.1.0
Summary: A JSON-schema-defined, agent-safe read-only SQL query DSL and compiler.
Author-email: Sachin Das <sachindas246@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/SachinDas246/sauceql
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: jsonschema>=4.18
Dynamic: license-file

# sauceql

A JSON-schema-defined, agent-safe read-only SQL query DSL and compiler.

Define your tables (columns, relations, and safety restrictions like required
filters, max limit, allowed operators) in a JSON file validated against
`db_schema.json`. Agents submit queries as JSON matching `query_schema.json` -
a structured AST (no raw SQL strings), which is validated against your table
definitions and compiled to parameterized PostgreSQL SQL.

## Install

```
pip install sauceql
```

## Usage

```python
from sauceql import SauceEngine

engine = SauceEngine(tables_path="my_tables.json")

query = {
    "from": "orders",
    "select": ["orders.id", "orders.status"],
    "where": {"column": "status", "op": "eq", "value": "paid"},
    "order_by": [{"column": "created_at", "dir": "desc"}],
    "limit": 20,
}

sql, params = engine.toPGSQL(query, context={"tenant_id": "acme-corp"})
```

See `examples/demo.py` and `examples/example_tables.json` for a full worked
example with joins, aggregates, and tenant-scoping restrictions.

## Status

Early / pre-1.0. See the project's design notes for known gaps (no window
functions, CTEs, subqueries, DISTINCT, or expression columns yet).
