@graphext/cuery 0.4.0 → 0.5.2

package/script/src/providers/pricing.js

@@ -0,0 +1,97 @@
+"use strict";
+/**
+ * Model pricing lookup and cost calculation.
+ *
+ * Pricing data is bundled from models.dev at build time.
+ * Run `deno task update-models` to refresh the data.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.lookupModel = lookupModel;
+exports.getModelPricing = getModelPricing;
+exports.getModelInfo = getModelInfo;
+exports.calculateCost = calculateCost;
+const models_js_1 = __importDefault(require("../assets/models.js"));
+// Build flat index: model ID -> { provider, model }
+const modelIndex = new Map();
+for (const [providerId, provider] of Object.entries(models_js_1.default)) {
+    if (!provider.models)
+        continue;
+    for (const [modelId, model] of Object.entries(provider.models)) {
+        modelIndex.set(modelId, { provider: providerId, model });
+    }
+}
+/**
+ * Normalize a model ID by removing date suffixes and common variations.
+ */
+function normalizeModel(modelId) {
+    return modelId.replace(/-\d{4}-\d{2}-\d{2}$/, '');
+}
+/**
+ * Look up a model entry by ID (with normalization fallback).
+ */
+function lookupModel(modelId) {
+    return modelIndex.get(modelId) ?? modelIndex.get(normalizeModel(modelId)) ?? null;
+}
+/**
+ * Get pricing information for a model.
+ */
+function getModelPricing(modelId) {
+    const entry = lookupModel(modelId);
+    if (!entry?.model.cost) {
+        return null;
+    }
+    const cost = entry.model.cost;
+    if (cost.input === 0 && cost.output === 0) {
+        return null;
+    }
+    return {
+        input: cost.input ?? 0,
+        output: cost.output ?? 0,
+        cacheRead: cost.cache_read,
+        cacheWrite: cost.cache_write,
+        reasoning: cost.reasoning,
+    };
+}
+/**
+ * Get full model information including pricing and capabilities.
+ */
+function getModelInfo(modelId) {
+    const entry = lookupModel(modelId);
+    if (!entry) {
+        return null;
+    }
+    const { provider, model: m } = entry;
+    return {
+        id: m.id,
+        name: m.name,
+        provider,
+        pricing: getModelPricing(modelId),
+        contextLimit: m.limit?.context ?? null,
+        outputLimit: m.limit?.output ?? null,
+        capabilities: {
+            structuredOutput: m.structured_output ?? false,
+            toolCall: m.tool_call ?? false,
+            reasoning: m.reasoning ?? false,
+        },
+    };
+}
+/**
+ * Calculate cost for token usage.
+ */
+function calculateCost(modelId, usage) {
+    const pricing = getModelPricing(modelId);
+    if (!pricing) {
+        return null;
+    }
+    const inputCost = (usage.inputTokens / 1_000_000) * pricing.input;
+    const outputCost = (usage.outputTokens / 1_000_000) * pricing.output;
+    return {
+        inputCost,
+        outputCost,
+        totalCost: inputCost + outputCost,
+        currency: 'USD',
+    };
+}

package/script/src/providers/registry.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Provider registry - instantiates LLM providers by name or model ID.
+ */
+import type { LLMProvider } from './types.js';
+/**
+ * Get a provider by name.
+ * Creates a fresh provider instance each time to support different API keys.
+ * @param name - Provider name ('openai', 'google')
+ * @param apiKey - Optional API key. If not provided, uses environment variable.
+ */
+export declare function getProvider(name: string, apiKey?: string): LLMProvider;
+/**
+ * Get the appropriate provider for a model ID.
+ * Infers provider from model name prefix.
+ * Creates a fresh provider instance each time to support different API keys.
+ * @param modelId - Model identifier (e.g., 'gpt-4.1', 'gemini-2.0-flash')
+ * @param apiKey - Optional API key. If not provided, uses environment variable.
+ */
+export declare function getProviderForModel(modelId: string, apiKey?: string): LLMProvider;
+//# sourceMappingURL=registry.d.ts.map

package/script/src/providers/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../src/src/providers/registry.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAI9C;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,WAAW,CAQtE;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,WAAW,CASjF"}

package/script/src/providers/registry.js

