@graphext/cuery 0.4.0 → 0.5.2

package/esm/src/providers/registry.js

@@ -0,0 +1,35 @@
+/**
+ * Provider registry - instantiates LLM providers by name or model ID.
+ */
+import { OpenAIProvider } from './openai.js';
+import { GoogleProvider } from './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.
+ */
+export function getProvider(name, apiKey) {
+    switch (name) {
+        case 'google':
+            return new GoogleProvider(apiKey);
+        case 'openai':
+        default:
+            return new 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.
+ */
+export function getProviderForModel(modelId, apiKey) {
+    const modelLower = modelId.toLowerCase();
+    if (modelLower.startsWith('gemini')) {
+        return new GoogleProvider(apiKey);
+    }
+    // Default to OpenAI for gpt-*, o1-*, o3-*, and unknown models
+    return new OpenAIProvider(apiKey);
+}

package/esm/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/esm/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/esm/src/providers/types.js

@@ -0,0 +1,7 @@
+/**
+ * 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.
+ */
+export {};

package/esm/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/esm/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/esm/src/response.js

@@ -0,0 +1,110 @@
+/**
+ * BatchResponse - A wrapper for batch LLM results with usage tracking.
+ *
+ * Provides an array-like interface for backwards compatibility while
+ * adding usage aggregation capabilities.
+ */
+import { calculateCost } from './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>.
+ */
+export 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 ? 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;
+    }
+}

package/esm/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/esm/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/esm/src/tool.js

@@ -0,0 +1,91 @@
+/**
+ * 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 { askLLMSafe } from './llm.js';
+import { mapParallel } from './helpers/async.js';
+import { BatchResponse } from './response.js';
+const DEFAULTS = {
+    maxRetries: 3,
+    maxConcurrency: 100,
+    trackCost: false,
+    throwOnFailure: false,
+};
+/**
+ * Abstract base class for LLM-powered tools.
+ */
+export 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 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 mapParallel(inputs, maxConcurrency, (input) => this.invoke(input, { model, modelParams, maxRetries }));
+        return new BatchResponse(responses.map((r) => r.parsed), trackCost ? responses.map((r) => r.usage) : undefined, trackCost ? model : undefined);
+    }
+}

package/esm/src/tools/brands.js

@@ -1,10 +1,10 @@
 import { z } from '../../deps/jsr.io/@zod/zod/4.3.6/src/index.js';
-import { mapParallel } from '../async.js';
-import { askOpenAISafe } from '../openai.js';
+import { mapParallel } from '../helpers/async.js';
+import { askLLMSafe } from '../llm.js';
 import { BrandSchema, BrandListSchema } from '../schemas/brand.schema.js';
 import { searchWithFormat } from './search.js';
