# 🚀 Datanaut — BigQuery SQL Agent

> Ask questions in plain English. Get BigQuery results instantly. No SQL required.

---

## What's in this folder

```
datanaut.exe      ← the app
launch.bat        ← double-click this to start
README.txt        ← this file
```

---

## Requirements

Before using Datanaut, make sure you have:

1. **An OpenAI API key**
   Get one at → https://platform.openai.com/api-keys

2. **Google Cloud access**
   You need to be logged into GCP with access to the `wehealanalysis` project.
   Install Google Cloud SDK → https://cloud.google.com/sdk/docs/install
   Then run once in any terminal:
   ```
   gcloud auth application-default login
   ```

---

## First Time Setup (2 minutes)

### Step 1 — Double-click `launch.bat`

A terminal window will open and ask for your OpenAI API key:

```
  DATANAUT - BigQuery SQL Agent

  Enter OpenAI API key (or press Enter to skip):
```

Paste your API key (starts with `sk-`) and press **Enter**.

Your key is saved to `C:\Users\YourName\.datanaut\config.json` — you only need to do this once.

### Step 2 — Start asking questions

The Datanaut banner will appear and you'll see:

```
  Type your question in plain English.
  Commands:  history · clear · exit

  🧑‍🚀  You:
```

Just type your question and press **Enter**.

---

## Example Questions

**Sessions**
```
how many sessions were completed yesterday?
show total session duration by listener this week
what is the average session duration for chat vs call?
which listeners had the most cancellations last week?
```

**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?
```

**Marketing**
```
which ad campaign brought the most users last month?
show revenue per user by ad category this week
top 5 UTM sources by number of payments this month
```

**Listeners**
```
show listener online duration for today
who are the top 10 listeners by session count this month?
which listeners applied for leave this week?
```

Datanaut always shows you the SQL and estimated scan size **before** running the query. You can review and confirm or cancel.

---

## Understanding the Output

```
  ╔══════════════════════════════════════════════╗
  ║  >>  MISSION QUERY                           ║   ← the generated SQL
  ╠══════════════════════════════════════════════╣
  ║  SELECT COUNT(*) AS sessions                 ║
  ║  FROM `wehealanalysis`...                    ║
  ╚══════════════════════════════════════════════╝

  ✅  Estimated scan: 43.2 MB                        ← cost estimate
  🚀  Launch this query? (y/n):                      ← your confirmation
```

**Cost badges:**
- ✅ Green  — small scan, safe to run
- ⚡ Yellow — medium scan, review the query
- ⚠️ Red    — large scan (>2 GB), consider narrowing your date range

---

## REPL Commands

While inside Datanaut, these special commands are available:

| Command | What it does |
|---|---|
| `history` | Show your previous questions and SQL |
| `clear` | Clear conversation memory |
| `exit` | Quit Datanaut |

---

## Tips for Better Results

- **Be specific with dates** — "last 7 days" or "yesterday" works better than "recently"
- **Name the metric clearly** — "total revenue" not just "revenue"
- **Follow up naturally** — Datanaut remembers your last 3 questions, so you can say "now group by region" after a previous query
- **If a query fails** — Datanaut will automatically retry up to 3 times with self-correction

---

## Troubleshooting

**Nothing happens when I double-click `launch.bat`**
→ Right-click `launch.bat` → Run as administrator

**`gcloud` is not recognized**
→ Install Google Cloud SDK from https://cloud.google.com/sdk/docs/install
→ Restart your terminal after installing

**API key error**
→ Run `launch.bat` again and re-enter your key
→ Or open CMD and run: `datanaut.exe config --api-key sk-...`

**Query exceeds scan limit**
→ Add a tighter date range to your question
→ Instead of "show all sessions" try "show sessions from last 7 days"

**Results look garbled with strange characters**
→ Use `launch.bat` instead of double-clicking `datanaut.exe` directly
→ Or open Windows Terminal (not CMD) for best display

---

## Need Help?

For any issue mail at: aman.gupta@wehealapp.in

---

*Datanaut v0.1.2 · Datanaut CLI Agent · WeHeal Internal Tool*
