teshq 1.3.2

A CLI tool that converts natural language queries into SQL and returns relevant tables using natural language.

🤖 TESH-Query

Transform natural language into SQL queries and get instant results — No SQL knowledge required.

TESH-Query (Text to Executable SQL Handler) is an AI-powered CLI tool that bridges the gap between human language and database queries, making data accessible to everyone on your team.

Here is detailed documentation of configuration and usage information, see the Detailed Documentation.

---

✨ See TESH-Query in Action!

Experience the power and simplicity of TESH-Query with a quick demonstration. See how easily you can get valuable data insights using just natural language.

---

🎯 What TESH-Query Does

Forget writing complex SQL queries. With TESH-Query, you simply ask for the data you need in plain English, and the tool handles the rest.

# Before: Crafting intricate SQL...
$ psql my_database -c "SELECT products.name, categories.category_name, orders.order_date FROM products JOIN order_items ON products.id = order_items.product_id JOIN orders ON order_items.order_id = orders.id JOIN categories ON products.category_id = categories.id WHERE categories.category_name = 'electronics' AND orders.order_date >= current_date - interval '1 month' ORDER BY orders.order_date DESC;"

# After: Just ask TESH-Query!
$ teshq query "Show me all high-value electronics orders from last month"

# Get instant, formatted results directly in your terminal:
┌────────────┬─────────────────┬───────────┬─────────────┐
│ Order ID   │ Product Name    │ Price     │ Order Date  │
├────────────┼─────────────────┼───────────┼─────────────┤
│ 12847      │ MacBook Pro M3  │ $2,499.00 │ 2025-04-15  │
│ 12923      │ OLED Monitor    │ $899.99   │ 2025-04-18  │
└────────────┴─────────────────┴───────────┴─────────────┘

---

💡 Why Choose TESH-Query?

Accessing data shouldn't be a bottleneck. TESH-Query empowers your team by making database interaction intuitive and fast.

Key Benefits:

• 🚀 Democratize Data Access — Enable everyone, regardless of technical background, to retrieve data independently.
• ⚡ Boost Productivity — Significantly reduce the time and effort required to get data insights.
• 🛡️ Reduce Errors — Minimize human errors associated with manual SQL writing.
• 🔍 Focus on Analysis — Spend more time understanding your data and less time wrestling with query syntax.

---

✨ Key Features

• 💬 Intuitive Natural Language Interface — Seamlessly interact with your database using everyday language.
• 🧠 Intelligent SQL Generation — Leverage the power of Google's Gemini AI (via Langchain) for accurate and context-aware SQL translation.
• 📊 Direct Data Display — Get query results presented in clean, readable tables right in your terminal.
• 🔌 Broad Database Compatibility — Connects natively with PostgreSQL, MySQL, and SQLite databases.
• 🛡️ Schema-Aware Queries — TESH-Query understands your database structure to generate highly relevant queries.
• 🎨 Modern CLI Experience — Enjoy a responsive, user-friendly, and visually appealing interface thanks to Typer and Rich.
• 🔒 Secure Credential Management — Your sensitive database and API credentials are stored securely.
• ⚙️ Customizable Configuration — Easily set up and manage your database connections, AI models, and other settings.

---

▶️ Getting Started: A Quick Walkthrough

Ready to unlock your data? Follow these simple steps:

1. Installation

Install TESH-Query easily using pip:

pip install teshq

Confirm successful installation:

teshq --version

2. Configuration (One-Time Setup)

Run the interactive configuration wizards to set up your database connection and Gemini API key:

# Configure database connection details
teshq config --config-db
# you can also use `teshq config --db-url postgresql://myuser:********@localhost:5432/mydatabase`

# Configure your Google Gemini API key
teshq config --config-gemini

These commands will guide you through the necessary steps and securely store your credentials.

3. Database schema Introspection

# Perform database schema introspection
teshq introspect

4. Start Querying!

Once configured, you can immediately start asking questions in natural language:

teshq query "What are the names and email addresses of users who signed up last week?"
teshq query "Show me the total sales amount for each product category in the last quarter."
teshq query "Find orders placed by '[e-mail]'."

TESH-Query takes your question, understands your database schema, generates the appropriate SQL, executes it, and displays the results in a formatted table.

Please be aware that TESH-Query is still under development and may occasionally return incorrect data. Exercise caution and prioritize its use for data retrieval rather than data manipulation.

---

📚 Command Reference

Here's a quick guide to the main TESH-Query commands:

General

# Get overall help menu
teshq --help

# Display installed version
teshq --version

Configuration

# Display current configuration settings
teshq config

# Get help specific to configuration commands
teshq config --help

# Interactively configure database connection
teshq config --config-db

# Interactively configure Google Gemini API key
teshq config --config-gemini

Database

# Perform database schema introspection
teshq introspect

Querying

# Get help specific to query commands
teshq query --help

# Execute a natural language query against the database
teshq query "your question here"

---

💡 Example Queries

See TESH-Query in action with these practical examples across different use cases:

Business Intelligence