@@ -0,0 +1,39 @@
+"use strict";
+/**
+ * Provider registry - instantiates LLM providers by name or model ID.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getProvider = getProvider;
+exports.getProviderForModel = getProviderForModel;
+const openai_js_1 = require("./openai.js");
+const google_js_1 = require("./google.js");
+/**
+ * Get a provider by name.
+ * Creates a fresh provider instance each time to support different API keys.
+ * @param name - Provider name ('openai', 'google')
+ * @param apiKey - Optional API key. If not provided, uses environment variable.
+ */
+function getProvider(name, apiKey) {
+    switch (name) {
+        case 'google':
+            return new google_js_1.GoogleProvider(apiKey);
+        case 'openai':
+        default:
+            return new openai_js_1.OpenAIProvider(apiKey);
+    }
+}
+/**
+ * Get the appropriate provider for a model ID.
+ * Infers provider from model name prefix.
+ * Creates a fresh provider instance each time to support different API keys.
+ * @param modelId - Model identifier (e.g., 'gpt-4.1', 'gemini-2.0-flash')
+ * @param apiKey - Optional API key. If not provided, uses environment variable.
+ */
+function getProviderForModel(modelId, apiKey) {
+    const modelLower = modelId.toLowerCase();
+    if (modelLower.startsWith('gemini')) {
+        return new google_js_1.GoogleProvider(apiKey);
+    }
+    // Default to OpenAI for gpt-*, o1-*, o3-*, and unknown models
+    return new openai_js_1.OpenAIProvider(apiKey);
+}

package/script/src/providers/types.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Core LLM types - provider-agnostic interfaces.
+ *
+ * This module is the foundation of the provider system.
+ * It has no dependencies on other modules to avoid circular imports.
+ */
+import type { z } from '../../deps/jsr.io/@zod/zod/4.3.6/src/index.js';
+import type { TokenUsage } from '../response.js';
+/**
+ * A message in an LLM conversation.
+ */
+export interface Message {
+    role: 'system' | 'user' | 'assistant';
+    content: string;
+}
+/**
+ * Response from an LLM provider.
+ */
+export interface LLMResponse<T> {
+    parsed: T | null;
+    text: string | null;
+    usage: TokenUsage | null;
+    error: Error | null;
+}
+/**
+ * Provider-specific parameters passed through to the underlying API.
+ */
+export type ProviderParams = Record<string, unknown>;
+/**
+ * Interface for LLM providers.
+ */
+export interface LLMProvider {
+    /** Provider name (e.g., 'openai', 'gemini') */
+    readonly name: string;
+    /**
+     * Make a completion request to the LLM.
+     *
+     * @param messages - The conversation messages
+     * @param model - The model identifier
+     * @param schema - Optional Zod schema for structured output
+     * @param params - Provider-specific parameters
+     */
+    complete<T>(messages: Message[], model: string, schema: z.ZodType<T> | null, params?: ProviderParams): Promise<LLMResponse<T>>;
+}
+/**
+ * Conversation type (array of messages).
+ */
+export type LLMConversation = Message[];
+//# sourceMappingURL=types.d.ts.map

package/script/src/providers/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/src/providers/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,+CAA+C,CAAC;AACvE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAEjD;;GAEG;AACH,MAAM,WAAW,OAAO;IACvB,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;IACtC,OAAO,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW,CAAC,CAAC;IAC7B,MAAM,EAAE,CAAC,GAAG,IAAI,CAAC;IACjB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,KAAK,EAAE,UAAU,GAAG,IAAI,CAAC;IACzB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAErD;;GAEG;AACH,MAAM,WAAW,WAAW;IAC3B,+CAA+C;IAC/C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB;;;;;;;OAOG;IACH,QAAQ,CAAC,CAAC,EACT,QAAQ,EAAE,OAAO,EAAE,EACnB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,IAAI,EAC3B,MAAM,CAAC,EAAE,cAAc,GACrB,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG,OAAO,EAAE,CAAC"}

package/script/src/providers/types.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * Core LLM types - provider-agnostic interfaces.
+ *
+ * This module is the foundation of the provider system.
+ * It has no dependencies on other modules to avoid circular imports.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/script/src/response.d.ts

