Metadata-Version: 2.4
Name: QuerySUTRA
Version: 0.1.3
Summary: SUTRA: Structured-Unstructured-Text-Retrieval-Architecture | Natural Language to SQL with MySQL/PostgreSQL export
Home-page: https://github.com/adityabatta/QuerySUTRA
Author: Aditya Batta
Author-email: Aditya Batta <b05aditya@gmail.com>
Project-URL: Homepage, https://github.com/adityabatta/QuerySUTRA
Project-URL: Repository, https://github.com/adityabatta/QuerySUTRA
Project-URL: Bug Reports, https://github.com/adityabatta/QuerySUTRA/issues
Keywords: natural-language,sql,database,query,nlp,ai,openai,mysql,postgresql,pdf,docx,text-retrieval
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Database
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: openai>=1.12.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: plotly>=5.0.0
Requires-Dist: matplotlib>=3.7.0
Requires-Dist: PyPDF2>=3.0.0
Requires-Dist: python-docx>=1.0.0
Requires-Dist: openpyxl>=3.1.0
Requires-Dist: sqlalchemy>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Provides-Extra: mysql
Requires-Dist: mysql-connector-python>=8.0.0; extra == "mysql"
Provides-Extra: postgres
Requires-Dist: psycopg2-binary>=2.9.0; extra == "postgres"
Provides-Extra: all
Requires-Dist: mysql-connector-python>=8.0.0; extra == "all"
Requires-Dist: psycopg2-binary>=2.9.0; extra == "all"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# 🚀 SUTRA - Simple Unified Tool for Relational Analysis

**Natural Language to SQL Query System with Auto-Visualization**

A single-file Python library that converts your questions into SQL queries and visualizes the results automatically.

---

## ✨ What You Get

✅ **One file** - Everything in `sutra.py`  
✅ **Natural language** - Ask questions in plain English  
✅ **Multiple formats** - CSV, Excel, JSON, SQL, DataFrames  
✅ **Direct SQL** - No API cost option  
✅ **Auto visualization** - Charts with one parameter  
✅ **Interactive mode** - Ask user for viz choice  
✅ **Jupyter ready** - Perfect for notebooks  

---

## 📦 Installation

```bash
pip install sutra
```

---

## 🎯 Complete Workflow (9 Steps)

### Step 1: Install
```bash
pip install sutra
```

### Step 2: Import
```python
from sutra import SUTRA
```

### Step 3: Enter API Key
```python
sutra = SUTRA(api_key="your-openai-api-key")
```

### Step 4: Upload Data (Any Format!)
```python
# CSV
sutra.upload("data.csv")

# Excel
sutra.upload("data.xlsx")

# DataFrame
import pandas as pd
df = pd.DataFrame({'sales': [100, 200], 'region': ['North', 'South']})
sutra.upload(df, name="sales_data")

# JSON
sutra.upload("data.json")
```

### Step 5: Database Auto-Created
Database is automatically created and managed!

### Step 6: Direct SQL (No API Cost!)
```python
result = sutra.sql("SELECT * FROM sales_data WHERE sales > 150")
print(result.data)
```

### Step 7: Natural Language Queries
```python
result = sutra.ask("What are total sales by region?")
print(result.data)
```

### Step 8: With Visualization
```python
# Set viz=True for automatic charts
result = sutra.ask("Show sales by region", viz=True)

# Or ask user interactively
result = sutra.interactive("Show sales by region")
# Prompts: "Do you want visualization? (yes/no):"
```

### Step 9: Works in Jupyter Notebooks!
See `SUTRA_Complete_Guide.ipynb` for step-by-step examples.

---

## 📖 Quick Examples

### Basic Usage
```python
from sutra import SUTRA

# Initialize
sutra = SUTRA(api_key="sk-...")

# Upload data
sutra.upload("sales.csv")

# Ask questions
result = sutra.ask("What are total sales?")
print(result.data)
```

### With Visualization
```python
result = sutra.ask("Show top 10 products by revenue", viz=True)
# Chart appears automatically!
print(result.data)
```

### Interactive Mode
```python
result = sutra.interactive("What are sales trends?")
# Asks: "Do you want visualization? (yes/no):"
```

### Direct SQL (No API Cost)
```python
result = sutra.sql("SELECT region, SUM(sales) FROM data GROUP BY region")
print(result.data)
```

### Export Results
```python
result = sutra.ask("Show all data")
sutra.export(result.data, "output.csv")
sutra.export(result.data, "output.xlsx", format="excel")
```

---

## 📊 Jupyter Notebook Guide

