README

Features

• 🤖 Multi-provider — OpenAI (GPT-4o, GPT-4, GPT-3.5-turbo), xAI Grok (grok-3) and Custom Provider via the same openai-php/client package
• 📝 Conversation context — every exchange is saved so the AI understands follow-up questions
• 🗄️ Auto schema extraction — introspect MySQL, PostgreSQL, or SQLite via PDO, or supply a PHP array / raw DDL
• 🧱 Fluent builder API — compose your generator in one readable chain
• 📦 PSR-4 autoloaded, PHP 8.1+

Installation

composer require btx/sql-ai-query

Quick Start

use Btx\SqlAiQuery\SqlAiQuery;

$result = SqlAiQuery::make()
    ->useOpenAI(apiKey: 'sk-...')          // or ->useGrok('xai-...')
    ->withSchemaFromPdo($pdo)              // auto-introspect live DB
    ->generate('Show me the 10 most recent orders with the customer name');

echo $result->getSql();
// SELECT o.id, c.name AS customer_name, o.total_amount, o.created_at
// FROM orders o
// JOIN customers c ON c.id = o.customer_id
// ORDER BY o.created_at DESC
// LIMIT 10;

Configuration

Choosing a Provider

// ChatGPT (default model: gpt-4o)
->useOpenAI(apiKey: 'sk-...', model: 'gpt-4o', temperature: 0.2, maxTokens: 2048)

// Grok (default model: grok-3)
->useGrok(apiKey: 'xai-...', model: 'grok-3', temperature: 0.2, maxTokens: 2048)

// Another AI Provider
->useCustomAi(apiKey: '...', model: 'gpt-4o', temperature: 0.2, maxTokens: 2048)

// Custom provider (implement AIProviderInterface)
->useProvider(new MyCustomProvider(...))

Providing the Schema

// Option A — Auto-introspect from a live PDO connection
->withSchemaFromPdo($pdo)
->withSchemaFromPdo($pdo, 'my_database')  // specify database name

// Option B — PHP array
->withSchemaFromArray([
    'users' => [
        'id'    => ['type' => 'BIGINT', 'nullable' => false, 'key' => 'PRI'],
        'email' => ['type' => 'VARCHAR(255)', 'nullable' => false],
    ],
])

// Option C — Raw DDL string
->withSchemaFromDdl('CREATE TABLE users (id INT PRIMARY KEY, ...)')

// Option D — Pre-formatted description string
->withSchema('TABLE users: id (BIGINT PRI), email (VARCHAR 255) ...')

Multi-turn Conversations

Every generate() call returns a QueryResult that carries a contextId.
Pass it back to continue the same conversation:

$generator = SqlAiQuery::make()
    ->useOpenAI('sk-...')
    ->withSchemaFromPdo($pdo)
    ->withStoragePath('/var/app/contexts')  // where to persist contexts
    ->build();

// First turn
$r1 = $generator->generate('Get all customers registered in the last 30 days');
$contextId = $r1->getContextId();

// Follow-up — AI remembers the previous query
$r2 = $generator->followUp('Now add the total number of orders for each', $contextId);

// Refine further
$r3 = $generator->followUp('Only keep those with more than 3 orders', $contextId);

Contexts are persisted as JSON files so they survive between requests / CLI runs.

API Reference

SqlAiQuery (Builder)

QueryGenerator

QueryResult

ConversationContext

ContextStore

Supported PDO Drivers

Project Structure

src/
├── Contracts/
│   └── AIProviderInterface.php   # Provider contract
├── Context/
│   ├── ConversationContext.php   # Manages message history
│   └── ContextStore.php          # File-based persistence
├── Exceptions/
│   ├── SqlAiQueryException.php
│   └── ProviderException.php
├── Providers/
│   ├── OpenAIProvider.php        # ChatGPT adapter
│   └── GrokProvider.php          # Grok adapter (OpenAI-compatible)
├── Schema/
│   └── SchemaExtractor.php       # PDO / array / DDL → formatted schema
├── QueryGenerator.php            # Core engine
├── QueryResult.php               # Response wrapper + SQL extractor
└── SqlAiQuery.php                # Fluent builder (main entry-point)

License

MIT