@graphext/cuery 0.3.0 → 0.5.1

package/script/src/tools/classifier.js

@@ -1,14 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.classify = classify;
-exports.classifyBatch = classifyBatch;
-exports.label = label;
-exports.labelBatch = labelBatch;
-exports.extractLabels = extractLabels;
-const index_js_1 = require("../../deps/jsr.io/@zod/zod/4.1.12/src/index.js");
-const async_js_1 = require("../async.js");
-const openai_js_1 = require("../openai.js");
-const utils_js_1 = require("../utils.js");
+exports.LabelExtractor = exports.Labeler = exports.Classifier = void 0;
+const index_js_1 = require("../../deps/jsr.io/@zod/zod/4.3.6/src/index.js");
+const tool_js_1 = require("../tool.js");
+const utils_js_1 = require("../helpers/utils.js");
 const PROMPT_TEMPLATE = (0, utils_js_1.dedent)(`
 # Instructions
 
@@ -43,7 +38,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)
@@ -60,7 +54,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);
@@ -73,7 +66,6 @@ function createLabelSchema(labels) {
             label: index_js_1.z.literal(label).describe(description)
         });
     }
-    // TypeScript now knows entries.length >= 2
     const literals = entries.map(([label, description]) => index_js_1.z.literal(label).describe(description));
     return index_js_1.z.object({
         label: index_js_1.z.union(literals)
@@ -81,7 +73,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);
@@ -93,55 +84,57 @@ 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.
  */
-async function classify(record, labels, instructions = '', model = 'gpt-4.1-mini') {
-    if (record == null || Object.keys(record).length === 0) {
-        return null;
+class Classifier extends tool_js_1.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 (0, openai_js_1.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.
- */
-function classifyBatch(records, labels, instructions = '', model = 'gpt-4.1-mini', maxConcurrency = 100) {
-    return (0, async_js_1.mapParallel)(records, maxConcurrency, record => classify(record, labels, instructions, model));
-}
-/**
- * Assigns one or more labels to a single data record using an LLM call.
- */
-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 (0, openai_js_1.askOpenAISafe)(prompt, model, multiLabelSchema);
-    if (!parsed) {
-        throw new Error('Failed to parse response from OpenAI');
+    extractResult(parsed) {
+        return parsed.label;
     }
-    return parsed.labels;
 }
+exports.Classifier = Classifier;
 /**
- * Assigns labels to multiple data records concurrently while preserving order.
+ * A tool that assigns one or more labels to records from provided options.
  */
-function labelBatch(records, labels, instructions = '', model = 'gpt-4.1-mini', maxConcurrency = 100) {
-    return (0, async_js_1.mapParallel)(records, maxConcurrency, record => label(record, labels, instructions, model));
+class Labeler extends tool_js_1.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;
+    }
 }
+exports.Labeler = Labeler;
 // =============================================================================
-// Label Extraction
+// LabelExtractor (extract classification labels from records)
 // =============================================================================
 const EXTRACT_LABELS_PROMPT = (0, utils_js_1.dedent)(`
 # Instructions
@@ -169,10 +162,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 = index_js_1.z.object({
     labels: index_js_1.z.array(index_js_1.z.object({
         name: index_js_1.z.string(),
@@ -180,39 +169,37 @@ const ExtractedLabelsSchema = index_js_1.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.
  */
-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 {};
+class LabelExtractor extends tool_js_1.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 = (0, utils_js_1.formatRecordsAttrWise)(sampledRecords);
+        return this.promptTemplate.replace('{records}', formattedRecords);
     }
-    const sampledRecords = records.length > maxSamples
-        ? records.slice(0, maxSamples)
-        : records;
-    const formattedRecords = (0, utils_js_1.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 (0, openai_js_1.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]));
 }
+exports.LabelExtractor = LabelExtractor;

package/script/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/script/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/script/src/tools/entities.js

@@ -1,14 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.EntitiesSchema = exports.EntitySchema = exports.PROMPT = void 0;
-exports.extractAnyEntities = extractAnyEntities;
-exports.extractEntitiesFromText = extractEntitiesFromText;
-exports.extractEntitiesBatch = extractEntitiesBatch;
-const async_js_1 = require("../async.js");
-const openai_js_1 = require("../openai.js");
+exports.EntitiesSchema = exports.EntitySchema = exports.EntityExtractor = void 0;
+const tool_js_1 = require("../tool.js");
 const entity_schema_js_1 = require("../schemas/entity.schema.js");
-const utils_js_1 = require("../utils.js");
-exports.PROMPT = (0, utils_js_1.dedent)(`
+const utils_js_1 = require("../helpers/utils.js");
+const PROMPT = (0, utils_js_1.dedent)(`
 # Instructions
 
 From the Data Record section below extract entities in the following categories:
@@ -35,54 +31,36 @@ 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.
  */
-async function extractAnyEntities(body, instructions = '', model, modelParams = {}) {
-    const prompt = exports.PROMPT
-        .replace('{definitions}', '')
-        .replace('{text}', body)
-        .replace('{instructions}', instructions);
-    const { parsed } = await (0, openai_js_1.askOpenAISafe)(prompt, model, entity_schema_js_1.EntitiesSchema, modelParams);
-    if (!parsed) {
-        throw new Error('Failed to parse response from OpenAI');
+class EntityExtractor extends tool_js_1.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.
- */
-async function extractEntitiesFromText(text, entityDefinitions, instructions = '', model = 'gpt-4.1-mini', modelParams = {}) {
-    if (text === null) {
-        return [];
+    schema() {
+        return entity_schema_js_1.EntitiesSchema;
     }
-    const definitionsText = typeof entityDefinitions === 'string'
-        ? entityDefinitions
-        : Object.entries(entityDefinitions)
-            .map(([type, description]) => `- ${type}: ${description}`)
-            .join('\n');
-    const prompt = exports.PROMPT
-        .replace('{definitions}', definitionsText)
-        .replace('{text}', text)
-        .replace('{instructions}', instructions);
-    const { parsed } = await (0, openai_js_1.askOpenAISafe)(prompt, model, entity_schema_js_1.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.
- */
-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 (0, async_js_1.mapParallel)(texts, maxConcurrency, (text) => extractEntitiesFromText(text, definitions, instructions, model, modelParams));
 }
+exports.EntityExtractor = EntityExtractor;
 var entity_schema_js_2 = require("../schemas/entity.schema.js");
 Object.defineProperty(exports, "EntitySchema", { enumerable: true, get: function () { return entity_schema_js_2.EntitySchema; } });
 Object.defineProperty(exports, "EntitiesSchema", { enumerable: true, get: function () { return entity_schema_js_2.EntitiesSchema; } });

package/script/src/tools/funnel.js

@@ -7,11 +7,11 @@ exports.customizeFunnel = customizeFunnel;
 exports.generateSeedKeywords = generateSeedKeywords;
 exports.reseedFunnel = reseedFunnel;
 exports.generateFunnel = generateFunnel;
-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 funnel_schema_js_1 = require("../schemas/funnel.schema.js");
 Object.defineProperty(exports, "FunnelWithExplanationSchema", { enumerable: true, get: function () { return funnel_schema_js_1.FunnelWithExplanationSchema; } });
-const utils_js_1 = require("../utils.js");
+const utils_js_1 = require("../helpers/utils.js");
 /**
  * Iterates over all categories in a funnel, yielding references to stage info and category objects.
  * This allows in-place modifications of categories within the funnel structure.
@@ -303,9 +303,9 @@ async function customizeFunnel(sector, language, userLanguage = null, country =
         .replace('{language}', language)
         .replace('{userLanguage}', userLanguage ?? language)
         .replace('{funnel}', JSON.stringify(funnelData, null, 2));
-    const { parsed } = await (0, openai_js_1.askOpenAISafe)(prompt, model, funnel_schema_js_1.FunnelWithExplanationSchema);
+    const { parsed } = await (0, llm_js_1.askLLMSafe)({ prompt, model, schema: funnel_schema_js_1.FunnelWithExplanationSchema });
     if (!parsed) {
-        throw new Error('Failed to parse response from OpenAI');
+        throw new Error('Failed to parse response from LLM');
     }
     return parsed;
 }
@@ -346,9 +346,9 @@ async function generateSeedKeywords(stage, goal, category, sector, language, cou
         .replace('{sector}', sector)
         .replace('{market}', country)
         .replace('{language}', language);
-    const { parsed } = await (0, openai_js_1.askOpenAISafe)(prompt, model, funnel_schema_js_1.SeedsSchema);
+    const { parsed } = await (0, llm_js_1.askLLMSafe)({ prompt, model, schema: funnel_schema_js_1.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/script/src/tools/generic.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Generic AI step tool for processing records with LLM-inferred response schemas.
+ *
+ * This tool allows for generic tasks that iterate over data, where the response schema
+ * 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 LLMResponse, type ProviderParams } from '../llm.js';
+import { BatchResponse } from '../response.js';
+export type AIParams = ProviderParams;
+/**
+ * Schema for the schema generation response.
+ */
+declare const SchemaResponseSchema: z.ZodObject<{
+    reasoning: z.ZodString;
+    jsonSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strip>;
+export type SchemaResponse = z.infer<typeof SchemaResponseSchema>;
+export interface GenerateSchemaOptions {
+    instructions: string;
+    model?: string;
+    modelParams?: AIParams;
+    maxRetries?: number;
+}
+/**
+ * Generates a JSON schema from natural language instructions.
+ *
+ * @param options - Configuration options
+ * @returns The generated schema response with reasoning and JSON schema
+ */
+export declare function generateSchema({ instructions, model, modelParams, maxRetries }: GenerateSchemaOptions): Promise<SchemaResponse>;
+/** Common options for LLM calls */
+interface BaseLLMOptions {
+    instructions: string;
+    model?: string;
+    modelParams?: AIParams;
+    maxRetries?: number;
+}
+export interface GenericOptions extends BaseLLMOptions {
+    record: Record<string, unknown> | null;
+    schema: Record<string, unknown>;
+}
+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<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, trackCost, }: GenericBatchOptions): Promise<BatchResponse<T | null>>;
+/** Common options for auto functions */
+interface BaseAutoOptions extends BaseLLMOptions {
+    schemaOrInstructions?: string | Record<string, unknown> | null;
+    schemaModel?: string;
+}
+export interface AutoOptions extends BaseAutoOptions {
+    record: Record<string, unknown> | null;
+}
+export interface AutoBatchOptions extends BaseAutoOptions {
+    records: Array<Record<string, unknown> | null>;
+    maxConcurrency?: number;
+}
+/** Result from auto functions includes the resolved schema */
+export interface AutoResult<T> {
+    data: T;
+    schema: Record<string, unknown>;
+    schemaReasoning: string;
+}
+/**
+ * Automatically generates a response schema from instructions and processes a single record.
+ *
+ * This is a fully automatic tool that:
+ * 1. Optionally converts general instructions into schema-specific instructions
+ * 2. Generates a JSON schema from the instructions
+ * 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<AutoBatchResult<T>>;
+export {};
+//# sourceMappingURL=generic.d.ts.map

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

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