Natural language to SQL

Install

git clone https://github.com/palmshed/predicate.git
cd predicate
cp .env.example .env
docker-compose up --build

Quick start

import requests

res = requests.post(
    "http://localhost:8000/api/v1/query/compile",
    headers={"X-Predicate-API-Key": "test_key_alpha"},
    json={"prompt": "Show me orders over $500 from active customers"}
)

data = res.json()
print(data["compiled_sql"])   # SELECT orders.id ...
print(data["parameters"])     # ['tenant_alpha', 500, 'active']
print(data["results"])        # [{...}, {...}]

What it does

• compile, translate natural language into parameterized SQL via configurable LLM providers (OpenAI, OpenRouter).
• execute, run the query against PostgreSQL with automatic tenant isolation.
• cache, Redis-backed SHA-256 query signature cache for sub-2ms repeated lookups.
• rate limit, per-tenant fixed-window rate limiting across three tiers.
• export, async Celery workers for bulk CSV exports without HTTP timeouts.
• audit, compliance sink that logs every prompt, query, and result to PostgreSQL.
• security, CSRF protection, security headers (HSTS, CSP, nosniff), input validation, query timeouts.
• observe, structured JSON logging, X-Request-ID correlation, TraceContext spans, Prometheus metrics.

Performance

The SQL compiler generates parameterized queries in 3.6 microseconds at median, scaling to 641k queries/sec across 4 CPU cores with zero lock contention.

• 3.6 us median compile latency
• 174k q/s single-process throughput
• 99.2% linear scaling efficiency (2 processes)
• 1 us SHA-256 signature overhead

API endpoints

POST /api/v1/query/compile    Translate NL to SQL and execute
POST /api/v1/export/async    Queue bulk CSV export (Celery)
GET  /api/v1/metrics         Per-tenant analytics
GET  /health                 Health check (db, redis, uptime)
GET  /ready                  Readiness probe
GET  /metrics                Prometheus metrics

Resources

• GitHub
• Documentation
• Swagger UI

Found something unexpected? Report an issue.