teshq query "What's our monthly revenue trend for the last 6 months?"
teshq query "Which sales rep has the highest conversion rate?"
teshq query "Show me customer churn rate by region"

Operations

teshq query "Find orders that haven't shipped in 3+ days"
teshq query "Which products are running low on inventory?"
teshq query "Show me all failed payment transactions today"

Analytics

teshq query "Average order value by customer segment"
teshq query "Most popular products in each category"
teshq query "Customer lifetime value for premium subscribers"

---

🏗️ How It Works: Under the Hood

TESH-Query simplifies data access through a robust process:

1. Natural Language Input: Your query is received via the CLI.
2. Configuration: Secure database and AI credentials are loaded.
3. Database Connection: A connection is made to your database using SQLAlchemy.
4. Schema Introspection: TESH-Query inspects your database schema to understand tables, columns, and relationships.
5. AI Generation: Your query and schema context are sent to Google Gemini (via Langchain) to generate optimized SQL.
6. SQL Execution: The generated SQL is executed against your database.
7. Result Formatting: Data is formatted into a clear, tabular output for the terminal.

Architecture Overview:

The project is structured into key modules:

• cli/: Handles command-line interface logic and user interaction (Typer).
• core/: Contains core business logic, including AI interaction, SQL execution, and schema handling.
• utils/: Provides shared utility functions (configuration, database helpers, formatting).

---

🔧 Tech Stack

TESH-Query is built using the following technologies:

Component	Technology
Core Language	Python 3.9+
CLI Framework	Typer, Rich
Database ORM/Kit	SQLAlchemy
Database Drivers	psycopg2-binary (PostgreSQL), mysql-connector-python (MySQL), sqlite3 (Built-in)
AI/LLM Integration	Langchain, langchain-google-genai (Google Gemini)
Configuration	python-dotenv, JSON
Data Display	Tabulate
Build & Packaging	Setuptools, setuptools-scm, Build, Twine
Code Quality	Black, isort, Flake8 (enforced via pre-commit)

---

📈 Project Status & Roadmap

TESH-Query is under active development with planned future enhancements.

✅ Implemented Features (v1.x)

• Robust CLI with Typer.
• Secure, interactive configuration.
• Database connection management (PostgreSQL, MySQL, SQLite).
• Core NLQ -> SQL -> Table pipeline with Gemini AI.
• Dynamic database schema introspection.
• Formatted tabular output.
• Git-based versioning (setuptools-scm).
• Automated PyPI publishing (GitHub Actions).
• Pre-commit hooks for code quality.

🚧 In Development (v2.x - Near-Term)

• Enhanced Error Handling.
• Query History & Bookmarks.
• Schema Caching for performance.
• More Complex Query Handling.
• Comprehensive Testing Expansion.

🔮 Future Vision (v3.x+ - Long-Term)

• Interactive Query Refinement.
• Support for More Databases.
• Basic Data Visualization.
• User-Defined AI Prompts.
• Plugin Architecture.

---

🤝 Contributing

We welcome contributions! If you'd like to help improve TESH-Query, please follow these steps:

Getting Started

1. Fork & Clone: Fork the repository and clone it locally.

   git clone https://github.com/YOUR_USERNAME/TESH-Query.git
   cd TESH-Query
   

2. Virtual Environment: Create and activate a Python virtual environment.

   python3 -m venv .venv
   source .venv/bin/activate  # Windows: .venv\Scripts\activate
   

3. Install Dependencies: Install in editable mode with development dependencies.

   pip install -e ".[dev]"
   

4. Pre-commit Hooks: Set up automated code quality checks.

   pre-commit install
   

Contribution Workflow

1. Create a new branch (git checkout -b feature/your-feature).
2. Implement changes and add/update tests.
3. Run pytest and pre-commit run --all-files.
4. Commit and push your branch.
5. Open a Pull Request to main.

Versioning

Versioning is automated via Git tags (vX.Y.Z) and setuptools-scm.

---

🔧 Troubleshooting & Support

Encountering issues? Here's some help:

Common Issues

• Connection Problems: Use teshq config --config-db. Check credentials, host, port, network.
  • Otherway to solve is teshq config --db-url <dialect>://<username>:<password>@<host>:<port>/<database>
  • Example teshq config --db-url postgresql://myuser:123456789@localhost:5432/mydatabase
• AI Generation Issues: Rephrase query, be specific, simplify requests.
• Permission Errors: Ensure database user has read access.

Getting Help

• Documentation: teshq --help and command-specific help.
• Bug Reports: Open a GitHub Issue.
• Feature Requests: Start a GitHub Discussion.
• Direct Contact: Reach out to the author (@theshashank1).

---

📄 License

This project is licensed under the MIT License. See the LICENSE file.

---

🌟 Show Your Support

Like TESH-Query? Please consider:

⭐ Starring the repo on GitHub 🐦 Sharing on social media 🗣️ Telling your colleagues 🤝 Contributing to the project

Your support is greatly appreciated!

---

Made with ❤️ by Shashank

Passionate about democratizing data access and building intelligent developer tools.