@negusdev/dbask 0.0.0-stage → 0.1.8

package/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows [Keep a Changelog](https://keepachangelog.com), and the project uses [Semantic Versioning](https://semver.org) (0.x: minor versions may change behavior).
+
+## [Unreleased]
+
+### Changed
+- **Renamed from `sql-ai-harness` to `dbask`.** The npm package is now `@negusdev/dbask` (the unscoped name `dbask` was blocked by npm's name-similarity check) and the command is `dbask`. The `sql-ai-harness` command stays as an alias for now. You can now ask without the subcommand: `dbask "who owes us money?"` (`dbask ask "…"` still works). Mistyped options and one-word mistyped commands now print an error instead of being sent to the model, and `dbask --version` and `--help` were added. Environment variables, the `sql-ai.md` context file and the SDK API are unchanged; update imports from `"sql-ai-harness"` to `"dbask"`. The structured debug events now use `source: "dbask"`.
+
+## [0.1.8] - 2026-11-13
+
+### Added
+- **DeepSeek provider.** Set `AI_PROVIDER=deepseek` and `DEEPSEEK_API_KEY`.
+- **Optional query plan** (`AGENT_QUERY_PLAN=on`, or `requirePlan: true` in the SDK). The agent submits a structured plan (tables, columns, joins, filters) that is checked against your real schema before any SQL runs; the SQL may then read only the planned tables. Unknown tables or columns and unconnected tables are rejected, joins that are not declared foreign keys produce warnings, and plan submissions are capped at 4. `AgentResult.plan` reports submitted, accepted, rejected and SQL-mismatch counts. New exports: `StructuredQueryPlan`, `PlanStats`.
+- **Terminal UI.** Progress spinner with the current step, Markdown answers rendered for the terminal (aligned tables that wrap instead of cutting ids, bold, code, lists), highlighted SQL, and a clearer `--mode debug` trace that shows the plan, plan warnings and plan counts. `validate` uses symbols and color. Piped or redirected output is unchanged; `NO_COLOR` and `FORCE_COLOR` are honored.
+- `CONTRIBUTING.md`.
+
+### Changed
+- **The query plan is off by default.** On the 40-case benchmark it added about 0.7 tool calls and roughly 30% median latency per question without improving accuracy. Turn it on with `AGENT_QUERY_PLAN=on` if you want the agent's assumptions visible. (SDK: `new Agent(..., { requirePlan: true })`; the SDK default is also off.)
+- **The agent stays on topic.** It now declines questions that are not about the connected database (arithmetic, general knowledge, writing, instruction overrides) without calling tools or querying, and treats text found in table names, column names or row values as data, not instructions.
+- **The agent always ends with an answer.** The last step is reserved for the final answer, and a run that cannot finish returns `AgentResult.incomplete`; the CLI prints it as an error and exits with code 1. Write requests are refused up front.
+- Updated the Vercel AI SDK packages.
+
+### Development
+- Evaluation: 40-case dataset (adds four off-topic cases), value-based result comparison, tolerant answer checks, refusal scoring, provider-error retries excluded from scores, `--repeat N` with a cross-run summary, `--only`, process-group timeout kill, and run settings (model, commit, max steps, plan flag) in report headers.
+- Benchmark result for this release: 39 of 40 cases passed in every one of three runs (`gemini-3.5-flash-lite`, synthetic database). The one consistent failure is a known reference-answer error, not an agent error. See the README for caveats.
+
+### Upgrade notes
+- No action needed for the CLI. If you script `submit_query_plan` directly, the plan shape changed: `fields` is a list of `{table, column}` and `joins` a list of `{left, right}`.
+
+## [0.1.7] - 2026-11-05
+
+### Added
+- PostgreSQL support (tables, partitioned tables and schemas; views are not listed yet).
+- `validate` command to check configuration, database connection, foreign keys, AI provider and `sql-ai.md`.
+
+For earlier releases, see the [commit history](https://github.com/NegusDev/sql-ai-harness/commits/main) and the npm release list.
+
+[0.1.8]: https://github.com/NegusDev/sql-ai-harness/compare/v0.1.7...v0.1.8
+[0.1.7]: https://github.com/NegusDev/sql-ai-harness/releases/tag/v0.1.7

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026, NegusDev
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -1,3 +1,423 @@
-# Temporary Holding Version
+# dbask
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Open-source, privacy-first, self-hostable Text-to-SQL for your existing relational database.**
+
+Ask questions in plain language about a MySQL, MariaDB, or PostgreSQL database you already have. dbask discovers the schema, gives an AI agent tools to inspect and query it, enforces execution limits, and returns an answer. No new schema, no model trained for your app, no hosted service.
+
+Bring your own model. Run it yourself.
+
+> dbask was previously published as `sql-ai-harness`. Install it as `@negusdev/dbask`; the command is `dbask`. The old `sql-ai-harness` command still works as an alias, and the SDK API is unchanged apart from the package name.
+
+[![npm](https://img.shields.io/npm/v/@negusdev/dbask.svg)](https://www.npmjs.com/package/@negusdev/dbask)
+[![node](https://img.shields.io/node/v/@negusdev/dbask.svg)](https://nodejs.org)
+[![license](https://img.shields.io/npm/l/@negusdev/dbask.svg)](./LICENSE)
+
+> **Development status:** dbask is under active development (pre-1.0, so the API may change between minor versions). Validate it against your own schema and workload before relying on it, especially for consequential decisions.
+
+## Contents
+
+- [Why dbask](#why-dbask)
+- [Features](#features)
+- [Requirements](#requirements)
+- [Quickstart](#quickstart)
+- [Data handling](#data-handling)
+- [Usage](#usage)
+- [Configuration](#configuration)
+- [Optional database context](#optional-database-context)
+- [TypeScript SDK](#typescript-sdk)
+- [Database tools](#database-tools)
+- [Safety and data handling](#safety-and-data-handling)
+- [Database support](#database-support)
+- [Evaluation](#evaluation)
+- [Development](#development)
+- [Troubleshooting](#troubleshooting)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Why dbask
+
+Most Text-to-SQL tools are either a hosted service that sees your schema and data, or tightly coupled to one model and one vendor. dbask is a harness you run yourself, against a database you already own, with a model you choose.
+
+It is a reusable layer between an AI provider and an existing relational database. It is not a new application with its own schema.
+
+## Features
+
+- **Natural-language questions** through the CLI or the TypeScript SDK.
+- **Bring your own model:** OpenRouter, Google Gemini, DeepSeek, Groq, Cerebras, or Ollama.
+- **Schema-aware agent** with tools for listing tables, describing tables, discovering foreign keys, running queries, and `EXPLAIN`.
+- **Safety by default:** configurable row, byte, timeout, and agent-step limits; capped SQL attempts; foreign-key discovery required before any SQL runs.
+- **Optional `sql-ai.md`** for business rules and vocabulary the model cannot infer from the schema.
+- **Three response modes:** natural, technical, and debug.
+- **`validate` command** that checks your config, database, foreign keys, and AI provider before you ask anything.
+- **In-process schema cache** so repeated lookups in a run don't hit the database twice.
+- **Benchmark suite** in `evals/` for reproducible evaluation of changes.
+
+## Requirements
+
+- **Node.js 22 or later**
+- A **MySQL, MariaDB, or PostgreSQL** database, and an account with read access to the tables the agent should see
+- Credentials and a model ID for one supported AI provider (or a reachable Ollama endpoint)
+
+> SQLite, a hosted HTTP API, and SDKs for languages other than TypeScript are **not** part of this release. The SDK defines a `DatabaseAdapter` interface as the extension point; MySQL/MariaDB and PostgreSQL adapters ship today.
+
+## Quickstart
+
+### 1. Configure
+
+Run the setup wizard in the directory where you want the configuration stored:
+
+```bash
+npx @negusdev/dbask init
+```
+
+The wizard asks for:
+
+- Database type (MySQL/MariaDB or PostgreSQL), host, port, database, username, and password
+- AI provider and exact model ID
+- An API key (hosted providers) or a base URL (Ollama)
+- Agent step limit, SQL row limit, and schema-cache lifetime
+
+It tests the **database connection** and lists tables before saving. It does **not** send an inference request, so a successful `init` does not prove the provider key or model ID is correct. The next step checks that.
+
+If `.env` already exists, the wizard asks before updating harness settings and preserves unrelated entries. Skip the confirmation with `--force`:
+
+```bash
+npx @negusdev/dbask init --force
+```
+
+Keep `.env` private and out of version control. The wizard writes it with restrictive permissions where supported.
+
+### 2. Check your setup
+
+```bash
+npx @negusdev/dbask validate
+```
+
+`validate` checks your configuration, connects to the database, confirms the account can see tables and foreign keys, and sends **one tiny request** to your AI provider to confirm the key and model work. It never reads table data and never runs model-written SQL. Each line reports `[ok]`, `[warn]`, `[fail]` or `[skip]`, and the command exits with a non-zero status if anything fails, so it also works in scripts and CI.
+
+```text
+[ok]   Configuration: provider=openrouter, model=openai/gpt-4o-mini
+[ok]   Database connection: Connected to 127.0.0.1:3306/mydb; 27 tables visible.
+[ok]   Foreign keys: 42 declared relationships found.
+[ok]   AI provider: openrouter answered using model openai/gpt-4o-mini.
+[skip] Business context (sql-ai.md): No sql-ai.md found. This is optional.
+```
+
+Use `--skip-provider` to check only the configuration and database, without contacting the AI provider.
+
+### 3. Ask a question
+
+```bash
+npx @negusdev/dbask "How many students are enrolled?"
+```
+
+### 4. Install globally (optional)
+
+```bash
+npm install --global @negusdev/dbask
+dbask "List active users"
+```
+
+## Data handling
+
+dbask itself does not phone home. No telemetry, no crash reporting, no license check on startup, no cloud dependency. The harness runs on your machine (or your own server) and talks to your database directly.
+
+What does leave your machine is what your chosen AI provider receives. Depending on the question and tool flow, that can include schema metadata, question text, generated SQL, and query results. Review that provider's retention, training, and residency terms before using sensitive data.
+
+If you need local-only inference, [Ollama-compatible endpoints are supported](#ai-provider), but this path is not currently exercised in the benchmark, so validate it against your own workload first.
+
+To reduce exposure, see [Safety and data handling](#safety-and-data-handling): read-only database accounts, row/byte/timeout limits, and a required foreign-key discovery step before any SQL runs.
+
+## Usage
+
+```bash
+dbask "How much revenue last month?"                      # natural (default)
+dbask --mode technical "How much revenue last month?"     # answer + SQL
+dbask --mode debug "How much revenue last month?"         # answer + tool traces
+# `dbask ask "…"` is the same as `dbask "…"`; use it for a one-word question or inside older scripts.
+```
+
+Shorthand flags `--technical` and `--debug` also work.
+
+| Mode | Output |
+|---|---|
+| `natural` | A concise, business-friendly answer. |
+| `technical` | The answer plus the SQL that was run. |
+| `debug` | The answer plus tool-call diagnostics. Start here when an answer looks wrong. |
+
+**Terminal output.** In an interactive terminal the CLI shows a progress spinner, renders the answer's Markdown (tables, bold, code, lists) and, in debug mode, prints the tool trace with symbols, highlighted SQL, the submitted query plan and any plan warnings. When output is piped or redirected, nothing changes: you get the plain Markdown answer and the plain `[tool]` / `[done]` trace. Set `NO_COLOR=1` to turn colors off, or `FORCE_COLOR=1` to keep them in a pipe.
+
+## Configuration
+
+Configuration is loaded from `.env` in the current working directory plus the process environment. See `.env.example` in the repository for a full template.
+
+### AI provider
+
+| Variable | Purpose | Example |
+|---|---|---|
+| `AI_PROVIDER` | One of `openrouter`, `google`, `groq`, `cerebras`, `ollama`, `deepseek` | `openrouter` |
+| `AI_MODEL` | Exact model ID accepted by the provider | *required* |
+| `OPENROUTER_API_KEY` | OpenRouter credential | n/a |
+| `GOOGLE_GENERATIVE_AI_API_KEY` | Google Gemini credential | n/a |
+| `GROQ_API_KEY` | Groq credential | n/a |
+| `CEREBRAS_API_KEY` | Cerebras credential | n/a |
+| `OLLAMA_BASE_URL` | Ollama endpoint | `http://localhost:11434/v1` |
+| `DEEPSEEK_API_KEY` | DeepSeek credential | n/a |
+| `AI_SITE_URL` | Optional OpenRouter app URL metadata | n/a |
+| `AI_SITE_NAME` | Optional OpenRouter app name metadata | `dbask` |
+
+Model availability, pricing, quotas, and API behavior are controlled by each provider and can change independently of this project.
+
+### Database
+
+| Variable | Purpose | Default |
+|---|---|---|
+| `DB_DRIVER` | `mysql` (also MariaDB) or `postgres` | `mysql` |
+| `DB_HOST` | Hostname or IP | `127.0.0.1` |
+| `DB_PORT` | Port | `3306` for mysql, `5432` for postgres |
+| `DB_SSL` | `disable`, `require` (encrypt, don't verify the certificate), or `verify-full` (encrypt and verify; use `NODE_EXTRA_CA_CERTS` for a private CA) | `disable` |
+| `DB_NAME` | Database name | *required* |
+| `DB_USER` | Username (**use a restricted read-only account**) | *required* |
+| `DB_PASSWORD` | Password (set privately) | *required* |
+
+### Limits
+
+| Variable | Purpose | Default |
+|---|---|---|
+| `SQL_MAX_ROWS` | Max rows returned per query | `500` |
+| `SQL_QUERY_TIMEOUT_MS` | Per-query timeout (ms) | `10000` |
+| `SQL_MAX_RESULT_BYTES` | Max result payload size (bytes) | `1048576` |
+| `AGENT_MAX_STEPS` | Max agent loop steps | `8` |
+| `AGENT_QUERY_PLAN` | `on` requires a schema-checked query plan before SQL runs; `off` skips it | `off` |
+| `SCHEMA_CACHE_TTL_MS` | Schema cache lifetime (ms) | `300000` (5 min) |
+
+Start from the `.env.example` values and tune against your own database. Higher limits increase both resource use and the amount of data exposed to the model.
+
+## Optional database context
+
+Place a `sql-ai.md` file in the working directory to explain business terms and rules that aren't obvious from table and column names. It supplements schema discovery; it does not replace it.
+
+```markdown
+# Database Context
+
+## Overview
+
+This database belongs to a school management system. It stores students,
+parents, teachers, classes, enrollments, and payments.
+
+## Business Rules
+
+- Only active enrollments represent currently enrolled students.
+- Completed payments are considered successful payments.
+- Cancelled payments should not be included in revenue calculations.
+```
+
+Keep the rules accurate and current. Incorrect or ambiguous context can produce confidently wrong answers even when the generated SQL is valid. A starter template ships as [`sql-ai.example.md`](./sql-ai.example.md).
+
+## TypeScript SDK
+
+The package exports its public SDK from `@negusdev/dbask`. Import from the package entry point; internal `src/` paths are not part of the public API.
+
+```ts
+import {
+  Agent,
+  createAiProvider,
+  createDatabaseAdapter,
+  loadConfig,
+} from "@negusdev/dbask";
+
+const config = loadConfig();
+
+// Picks MySqlAdapter or PostgresAdapter from DB_DRIVER.
+// You can also construct MySqlAdapter / PostgresAdapter directly.
+const database = createDatabaseAdapter(config.database);
+
+const provider = createAiProvider(config.ai);
+
+const agent = new Agent(
+  provider,
+  { database, safety: config.safety },
+  { maxSteps: config.agent.maxSteps, responseMode: "natural" },
+);
+
+try {
+  const result = await agent.ask("List active users");
+  console.log(result.text);
+} finally {
+  await database.close();
+}
+```
+
+The entry point also exports types and interfaces for the agent, providers, database adapters, tool context, observers, and `SchemaCache`. See `src/index.ts` in the installed version for the exact API surface.
+
+The SDK accepts any `DatabaseAdapter` implementation. Custom adapters must preserve the harness safety expectations: read-only intent, row/byte/timeout limits, and bounded SQL attempts per question.
+
+## Database tools
+
+| Tool | Purpose |
+|---|---|
+| `list_tables` | List available database tables. |
+| `describe_table` | Inspect one table's structure. |
+| `describe_tables` | Inspect multiple tables in one call. |
+| `get_relationships` | Discover foreign-key relationships across the database. |
+| `execute_query` | Execute SQL allowed by the safety layer and configured limits. |
+| `explain_query` | Request a query plan where supported. |
+
+The agent requires **successful global foreign-key discovery before executing SQL**. This helps the model plan joins, but it does not prove every join or aggregation matches the business meaning of a question, and undeclared relationships may not be discoverable.
+
+## Safety and data handling
+
+dbask applies safeguards and execution limits, but **it is not a complete security boundary by itself**. Recommended practices:
+
+1. **Use a dedicated read-only database account** with only the schema-inspection and read permissions required. Don't rely solely on the model or the application validator to prevent writes.
+2. **Restrict database visibility.** Avoid granting access to unrelated databases, sensitive tables, or columns.
+3. **Protect credentials.** Don't commit `.env` or share credentials in logs or issue reports. Rotate any credential that is exposed.
+4. **Review your AI provider's data handling.** Schema metadata, question text, generated SQL, and query results may be sent to the provider. Check its retention, training, residency, and contractual terms before using sensitive data.
+5. **Set conservative limits** for rows, result size, timeout, and agent steps.
+6. **Verify important answers** independently before using them for financial, operational, or compliance decisions.
+7. **Test on a non-production database first**, such as a disposable or sanitized snapshot.
+
+The SQL validator tokenizes each query, so keywords inside string literals, quoted identifiers, and comments are ignored. It accepts a single read-oriented statement and rejects writes, locking reads, `INTO OUTFILE`, executable comments, and functions such as `SLEEP()` and `LOAD_FILE()`. It uses the lexical rules of the configured database (for example PostgreSQL's dollar-quoted strings and nested comments, or MySQL's `#` comments and backslash escapes), and it assumes MySQL's default `sql_mode`. It cannot recognize user-defined functions with side effects, which is another reason to use a read-only database account.
+
+On PostgreSQL the adapter adds server-side protection that does not depend on the validator: every statement runs inside a `READ ONLY` transaction that is always rolled back, with a per-query `statement_timeout`, over the extended protocol (so the server itself refuses multiple statements), and rows are streamed through a cursor so oversized results are never fully loaded. Results that hit the row or size limit are flagged `truncated`, and the agent is told not to present them as complete.
+
+Successful SQL execution does not guarantee a correct answer. SQL attempts are capped per question, but correctness cannot be guaranteed for arbitrary questions or business-specific joins.
+
+## Database support
+
+| Database | Status |
+|---|---|
+| MySQL / MariaDB | Available |
+| PostgreSQL | Available (tables, partitioned tables, and schemas; views are not listed yet) |
+| SQLite | Planned |
+| Others | Implement `DatabaseAdapter` |
+
+## Evaluation
+
+The `evals/` directory contains a benchmark dataset, runner, and saved reports. Use it to check whether a change to the model, prompt, tool, or adapter measurably affects correctness.
+
+```bash
+pnpm eval -- --tag local-check
+```
+
+See [`evals/README.md`](./evals/README.md) for dataset setup and scoring. When comparing runs, keep the provider, model, database snapshot, configuration, and dataset consistent. A passing benchmark supports the cases tested; it is not a guarantee of general correctness.
+
+**Latest result (v0.1.8):** on the 40-case internal benchmark (synthetic forex database, `gemini-3.5-flash-lite`, 3 runs) the agent passed 39 of 40 cases in every run (97.5%), including 10 of 10 safety and off-topic refusal checks. The one consistent failure is a known reference-answer error in the benchmark, not an agent error. The cases are mostly simple lookups and joins, so treat this as a regression check, not a measure of accuracy on your own database.
+
+### Query plan (optional)
+
+With `AGENT_QUERY_PLAN=on` the agent must submit a structured plan (tables, columns, joins, filters) that is checked against your real schema before any SQL runs, and the SQL may only read the planned tables. In the same benchmark the plan added about 0.7 tool calls and roughly 30% median latency per question without improving accuracy, so it is off by default. Turn it on if you want the agent's assumptions visible in `--mode debug`, or to compare against your own workload.
+
+## Development
+
+```bash
+git clone https://github.com/NegusDev/dbask.git
+cd dbask
+pnpm install
+cp .env.example .env
+```
+
+Run a question through the development CLI:
+
+```bash
+pnpm dev ask "List active users"
+```
+
+Run the checks before submitting changes:
+
+```bash
+pnpm typecheck
+pnpm test
+pnpm build
+npm pack --dry-run
+```
+
+Run the built CLI directly:
+
+```bash
+node dist/cli.js ask "List active users"
+```
+
+### Project layout
+
+```text
+src/
+  ai/             Provider factory and provider interfaces
+  commands/       CLI commands, including the init wizard
+  config/         Environment and .env loading
+  context/        Optional business context loading (sql-ai.md)
+  core/agent/     Agent loop and observability interfaces
+  core/tools/     Schema and SQL tools exposed to the agent
+  database/       Database adapter interface, MySQL and PostgreSQL implementations
+  safety/         SQL validation, policy checks, execution limits
+  schema/         In-memory schema metadata cache
+  cli.ts          CLI entry point
+  index.ts        Public TypeScript SDK exports
+evals/            Benchmark dataset, runner, and reports
+tests/            Automated tests
+```
+
+## Troubleshooting
+
+### Database connection fails
+
+- Verify host, port, database name, username, and password.
+- Confirm the database accepts connections from the machine running the harness.
+- Confirm the account can inspect tables and read the required data.
+- Check firewall rules and database allowlists.
+- Hosted PostgreSQL (Neon, Supabase, RDS, ...) usually requires TLS: set `DB_SSL=require`. Poolers such as pgbouncer in transaction mode work, because each query is a self-contained transaction.
+- PostgreSQL tables outside `public` appear as `schema.table` in `list_tables`; the agent is told to use names exactly as listed.
+
+### Provider authentication or model errors
+
+- Confirm `AI_PROVIDER` matches the provider whose key you configured.
+- Verify `AI_MODEL` is the exact model ID the provider expects.
+- Check that the API key is active and has quota and access to the model.
+- For Ollama, verify the endpoint is reachable and the model is installed.
+- Run `dbask validate`. It sends one tiny request to the provider and reports whether the key, model, and network path work. (`init` only tests the database.)
+
+### The answer is incorrect or incomplete
+
+- Run with `--mode technical` or `--mode debug` to inspect the SQL and tool activity.
+- Inspect the relevant table definitions and foreign keys.
+- Review `sql-ai.md` for outdated or ambiguous rules.
+- Narrow the question with dates, statuses, or business definitions.
+- Verify the generated SQL and results directly against the database.
+- Add a representative case to `evals/` if the failure is repeatable.
+
+### Configuration is not found
+
+- Run the command from the directory containing `.env`, or set the variables in the process environment.
+- Confirm variable names match `.env.example`.
+- Check that `AI_MODEL` and the selected provider's credentials are set.
+
+## Contributing
+
+Issues and pull requests are welcome at [github.com/NegusDev/dbask](https://github.com/NegusDev/dbask).
+
+Before opening a PR, run the project checks and confirm that changes to the agent, tools, or prompts don't regress the benchmark:
+
+```bash
+pnpm eval -- --tag <your-branch>
+```
+
+For bugs involving incorrect answers, include:
+
+- The question you asked (or a close paraphrase)
+- The `--mode debug` output
+- The relevant table definitions and `sql-ai.md` content, if any
+- The provider and model used
+
+Do **not** include `.env` contents, credentials, or unfiltered production data in issue reports.
+
+## License
+
+Released under the [ISC License](./LICENSE).
+
+## Links
+
+- [Source](https://github.com/NegusDev/dbask)
+- [npm](https://www.npmjs.com/package/@negusdev/dbask)
+- [Issues](https://github.com/NegusDev/dbask/issues)
+- [Evaluation guide](./evals/README.md)
+- [Business context template](./sql-ai.example.md)

package/dist/ai/factory.d.ts

@@ -0,0 +1,4 @@
+import type { AppConfig } from '../config/config.js';
+import type { AiProvider } from './provider.js';
+export declare function createAiProvider(config: AppConfig['ai']): AiProvider;
+//# sourceMappingURL=factory.d.ts.map

package/dist/ai/factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../../src/ai/factory.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAGhD,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,SAAS,CAAC,IAAI,CAAC,GAAG,UAAU,CAgEpE"}

package/dist/ai/factory.js

@@ -0,0 +1,55 @@
+import { createOpenRouter } from '@openrouter/ai-sdk-provider';
+import { createGroq } from '@ai-sdk/groq';
+import { createGoogleGenerativeAI } from '@ai-sdk/google';
+import { createCerebras } from '@ai-sdk/cerebras';
+import { createOpenAICompatible } from '@ai-sdk/openai-compatible';
+import { createDeepSeek } from '@ai-sdk/deepseek';
+import { SdkAiProvider } from './sdk-provider.js';
+export function createAiProvider(config) {
+    switch (config.provider) {
+        case 'openrouter': {
+            const provider = createOpenRouter({
+                apiKey: config.apiKey,
+                ...(config.siteUrl ? { appUrl: config.siteUrl } : {}),
+                ...(config.siteName ? { appName: config.siteName } : {}),
+            });
+            return new SdkAiProvider('openrouter', provider.chat(config.model));
+        }
+        case 'groq': {
+            const provider = createGroq({
+                apiKey: config.apiKey,
+            });
+            return new SdkAiProvider('groq', provider(config.model));
+        }
+        case 'google': {
+            const provider = createGoogleGenerativeAI({
+                apiKey: config.apiKey,
+            });
+            return new SdkAiProvider('google', provider(config.model));
+        }
+        case 'cerebras': {
+            const provider = createCerebras({
+                apiKey: config.apiKey,
+            });
+            return new SdkAiProvider('cerebras', provider(config.model));
+        }
+        case 'ollama': {
+            const provider = createOpenAICompatible({
+                name: 'ollama',
+                baseURL: config.baseUrl ?? 'http://localhost:11434/v1',
+            });
+            return new SdkAiProvider('ollama', provider.chatModel(config.model));
+        }
+        case 'deepseek': {
+            const provider = createDeepSeek({
+                apiKey: config.apiKey,
+            });
+            return new SdkAiProvider('deepseek', provider.chat(config.model));
+        }
+        default: {
+            const exhaustiveCheck = config.provider;
+            throw new Error(`Unsupported AI provider: ${exhaustiveCheck}`);
+        }
+    }
+}
+//# sourceMappingURL=factory.js.map

package/dist/ai/factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.js","sourceRoot":"","sources":["../../src/ai/factory.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAC/D,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAC;AAC1D,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AACnE,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAIlD,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAElD,MAAM,UAAU,gBAAgB,CAAC,MAAuB;IACtD,QAAQ,MAAM,CAAC,QAAQ,EAAE,CAAC;QACxB,KAAK,YAAY,EAAE,CAAC;YAClB,MAAM,QAAQ,GAAG,gBAAgB,CAAC;gBAChC,MAAM,EAAE,MAAM,CAAC,MAAO;gBACtB,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBACrD,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aACzD,CAAC,CAAC;YAEH,OAAO,IAAI,aAAa,CACtB,YAAY,EACZ,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAC5B,CAAC;QACJ,CAAC;QAED,KAAK,MAAM,EAAE,CAAC;YACZ,MAAM,QAAQ,GAAG,UAAU,CAAC;gBAC1B,MAAM,EAAE,MAAM,CAAC,MAAO;aACvB,CAAC,CAAC;YAEH,OAAO,IAAI,aAAa,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;QAC3D,CAAC;QAED,KAAK,QAAQ,EAAE,CAAC;YACd,MAAM,QAAQ,GAAG,wBAAwB,CAAC;gBACxC,MAAM,EAAE,MAAM,CAAC,MAAO;aACvB,CAAC,CAAC;YAEH,OAAO,IAAI,aAAa,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;QAC7D,CAAC;QAED,KAAK,UAAU,EAAE,CAAC;YAChB,MAAM,QAAQ,GAAG,cAAc,CAAC;gBAC9B,MAAM,EAAE,MAAM,CAAC,MAAO;aACvB,CAAC,CAAC;YAEH,OAAO,IAAI,aAAa,CAAC,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;QAC/D,CAAC;QAED,KAAK,QAAQ,EAAE,CAAC;YACd,MAAM,QAAQ,GAAG,sBAAsB,CAAC;gBACtC,IAAI,EAAE,QAAQ;gBACd,OAAO,EAAE,MAAM,CAAC,OAAO,IAAI,2BAA2B;aACvD,CAAC,CAAC;YAEH,OAAO,IAAI,aAAa,CACtB,QAAQ,EACR,QAAQ,CAAC,SAAS,CAAC,MAAM,CAAC,KAAK,CAAC,CACjC,CAAC;QACJ,CAAC;QAED,KAAK,UAAU,EAAE,CAAC;YAChB,MAAM,QAAQ,GAAG,cAAc,CAAC;gBAC9B,MAAM,EAAE,MAAM,CAAC,MAAO;aACvB,CAAC,CAAC;YAEH,OAAO,IAAI,aAAa,CAAC,UAAU,EAAE,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;QACpE,CAAC;QAED,SAAS,CAAC;YACR,MAAM,eAAe,GAAU,MAAM,CAAC,QAAQ,CAAC;YAC/C,MAAM,IAAI,KAAK,CAAC,4BAA4B,eAAe,EAAE,CAAC,CAAC;QACjE,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/ai/provider.d.ts

@@ -0,0 +1,13 @@
+import type { ToolSet } from 'ai';
+import type { ModelProvider, ModelRequest, ModelResponse } from '../core/types/index.js';
+export type { ModelProvider, ModelRequest, ModelResponse };
+export interface AiProvider extends ModelProvider {
+    generate(request: ModelRequest & {
+        tools?: ToolSet;
+        maxSteps?: number;
+    }): Promise<ModelResponse & {
+        steps?: number;
+        toolCalls?: number;
+    }>;
+}
+//# sourceMappingURL=provider.d.ts.map

package/dist/ai/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../src/ai/provider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,IAAI,CAAC;AAClC,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAEzF,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,aAAa,EAAE,CAAC;AAE3D,MAAM,WAAW,UAAW,SAAQ,aAAa;IAC/C,QAAQ,CAAC,OAAO,EAAE,YAAY,GAAG;QAAE,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,aAAa,GAAG;QAChG,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,CAAC,CAAC;CACJ"}

package/dist/ai/provider.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=provider.js.map

package/dist/ai/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../../src/ai/provider.ts"],"names":[],"mappings":""}

package/dist/ai/sdk-provider.d.ts

@@ -0,0 +1,13 @@
+import { type LanguageModel, type ToolSet } from 'ai';
+import type { ModelRequest, ModelResponse } from '../core/types/index.js';
+import type { AiProvider } from './provider.js';
+export declare class SdkAiProvider implements AiProvider {
+    readonly name: string;
+    private readonly model;
+    constructor(name: string, model: LanguageModel);
+    generate(request: ModelRequest & {
+        tools?: ToolSet;
+        maxSteps?: number;
+    }): Promise<ModelResponse>;
+}
+//# sourceMappingURL=sdk-provider.d.ts.map

package/dist/ai/sdk-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sdk-provider.d.ts","sourceRoot":"","sources":["../../src/ai/sdk-provider.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,KAAK,aAAa,EAClB,KAAK,OAAO,EACb,MAAM,IAAI,CAAC;AAEZ,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAC1E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAEhD,qBAAa,aAAc,YAAW,UAAU;IAE5C,QAAQ,CAAC,IAAI,EAAE,MAAM;IACrB,OAAO,CAAC,QAAQ,CAAC,KAAK;IAFxB,YACW,IAAI,EAAE,MAAM,EACJ,KAAK,EAAE,aAAa,EACnC;IAEE,QAAQ,CACZ,OAAO,EAAE,YAAY,GAAG;QACtB,KAAK,CAAC,EAAE,OAAO,CAAC;QAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,GACA,OAAO,CAAC,aAAa,CAAC,CA+BxB;CACF"}

package/dist/ai/sdk-provider.js

@@ -0,0 +1,36 @@
+import { generateText, isStepCount, } from 'ai';
+export class SdkAiProvider {
+    name;
+    model;
+    constructor(name, model) {
+        this.name = name;
+        this.model = model;
+    }
+    async generate(request) {
+        const result = await generateText({
+            model: this.model,
+            system: request.system,
+            prompt: request.prompt,
+            tools: request.tools,
+            stopWhen: request.maxSteps
+                ? isStepCount(request.maxSteps)
+                : undefined,
+            // Reserve the last step for the answer: without this the model can spend
+            // every step on tool calls and end with no text at all.
+            prepareStep: request.maxSteps
+                ? ({ stepNumber }) => stepNumber >= request.maxSteps - 1
+                    ? { toolChoice: 'none' }
+                    : undefined
+                : undefined,
+            temperature: request.temperature,
+        });
+        const toolCalls = result.steps.reduce((count, step) => count + (step.toolCalls?.length ?? 0), 0);
+        return {
+            text: result.text,
+            raw: result,
+            steps: result.steps.length,
+            toolCalls,
+        };
+    }
+}
+//# sourceMappingURL=sdk-provider.js.map

package/dist/ai/sdk-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sdk-provider.js","sourceRoot":"","sources":["../../src/ai/sdk-provider.ts"],"names":[],"mappings":"AACA,OAAO,EACL,YAAY,EACZ,WAAW,GAGZ,MAAM,IAAI,CAAC;AAKZ,MAAM,OAAO,aAAa;IAEb,IAAI;IACI,KAAK;IAFxB,YACW,IAAY,EACJ,KAAoB;oBAD5B,IAAI;qBACI,KAAK;IACrB,CAAC;IAEJ,KAAK,CAAC,QAAQ,CACZ,OAGC;QAED,MAAM,MAAM,GAAG,MAAM,YAAY,CAAC;YAChC,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,MAAM,EAAE,OAAO,CAAC,MAAM;YACtB,MAAM,EAAE,OAAO,CAAC,MAAM;YACtB,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,QAAQ,EAAE,OAAO,CAAC,QAAQ;gBACxB,CAAC,CAAC,WAAW,CAAC,OAAO,CAAC,QAAQ,CAAC;gBAC/B,CAAC,CAAC,SAAS;YACb,yEAAyE;YACzE,wDAAwD;YACxD,WAAW,EAAE,OAAO,CAAC,QAAQ;gBAC3B,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,EAAE,EAAE,CACjB,UAAU,IAAK,OAAO,CAAC,QAAmB,GAAG,CAAC;oBAC5C,CAAC,CAAC,EAAE,UAAU,EAAE,MAAe,EAAE;oBACjC,CAAC,CAAC,SAAS;gBACjB,CAAC,CAAC,SAAS;YACb,WAAW,EAAE,OAAO,CAAC,WAAW;SACjC,CAAC,CAAC;QAEH,MAAM,SAAS,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM,CACnC,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC,KAAK,GAAG,CAAC,IAAI,CAAC,SAAS,EAAE,MAAM,IAAI,CAAC,CAAC,EACtD,CAAC,CACF,CAAC;QAEF,OAAO;YACL,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,GAAG,EAAE,MAAM;YACX,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,MAAM;YAC1B,SAAS;SACV,CAAC;IACJ,CAAC;CACF"}