@negusdev/dbask 0.0.0-stage → 0.1.8

package/dist/config/config.js

@@ -0,0 +1,94 @@
+import 'dotenv/config';
+import { z } from 'zod';
+const providerSchema = z.enum([
+    'openrouter',
+    'groq',
+    'google',
+    'cerebras',
+    'ollama',
+    'deepseek',
+]);
+const envSchema = z.object({
+    AI_PROVIDER: providerSchema.default('openrouter'),
+    AI_MODEL: z.string().min(1, 'AI_MODEL is required'),
+    OPENROUTER_API_KEY: z.string().optional(),
+    GROQ_API_KEY: z.string().optional(),
+    GOOGLE_GENERATIVE_AI_API_KEY: z.string().optional(),
+    CEREBRAS_API_KEY: z.string().optional(),
+    DEEPSEEK_API_KEY: z.string().optional(),
+    OLLAMA_BASE_URL: z.string().url().default('http://localhost:11434/v1'),
+    AI_SITE_URL: z.preprocess((value) => value === '' ? undefined : value, z.string().url().optional()),
+    AI_SITE_NAME: z.string().default('dbask'),
+    DB_DRIVER: z.enum(['mysql', 'postgres', 'sqlite']).default('mysql'),
+    DB_HOST: z.string().default('127.0.0.1'),
+    // Empty means "use the driver's default port" (3306 / 5432).
+    DB_PORT: z.preprocess((value) => value === '' ? undefined : value, z.coerce.number().int().min(1).max(65535).optional()),
+    DB_NAME: z.string().default(''),
+    DB_USER: z.string().default(''),
+    DB_PASSWORD: z.string().default(''),
+    DB_SSL: z.enum(['disable', 'require', 'verify-full']).default('disable'),
+    SQL_MAX_ROWS: z.coerce.number().int().positive().default(500),
+    SQL_QUERY_TIMEOUT_MS: z.coerce.number().int().positive().default(10_000),
+    SQL_MAX_RESULT_BYTES: z.coerce.number().int().positive().default(1_048_576),
+    AGENT_MAX_STEPS: z.coerce.number().int().min(1).max(20).default(8),
+    // "on" makes the agent submit a schema-checked query plan before running SQL.
+    AGENT_QUERY_PLAN: z.enum(['on', 'off']).default('off'),
+    SCHEMA_CACHE_TTL_MS: z.coerce.number().int().positive().default(300_000),
+});
+export function loadConfig(env = process.env) {
+    const parsed = envSchema.parse(env);
+    const apiKeys = {
+        openrouter: parsed.OPENROUTER_API_KEY,
+        groq: parsed.GROQ_API_KEY,
+        google: parsed.GOOGLE_GENERATIVE_AI_API_KEY,
+        cerebras: parsed.CEREBRAS_API_KEY,
+        ollama: undefined,
+        deepseek: parsed.DEEPSEEK_API_KEY,
+    };
+    const apiKey = apiKeys[parsed.AI_PROVIDER];
+    if (parsed.AI_PROVIDER !== 'ollama' && !apiKey?.trim()) {
+        const envNames = {
+            openrouter: 'OPENROUTER_API_KEY',
+            groq: 'GROQ_API_KEY',
+            google: 'GOOGLE_GENERATIVE_AI_API_KEY',
+            cerebras: 'CEREBRAS_API_KEY',
+            deepseek: 'DEEPSEEK_API_KEY',
+        };
+        throw new Error(`${envNames[parsed.AI_PROVIDER]} is required when AI_PROVIDER=${parsed.AI_PROVIDER}`);
+    }
+    return {
+        ai: {
+            provider: parsed.AI_PROVIDER,
+            apiKey,
+            model: parsed.AI_MODEL,
+            baseUrl: parsed.AI_PROVIDER === 'ollama'
+                ? parsed.OLLAMA_BASE_URL
+                : undefined,
+            siteUrl: parsed.AI_SITE_URL,
+            siteName: parsed.AI_SITE_NAME,
+        },
+        database: {
+            driver: parsed.DB_DRIVER,
+            host: parsed.DB_HOST,
+            port: parsed.DB_PORT ?? (parsed.DB_DRIVER === 'postgres' ? 5432 : 3306),
+            name: parsed.DB_NAME,
+            user: parsed.DB_USER,
+            password: parsed.DB_PASSWORD,
+            ssl: parsed.DB_SSL,
+        },
+        agent: {
+            maxSteps: parsed.AGENT_MAX_STEPS,
+            queryPlan: parsed.AGENT_QUERY_PLAN === 'on',
+        },
+        schema: {
+            cacheTtlMs: parsed.SCHEMA_CACHE_TTL_MS,
+        },
+        safety: {
+            readOnly: true,
+            maxRows: parsed.SQL_MAX_ROWS,
+            queryTimeoutMs: parsed.SQL_QUERY_TIMEOUT_MS,
+            maxResultBytes: parsed.SQL_MAX_RESULT_BYTES,
+        },
+    };
+}
+//# sourceMappingURL=config.js.map

package/dist/config/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/config/config.ts"],"names":[],"mappings":"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"}

package/dist/context/db-context.d.ts

@@ -0,0 +1,12 @@
+import type { DatabaseContext } from '../core/types/index.js';
+export declare const DEFAULT_DATABASE_CONTEXT_FILE = "sql-ai.md";
+export interface DatabaseContextLoaderOptions {
+    cwd?: string;
+    fileName?: string;
+}
+/**
+ * Loads optional, user-authored business/domain context for the connected database.
+ * Missing context is normal and never prevents the harness from running.
+ */
+export declare function loadDatabaseContext(options?: DatabaseContextLoaderOptions): Promise<DatabaseContext>;
+//# sourceMappingURL=db-context.d.ts.map

