@taodigital/agents 0.0.0-stage → 1.2.1

package/dist/llm.js

@@ -0,0 +1,438 @@
+"use strict";
+/**
+ * Multi-provider LLM module.
+ *
+ * Providers using their own SDK: Anthropic.
+ * Providers via OpenAI-compatible API (single openai package): OpenAI, Gemini,
+ * Grok (xAI), OpenRouter, Ollama (local), Nvidia NIM.
+ *
+ * Config is resolved per-tenant only (set in Workspace → Settings → AI Provider).
+ * No platform-level API key fallback — every workspace must configure its own provider.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LLMProviderError = exports.DEFAULT_MODELS = void 0;
+exports.deterministicSeed = deterministicSeed;
+exports.sanitizeProviderError = sanitizeProviderError;
+exports.askTrackedWithImages = askTrackedWithImages;
+exports.askWithImages = askWithImages;
+exports.askTracked = askTracked;
+exports.ask = ask;
+const sdk_1 = __importDefault(require("@anthropic-ai/sdk"));
+const openai_1 = __importDefault(require("openai"));
+const core_1 = require("@taodigital/core");
+const token_pricing_1 = require("./token-pricing");
+const llm_mock_js_1 = require("./llm-mock.js");
+function deterministicSeed(input) {
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < input.length; i++) {
+        hash ^= input.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return hash >>> 1;
+}
+// Per-request cap. Without this the SDKs default to 10 minutes, so one hung
+// provider call can silently stall a whole generation batch.
+// Default 120s — long enough for large prompts on free/slow LLMs, short enough to fail fast.
+const LLM_REQUEST_TIMEOUT_MS = Math.max(10_000, Number(process.env.LLM_REQUEST_TIMEOUT_MS ?? 120_000));
+const APP_PUBLIC_URL = process.env.APP_PUBLIC_URL ?? 'https://zeta-ai.io';
+const APP_TITLE = process.env.APP_TITLE ?? 'ZeTa-AI';
+const PROVIDER_BASE_URLS = {
+    anthropic: '',
+    openai: process.env.OPENAI_BASE_URL ?? 'https://api.openai.com/v1',
+    gemini: process.env.GEMINI_BASE_URL ?? 'https://generativelanguage.googleapis.com/v1beta/openai/',
+    grok: process.env.GROK_BASE_URL ?? 'https://api.x.ai/v1',
+    openrouter: process.env.OPENROUTER_BASE_URL ?? 'https://openrouter.ai/api/v1',
+    ollama: process.env.OLLAMA_BASE_URL ?? 'http://localhost:11434/v1',
+    nvidia: process.env.NVIDIA_BASE_URL ?? 'https://integrate.api.nvidia.com/v1',
+    groq: process.env.GROQ_BASE_URL ?? 'https://api.groq.com/openai/v1',
+    mistral: process.env.MISTRAL_BASE_URL ?? 'https://api.mistral.ai/v1',
+    deepseek: process.env.DEEPSEEK_BASE_URL ?? 'https://api.deepseek.com/v1',
+    perplexity: process.env.PERPLEXITY_BASE_URL ?? 'https://api.perplexity.ai',
+    togetherai: process.env.TOGETHERAI_BASE_URL ?? 'https://api.together.xyz/v1',
+    bedrock: '',
+    vertex: '',
+    azure: '',
+};
+exports.DEFAULT_MODELS = {
+    anthropic: 'claude-sonnet-4-6',
+    openai: 'gpt-4o',
+    gemini: 'gemini-2.5-pro',
+    grok: 'grok-3',
+    openrouter: 'anthropic/claude-3-5-sonnet:beta',
+    ollama: 'llama3',
+    nvidia: 'meta/llama-3.1-70b-instruct',
+    groq: 'llama-3.3-70b-versatile',
+    mistral: 'mistral-large-latest',
+    deepseek: 'deepseek-chat',
+    perplexity: 'llama-3.1-sonar-large-128k-online',
+    togetherai: 'meta-llama/Llama-3.3-70B-Instruct-Turbo',
+    bedrock: 'anthropic.claude-3-5-sonnet-20241022-v2:0',
+    vertex: 'gemini-2.5-pro',
+    azure: 'gpt-4o',
+};
+/**
+ * Thrown in place of a raw provider SDK error. Provider error messages
+ * sometimes echo back a snippet of the request/prompt content (e.g. a
+ * content-policy rejection quoting the offending text), which may include a
+ * customer's crawled screen content or other sensitive data - safe to log
+ * server-side, not safe to return verbatim to whoever's looking at the API
+ * response. sanitizeProviderError() below preserves the actionable signal
+ * (rate limited vs. bad auth vs. bad request) without the raw text.
+ */
+class LLMProviderError extends Error {
+    /** True when the error is not transient and retrying will not help. */
+    nonRetryable;
+    constructor(message = 'AI service temporarily unavailable. Please try again.', nonRetryable = false) {
+        super(message);
+        this.name = 'LLMProviderError';
+        this.nonRetryable = nonRetryable;
+    }
+}
+exports.LLMProviderError = LLMProviderError;
+function sanitizeProviderError(e) {
+    console.error('[llm] provider error (sanitized before returning to caller):', e);
+    // Re-throw LLMProviderErrors we deliberately raised (e.g. "key not configured") without
+    // replacing their message with the generic fallback.
+    if (e instanceof LLMProviderError)
+        return e;
+    const status = e?.status ?? e?.statusCode;
+    const causeCode = e?.cause?.code ?? e?.code;
+    if (causeCode === 'ENOTFOUND')
+        return new LLMProviderError('AI provider endpoint is unreachable. Check Workspace → Settings → AI Provider.', true);
+    if (status === 429)
+        return new LLMProviderError('AI provider rate limit reached. Please try again shortly.');
+    if (status === 401 || status === 403)
+        return new LLMProviderError('AI provider rejected the configured API key. Check Workspace → Settings → AI Provider.');
+    if (status === 404)
+        return new LLMProviderError('Model not found on this provider. Check the model ID is correct and available on the production API (not just the playground).');
+    if (status === 400)
+        return new LLMProviderError('The AI provider rejected this request (invalid input or content policy).');
+    if (status === 502 || status === 503 || status === 504)
+        return new LLMProviderError('AI provider is temporarily unavailable. Please try again shortly.');
+    return new LLMProviderError();
+}
+/** Mock-aware entry point (see llm-mock.ts). With ZETA_LLM_MOCK unset this is a pass-through. */
+async function askTrackedWithImages(system, user, images, llmCfg, options) {
+    const mode = (0, llm_mock_js_1.getMockMode)();
+    if (mode === 'off') {
+        const real = await _askTrackedWithImagesReal(system, user, images, llmCfg, options);
+        (0, llm_mock_js_1.recordLlmCall)(real.usage, (0, llm_mock_js_1.mockKey)(system, user, 'vision'), 'real');
+        return real;
+    }
+    const key = (0, llm_mock_js_1.mockKey)(system, user, 'vision');
+    const out = (0, llm_mock_js_1.resolveMock)(mode, system, user, { kind: 'vision' });
+    if (out.kind === 'result') {
+        (0, llm_mock_js_1.recordLlmCall)(out.res.usage, key, out.source);
+        return out.res;
+    }
+    if (out.kind === 'error')
+        throw sanitizeProviderError({ status: out.status });
+    const real = await _askTrackedWithImagesReal(system, user, images, llmCfg, options);
+    (0, llm_mock_js_1.saveFixture)(key, real);
+    (0, llm_mock_js_1.recordLlmCall)(real.usage, key, 'recorded');
+    return real;
+}
+async function _askTrackedWithImagesReal(system, user, images, llmCfg, options) {
+    const provider = llmCfg?.provider ?? 'openai';
+    const model = llmCfg?.model ?? (core_1.config.llmModel || exports.DEFAULT_MODELS[provider]);
+    const apiKey = llmCfg?.apiKey ?? (provider === 'openai' ? (process.env.OPENAI_API_KEY ?? '') : '');
+    const baseUrl = llmCfg?.baseUrl ?? PROVIDER_BASE_URLS[provider];
+    if (provider === 'anthropic') {
+        if (!apiKey) {
+            throw new LLMProviderError('No AI provider configured. Go to Workspace → Settings → AI Provider to add your API key.');
+        }
+        try {
+            return await _askAnthropicWithImages(system, user, images, apiKey, model, options);
+        }
+        catch (e) {
+            throw sanitizeProviderError(e);
+        }
+    }
+    try {
+        return await _askOpenAICompatWithImages(system, user, images, provider, model, apiKey, baseUrl, options);
+    }
+    catch (e) {
+        throw sanitizeProviderError(e);
+    }
+}
+async function askWithImages(system, user, images, llmCfg) {
+    const res = await askTrackedWithImages(system, user, images, llmCfg);
+    return res.text;
+}
+async function _askAnthropicWithImages(system, user, images, apiKey, model, askOptions) {
+    const client = new sdk_1.default({ apiKey, timeout: LLM_REQUEST_TIMEOUT_MS, maxRetries: 1 });
+    const content = images.map((img) => ({
+        type: 'image',
+        source: { type: 'base64', media_type: img.mediaType, data: img.base64 },
+    }));
+    content.push({ type: 'text', text: user });
+    const visionMaxTokens = parseInt(process.env.VISION_MAX_TOKENS ?? '') || 4096;
+    const res = await client.messages.create({
+        model,
+        max_tokens: visionMaxTokens,
+        ...(askOptions?.temperature != null ? { temperature: askOptions.temperature } : {}),
+        // @ts-ignore: cache_control is supported in beta
+        system: [{ type: 'text', text: system, cache_control: { type: 'ephemeral' } }],
+        messages: [{ role: 'user', content }],
+    });
+    const text = res.content.map((b) => (b.type === 'text' ? b.text : '')).join('\n').trim();
+    const u = res.usage;
+    const provider = 'anthropic';
+    const providerKey = `${provider}/${model}`;
+    const cacheReadTokens = u.cache_read_input_tokens ?? 0;
+    const cacheWriteTokens = u.cache_creation_input_tokens ?? 0;
+    const usage = {
+        provider, model,
+        promptTokens: u.input_tokens,
+        completionTokens: u.output_tokens,
+        cacheReadTokens,
+        cacheWriteTokens,
+        totalTokens: u.input_tokens + u.output_tokens,
+        estimatedCostUsd: (0, token_pricing_1.estimateCost)({ provider, model, promptTokens: u.input_tokens, completionTokens: u.output_tokens, cacheReadTokens, cacheWriteTokens, totalTokens: u.input_tokens + u.output_tokens }, providerKey),
+    };
+    return { text, usage };
+}
+async function _askOpenAICompatWithImages(system, user, images, provider, model, apiKey, baseUrl, askOptions) {
+    const effectiveKey = apiKey || (provider === 'ollama' ? 'ollama' : '');
+    if (!effectiveKey && provider !== 'ollama') {
+        throw new LLMProviderError(`API key for provider "${provider}" is not configured. Go to Workspace → Settings → AI Provider and re-enter your key.`);
+    }
+    const client = new openai_1.default({
+        apiKey: effectiveKey,
+        baseURL: baseUrl,
+        timeout: LLM_REQUEST_TIMEOUT_MS,
+        maxRetries: 1,
+        ...(provider === 'openrouter' && { defaultHeaders: { 'HTTP-Referer': APP_PUBLIC_URL, 'X-Title': APP_TITLE } }),
+    });
+    const imageContent = images.map((img) => ({
+        type: 'image_url',
+        image_url: { url: `data:${img.mediaType};base64,${img.base64}` },
+    }));
+    const systemContent = provider === 'openrouter'
+        ? [{ type: 'text', text: system, cache_control: { type: 'ephemeral' } }]
+        : system;
+    const visionMaxTokens = parseInt(process.env.VISION_MAX_TOKENS ?? '') || 4096;
+    const res = await client.chat.completions.create({
+        model,
+        max_tokens: visionMaxTokens,
+        ...(askOptions?.temperature != null ? { temperature: askOptions.temperature } : {}),
+        ...(Number.isInteger(askOptions?.seed) ? { seed: askOptions?.seed } : {}),
+        messages: [
+            { role: 'system', content: systemContent },
+            { role: 'user', content: [...imageContent, { type: 'text', text: user }] },
+        ],
+    });
+    const text = res.choices[0]?.message?.content?.trim() ?? '';
+    const u = res.usage ?? { prompt_tokens: 0, completion_tokens: 0, total_tokens: 0 };
+    const usage = {
+        provider, model,
+        promptTokens: u.prompt_tokens,
+        completionTokens: u.completion_tokens,
+        cacheReadTokens: 0,
+        cacheWriteTokens: 0,
+        totalTokens: u.total_tokens,
+        estimatedCostUsd: (0, token_pricing_1.estimateCost)({ provider, model, promptTokens: u.prompt_tokens, completionTokens: u.completion_tokens, cacheReadTokens: 0, cacheWriteTokens: 0, totalTokens: u.total_tokens }, `${provider}/${model}`),
+    };
+    return { text, usage };
+}
+/** Mock-aware entry point (see llm-mock.ts). With ZETA_LLM_MOCK unset this is a pass-through. */
+async function askTracked(system, user, llmCfg, maxTokens = parseInt(process.env.AGENT_MAX_TOKENS ?? '4096', 10), schema, options) {
+    const mode = (0, llm_mock_js_1.getMockMode)();
+    if (mode === 'off') {
+        const real = await _askTrackedReal(system, user, llmCfg, maxTokens, schema, options);
+        (0, llm_mock_js_1.recordLlmCall)(real.usage, (0, llm_mock_js_1.mockKey)(system, user), 'real');
+        return real;
+    }
+    const key = (0, llm_mock_js_1.mockKey)(system, user);
+    const out = (0, llm_mock_js_1.resolveMock)(mode, system, user, { schema });
+    if (out.kind === 'result') {
+        (0, llm_mock_js_1.recordLlmCall)(out.res.usage, key, out.source);
+        return out.res;
+    }
+    if (out.kind === 'error')
+        throw sanitizeProviderError({ status: out.status });
+    const real = await _askTrackedReal(system, user, llmCfg, maxTokens, schema, options);
+    (0, llm_mock_js_1.saveFixture)(key, real);
+    (0, llm_mock_js_1.recordLlmCall)(real.usage, key, 'recorded');
+    return real;
+}
+async function _askTrackedReal(system, user, llmCfg, maxTokens = parseInt(process.env.AGENT_MAX_TOKENS ?? '4096', 10), schema, options) {
+    const provider = llmCfg?.provider ?? 'openai';
+    const model = llmCfg?.model ?? (core_1.config.llmModel || exports.DEFAULT_MODELS[provider]);
+    const apiKey = llmCfg?.apiKey ?? (provider === 'openai' ? (process.env.OPENAI_API_KEY ?? '') : '');
+    const baseUrl = llmCfg?.baseUrl ?? PROVIDER_BASE_URLS[provider];
+    if (provider === 'anthropic') {
+        if (!apiKey) {
+            throw new LLMProviderError('No AI provider configured. Go to Workspace → Settings → AI Provider to add your API key.');
+        }
+        try {
+            return await _askAnthropic(system, user, apiKey, model, maxTokens, schema, options);
+        }
+        catch (e) {
+            throw sanitizeProviderError(e);
+        }
+    }
+    if ((provider === 'bedrock' || provider === 'vertex') && !llmCfg?.baseUrl) {
+        throw new Error(`Provider "${provider}" requires a proxy base URL. Set the Base URL field in Workspace → Settings → AI Provider to a compatible endpoint (e.g., LiteLLM).`);
+    }
+    // Non-Anthropic providers: flatten multi-block system to a single string
+    const systemStr = Array.isArray(system) ? system.map(b => b.text).join('\n\n') : system;
+    try {
+        return await _askOpenAICompat(systemStr, user, provider, model, apiKey, baseUrl, maxTokens, schema, options);
+    }
+    catch (e) {
+        throw sanitizeProviderError(e);
+    }
+}
+async function ask(system, user, llmCfg, maxTokens = parseInt(process.env.AGENT_MAX_TOKENS ?? '4096', 10)) {
+    const res = await askTracked(system, user, llmCfg, maxTokens);
+    return res.text;
+}
+async function withRetry(fn, maxAttempts = parseInt(process.env.LLM_MAX_RETRIES ?? '') || 3) {
+    const retryBaseMs = parseInt(process.env.LLM_RETRY_BASE_MS ?? '') || 1000;
+    let lastErr;
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (e) {
+            const status = e?.status ?? e?.statusCode ?? 0;
+            const isRateLimit = status === 429 || status === 503;
+            // DNS failures (ENOTFOUND) are not transient — skip retries immediately.
+            const isDnsFailure = e?.cause?.code === 'ENOTFOUND' || e?.code === 'ENOTFOUND';
+            // APIConnectionTimeoutError = model took too long — don't retry (would waste another timeout window).
+            // Only retry on transient network errors (ETIMEDOUT = socket-level, not request-level) and rate limits.
+            const isConnErr = !isDnsFailure && status === 0 && (e?.code === 'ETIMEDOUT' || e?.cause?.code === 'ETIMEDOUT' || e?.constructor?.name === 'APIConnectionError');
+            if ((isRateLimit || isConnErr) && attempt < maxAttempts - 1) {
+                const delay = isRateLimit
+                    ? Math.pow(2, attempt) * retryBaseMs + Math.random() * 500
+                    : retryBaseMs * 2 + Math.random() * 1000;
+                await new Promise(r => setTimeout(r, delay));
+                lastErr = e;
+                continue;
+            }
+            throw e;
+        }
+    }
+    throw lastErr;
+}
+async function _askAnthropic(system, user, apiKey, model, maxTokens = parseInt(process.env.AGENT_MAX_TOKENS ?? '4096', 10), schema, askOptions) {
+    const client = new sdk_1.default({ apiKey, timeout: LLM_REQUEST_TIMEOUT_MS, maxRetries: 1 });
+    const systemBlocks = Array.isArray(system)
+        ? system.map(b => b.cache
+            ? { type: 'text', text: b.text, cache_control: { type: 'ephemeral' } }
+            : { type: 'text', text: b.text })
+        : [{ type: 'text', text: system, cache_control: { type: 'ephemeral' } }];
+    const options = {
+        model,
+        max_tokens: maxTokens,
+        ...(askOptions?.temperature != null ? { temperature: askOptions.temperature } : {}),
+        ...(askOptions?.topP != null ? { top_p: askOptions.topP } : {}),
+        // @ts-ignore: cache_control is supported in beta
+        system: systemBlocks,
+        messages: [{ role: 'user', content: user }],
+    };
+    if (schema) {
+        options.tools = [{
+                name: 'extract_data',
+                description: 'Extract or derive structured data',
+                input_schema: schema,
+            }];
+        options.tool_choice = { type: 'tool', name: 'extract_data' };
+    }
+    const res = (await withRetry(() => client.messages.create(options)));
+    let text = '';
+    if (schema) {
+        const toolCall = res.content.find((b) => b.type === 'tool_use');
+        if (toolCall) {
+            text = JSON.stringify(toolCall.input);
+        }
+        else {
+            text = res.content.map((b) => (b.type === 'text' ? b.text : '')).join('\n').trim();
+        }
+    }
+    else {
+        text = res.content.map((b) => (b.type === 'text' ? b.text : '')).join('\n').trim();
+    }
+    const u = res.usage;
+    const provider = 'anthropic';
+    const providerKey = `${provider}/${model}`;
+    const cacheReadTokens = u.cache_read_input_tokens ?? 0;
+    const cacheWriteTokens = u.cache_creation_input_tokens ?? 0;
+    const usage = {
+        provider, model,
+        promptTokens: u.input_tokens,
+        completionTokens: u.output_tokens,
+        cacheReadTokens,
+        cacheWriteTokens,
+        totalTokens: u.input_tokens + u.output_tokens,
+        estimatedCostUsd: (0, token_pricing_1.estimateCost)({ provider, model, promptTokens: u.input_tokens, completionTokens: u.output_tokens, cacheReadTokens, cacheWriteTokens, totalTokens: u.input_tokens + u.output_tokens }, providerKey),
+    };
+    return { text, usage };
+}
+async function _askOpenAICompat(system, user, provider, model, apiKey, baseUrl, maxTokens = parseInt(process.env.AGENT_MAX_TOKENS ?? '4096', 10), schema, askOptions) {
+    const effectiveKey = apiKey || (provider === 'ollama' ? 'ollama' : '');
+    if (!effectiveKey && provider !== 'ollama') {
+        throw new LLMProviderError(`API key for provider "${provider}" is not configured. Go to Workspace → Settings → AI Provider and re-enter your key.`);
+    }
+    const client = new openai_1.default({
+        apiKey: effectiveKey,
+        baseURL: baseUrl,
+        timeout: LLM_REQUEST_TIMEOUT_MS,
+        maxRetries: 1,
+        ...(provider === 'openrouter' && { defaultHeaders: { 'HTTP-Referer': APP_PUBLIC_URL, 'X-Title': APP_TITLE } }),
+    });
+    const systemContent = provider === 'openrouter'
+        ? [{ type: 'text', text: system, cache_control: { type: 'ephemeral' } }]
+        : system;
+    const options = {
+        model,
+        max_tokens: maxTokens,
+        ...(askOptions?.temperature != null ? { temperature: askOptions.temperature } : {}),
+        ...(askOptions?.topP != null ? { top_p: askOptions.topP } : {}),
+        ...(Number.isInteger(askOptions?.seed) ? { seed: askOptions?.seed } : {}),
+        messages: [
+            { role: 'system', content: systemContent },
+            { role: 'user', content: user },
+        ],
+    };
+    if (schema) {
+        options.tools = [{
+                type: 'function',
+                function: {
+                    name: 'extract_data',
+                    description: 'Extract or derive structured data',
+                    parameters: schema,
+                }
+            }];
+        options.tool_choice = { type: 'function', function: { name: 'extract_data' } };
+    }
+    const res = await withRetry(() => client.chat.completions.create(options));
+    let text = '';
+    if (schema) {
+        const toolCall = res.choices[0]?.message?.tool_calls?.[0];
+        if (toolCall?.function?.arguments) {
+            text = toolCall.function.arguments;
+        }
+        else {
+            text = res.choices[0]?.message?.content?.trim() ?? '';
+        }
+    }
+    else {
+        text = res.choices[0]?.message?.content?.trim() ?? '';
+    }
+    const u = res.usage ?? { prompt_tokens: 0, completion_tokens: 0, total_tokens: 0 };
+    const usage = {
+        provider, model,
+        promptTokens: u.prompt_tokens,
+        completionTokens: u.completion_tokens,
+        cacheReadTokens: 0,
+        cacheWriteTokens: 0,
+        totalTokens: u.total_tokens,
+        estimatedCostUsd: (0, token_pricing_1.estimateCost)({ provider, model, promptTokens: u.prompt_tokens, completionTokens: u.completion_tokens, cacheReadTokens: 0, cacheWriteTokens: 0, totalTokens: u.total_tokens }, `${provider}/${model}`),
+    };
+    return { text, usage };
+}