@@ -0,0 +1,74 @@
+/**
+ * BatchResponse - A wrapper for batch LLM results with usage tracking.
+ *
+ * Provides an array-like interface for backwards compatibility while
+ * adding usage aggregation capabilities.
+ */
+/**
+ * Token usage from a single LLM call.
+ */
+export interface TokenUsage {
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+}
+/**
+ * Cost calculation result in USD.
+ */
+export interface UsageCost {
+    inputCost: number;
+    outputCost: number;
+    totalCost: number;
+    currency: 'USD';
+}
+/**
+ * Aggregated usage across multiple LLM calls.
+ */
+export interface AggregatedUsage {
+    tokens: TokenUsage;
+    cost: UsageCost | null;
+    callCount: number;
+    model: string | null;
+}
+/**
+ * A batch of LLM results with usage tracking.
+ *
+ * Implements Iterable<T> and provides array-like methods for backwards
+ * compatibility with code expecting Array<T>.
+ */
+export declare class BatchResponse<T> implements Iterable<T> {
+    readonly results: ReadonlyArray<T>;
+    private readonly _tokenUsages;
+    private readonly _model;
+    constructor(results: T[], tokenUsages?: Array<TokenUsage | null | undefined>, model?: string);
+    get length(): number;
+    [Symbol.iterator](): Iterator<T>;
+    at(index: number): T | undefined;
+    map<U>(fn: (value: T, index: number) => U): BatchResponse<U>;
+    filter(fn: (value: T, index: number) => boolean): BatchResponse<T>;
+    forEach(fn: (value: T, index: number) => void): void;
+    find(fn: (value: T, index: number) => boolean): T | undefined;
+    findIndex(fn: (value: T, index: number) => boolean): number;
+    some(fn: (value: T, index: number) => boolean): boolean;
+    every(fn: (value: T, index: number) => boolean): boolean;
+    reduce<U>(fn: (acc: U, value: T, index: number) => U, initial: U): U;
+    /**
+     * Convert to a plain array.
+     */
+    toArray(): T[];
+    /**
+     * Get aggregated usage across all calls in this batch.
+     * Cost is calculated lazily only if model and costCalculator were provided.
+     * Returns null if usage tracking was not enabled.
+     */
+    usage(): AggregatedUsage | null;
+    /**
+     * Get token usage for a specific index.
+     */
+    usageAt(index: number): TokenUsage | undefined;
+    /**
+     * Check if any usage info is available.
+     */
+    hasUsage(): boolean;
+}
+//# sourceMappingURL=response.d.ts.map

package/script/src/response.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"response.d.ts","sourceRoot":"","sources":["../../src/src/response.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH;;GAEG;AACH,MAAM,WAAW,UAAU;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,KAAK,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC/B,MAAM,EAAE,UAAU,CAAC;IACnB,IAAI,EAAE,SAAS,GAAG,IAAI,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACrB;AAED;;;;;GAKG;AACH,qBAAa,aAAa,CAAC,CAAC,CAAE,YAAW,QAAQ,CAAC,CAAC,CAAC;IACnD,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,CAAC;IACnC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAuC;IACpE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgB;gBAGtC,OAAO,EAAE,CAAC,EAAE,EACZ,WAAW,CAAC,EAAE,KAAK,CAAC,UAAU,GAAG,IAAI,GAAG,SAAS,CAAC,EAClD,KAAK,CAAC,EAAE,MAAM;IAUf,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,QAAQ,CAAC,CAAC,CAAC;IAIhC,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS;IAIhC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC;IAK5D,MAAM,CAAC,EAAE,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,GAAG,aAAa,CAAC,CAAC,CAAC;IAclE,OAAO,CAAC,EAAE,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI;IAIpD,IAAI,CAAC,EAAE,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,GAAG,CAAC,GAAG,SAAS;IAI7D,SAAS,CAAC,EAAE,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,GAAG,MAAM;IAI3D,IAAI,CAAC,EAAE,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,GAAG,OAAO;IAIvD,KAAK,CAAC,EAAE,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,GAAG,OAAO;IAIxD,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,CAAC,EAAE,OAAO,EAAE,CAAC,GAAG,CAAC;IAIpE;;OAEG;IACH,OAAO,IAAI,CAAC,EAAE;IAMd;;;;OAIG;IACH,KAAK,IAAI,eAAe,GAAG,IAAI;IAwB/B;;OAEG;IACH,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;IAI9C;;OAEG;IACH,QAAQ,IAAI,OAAO;CAGnB"}

