datanaut 0.1.1

A CLI SQL agent that converts natural language to optimized BigQuery SQL using GPT-4

🚀 Datanaut — BigQuery SQL Agent

A CLI agent that converts plain English questions into optimized BigQuery SQL using GPT-4. Built for data teams who want to query BigQuery without writing SQL.

  ✦ · ✧ · ✦ · ✧ · ✦ · ✧ · ✦ · ✧ · ✦ · ✧ · ✦ · ✧ · ✦ · ✧

  DATANAUT  >>  SQL Explorer v1.0
  Navigating the BigQuery galaxy...

  ✦ · ✧ · ✦ · ✧ · ✦ · ✧ · ✦ · ✧ · ✦ · ✧ · ✦ · ✧ · ✦ · ✧

Installation

pip install datanaut

Quick start

# 1. Scaffold config in your project folder
datanaut init

# 2. Fill in your keys in .env
#    OPENAI_API_KEY=sk-...
#    BIGQUERY_PROJECT_ID=your-project

# 3. Edit schema.json with your BigQuery tables / table functions

# 4. Authenticate with GCP
gcloud auth application-default login

# 5. Launch
datanaut

Usage

datanaut                              # interactive REPL
datanaut ask "total revenue today"    # one-shot query
datanaut ask "..." --dry-run          # validate SQL, skip execution
datanaut test                         # run accuracy test suite
datanaut init                         # scaffold .env + schema.json
datanaut --version

Interactive REPL example

  🧑‍🚀  You: show me total revenue by region last month

  🗺️   Retrieving relevant schema...
  🤖   Generating SQL with GPT-4...
  ⚗️   Running BigQuery dry run...

  ╔══════════════════════════════════════════════╗
  ║  >>  MISSION QUERY                           ║
  ╠══════════════════════════════════════════════╣
  ║  WITH last_month AS (                        ║
  ║    SELECT region,                            ║
  ║           SUM(total_revenue) AS revenue      ║
  ║    FROM `project.dataset.orders`             ║
  ║    WHERE order_date >= ...                   ║
  ║  )                                           ║
  ║  SELECT * FROM last_month                    ║
  ║  ORDER BY revenue DESC LIMIT 1000            ║
  ╚══════════════════════════════════════════════╝

  ✅  Estimated scan: 84.2 MB
  🚀  Launch this query? (y/n):

Configuration

.env

OPENAI_API_KEY=sk-...
BIGQUERY_PROJECT_ID=your-gcp-project-id
BQ_COST_THRESHOLD_BYTES=5368709120   # 5 GB — queries above this are rejected
CACHE_ENABLED=true
CACHE_TTL_SECONDS=3600
GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json   # optional

schema.json

Describe your BigQuery tables or table functions. The richer the descriptions, the more accurate GPT-4's SQL will be.

[
  {
    "dataset": "your_dataset",
    "table_name": "orders",
    "description": "Customer orders with revenue and status",
    "partition_column": "order_date",
    "tags": ["sales", "revenue", "orders"],
    "columns": [
      { "name": "order_id",      "type": "STRING",  "description": "Unique order ID" },
      { "name": "order_date",    "type": "DATE",    "description": "Order date — partition column" },
      { "name": "total_revenue", "type": "FLOAT64", "description": "Revenue in USD" }
    ]
  }
]

For BigQuery table functions (TVFs), use:

{
  "function_name": "healing_sessions",
  "description": "Session data filtered by date range",
  "call_syntax": "`project`.`dataset`.healing_sessions(start_date_param, end_date_param)",
  "parameters": [
    { "name": "start_date_param", "type": "DATE" },
    { "name": "end_date_param",   "type": "DATE" }
  ],
  "columns": [ ... ]
}

GCP Authentication

# Option A — personal credentials (easiest)
gcloud auth application-default login

# Option B — service account key
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json

Features

• GPT-4 with function calling for structured, reliable SQL output
• BigQuery dry run before every execution — validates SQL and estimates cost
• Configurable cost threshold — rejects expensive queries automatically
• Self-correcting retry loop — passes BigQuery errors back to GPT-4
• In-memory result cache with TTL (Redis-ready interface)
• Multi-turn conversation memory — refine queries across turns
• Keyword-based schema retrieval (swap for vector search in production)
• Batch test runner for accuracy regression testing

License

MIT