sqlthought 0.0.5

A modular agentic reasoning engine for structured data, including NLQ-to-SQL transformations.

SQLThought

SQLThought exists to simplify how people work with structured data. Many users know the questions they want to ask, but writing correct SQL or debugging failures is slow and technical. Traditional NLQ systems jump directly from text to SQL, which often leads to invalid queries and no clear reasoning.

SQLThought takes a different approach. It breaks the problem into steps, understands the schema, plans the query, generates SQL, executes it, and fixes errors automatically. It also provides an easy way to build a SQLite database from CSV files so users can start querying without external tools.

The current version includes a complete Groq powered NLQ to SQL pipeline, correction loop, local configuration, and workspace tools. The framework is designed to grow into a broader reasoning engine for structured data and analytical workflows.

Key Features

Multi-Agent Reasoning

SQLThought uses LangGraph to orchestrate intelligent pipelines with:

• Stepwise decomposition
• State-aware execution
• Deterministic branches
• Automatic SQL correction loops
• Fully transparent, debuggable agent workflows

Groq-Powered LLM Execution

Fast agentic reasoning using Groq’s API, providing:

• Low-latency inference
• Predictable outputs
• Easy model switching
• Secure local configuration

Modular, Extensible Architecture

Every reasoning stage is isolated and replaceable.

Zero-Friction CLI

SQLThought includes a full command-line interface:

• sqlthought configure — Configure Groq API + model
• sqlthought query — Query your database using natural language
• sqlthought version — Show installed version
• sqlthought build-db — Build a SQLite database from CSV files

Secure Local Config Storage

~/.sqlthought/config.json

Stores API keys and model preferences locally (never uploaded or logged).

Project Structure

sqlthought/
├── nlq/
│   ├── conversion.py       # Public NLQ→SQL API
│   ├── build_graph.py      # LangGraph pipeline
│   ├── nodes.py            # Multi-agent reasoning nodes
│   ├── state.py            # Typed pipeline state
│   └── prompts/            # Prompt templates
├── ingestion/
│   └── build_db.py         # CSV → SQLite builder
├── utils/
│   ├── db_utils.py
│   ├── logger.py
│   └── visualizer.py
└── cli.py                  # Command-line entrypoint

Installation

pip install sqlthought

Usage

First-Time Setup

sqlthought configure

You will be prompted for:

• Groq API key
• Model name (e.g., openai/gpt-oss-20b or another Groq-hosted model)

Configuration only needs to be done once.

Building Databases from CSV Files

• SQLThought ships with a helper for assembling SQLite databases from CSVs.

sqlthought init

• Upload CSV files into:

sqlthought_data/csv/

• Then build the database:

sqlthought build-db sample.db

• Your DB will be created at:

sqlthought_data/sample.db

And is now ready for NLQ reasoning.

NLQ to SQL conversion

The first reasoning module shipped with SQLThought is a full NLQ → SQL agentic system with:

• Schema understanding
• Subtask decomposition
• Query planning
• SQL generation
• SQL execution
• Automatic correction loops

CLI Example

sqlthought query "List employees earning above 70000" sample.db

Contributing

Contributions, feature ideas, and pull requests are welcome! More documentation and developer guides will be added soon.

License

MIT License © 2025 Tiyasa Mukherjee