Metadata-Version: 2.4
Name: sqlthought
Version: 0.0.5
Summary: A modular agentic reasoning engine for structured data, including NLQ-to-SQL transformations.
Author-email: Tiyasa Mukherjee <mukherjeetiyasa1998@gmail.com>
License-Expression: MIT
Keywords: nlq,sql,langgraph,groq,agentic-ai
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: langgraph>=0.3.3
Requires-Dist: sqlparse
Requires-Dist: pydantic>=2.0
Requires-Dist: psutil
Requires-Dist: Pillow
Requires-Dist: deepeval
Requires-Dist: groq>=0.5.0
Dynamic: license-file

# 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
```bash
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