package/dist/context/db-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"db-context.d.ts","sourceRoot":"","sources":["../../src/context/db-context.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAE9D,eAAO,MAAM,6BAA6B,cAAc,CAAC;AAEzD,MAAM,WAAW,4BAA4B;IAC3C,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,GAAE,4BAAiC,GACzC,OAAO,CAAC,eAAe,CAAC,CAqB1B"}

package/dist/context/db-context.js

@@ -0,0 +1,29 @@
+import { access, readFile } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { resolve } from 'node:path';
+export const DEFAULT_DATABASE_CONTEXT_FILE = 'sql-ai.md';
+/**
+ * Loads optional, user-authored business/domain context for the connected database.
+ * Missing context is normal and never prevents the harness from running.
+ */
+export async function loadDatabaseContext(options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const fileName = options.fileName ?? DEFAULT_DATABASE_CONTEXT_FILE;
+    const path = resolve(cwd, fileName);
+    try {
+        await access(path, constants.R_OK);
+        const content = (await readFile(path, 'utf8')).trim();
+        if (!content)
+            return {};
+        return { content, source: path };
+    }
+    catch (error) {
+        const code = error && typeof error === 'object' && 'code' in error
+            ? error.code
+            : undefined;
+        if (code === 'ENOENT')
+            return {};
+        throw error;
+    }
+}
+//# sourceMappingURL=db-context.js.map

package/dist/context/db-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"db-context.js","sourceRoot":"","sources":["../../src/context/db-context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAGpC,MAAM,CAAC,MAAM,6BAA6B,GAAG,WAAW,CAAC;AAOzD;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,OAAO,GAAiC,EAAE;IAE1C,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;IACzC,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,6BAA6B,CAAC;IACnE,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;IAEpC,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,IAAI,EAAE,SAAS,CAAC,IAAI,CAAC,CAAC;QACnC,MAAM,OAAO,GAAG,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QAEtD,IAAI,CAAC,OAAO;YAAE,OAAO,EAAE,CAAC;QAExB,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;IACnC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,GAAG,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,IAAI,KAAK;YAChE,CAAC,CAAE,KAA2B,CAAC,IAAI;YACnC,CAAC,CAAC,SAAS,CAAC;QAEd,IAAI,IAAI,KAAK,QAAQ;YAAE,OAAO,EAAE,CAAC;QAEjC,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist/core/agent/agent.d.ts

@@ -0,0 +1,57 @@
+import type { AiProvider } from "../../ai/provider.js";
+import type { DatabaseContext, ToolContext } from "../types/index.js";
+import { type AgentObserver } from "./observability.js";
+export type ResponseMode = "natural" | "technical" | "debug";
+export interface AgentOptions {
+    maxSteps?: number;
+    databaseContext?: DatabaseContext;
+    responseMode?: ResponseMode;
+    temperature?: number;
+    observer?: AgentObserver;
+    /**
+     * Require a validated query plan before any SQL runs. Defaults to false:
+     * on the benchmark the plan added about 0.7 tool calls and ~30% latency per
+     * question without improving accuracy.
+     */
+    requirePlan?: boolean;
+}
+export interface PlanStats {
+    submitted: number;
+    accepted: number;
+    rejected: number;
+    /** execute_query calls blocked because the SQL used tables outside the plan. */
+    sqlMismatches: number;
+}
+export interface AgentResult {
+    text: string;
+    steps: number;
+    toolCalls: number;
+    raw?: unknown;
+    /**
+     * True when the model produced no final answer (for example it ran out of
+     * steps). `text` then holds an explanation instead of an answer.
+     */
+    incomplete?: boolean;
+    /** Plan counters for this question; absent when plans are switched off. */
+    plan?: PlanStats;
+}
+/**
+ * Application-level agent. Provider-specific model calls stay behind AiProvider;
+ * database access stays behind ToolContext and the tool registry.
+ */
+export declare class Agent {
+    private readonly provider;
+    private readonly context;
+    private readonly options;
+    constructor(provider: AiProvider, context: ToolContext, options?: AgentOptions);
+    ask(question: string): Promise<AgentResult>;
+    private get planRequired();
+    private planStats;
+    private planInstructions;
+    private dialectInstructions;
+    private responseInstructions;
+    private buildTools;
+    private loadSchemaFacts;
+    private discoverRelationships;
+}
+//# sourceMappingURL=agent.d.ts.map

package/dist/core/agent/agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../../src/core/agent/agent.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,KAAK,EACV,eAAe,EAIf,WAAW,EACZ,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAqB,KAAK,aAAa,EAAE,MAAM,oBAAoB,CAAC;AA2C3E,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,WAAW,GAAG,OAAO,CAAC;AAE7D,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,YAAY,CAAC,EAAE,YAAY,CAAC;IAE5B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,MAAM,WAAW,SAAS;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,gFAAgF;IAChF,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,CAAC,EAAE,OAAO,CAAC;IACd;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,2EAA2E;IAC3E,IAAI,CAAC,EAAE,SAAS,CAAC;CAClB;AA4ED;;;GAGG;AACH,qBAAa,KAAK;IAEd,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAH1B,YACmB,QAAQ,EAAE,UAAU,EACpB,OAAO,EAAE,WAAW,EACpB,OAAO,GAAE,YAAiB,EACzC;IAEE,GAAG,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAkGhD;IAED,OAAO,KAAK,YAAY,GAEvB;IAED,OAAO,CAAC,SAAS;IAajB,OAAO,CAAC,gBAAgB;IAYxB,OAAO,CAAC,mBAAmB;IAkB3B,OAAO,CAAC,oBAAoB;IAyB5B,OAAO,CAAC,UAAU;YA0PJ,eAAe;YAoBf,qBAAqB;CAmDpC"}