Open `SUTRA_Complete_Guide.ipynb` for a complete step-by-step tutorial with:
- All 9 steps explained
- Multiple examples
- Interactive queries
- Visualization options
- Export examples

---

## 🛠️ API Reference

### Main Methods

```python
# Initialize
sutra = SUTRA(api_key="...", db="mydb.db")

# Upload data
sutra.upload(data, name="table_name")  # data = file path or DataFrame

# View database
sutra.tables()           # List all tables
sutra.schema()           # Show schema
sutra.peek(n=10)        # Preview data

# Query with SQL
result = sutra.sql("SELECT ...", viz=False)

# Query with natural language
result = sutra.ask("question", viz=False, table="table_name")

# Interactive query
result = sutra.interactive("question")  # Prompts for viz choice

# Export
sutra.export(data, "file.csv", format="csv")  # or "excel", "json"

# Close
sutra.close()
```

### QueryResult Object

```python
result.success  # bool
result.sql      # Generated SQL query
result.data     # pandas DataFrame
result.viz      # Visualization object
result.error    # Error message (if failed)
```

---

## 🎨 Features

| Feature | Description |
|---------|-------------|
| **Single File** | Everything in one `sutra.py` |
| **Multi-Format** | CSV, Excel, JSON, SQL, DataFrame |
| **No API Mode** | Use `.sql()` for free queries |
| **NLP Mode** | Use `.ask()` with OpenAI |
| **Auto Viz** | Set `viz=True` for charts |
| **Interactive** | `.interactive()` asks user |
| **Caching** | Saves API costs |
| **Export** | CSV, Excel, JSON |
| **Jupyter** | Perfect for notebooks |

---

## 💰 Cost Saving

Use direct SQL to save API costs:

```python
# FREE - No API call
result = sutra.sql("SELECT * FROM data WHERE amount > 1000")

# USES API - Costs ~$0.001 per query
result = sutra.ask("Show data where amount is greater than 1000")
```

---

## 📝 Publishing to PyPI

See `PUBLISHING_GUIDE.md` for complete instructions.

Quick version:
```bash
# Install tools
pip install build twine

# Build
python -m build

# Upload
python -m twine upload dist/*
```

---

## 🧪 Testing

Run the test script:
```bash
python test_package.py
```

---

## 📚 Files Included

- `sutra/sutra.py` - Main single-file library
- `sutra/__init__.py` - Package initialization
- `SUTRA_Complete_Guide.ipynb` - Jupyter notebook tutorial
- `setup.py` - Package configuration
- `pyproject.toml` - Modern Python packaging
- `README.md` - This file
- `PUBLISHING_GUIDE.md` - How to publish
- `LICENSE` - MIT License

---

## 🤝 Contributing

Contributions welcome! This is a single-file library, so it's easy to modify and extend.

---

## 📄 License

MIT License - feel free to use in your projects!

---

## 🎓 Examples

### Example 1: Quick Analysis
```python
from sutra import SUTRA

sutra = SUTRA(api_key="sk-...")
sutra.upload("sales.csv")
result = sutra.ask("What region has highest sales?", viz=True)
print(result.data)
```

### Example 2: Multiple Queries
```python
questions = [
    "What are total sales?",
    "Show top 5 products",
    "Which region performs best?"
]

for q in questions:
    result = sutra.interactive(q)  # Asks for viz each time
    if result.success:
        print(result.data)
```

### Example 3: Context Manager
```python
with SUTRA(api_key="sk-...") as sutra:
    sutra.upload(df)
    result = sutra.ask("Show all", viz=True)
# Automatically closes
```

---

## ❓ FAQ

**Q: Do I need an API key?**  
A: Only for natural language queries (`.ask()`). Direct SQL (`.sql()`) works without API key.

**Q: What formats are supported?**  
A: CSV, Excel (.xlsx, .xls), JSON, SQL files, and pandas DataFrames.

**Q: How do I visualize?**  
A: Set `viz=True` in `.ask()` or `.sql()` methods, or use `.interactive()` to prompt user.

**Q: Can I use without Jupyter?**  
A: Yes! Works in any Python environment - scripts, notebooks, REPL.

**Q: Is it a single file?**  
A: Yes! The core is in `sutra/sutra.py` - one file with everything.

---

## 🚀 Get Started Now!

```bash
pip install sutra
```

```python
from sutra import SUTRA

sutra = SUTRA(api_key="your-key")
sutra.upload("data.csv")
result = sutra.ask("Show me insights", viz=True)
```

**That's it! You're analyzing data with natural language!** 🎉

---

**Made with ❤️ by Aditya Batta**
