sqlthought 0.0.4

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

SQLThought

SQLThought is a modular, extensible multi-agent reasoning framework built for intelligent interaction with structured data, databases, and future analytical workflows.
It currently includes a build database and natural-language query (NLQ) to SQL reasoning pipeline powered by Groq, but the architecture is intentionally designed to support many more reasoning tasks as the project evolves.

SQLThought is not just a utility, it's a foundation for agentic, step-wise, auditable reasoning over structured information.

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