-import { dedent } from '../utils.js';
-import { extractDomain } from '../urls.js';
+import { dedent } from '../helpers/utils.js';
+import { extractDomain } from '../helpers/urls.js';
 export function buildBrandContext({ brand, brandDomain, sector, market, briefing }) {
     let brandContext;
     if (brandDomain) {
@@ -148,9 +148,9 @@ export async function generatePortfolioKeywords(product, sector, market, languag
         .replaceAll('{sector}', sector)
         .replaceAll('{market}', market)
         .replaceAll('{language}', language);
-    const { parsed } = await askOpenAISafe(prompt, model, PortfolioKeywordsSchema);
+    const { parsed } = await 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;
 }

package/esm/src/tools/classifier.d.ts

@@ -1,34 +1,97 @@
-import { type AIParams } from '../openai.js';
+import { z } from '../../deps/jsr.io/@zod/zod/4.3.6/src/index.js';
+import { Tool, type ModelConfig } from '../tool.js';
+interface ClassifierConfig {
+    /** Map of label names to descriptions */
+    labels: Record<string, string>;
+    /** Additional instructions for the classifier */
+    instructions?: string;
+}
 /**
- * Classifies a single data record into one of the provided categories using an LLM call.
+ * A tool that classifies records into one of the provided categories.
  */
-export declare function classify(record: Record<string, unknown> | null, labels: Record<string, string>, instructions?: string, model?: string): Promise<string | null>;
+export declare class Classifier extends Tool<Record<string, unknown> | null, {
+    label: string;
+}, string> {
+    private readonly labelSchema;
+    private readonly promptTemplate;
+    constructor(config: ClassifierConfig, modelConfig: ModelConfig);
+    protected schema(): z.ZodObject<{
+        label: z.ZodLiteral<string>;
+    }, z.core.$strip> | z.ZodObject<{
+        label: z.ZodUnion<[z.ZodLiteral<string>, z.ZodLiteral<string>, ...z.ZodLiteral<string>[]]>;
+    }, z.core.$strip>;
+    protected prompt(record: Record<string, unknown> | null): string;
+    protected extractResult(parsed: {
+        label: string;
+    }): string;
+}
 /**
- * Classifies multiple data records concurrently while preserving order.
+ * Configuration for the Labeler tool.
  */
-export declare function classifyBatch(records: Array<Record<string, unknown> | null>, labels: Record<string, string>, instructions?: string, model?: string, maxConcurrency?: number): Promise<Array<string | null>>;
+export interface LabelerConfig {
+    /** Map of label names to descriptions */
+    labels: Record<string, string>;
+    /** Additional instructions for the labeler */
+    instructions?: string;
+}
 /**
- * Assigns one or more labels to a single data record using an LLM call.
+ * A tool that assigns one or more labels to records from provided options.
  */
-export declare function label(record: Record<string, unknown> | null, labels: Record<string, string>, instructions?: string, model?: string): Promise<Array<string> | null>;
+export declare class Labeler extends Tool<Record<string, unknown> | null, {
+    labels: Array<string>;
+}, Array<string>> {
+    private readonly multiLabelSchema;
+    private readonly promptTemplate;
+    constructor(config: LabelerConfig, modelConfig: ModelConfig);
+    protected schema(): z.ZodObject<{
+        labels: z.ZodArray<z.ZodLiteral<string> | z.ZodUnion<[z.ZodLiteral<string>, z.ZodLiteral<string>, ...z.ZodLiteral<string>[]]>>;
+    }, z.core.$strip>;
+    protected prompt(record: Record<string, unknown> | null): string;
+    protected extractResult(parsed: {
+        labels: Array<string>;
+    }): string[];
+}
 /**
- * Assigns labels to multiple data records concurrently while preserving order.
+ * Configuration for the LabelExtractor tool.
  */
-export declare function labelBatch(records: Array<Record<string, unknown> | null>, labels: Record<string, string>, instructions?: string, model?: string, maxConcurrency?: number): Promise<Array<Array<string> | null>>;
-export interface LabelExtractionOptions {
-    records: Array<Record<string, unknown>>;
+export interface LabelExtractorConfig {
+    /** Maximum number of labels to extract (default: 10) */
     nLabels?: number;
+    /** Additional instructions for label extraction */
     instructions?: string;
+    /** Maximum number of records to sample (default: 500) */
     maxSamples?: number;
-    model?: string;
-    modelParams?: AIParams;
-    maxRetries?: number;
+    /** Language for labels and descriptions (default: same as records) */
     language?: string;
 }
 /**
- * Extracts a set of classification labels from an array of records using an LLM.
+ * A tool that extracts classification labels from a set of records.
  * Returns a Record<string, string> mapping label names to descriptions,
- * which can be used directly with classify() and classifyBatch().
+ * which can be used directly with Classifier and Labeler.
  */
-export declare function extractLabels({ records, nLabels, instructions, maxSamples, model, modelParams, maxRetries, language }: LabelExtractionOptions): Promise<Record<string, string>>;
+export declare class LabelExtractor extends Tool<Array<Record<string, unknown>>, {
+    labels: Array<{
+        name: string;
+        description: string;
+    }>;
+}, Record<string, string>> {
+    private readonly maxSamples;
+    private readonly promptTemplate;
+    constructor(config: LabelExtractorConfig | undefined, modelConfig: ModelConfig);
+    protected schema(): z.ZodObject<{
+        labels: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            description: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    protected prompt(records: Array<Record<string, unknown>>): string;
+    protected isEmpty(records: Array<Record<string, unknown>>): boolean;
+    protected extractResult(parsed: {
+        labels: Array<{
+            name: string;
+            description: string;
+        }>;
+    }): Record<string, string>;
+}
+export {};
 //# sourceMappingURL=classifier.d.ts.map

package/esm/src/tools/classifier.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"classifier.d.ts","sourceRoot":"","sources":["../../../src/src/tools/classifier.ts"],"names":[],"mappings":"AAEA,OAAO,EAAiB,KAAK,QAAQ,EAAE,MAAM,cAAc,CAAC;AAoG5D;;GAEG;AACH,wBAAsB,QAAQ,CAC7B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,EACtC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC9B,YAAY,GAAE,MAAW,EACzB,KAAK,GAAE,MAAuB,GAC5B,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAiBxB;AAED;;GAEG;AACH,wBAAgB,aAAa,CAC5B,OAAO,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC,EAC9C,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC9B,YAAY,GAAE,MAAW,EACzB,KAAK,GAAE,MAAuB,EAC9B,cAAc,GAAE,MAAY,GAC1B,OAAO,CAAC,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC,CAM/B;AAED;;GAEG;AACH,wBAAsB,KAAK,CAC1B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,EACtC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC9B,YAAY,GAAE,MAAW,EACzB,KAAK,GAAE,MAAuB,GAC5B,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC,CAiB/B;AAED;;GAEG;AACH,wBAAgB,UAAU,CACzB,OAAO,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC,EAC9C,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC9B,YAAY,GAAE,MAAW,EACzB,KAAK,GAAE,MAAuB,EAC9B,cAAc,GAAE,MAAY,GAC1B,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC,CAAC,CAMtC;AA4CD,MAAM,WAAW,sBAAsB;IACtC,OAAO,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACxC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,QAAQ,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;GAIG;AACH,wBAAsB,aAAa,CAAC,EACnC,OAAO,EACP,OAAY,EACZ,YAAiB,EACjB,UAAgB,EAChB,KAAiB,EACjB,WAAgB,EAChB,UAAc,EACd,QAA6C,EAC7C,EAAE,sBAAsB,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAsC1D"}
+{"version":3,"file":"classifier.d.ts","sourceRoot":"","sources":["../../../src/src/tools/classifier.ts"],"names":[],"mappings":"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"}