Molecule Agent

An AI-powered CLI tool that allows you to query PostgreSQL, Oracle, and MySQL databases using natural language.

🚀 Features

• 🗣️ Natural Language Queries - Ask questions in plain English
• 🔧 Multi-Database Support - PostgreSQL, Oracle, MySQL
• 🤖 Multiple AI Providers - OpenAI, Groq (free), HuggingFace, Local LLMs
• 📊 Data Visualization - ASCII charts and tables
• 🛡️ Built-in Safety - Prevents destructive operations
• ⚡ Fast & Efficient - Schema caching and optimizations
• 🎨 Customizable Display - Multiple table styles and formats

📦 Installation

npm install -g molecule-agent

🚀 Quick Start

1. Configure Your AI Provider

Option A: Free AI with Groq (Recommended)

# Get a free API key at https://console.groq.com
export GROQ_API_KEY=your_groq_key_here
export USE_GROQ=true

Option B: OpenAI

export OPENAI_API_KEY=your_openai_key_here

2. Configure Your Database

# PostgreSQL (default)
export DB_TYPE=postgresql
export DB_HOST=localhost
export DB_PORT=5432
export DB_NAME=your_database
export DB_USER=your_username
export DB_PASSWORD=your_password

# Or create a .env file with these settings

3. Start Querying

# Interactive mode
molecule query

# Or with options
molecule query --show-sql --table-style compact

🔧 Configuration

Environment Variables

Create a .env file in your project directory:

# AI Provider (choose one)
AI_PROVIDER=groq                              # Use free Groq
USE_GROQ=true
GROQ_API_KEY=your_groq_key_here
GROQ_MODEL=llama3-8b-8192

# OR use OpenAI
# OPENAI_API_KEY=your_openai_key_here
# AI_MODEL=gpt-4o

# Database Configuration
DB_TYPE=postgresql                            # postgresql, oracle, mysql
DB_HOST=localhost
DB_PORT=5432
DB_NAME=your_database
DB_USER=your_username
DB_PASSWORD=your_password

# Display Options
SHOW_SQL=true
TABLE_STYLE=default                          # default, compact, simple, markdown
MAX_ROWS=50

# Authentication (optional - disable for local use)
ENABLE_AUTH=false

Interactive Configuration

molecule config

This will guide you through setting up your database and AI provider.

🤖 AI Providers

Groq (Free & Fast) ⭐ Recommended

1. Get a free API key at console.groq.com
2. Set environment variable: GROQ_API_KEY=your_key_here
3. Set USE_GROQ=true

Available Models:

• llama3-8b-8192 (default, fast)
• llama3-70b-8192 (most capable)
• gemma-7b-it (very fast)

OpenAI

1. Get API key from OpenAI
2. Set OPENAI_API_KEY=your_key_here

HuggingFace (Free with Token)

1. Get token from HuggingFace
2. Set USE_HUGGINGFACE=true and HUGGINGFACE_API_KEY=your_token

Local LLM (Ollama)

1. Install Ollama
2. Run ollama pull llama3
3. Set USE_LOCAL_LLM=true

💾 Database Support

PostgreSQL

DB_TYPE=postgresql
DB_PORT=5432

Oracle

DB_TYPE=oracle
DB_PORT=1521
# Requires Oracle Instant Client

MySQL/MariaDB

DB_TYPE=mysql
DB_PORT=3306

💬 Example Queries

> How many users are in the system?
> Show me the top 5 products by price
> What's the average order value this month?
> List departments with more than 10 employees
> Find customers who haven't ordered in 90 days

🎨 Visualization

After running queries, create visualizations:

> visualize              # Auto-detect best chart type
> visualize line         # Line chart
> visualize bar          # Bar chart
> visualize table        # Formatted table

🛠️ Commands

Query Commands

• molecule query - Start interactive mode
• molecule query --show-sql - Show generated SQL
• molecule query --api-key KEY - Use specific API key

Configuration

• molecule config - Interactive configuration
• molecule config --list - Show current settings
• molecule config --set key=value - Set configuration
• molecule config --reset - Reset to defaults

Special Commands (in interactive mode)

• help - Show available commands
• exit - Exit the application
• schema - Display database schema
• history - Show command history
• clear - Clear screen

🛡️ Safety Features

• AI Safety: Trained to avoid destructive operations
• Query Validation: Blocks dangerous SQL patterns
• Read-First: Shows what would be affected instead of deleting
• Timeouts: Prevents long-running queries
• Error Handling: Clear error messages and suggestions

🔒 Authentication (Optional)

Authentication is disabled by default for local use. Enable it for team/enterprise use:

ENABLE_AUTH=true
AUTH_API_URL=your_auth_server_url

🐛 Troubleshooting

Database Connection Issues

• Verify database is running and accessible
• Check connection details (host, port, credentials)
• Ensure user has necessary permissions

AI Provider Issues

• Groq: Verify API key at console.groq.com
• OpenAI: Check API key and quota
• Local LLM: Ensure Ollama is running (ollama serve)

Common Solutions

# Test database connection
molecule config --get database

# Reset configuration
molecule config --reset

# Enable debug mode
DEBUG=* molecule query

📚 Examples

Basic Usage

# Set up Groq (free)
export GROQ_API_KEY=gsk_your_key_here
export USE_GROQ=true

# Configure database
export DB_HOST=localhost
export DB_NAME=myapp
export DB_USER=postgres
export DB_PASSWORD=password

# Start querying
molecule query

Advanced Configuration

# Use specific model and settings
export GROQ_MODEL=llama3-70b-8192
export SHOW_SQL=true
export TABLE_STYLE=compact
export MAX_ROWS=100

molecule query --table-style markdown

🤝 Contributing

We welcome contributions! Please see our contributing guidelines for more details.

📄 License

ISC

🔗 Links

• Groq Console - Get free API key
• OpenAI Platform - OpenAI API keys
• Ollama - Local LLM runner
• Issue Tracker - Report bugs

Made with ❤️ for developers who want to query databases with natural language.