QuerySUTRA 0.1.3

SUTRA: Structured-Unstructured-Text-Retrieval-Architecture | Natural Language to SQL with MySQL/PostgreSQL export

🚀 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

pip install sutra

---

🎯 Complete Workflow (9 Steps)

Step 1: Install

pip install sutra

Step 2: Import

from sutra import SUTRA

Step 3: Enter API Key

sutra = SUTRA(api_key="your-openai-api-key")

Step 4: Upload Data (Any Format!)

# 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!)

result = sutra.sql("SELECT * FROM sales_data WHERE sales > 150")
print(result.data)

Step 7: Natural Language Queries

result = sutra.ask("What are total sales by region?")
print(result.data)

Step 8: With Visualization

# 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

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

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

Interactive Mode

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

Direct SQL (No API Cost)

result = sutra.sql("SELECT region, SUM(sales) FROM data GROUP BY region")
print(result.data)

Export Results

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

# 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

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:

# 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:

# Install tools
pip install build twine

# Build
python -m build

# Upload
python -m twine upload dist/*

---

🧪 Testing

Run the test script:

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

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

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

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!

pip install sutra

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