package/script/src/response.js

@@ -0,0 +1,114 @@
+"use strict";
+/**
+ * BatchResponse - A wrapper for batch LLM results with usage tracking.
+ *
+ * Provides an array-like interface for backwards compatibility while
+ * adding usage aggregation capabilities.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BatchResponse = void 0;
+const pricing_js_1 = require("./providers/pricing.js");
+/**
+ * A batch of LLM results with usage tracking.
+ *
+ * Implements Iterable<T> and provides array-like methods for backwards
+ * compatibility with code expecting Array<T>.
+ */
+class BatchResponse {
+    results;
+    _tokenUsages;
+    _model;
+    constructor(results, tokenUsages, model) {
+        this.results = results;
+        // Normalize null to undefined for internal storage, or null if not provided
+        this._tokenUsages = tokenUsages ? tokenUsages.map(u => u ?? undefined) : null;
+        this._model = model ?? null;
+    }
+    // Array-like interface
+    get length() {
+        return this.results.length;
+    }
+    [Symbol.iterator]() {
+        return this.results[Symbol.iterator]();
+    }
+    at(index) {
+        return this.results.at(index);
+    }
+    map(fn) {
+        const mapped = this.results.map((item, i) => fn(item, i));
+        return new BatchResponse(mapped, this._tokenUsages ?? undefined, this._model ?? undefined);
+    }
+    filter(fn) {
+        const filtered = [];
+        const usages = this._tokenUsages ? [] : undefined;
+        this.results.forEach((item, i) => {
+            if (fn(item, i)) {
+                filtered.push(item);
+                usages?.push(this._tokenUsages[i]);
+            }
+        });
+        return new BatchResponse(filtered, usages, this._model ?? undefined);
+    }
+    forEach(fn) {
+        this.results.forEach(fn);
+    }
+    find(fn) {
+        return this.results.find(fn);
+    }
+    findIndex(fn) {
+        return this.results.findIndex(fn);
+    }
+    some(fn) {
+        return this.results.some(fn);
+    }
+    every(fn) {
+        return this.results.every(fn);
+    }
+    reduce(fn, initial) {
+        return this.results.reduce(fn, initial);
+    }
+    /**
+     * Convert to a plain array.
+     */
+    toArray() {
+        return [...this.results];
+    }
+    // Usage tracking
+    /**
+     * Get aggregated usage across all calls in this batch.
+     * Cost is calculated lazily only if model and costCalculator were provided.
+     * Returns null if usage tracking was not enabled.
+     */
+    usage() {
+        if (!this._tokenUsages) {
+            return null;
+        }
+        const valid = this._tokenUsages.filter((u) => u !== undefined);
+        const aggregatedTokens = {
+            inputTokens: valid.reduce((sum, u) => sum + u.inputTokens, 0),
+            outputTokens: valid.reduce((sum, u) => sum + u.outputTokens, 0),
+            totalTokens: valid.reduce((sum, u) => sum + u.totalTokens, 0),
+        };
+        // Calculate cost if we have a model
+        const cost = this._model ? (0, pricing_js_1.calculateCost)(this._model, aggregatedTokens) : null;
+        return {
+            tokens: aggregatedTokens,
+            cost,
+            callCount: valid.length,
+            model: this._model,
+        };
+    }
+    /**
+     * Get token usage for a specific index.
+     */
+    usageAt(index) {
+        return this._tokenUsages?.[index];
+    }
+    /**
+     * Check if any usage info is available.
+     */
+    hasUsage() {
+        return this._tokenUsages?.some((u) => u !== undefined) ?? false;
+    }
+}
+exports.BatchResponse = BatchResponse;

