datanaut 0.1.2

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

  ██████╗  █████╗ ████████╗ █████╗ ███╗   ██╗ █████╗ ██╗   ██╗████████╗
  ██╔══██╗██╔══██╗╚══██╔══╝██╔══██╗████╗  ██║██╔══██╗██║   ██║╚══██╔══╝
  ██║  ██║███████║   ██║   ███████║██╔██╗ ██║███████║██║   ██║   ██║
  ██║  ██║██╔══██║   ██║   ██╔══██║██║╚██╗██║██╔══██║██║   ██║   ██║
  ██████╔╝██║  ██║   ██║   ██║  ██║██║ ╚████║██║  ██║╚██████╔╝   ██║
  ╚═════╝ ╚═╝  ╚═╝   ╚═╝   ╚═╝  ╚═╝╚═╝  ╚═══╝╚═╝  ╚═╝ ╚═════╝    ╚═╝

  🚀  SQL Explorer v1.0  ·  Navigating the BigQuery galaxy...

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

What is Datanaut?

Datanaut is a CLI agent that converts plain English questions into optimized BigQuery SQL using GPT-4. No SQL knowledge required — just ask your question and Datanaut handles schema retrieval, query generation, cost estimation, and execution.

  🧑‍🚀  You: how many sessions were completed yesterday?

  🗺️   Retrieving relevant schema...
  🤖   Generating SQL with GPT-4...
       GPT-4: Counts completed healing sessions for the previous day.
       Optimizations: partition pruning, specific column selection
  ⚗️   Running BigQuery dry run...

  ╔══════════════════════════════════════════════════════════╗
  ║  >>  MISSION QUERY                                       ║
  ╠══════════════════════════════════════════════════════════╣
  ║  SELECT COUNT(*) AS completed_sessions                   ║
  ║  FROM `wehealanalysis`.`asia_south1_healing`             ║
  ║       .healing_sessions(                                 ║
  ║         DATE_SUB(CURRENT_DATE(), INTERVAL 1 DAY),        ║
  ║         DATE_SUB(CURRENT_DATE(), INTERVAL 1 DAY)         ║
  ║       )                                                  ║
  ║  WHERE completedTimestamp IS NOT NULL                    ║
  ╚══════════════════════════════════════════════════════════╝

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

Installation

pip install datanaut

Setup Within Few Minutes

Step 1 — Authenticate with Google Cloud

gcloud auth application-default login

Don't have the Google Cloud SDK? Download it from cloud.google.com/sdk

Step 2 — Set your OpenAI API key

datanaut config --api-key sk-...

This saves your key globally to ~/.datanaut/config.json — you only need to do this once. No .env file needed in every folder.

Don't have an OpenAI API key? Get one at platform.openai.com/api-keys

Step 3 — Launch

datanaut

That's it. Start asking questions.

Commands

Interactive REPL commands

Once inside the REPL, these special commands are available:

Example questions you can ask

Sessions

how many sessions were completed yesterday?
show me total session duration by listener this week
which session types are most popular this month?
what is the average session duration for chat vs call?

Payments & Revenue

total revenue today
show payments by medium for last 7 days
which users made their first payment this week?
what is revenue by UTM campaign this month?

Users

how many new users signed up yesterday?
show me DAU for the last 30 days
which users have been active but never paid?

Listeners

which listeners had the most cancellations last week?
show listener online duration for today
who are the top 10 listeners by session count this month?

Marketing

which ad campaign brought the most users last month?
show revenue per user by ad category this week
what is CTR by marketing channel?

Features

• GPT-4 with function calling — structured, reliable SQL output every time
• BigQuery dry run — validates SQL and estimates cost before execution
• Cost guardrail — automatically rejects queries that would scan more than 5 GB
• Self-correcting retry — passes BigQuery errors back to GPT-4 for auto-fix (up to 3 attempts)
• Conversation memory — refine queries across turns ("now filter by last 7 days", "add region breakdown")
• Result cache — identical queries skip BigQuery entirely, zero cost
• Datanaut theme — space explorer animations, syntax-highlighted SQL, color-coded cost badges

How it works

Your question
     │
     ▼
Schema retrieval ──── Finds the most relevant table functions from schema.json
     │
     ▼
GPT-4 generation ──── Injects schema + BigQuery rules + your question
     │
     ▼
Dry run ────────────── Validates SQL, estimates bytes scanned, checks cost limit
     │
     ▼
Your confirmation ──── Shows you the SQL and cost before running
     │
     ▼
BigQuery execution ─── Streams results back to your terminal

Requirements

Troubleshooting

ModuleNotFoundError: No module named 'datanaut'

pip install --upgrade datanaut

google.auth.exceptions.DefaultCredentialsError

gcloud auth application-default login

OPENAI_API_KEY is not set

datanaut config --api-key sk-...

Query exceeds 5 GB scan limit Add a tighter date range to your question:

instead of: "show all sessions"
ask:        "show sessions from last 7 days"

License

MIT © 2024 WeHeal