QuerySUTRA 0.6.2
AI-powered data analysis for structured and unstructured data. Query PDF, Word, CSV, Excel with natural language.
License: MIT
Requires Python: >=3.8
Keywords: ai, data-analysis, nlp, sql, pdf, openai, natural-language, query, database

# QuerySUTRA

**Natural language to SQL.** Upload PDF, CSV, Excel — ask questions in plain English.

```
pip install QuerySUTRA
```

## Usage

```python
from sutra import SUTRA

sutra = SUTRA(api_key="your-openai-key")
sutra.upload("data.pdf")
result = sutra.ask("How many employees are in each state?")
print(result.data)
```

## Upload Any Format

```python
sutra.upload("report.pdf")       # PDF — AI extracts entities into related tables
sutra.upload("sales.csv")        # CSV
sutra.upload("data.xlsx")        # Excel
sutra.upload("records.json")     # JSON

import pandas as pd
df = pd.DataFrame({"name": ["Alice", "Bob"], "score": [95, 87]})
sutra.upload(df, name="students")
```

## Ask Questions

```python
result = sutra.ask("Show top 5 products by revenue")
print(result.sql)         # Generated SQL
print(result.data)        # pandas DataFrame

# With charts
result = sutra.ask("Sales by region", viz=True)        # Auto-picks best chart
result = sutra.ask("Revenue split", viz="pie")          # Specific chart type
result = sutra.ask("Price over time", viz="line")       # pie | bar | line | scatter
```

## Explore Data

```python
sutra.tables()              # List all tables
sutra.schema()              # Show columns and types
sutra.peek()                # Preview rows
sutra.peek("sales", 10)    # Specific table
```

## Direct SQL

```python
result = sutra.sql("SELECT * FROM products WHERE price > 100")
```

## Export

```python
sutra.save_to_mysql("localhost", "root", "password", "my_db")
sutra.export_db("backup.json", format="json")
```

## How It Works

```
Upload File → AI extracts entities into related tables (with foreign keys)
            → Stored in SQLite
            → Ask questions in English
            → AI generates SQL with proper JOINs
            → Results as DataFrame + optional chart
```

**Smart JOINs** — QuerySUTRA detects foreign key relationships between tables (`person_id → people.id`) and generates proper JOIN queries automatically. When you ask "Who is the DevOps engineer?", it knows to JOIN work_experience with people to get the name.

**Smart Charts** — Auto-picks the right visualization. Few categories → pie. Many categories → bar. Two numbers → scatter. Or specify: `viz="pie"`.

## Troubleshooting

After installing or upgrading, if your Jupyter notebook still uses the old version:

```python
# Option 1: Restart kernel and re-import
# Kernel → Restart Kernel

# Option 2: Force reload without restarting
import importlib
import sutra
import sutra.sutra
importlib.reload(sutra.sutra)
from sutra.sutra import SUTRA
```

Check which version is loaded:

```python
import sutra
print(sutra.__version__, sutra.__file__)
```

## Install Extras

```bash
pip install QuerySUTRA[mysql]       # MySQL export
pip install QuerySUTRA[embeddings]  # Semantic similarity
pip install QuerySUTRA[all]         # Everything
```

## API

| Method | Description |
|--------|-------------|
| `SUTRA(api_key, db)` | Initialize. `db` defaults to `"sutra.db"` |
| `.upload(file_or_df, name)` | Upload from file path or DataFrame |
| `.ask(question, viz)` | Natural language query. `viz=True` or `"pie"/"bar"/"line"/"scatter"` |
| `.sql(query)` | Direct SQL |
| `.tables()` | List tables |
| `.schema()` | Show structure |
| `.peek(table, n)` | Preview rows |
| `.save_to_mysql(host, user, pw, db)` | Export to MySQL |
| `.export_db(path, format)` | Export SQLite or JSON |
| `.close()` | Close connection |

**QueryResult:**
`result.success` · `result.sql` · `result.data` · `result.viz` · `result.error`

## License

MIT — Aditya Batta