package/script/src/tool.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Tool abstraction for LLM-powered operations.
+ *
+ * Provides a base class for building tools with consistent
+ * single-item and batch processing, usage tracking, and error handling.
+ */
+import type { z } from '../deps/jsr.io/@zod/zod/4.3.6/src/index.js';
+import { type LLMResponse, type Message, type ProviderParams } from './llm.js';
+import { BatchResponse } from './response.js';
+/**
+ * Configuration for LLM calls. Can be overridden per-invocation.
+ */
+export interface ModelConfig {
+    /** The model to use */
+    model: string;
+    /** Provider-specific parameters */
+    modelParams?: ProviderParams;
+    /** Maximum retry attempts (default: 3) */
+    maxRetries?: number;
+    /** Max concurrent requests for batch (default: 100) */
+    maxConcurrency?: number;
+    /** Enable cost tracking for batch (default: false) */
+    trackCost?: boolean;
+    /** Throw an error instead of returning null on failure (default: false) */
+    throwOnFailure?: boolean;
+}
+/**
+ * Abstract base class for LLM-powered tools.
+ */
+export declare abstract class Tool<TInput, TOutput, TResult = TOutput> {
+    protected readonly modelConfig: ModelConfig;
+    constructor(modelConfig: ModelConfig);
+    /**
+     * Define the Zod schema for LLM response validation.
+     * Override this to provide structured output validation.
+     *
+     * Returns null by default for raw text mode.
+     * When returning null, TOutput must be `string`.
+     *
+     * Make this as cheap as possible, as it's called on every invocation (row).
+     * E.g. by preparing it in the constructor if it doesn't depend on input.
+     */
+    protected schema(): z.ZodType<TOutput> | null;
+    /** Build the prompt from a single input
+     * Make this as cheap as possible, as it's called on every invocation (row).
+     * E.g. by preparing it in the constructor if it doesn't depend on input.
+    */
+    protected abstract prompt(input: TInput): string | Message[];
+    /** Extract final result from parsed output. Override to transform. */
+    protected extractResult(parsed: TOutput): TResult;
+    /** Check if input should be skipped (returns null without LLM call) */
+    protected isEmpty(input: TInput): boolean;
+    /** Process a single input */
+    invoke(input: TInput, options?: Partial<ModelConfig>): Promise<LLMResponse<TResult | null>>;
+    /** Process multiple inputs with usage tracking */
+    batch(inputs: TInput[], options?: Partial<ModelConfig>): Promise<BatchResponse<TResult | null>>;
+}
+//# sourceMappingURL=tool.d.ts.map

package/script/src/tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool.d.ts","sourceRoot":"","sources":["../../src/src/tool.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,4CAA4C,CAAC;AACpE,OAAO,EAAc,KAAK,WAAW,EAAE,KAAK,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,UAAU,CAAC;AAE3F,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAE9C;;GAEG;AACH,MAAM,WAAW,WAAW;IAC3B,uBAAuB;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,mCAAmC;IACnC,WAAW,CAAC,EAAE,cAAc,CAAC;IAC7B,0CAA0C;IAC1C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,uDAAuD;IACvD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,sDAAsD;IACtD,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,2EAA2E;IAC3E,cAAc,CAAC,EAAE,OAAO,CAAC;CACzB;AASD;;GAEG;AACH,8BAAsB,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO;IAC5D,SAAS,CAAC,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;gBAEhC,WAAW,EAAE,WAAW;IAIpC;;;;;;;;;OASG;IACH,SAAS,CAAC,MAAM,IAAI,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI;IAI7C;;;MAGE;IACF,SAAS,CAAC,QAAQ,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,EAAE;IAE5D,sEAAsE;IACtE,SAAS,CAAC,aAAa,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO;IAIjD,uEAAuE;IACvE,SAAS,CAAC,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IAOzC,6BAA6B;IACvB,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,OAAO,CAAC,WAAW,CAAM,GAAG,OAAO,CAAC,WAAW,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC;IAmCrG,kDAAkD;IAC5C,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,OAAO,CAAC,WAAW,CAAM,GAAG,OAAO,CAAC,aAAa,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC;CAiBzG"}

package/script/src/tool.js