package/dist/nlp-agent.d.ts

@@ -0,0 +1,208 @@
+/**
+ * ZeTa-AI NLP Test Input Agent
+ *
+ * Converts plain-English test descriptions into structured, grounded test cases.
+ * Unlike competitors (testRigor, Functionize) this grounds the output in the
+ * Zeta Core — only uses elements that ACTUALLY EXIST on the real screen.
+ *
+ * Input:  "When a user logs in with valid credentials, they should see the dashboard"
+ * Output: A structured TestCase grounded in real elements, ready for review.
+ */
+import type { TestKind } from '@taodigital/core';
+export declare function convertNlpToTest(opts: {
+    tenantId: string;
+    projectId: string;
+    description: string;
+    suiteId?: string;
+}): Promise<{
+    error: string;
+    description: string;
+    id?: undefined;
+    ref?: undefined;
+    title?: undefined;
+    steps?: undefined;
+    expectedResult?: undefined;
+    confidence?: undefined;
+    understoodIntent?: undefined;
+    unmatchedTerms?: undefined;
+    testCase?: undefined;
+    saved?: undefined;
+    warning?: undefined;
+} | {
+    id: any;
+    ref: any;
+    title: string;
+    steps: string[];
+    expectedResult: string;
+    confidence: number;
+    understoodIntent: string;
+    unmatchedTerms: string[];
+    testCase: {
+        id: any;
+        ref: any;
+        screenId: string;
+        title: string;
+        kind: TestKind;
+        steps: string[];
+        expectedResult: string;
+        groundedOn: string[];
+    };
+    saved: {
+        suite: {
+            tenantId: string;
+            id: string;
+            projectId: string;
+            name: string;
+            createdAt: Date;
+            genModel: string | null;
+            category: import(".prisma/client").$Enums.SuiteCategory | null;
+            parentId: string | null;
+            ownerUserId: string | null;
+            genTotalTokens: number | null;
+            genTotalCostUsd: number | null;
+            genAt: Date | null;
+            genScreenCount: number | null;
+            coverageReport: import("@prisma/client/runtime/library").JsonValue | null;
+        };
+        testCases: {
+            tenantId: string;
+            screenId: string | null;
+            id: string;
+            projectId: string;
+            source: string;
+            status: string;
+            createdAt: Date;
+            updatedAt: Date;
+            steps: import("@prisma/client/runtime/library").JsonValue;
+            kind: string;
+            tags: import("@prisma/client/runtime/library").JsonValue;
+            approvedBy: string | null;
+            suiteId: string;
+            ref: string | null;
+            title: string;
+            priority: string;
+            preconditions: string | null;
+            expectedResult: string | null;
+            gherkin: string | null;
+            approvedAt: Date | null;
+            groundedOn: import("@prisma/client/runtime/library").JsonValue;
+            caseRefs: import("@prisma/client/runtime/library").JsonValue;
+            viewports: import("@prisma/client/runtime/library").JsonValue;
+            viewportConstraint: string;
+            techniqueOfRecord: string | null;
+            traceTo: string | null;
+            traceToExtra: import("@prisma/client/runtime/library").JsonValue;
+            testDataInline: import("@prisma/client/runtime/library").JsonValue | null;
+            dataNote: string | null;
+            scriptNote: string | null;
+            structuredSteps: import("@prisma/client/runtime/library").JsonValue | null;
+            artifactId: string | null;
+            scenarioId: string | null;
+            suspect: boolean;
+            suspectReason: string | null;
+            flakyScore: number;
+            consecutiveFlakes: number;
+            lastFlakyAt: Date | null;
+            quarantined: boolean;
+            quarantinedAt: Date | null;
+            quarantineReason: string | null;
+            genPromptTokens: number | null;
+            genCompletionTokens: number | null;
+            genCostUsd: number | null;
+            genModel: string | null;
+            dataSetId: string | null;
+            repoTargetPath: string | null;
+            stepsKey: string | null;
+            gherkinKey: string | null;
+            contentHash: string | null;
+            groundingHash: string | null;
+            locatorsJson: import("@prisma/client/runtime/library").JsonValue | null;
+            locatorsExtractedAt: Date | null;
+            captureStepScreenshots: import("@prisma/client/runtime/library").JsonValue | null;
+        }[];
+    } | {
+        tenantId: string;
+        screenId: string | null;
+        id: string;
+        projectId: string;
+        source: string;
+        status: string;
+        createdAt: Date;
+        updatedAt: Date;
+        steps: import("@prisma/client/runtime/library").JsonValue;
+        kind: string;
+        tags: import("@prisma/client/runtime/library").JsonValue;
+        approvedBy: string | null;
+        suiteId: string;
+        ref: string | null;
+        title: string;
+        priority: string;
+        preconditions: string | null;
+        expectedResult: string | null;
+        gherkin: string | null;
+        approvedAt: Date | null;
+        groundedOn: import("@prisma/client/runtime/library").JsonValue;
+        caseRefs: import("@prisma/client/runtime/library").JsonValue;
+        viewports: import("@prisma/client/runtime/library").JsonValue;
+        viewportConstraint: string;
+        techniqueOfRecord: string | null;
+        traceTo: string | null;
+        traceToExtra: import("@prisma/client/runtime/library").JsonValue;
+        testDataInline: import("@prisma/client/runtime/library").JsonValue | null;
+        dataNote: string | null;
+        scriptNote: string | null;
+        structuredSteps: import("@prisma/client/runtime/library").JsonValue | null;
+        artifactId: string | null;
+        scenarioId: string | null;
+        suspect: boolean;
+        suspectReason: string | null;
+        flakyScore: number;
+        consecutiveFlakes: number;
+        lastFlakyAt: Date | null;
+        quarantined: boolean;
+        quarantinedAt: Date | null;
+        quarantineReason: string | null;
+        genPromptTokens: number | null;
+        genCompletionTokens: number | null;
+        genCostUsd: number | null;
+        genModel: string | null;
+        dataSetId: string | null;
+        repoTargetPath: string | null;
+        stepsKey: string | null;
+        gherkinKey: string | null;
+        contentHash: string | null;
+        groundingHash: string | null;
+        locatorsJson: import("@prisma/client/runtime/library").JsonValue | null;
+        locatorsExtractedAt: Date | null;
+        captureStepScreenshots: import("@prisma/client/runtime/library").JsonValue | null;
+    };
+    warning: string | undefined;
+    error?: undefined;
+    description?: undefined;
+}>;
+export interface ExtractedLocator {
+    key: string;
+    expression: string;
+    elementType: string;
+    confidence: 'high' | 'medium' | 'low';
+    source: string;
+    description: string;
+}
+/**
+ * Use an LLM to extract Playwright locators from test case steps of any format.
+ * Handles structured (QA Wolf), plain-English (AI-generated), or mixed step formats.
+ * Falls back to empty array if no LLM is configured or extraction fails.
+ */
+export declare function extractLocatorsWithLLM(opts: {
+    tenantId: string;
+    steps: Array<Record<string, unknown> | string>;
+    dataFields?: Array<{
+        fieldKey: string;
+        exampleValue: string;
+    }>;
+    tcContext?: {
+        title?: string;
+        gherkin?: string;
+        preconditions?: string;
+    };
+}): Promise<ExtractedLocator[]>;