sqlthought 0.0.3

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 complete natural-language query (NLQ) → 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 (LangGraph)

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

Ultra-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).

📦 Installation

pip install sqlthought

🔧 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.

---

📂 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

---

🔨 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.

---

🧠 Natural Language → SQL

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