@graphext/cuery 0.4.0 → 0.5.2

package/esm/src/tools/classifier.js

@@ -1,7 +1,6 @@
 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 { dedent, formatRecordsAttrWise } from '../utils.js';
+import { Tool } from '../tool.js';
+import { dedent, formatRecordsAttrWise } from '../helpers/utils.js';
 const PROMPT_TEMPLATE = dedent(`
 # Instructions
 
@@ -36,7 +35,6 @@ if it matches multiple categories. Assign all relevant labels that apply to the
 `);
 /**
  * Formats a record object into a human-readable text representation.
- * Similar to the record_to_text.jinja template in Python.
  */
 function formatRecord(record) {
     return Object.entries(record)
@@ -53,7 +51,6 @@ function formatLabels(labels) {
 }
 /**
  * Creates a dynamic Category schema based on provided labels.
- * Each category literal includes its description, which helps the LLM understand the classification.
  */
 function createLabelSchema(labels) {
     const entries = Object.entries(labels);
@@ -66,7 +63,6 @@ function createLabelSchema(labels) {
             label: z.literal(label).describe(description)
         });
     }
-    // TypeScript now knows entries.length >= 2
     const literals = entries.map(([label, description]) => z.literal(label).describe(description));
     return z.object({
         label: z.union(literals)
@@ -74,7 +70,6 @@ function createLabelSchema(labels) {
 }
 /**
  * Creates a dynamic multi-label schema based on provided labels.
- * Returns a schema that accepts an array of labels, reusing the single label schema.
  */
 function createMultiLabelSchema(labels) {
     const singleLabelSchema = createLabelSchema(labels);
@@ -86,55 +81,55 @@ function createMultiLabelSchema(labels) {
     });
 }
 /**
- * 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 async function classify(record, labels, instructions = '', model = 'gpt-4.1-mini') {
-    if (record == null || Object.keys(record).length === 0) {
-        return null;
+export class Classifier extends Tool {
+    labelSchema;
+    promptTemplate;
+    constructor(config, modelConfig) {
+        super(modelConfig);
+        const { labels, instructions = '' } = config;
+        this.labelSchema = createLabelSchema(labels);
+        this.promptTemplate = PROMPT_TEMPLATE
+            .replace('{labels}', formatLabels(labels))
+            .replace('{instructions}', instructions);
     }
-    const categorySchema = createLabelSchema(labels);
-    const prompt = PROMPT_TEMPLATE
-        .replace('{labels}', formatLabels(labels))
-        .replace('{instructions}', instructions)
-        .replace('{record}', formatRecord(record));
-    const { parsed } = await askOpenAISafe(prompt, model, categorySchema);
-    if (!parsed) {
-        throw new Error('Failed to parse response from OpenAI');
+    schema() {
+        return this.labelSchema;
     }
-    return parsed.label;
-}
-/**
- * Classifies multiple data records concurrently while preserving order.
- */
-export function classifyBatch(records, labels, instructions = '', model = 'gpt-4.1-mini', maxConcurrency = 100) {
-    return mapParallel(records, maxConcurrency, record => classify(record, labels, instructions, model));
-}
-/**
- * Assigns one or more labels to a single data record using an LLM call.
- */
-export async function label(record, labels, instructions = '', model = 'gpt-4.1-mini') {
-    if (record == null || Object.keys(record).length === 0) {
-        return null;
+    prompt(record) {
+        return this.promptTemplate.replace('{record}', formatRecord(record));
     }
-    const multiLabelSchema = createMultiLabelSchema(labels);
-    const prompt = MULTI_LABEL_PROMPT_TEMPLATE
-        .replace('{labels}', formatLabels(labels))
-        .replace('{instructions}', instructions)
-        .replace('{record}', formatRecord(record));
-    const { parsed } = await askOpenAISafe(prompt, model, multiLabelSchema);
-    if (!parsed) {
-        throw new Error('Failed to parse response from OpenAI');
+    extractResult(parsed) {
+        return parsed.label;
     }
-    return parsed.labels;
 }
 /**
- * Assigns labels to multiple data records concurrently while preserving order.
+ * A tool that assigns one or more labels to records from provided options.
  */
-export function labelBatch(records, labels, instructions = '', model = 'gpt-4.1-mini', maxConcurrency = 100) {
-    return mapParallel(records, maxConcurrency, record => label(record, labels, instructions, model));
+export class Labeler extends Tool {
+    multiLabelSchema;
+    promptTemplate;
+    constructor(config, modelConfig) {
+        super(modelConfig);
+        const { labels, instructions = '' } = config;
+        this.multiLabelSchema = createMultiLabelSchema(labels);
+        this.promptTemplate = MULTI_LABEL_PROMPT_TEMPLATE
+            .replace('{labels}', formatLabels(labels))
+            .replace('{instructions}', instructions);
+    }
+    schema() {
+        return this.multiLabelSchema;
+    }
+    prompt(record) {
+        return this.promptTemplate.replace('{record}', formatRecord(record));
+    }
+    extractResult(parsed) {
+        return parsed.labels;
+    }
 }
 // =============================================================================
-// Label Extraction
+// LabelExtractor (extract classification labels from records)
 // =============================================================================
 const EXTRACT_LABELS_PROMPT = dedent(`
 # Instructions
@@ -162,10 +157,6 @@ unless the user provides different instructions below.
 
 {records}
 `);
-/**
- * Schema for extracted labels - an array of label objects.
- * Uses array format instead of record because OpenAI doesn't support propertyNames in JSON schema.
- */
 const ExtractedLabelsSchema = z.object({
     labels: z.array(z.object({
         name: z.string(),
@@ -173,39 +164,36 @@ const ExtractedLabelsSchema = z.object({
     }))
 });
 /**
- * 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 async function extractLabels({ records, nLabels = 10, instructions = '', maxSamples = 500, model = 'gpt-4.1', modelParams = {}, maxRetries = 8, language = 'The same language as the records' }) {
-    if (!records || records.length === 0) {
-        return {};
+export class LabelExtractor extends Tool {
+    maxSamples;
+    promptTemplate;
+    constructor(config = {}, modelConfig) {
+        super(modelConfig);
+        const { nLabels = 10, instructions = '', maxSamples = 500, language = 'The same language as the records' } = config;
+        this.maxSamples = maxSamples;
+        this.promptTemplate = EXTRACT_LABELS_PROMPT
+            .replace('{n_labels}', String(nLabels))
+            .replace('{instructions}', instructions)
+            .replace('{language}', language);
+    }
+    schema() {
+        return ExtractedLabelsSchema;
+    }
+    prompt(records) {
+        const sampledRecords = records.length > this.maxSamples
+            ? records.slice(0, this.maxSamples)
+            : records;
+        const formattedRecords = formatRecordsAttrWise(sampledRecords);
+        return this.promptTemplate.replace('{records}', formattedRecords);
     }
-    const sampledRecords = records.length > maxSamples
-        ? records.slice(0, maxSamples)
-        : records;
-    const formattedRecords = formatRecordsAttrWise(sampledRecords);
-    const prompt = EXTRACT_LABELS_PROMPT
-        .replace('{n_labels}', String(nLabels))
-        .replace('{instructions}', instructions)
-        .replace('{records}', formattedRecords)
-        .replace('{language}', language);
-    const { parsed, output_text, error } = await askOpenAISafe(prompt, model, ExtractedLabelsSchema, modelParams, maxRetries, 'return');
-    if (error != null) {
-        if (output_text == null) {
-            throw new Error('Failed to get response from OpenAI');
-        }
-        try {
-            const extracted = JSON.parse(output_text);
-            const { labels } = ExtractedLabelsSchema.parse(extracted);
-            return Object.fromEntries(labels.map(l => [l.name, l.description]));
-        }
-        catch (parseError) {
-            throw new Error(`Failed to parse response: ${parseError instanceof Error ? parseError.message : String(parseError)}`);
-        }
+    isEmpty(records) {
+        return !records || records.length === 0;
     }
-    if (parsed == null) {
-        throw new Error('Failed to parse response from OpenAI');
+    extractResult(parsed) {
+        return Object.fromEntries(parsed.labels.map(l => [l.name, l.description]));
     }
-    return Object.fromEntries(parsed.labels.map(l => [l.name, l.description]));
 }

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

@@ -1,19 +1,30 @@
-import { type AIParams } from '../openai.js';
-import { type Entity } from '../schemas/entity.schema.js';
-export declare const PROMPT: string;
+import { Tool, type ModelConfig } from '../tool.js';
+import { type Entity, type Entities } from '../schemas/entity.schema.js';
 /**
- *
- * Extracts free-form entities from the given text (without enforced entity types).
+ * Configuration for the EntityExtractor tool.
  */
-export declare function extractAnyEntities(body: string, instructions: string | undefined, model: string, modelParams?: AIParams): Promise<Array<Entity>>;
+export interface EntityExtractorConfig {
+    /** Entity type definitions (string or map of type to description) */
+    entityDefinitions?: string | Record<string, string>;
+    /** Additional instructions */
+    instructions?: string;
+}
 /**
- * Extracts entities in pre-specified categories from a single text.
+ * A tool that extracts entities from text.
  */
-export declare function extractEntitiesFromText(text: string | null, entityDefinitions: string | Record<string, string>, instructions?: string, model?: string, modelParams?: AIParams): Promise<Array<Entity>>;
-/**
- * Extracts entities from a batch of texts.
- */
-export declare function extractEntitiesBatch(texts: Array<string | null>, entityDefinitions: Record<string, string> | string, instructions?: string, model?: string, maxConcurrency?: number, modelParams?: AIParams): Promise<Array<Array<Entity>>>;
+export declare class EntityExtractor extends Tool<string | null, Entities, Array<Entity>> {
+    private readonly promptTemplate;
+    constructor(config: EntityExtractorConfig | undefined, modelConfig: ModelConfig);
+    protected schema(): import("../../deps/jsr.io/@zod/zod/4.3.6/src/index.js").ZodObject<{
+        entities: import("../../deps/jsr.io/@zod/zod/4.3.6/src/index.js").ZodArray<import("../../deps/jsr.io/@zod/zod/4.3.6/src/index.js").ZodObject<{
+            name: import("../../deps/jsr.io/@zod/zod/4.3.6/src/index.js").ZodString;
+            type: import("../../deps/jsr.io/@zod/zod/4.3.6/src/index.js").ZodString;
+        }, import("../../deps/jsr.io/@zod/zod/4.3.6/src/v4/core/schemas.js").$strip>>;
+    }, import("../../deps/jsr.io/@zod/zod/4.3.6/src/v4/core/schemas.js").$strip>;
+    protected prompt(text: string | null): string;
+    protected isEmpty(text: string | null): boolean;
+    protected extractResult(parsed: Entities): Array<Entity>;
+}
 export type { Entity, Entities } from '../schemas/entity.schema.js';
 export { EntitySchema, EntitiesSchema } from '../schemas/entity.schema.js';
 //# sourceMappingURL=entities.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"entities.d.ts","sourceRoot":"","sources":["../../../src/src/tools/entities.ts"],"names":[],"mappings":"AACA,OAAO,EAAiB,KAAK,QAAQ,EAAE,MAAM,cAAc,CAAC;AAE5D,OAAO,EAAkB,KAAK,MAAM,EAAE,MAAM,6BAA6B,CAAC;AAG1E,eAAO,MAAM,MAAM,QAyBjB,CAAC;AAEH;;;GAGG;AACH,wBAAsB,kBAAkB,CACvC,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,MAAM,YAAK,EACzB,KAAK,EAAE,MAAM,EACb,WAAW,GAAE,QAAa,GACxB,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAYxB;AAED;;GAEG;AACH,wBAAsB,uBAAuB,CAC5C,IAAI,EAAE,MAAM,GAAG,IAAI,EACnB,iBAAiB,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAClD,YAAY,GAAE,MAAW,EACzB,KAAK,GAAE,MAAuB,EAC9B,WAAW,GAAE,QAAa,GACxB,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAsBxB;AAGD;;GAEG;AACH,wBAAsB,oBAAoB,CACzC,KAAK,EAAE,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC,EAC3B,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,EAClD,YAAY,GAAE,MAAW,EACzB,KAAK,GAAE,MAAuB,EAC9B,cAAc,GAAE,MAAY,EAC5B,WAAW,GAAE,QAAa,GACxB,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAc/B;AAED,YAAY,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,6BAA6B,CAAC;AACpE,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC"}
+{"version":3,"file":"entities.d.ts","sourceRoot":"","sources":["../../../src/src/tools/entities.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AACpD,OAAO,EAAkB,KAAK,MAAM,EAAE,KAAK,QAAQ,EAAE,MAAM,6BAA6B,CAAC;AAkCzF;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACrC,qEAAqE;IACrE,iBAAiB,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpD,8BAA8B;IAC9B,YAAY,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,qBAAa,eAAgB,SAAQ,IAAI,CAAC,MAAM,GAAG,IAAI,EAAE,QAAQ,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAChF,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;gBAE5B,MAAM,EAAE,qBAAqB,YAAK,EAAE,WAAW,EAAE,WAAW;cAgBrD,MAAM;;;;;;IAIzB,SAAS,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;cAIjB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO;cAIrC,aAAa,CAAC,MAAM,EAAE,QAAQ,GAAG,KAAK,CAAC,MAAM,CAAC;CAGjE;AAGD,YAAY,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,6BAA6B,CAAC;AACpE,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC"}

package/esm/src/tools/entities.js

@@ -1,8 +1,7 @@
-import { mapParallel } from '../async.js';
-import { askOpenAISafe } from '../openai.js';
+import { Tool } from '../tool.js';
 import { EntitiesSchema } from '../schemas/entity.schema.js';
-import { dedent } from '../utils.js';
-export const PROMPT = dedent(`
+import { dedent } from '../helpers/utils.js';
+const PROMPT = dedent(`
 # Instructions
 
 From the Data Record section below extract entities in the following categories:
@@ -29,52 +28,33 @@ definitions include a "brand" category and a "product" category, the expected ou
 {text}
 `);
 /**
- *
- * Extracts free-form entities from the given text (without enforced entity types).
+ * A tool that extracts entities from text.
  */
-export async function extractAnyEntities(body, instructions = '', model, modelParams = {}) {
-    const prompt = PROMPT
-        .replace('{definitions}', '')
-        .replace('{text}', body)
-        .replace('{instructions}', instructions);
-    const { parsed } = await askOpenAISafe(prompt, model, EntitiesSchema, modelParams);
-    if (!parsed) {
-        throw new Error('Failed to parse response from OpenAI');
+export class EntityExtractor extends Tool {
+    promptTemplate;
+    constructor(config = {}, modelConfig) {
+        super(modelConfig);
+        const { entityDefinitions = '', instructions = '' } = config;
+        const definitionsText = typeof entityDefinitions === 'string'
+            ? entityDefinitions
+            : Object.entries(entityDefinitions)
+                .map(([type, description]) => `- ${type}: ${description}`)
+                .join('\n');
+        this.promptTemplate = PROMPT
+            .replace('{definitions}', definitionsText)
+            .replace('{instructions}', instructions);
     }
-    return parsed.entities;
-}
-/**
- * Extracts entities in pre-specified categories from a single text.
- */
-export async function extractEntitiesFromText(text, entityDefinitions, instructions = '', model = 'gpt-4.1-mini', modelParams = {}) {
-    if (text === null) {
-        return [];
+    schema() {
+        return EntitiesSchema;
     }
-    const definitionsText = typeof entityDefinitions === 'string'
-        ? entityDefinitions
-        : Object.entries(entityDefinitions)
-            .map(([type, description]) => `- ${type}: ${description}`)
-            .join('\n');
-    const prompt = PROMPT
-        .replace('{definitions}', definitionsText)
-        .replace('{text}', text)
-        .replace('{instructions}', instructions);
-    const { parsed } = await askOpenAISafe(prompt, model, EntitiesSchema, modelParams);
-    if (!parsed) {
-        throw new Error('Failed to parse response from OpenAI');
+    prompt(text) {
+        return this.promptTemplate.replace('{text}', text ?? '');
+    }
+    isEmpty(text) {
+        return text == null || text.trim() === '';
+    }
+    extractResult(parsed) {
+        return parsed.entities;
     }
-    return parsed.entities;
-}
-/**
- * Extracts entities from a batch of texts.
- */
-export async function extractEntitiesBatch(texts, entityDefinitions, instructions = '', model = 'gpt-4.1-mini', maxConcurrency = 100, modelParams = {}) {
-    // Do this once outside the loop
-    const definitions = typeof entityDefinitions === 'string'
-        ? entityDefinitions
-        : Object.entries(entityDefinitions)
-            .map(([type, description]) => `- ${type}: ${description}`)
-            .join('\n');
-    return mapParallel(texts, maxConcurrency, (text) => extractEntitiesFromText(text, definitions, instructions, model, modelParams));
 }
 export { EntitySchema, EntitiesSchema } from '../schemas/entity.schema.js';

package/esm/src/tools/funnel.js

@@ -1,7 +1,7 @@
-import { mapParallel } from '../async.js';
-import { askOpenAISafe } from '../openai.js';
+import { mapParallel } from '../helpers/async.js';
+import { askLLMSafe } from '../llm.js';
 import { FunnelWithExplanationSchema, SeedsSchema } from '../schemas/funnel.schema.js';
-import { dedent } from '../utils.js';
+import { dedent } from '../helpers/utils.js';
 export { FunnelWithExplanationSchema };
 /**
  * Iterates over all categories in a funnel, yielding references to stage info and category objects.
@@ -294,9 +294,9 @@ export async function customizeFunnel(sector, language, userLanguage = null, cou
         .replace('{language}', language)
         .replace('{userLanguage}', userLanguage ?? language)
         .replace('{funnel}', JSON.stringify(funnelData, null, 2));
-    const { parsed } = await askOpenAISafe(prompt, model, FunnelWithExplanationSchema);
+    const { parsed } = await askLLMSafe({ prompt, model, schema: FunnelWithExplanationSchema });
     if (!parsed) {
-        throw new Error('Failed to parse response from OpenAI');
+        throw new Error('Failed to parse response from LLM');
     }
     return parsed;
 }
@@ -337,9 +337,9 @@ export async function generateSeedKeywords(stage, goal, category, sector, langua
         .replace('{sector}', sector)
         .replace('{market}', country)
         .replace('{language}', language);
-    const { parsed } = await askOpenAISafe(prompt, model, SeedsSchema);
+    const { parsed } = await askLLMSafe({ prompt, model, schema: SeedsSchema });
     if (!parsed) {
-        throw new Error('Failed to parse seed keywords from OpenAI');
+        throw new Error('Failed to parse seed keywords from LLM');
     }
     return parsed.seeds;
 }

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

@@ -5,7 +5,9 @@
  * is either provided directly or inferred from the user's instructions using an LLM.
  */
 import { z } from '../../deps/jsr.io/@zod/zod/4.3.6/src/index.js';
-import { type AIParams } from '../openai.js';
+import { type LLMResponse, type ProviderParams } from '../llm.js';
+import { BatchResponse } from '../response.js';
+export type AIParams = ProviderParams;
 /**
  * Schema for the schema generation response.
  */
@@ -42,15 +44,18 @@ export interface GenericBatchOptions extends BaseLLMOptions {
     records: Array<Record<string, unknown> | null>;
     schema: Record<string, unknown>;
     maxConcurrency?: number;
+    trackCost?: boolean;
 }
 /**
  * Processes a single record using an LLM with a provided JSON schema.
+ * Returns both the result and usage information.
  */
-export declare function generic<T = Record<string, unknown>>({ record, instructions, schema, model, modelParams, maxRetries }: GenericOptions): Promise<T | null>;
+export declare function generic<T = Record<string, unknown>>({ record, instructions, schema, model, modelParams, maxRetries }: GenericOptions): Promise<LLMResponse<T | null>>;
 /**
  * Processes multiple records using an LLM with a provided JSON schema.
+ * Returns a BatchResponse with usage tracking.
  */
-export declare function genericBatch<T = Record<string, unknown>>({ records, instructions, schema, model, modelParams, maxRetries, maxConcurrency }: GenericBatchOptions): Promise<Array<T | null>>;
+export declare function genericBatch<T = Record<string, unknown>>({ records, instructions, schema, model, modelParams, maxRetries, maxConcurrency, trackCost, }: GenericBatchOptions): Promise<BatchResponse<T | null>>;
 /** Common options for auto functions */
 interface BaseAutoOptions extends BaseLLMOptions {
     schemaOrInstructions?: string | Record<string, unknown> | null;
@@ -78,11 +83,19 @@ export interface AutoResult<T> {
  * 3. Processes the record using the generated schema
  */
 export declare function auto<T = Record<string, unknown>>({ record, instructions, schemaOrInstructions, model, schemaModel, modelParams, maxRetries }: AutoOptions): Promise<AutoResult<T | null>>;
+/**
+ * Result from autoBatch includes schema info and BatchResponse.
+ */
+export interface AutoBatchResult<T> {
+    data: BatchResponse<T | null>;
+    schema: Record<string, unknown>;
+    schemaReasoning: string;
+}
 /**
  * Automatically generates a response schema and processes multiple records.
  *
  * The schema is generated once from the instructions, then used to process all records.
  */
-export declare function autoBatch<T = Record<string, unknown>>({ records, instructions, schemaOrInstructions, model, schemaModel, modelParams, maxRetries, maxConcurrency }: AutoBatchOptions): Promise<AutoResult<Array<T | null>>>;
+export declare function autoBatch<T = Record<string, unknown>>({ records, instructions, schemaOrInstructions, model, schemaModel, modelParams, maxRetries, maxConcurrency }: AutoBatchOptions): Promise<AutoBatchResult<T>>;
 export {};
 //# sourceMappingURL=generic.d.ts.map

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

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

package/esm/src/tools/generic.js

@@ -5,9 +5,10 @@
  * is either provided directly or inferred from the user's instructions using an LLM.
  */
 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 { dedent } from '../utils.js';
+import { mapParallel } from '../helpers/async.js';
+import { askLLMSafe } from '../llm.js';
+import { BatchResponse } from '../response.js';
+import { dedent } from '../helpers/utils.js';
 // ============================================================================
 // Prompts
 // ============================================================================
@@ -108,7 +109,14 @@ export async function generateSchema({ instructions, model = 'gpt-4.1', modelPar
         { role: 'system', content: SCHEMA_GENERATION_SYSTEM_PROMPT },
         { role: 'user', content: SCHEMA_GENERATION_PROMPT.replace('{instructions}', instructions) }
     ];
-    const { parsed, error } = await askOpenAISafe(prompt, model, SchemaResponseSchema, modelParams, maxRetries, 'return');
+    const { parsed, error } = await askLLMSafe({
+        prompt,
+        model,
+        schema: SchemaResponseSchema,
+        params: modelParams,
+        maxRetries,
+        onError: 'return',
+    });
     if (error || !parsed) {
         throw new Error(`Failed to generate schema: ${error?.message ?? 'Unknown error'}`);
     }
@@ -120,7 +128,14 @@ export async function generateSchema({ instructions, model = 'gpt-4.1', modelPar
  */
 async function convertToSchemaInstructions(instructions, model, modelParams, maxRetries) {
     const prompt = SCHEMA_CONVERSION_PROMPT.replace('{instructions}', instructions);
-    const { parsed, error } = await askOpenAISafe(prompt, model, SchemaInstructionsSchema, modelParams, maxRetries, 'return');
+    const { parsed, error } = await askLLMSafe({
+        prompt,
+        model,
+        schema: SchemaInstructionsSchema,
+        params: modelParams,
+        maxRetries,
+        onError: 'return',
+    });
     if (error || !parsed) {
         throw new Error(`Failed to convert instructions: ${error?.message ?? 'Unknown error'}`);
     }
@@ -128,26 +143,36 @@ async function convertToSchemaInstructions(instructions, model, modelParams, max
 }
 /**
  * Processes a single record using an LLM with a provided JSON schema.
+ * Returns both the result and usage information.
  */
 export async function generic({ record, instructions, schema, model = 'gpt-4.1-mini', modelParams = {}, maxRetries = 3 }) {
     if (record == null || Object.keys(record).length === 0) {
-        return null;
+        return { parsed: null, text: null, usage: null, error: null };
     }
     const zodSchema = z.fromJSONSchema(schema);
     const prompt = GENERIC_PROMPT
         .replace('{instructions}', instructions)
         .replace('{record}', formatRecord(record));
-    const { parsed, error } = await askOpenAISafe(prompt, model, zodSchema, modelParams, maxRetries, 'return');
-    if (error || parsed == null) {
-        throw new Error(`Failed to process record: ${error?.message ?? 'Unknown error'}`);
+    const response = await askLLMSafe({
+        prompt,
+        model,
+        schema: zodSchema,
+        params: modelParams,
+        maxRetries,
+        onError: 'return',
+    });
+    if (response.error || response.parsed == null) {
+        throw new Error(`Failed to process record: ${response.error?.message ?? 'Unknown error'}`);
     }
-    return parsed;
+    return { parsed: response.parsed, text: response.text, usage: response.usage, error: null };
 }
 /**
  * Processes multiple records using an LLM with a provided JSON schema.
+ * Returns a BatchResponse with usage tracking.
  */
-export function genericBatch({ records, instructions, schema, model = 'gpt-4.1-mini', modelParams = {}, maxRetries = 3, maxConcurrency = 100 }) {
-    return mapParallel(records, maxConcurrency, (record) => generic({ record, instructions, schema, model, modelParams, maxRetries }));
+export async function genericBatch({ records, instructions, schema, model = 'gpt-4.1-mini', modelParams = {}, maxRetries = 3, maxConcurrency = 100, trackCost = false, }) {
+    const responses = await mapParallel(records, maxConcurrency, (record) => generic({ record, instructions, schema, model, modelParams, maxRetries }));
+    return new BatchResponse(responses.map(r => r.parsed), trackCost ? responses.map(r => r.usage) : undefined, trackCost ? model : undefined);
 }
 /**
  * Resolves a schema from various input types:
@@ -189,7 +214,7 @@ async function resolveSchema(schemaOrInstructions, taskInstructions, model, mode
  */
 export async function auto({ record, instructions, schemaOrInstructions = null, model = 'gpt-4.1-mini', schemaModel = 'gpt-4.1', modelParams = {}, maxRetries = 3 }) {
     const { schema, schemaReasoning } = await resolveSchema(schemaOrInstructions, instructions, schemaModel, modelParams, maxRetries);
-    const data = await generic({
+    const response = await generic({
         record,
         instructions,
         schema,
@@ -197,7 +222,7 @@ export async function auto({ record, instructions, schemaOrInstructions = null,
         modelParams,
         maxRetries
     });
-    return { data, schema, schemaReasoning };
+    return { data: response.parsed, schema, schemaReasoning };
 }
 /**
  * Automatically generates a response schema and processes multiple records.

package/esm/src/tools/keywords.js

@@ -1,8 +1,8 @@
-import { mapParallel } from '../async.js';
-import { askOpenAISafe } from '../openai.js';
+import { mapParallel } from '../helpers/async.js';
+import { askLLMSafe } from '../llm.js';
 import { buildBrandContext } from './brands.js';
 import { KeywordsResponseSchema } from '../schemas/keyword.schema.js';
-import { dedent } from '../utils.js';
+import { dedent } from '../helpers/utils.js';
 import { keywords as getGoogleAdsKeywords } from '../apis/googleAds/keywordPlanner.js';
 export async function expandKeywords({ seedKeywords, url, urlAsExpandRelevanceContext, language = 'EN', countryISOCode, generateIdeasFromSeeds = false, includeSeedKeywords = false }) {
     url = url?.trim();
@@ -163,9 +163,9 @@ export async function generateKeywords({ sector, market, brand, brandDomain, lan
         .replaceAll('{brandsInfo}', brandsInfo || '')
         .replaceAll('{personasInfo}', personasInfo || '')
         .replaceAll('{funnelInfo}', funnelInfo || '');
-    const { parsed } = await askOpenAISafe(content, model, KeywordsResponseSchema);
+    const { parsed } = await askLLMSafe({ prompt: content, model, schema: KeywordsResponseSchema });
     if (!parsed) {
-        throw new Error('Failed to parse response from OpenAI');
+        throw new Error('Failed to parse response from LLM');
     }
     return parsed;
 }