@@ -0,0 +1,95 @@
+"use strict";
+/**
+ * Tool abstraction for LLM-powered operations.
+ *
+ * Provides a base class for building tools with consistent
+ * single-item and batch processing, usage tracking, and error handling.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Tool = void 0;
+const llm_js_1 = require("./llm.js");
+const async_js_1 = require("./helpers/async.js");
+const response_js_1 = require("./response.js");
+const DEFAULTS = {
+    maxRetries: 3,
+    maxConcurrency: 100,
+    trackCost: false,
+    throwOnFailure: false,
+};
+/**
+ * Abstract base class for LLM-powered tools.
+ */
+class Tool {
+    modelConfig;
+    constructor(modelConfig) {
+        this.modelConfig = modelConfig;
+    }
+    /**
+     * Define the Zod schema for LLM response validation.
+     * Override this to provide structured output validation.
+     *
+     * Returns null by default for raw text mode.
+     * When returning null, TOutput must be `string`.
+     *
+     * Make this as cheap as possible, as it's called on every invocation (row).
+     * E.g. by preparing it in the constructor if it doesn't depend on input.
+     */
+    schema() {
+        return null;
+    }
+    /** Extract final result from parsed output. Override to transform. */
+    extractResult(parsed) {
+        return parsed;
+    }
+    /** Check if input should be skipped (returns null without LLM call) */
+    isEmpty(input) {
+        if (input == null)
+            return true;
+        if (typeof input === 'string' && input.trim() === '')
+            return true;
+        if (typeof input === 'object' && Object.keys(input).length === 0)
+            return true;
+        return false;
+    }
+    /** Process a single input */
+    async invoke(input, options = {}) {
+        if (this.isEmpty(input)) {
+            return { parsed: null, text: null, usage: null, error: null };
+        }
+        const { model, modelParams, maxRetries, throwOnFailure } = { ...DEFAULTS, ...this.modelConfig, ...options };
+        const response = await (0, llm_js_1.askLLMSafe)({
+            prompt: this.prompt(input),
+            model,
+            schema: this.schema(),
+            params: modelParams,
+            maxRetries,
+            onError: 'return',
+        });
+        if (response.error != null || response.parsed == null) {
+            if (throwOnFailure) {
+                throw response.error ?? new Error('LLM call failed to produce a result');
+            }
+            return { parsed: null, text: response.text, usage: response.usage, error: response.error };
+        }
+        // Type assertion: when schema() returns null, askLLMSafe returns string,
+        // which should match TOutput (caller's responsibility to set TOutput = string)
+        const parsed = response.parsed;
+        return {
+            parsed: this.extractResult(parsed),
+            text: response.text,
+            usage: response.usage,
+            error: null,
+        };
+    }
+    /** Process multiple inputs with usage tracking */
+    async batch(inputs, options = {}) {
+        const { model, modelParams, maxRetries, maxConcurrency, trackCost } = {
+            ...DEFAULTS,
+            ...this.modelConfig,
+            ...options,
+        };
+        const responses = await (0, async_js_1.mapParallel)(inputs, maxConcurrency, (input) => this.invoke(input, { model, modelParams, maxRetries }));
+        return new response_js_1.BatchResponse(responses.map((r) => r.parsed), trackCost ? responses.map((r) => r.usage) : undefined, trackCost ? model : undefined);
+    }
+}
+exports.Tool = Tool;

package/script/src/tools/brands.js

@@ -11,12 +11,12 @@ exports.createBrandMatchKey = createBrandMatchKey;
 exports.rankBrandsInText = rankBrandsInText;
 exports.rankBrandsInTexts = rankBrandsInTexts;
 const index_js_1 = require("../../deps/jsr.io/@zod/zod/4.3.6/src/index.js");
-const async_js_1 = require("../async.js");
-const openai_js_1 = require("../openai.js");
+const async_js_1 = require("../helpers/async.js");
+const llm_js_1 = require("../llm.js");
 const brand_schema_js_1 = require("../schemas/brand.schema.js");
 const search_js_1 = require("./search.js");
-const utils_js_1 = require("../utils.js");
-const urls_js_1 = require("../urls.js");
+const utils_js_1 = require("../helpers/utils.js");
+const urls_js_1 = require("../helpers/urls.js");
 function buildBrandContext({ brand, brandDomain, sector, market, briefing }) {
     let brandContext;
     if (brandDomain) {
@@ -160,9 +160,9 @@ async function generatePortfolioKeywords(product, sector, market, language = 'en
         .replaceAll('{sector}', sector)
         .replaceAll('{market}', market)
         .replaceAll('{language}', language);
-    const { parsed } = await (0, openai_js_1.askOpenAISafe)(prompt, model, PortfolioKeywordsSchema);
+    const { parsed } = await (0, llm_js_1.askLLMSafe)({ prompt, model, schema: PortfolioKeywordsSchema });
     if (!parsed) {
-        throw new Error('Failed to parse portfolio keywords from OpenAI response');
+        throw new Error('Failed to parse portfolio keywords from LLM response');
     }
     return parsed.keywords;
 }