@graphext/cuery 0.4.0 → 0.5.2

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

@@ -1,3 +1,50 @@
-import type { PersonasOptions, PersonasResponse } from '../schemas/persona.schema.js';
-export declare function generatePersonas({ sector, market, brand, brandDomain, language, userLanguage, count, model, briefing, instructions, personas }: PersonasOptions): Promise<PersonasResponse>;
+import { Tool, type ModelConfig } from '../tool.js';
+import type { Persona, PersonasResponse } from '../schemas/persona.schema.js';
+/**
+ * Configuration for the PersonaGenerator tool.
+ */
+export interface PersonaGeneratorConfig {
+    /** Industry sector the brand operates in */
+    sector: string;
+    /** Geographical market or region */
+    market: string;
+    /** Brand name */
+    brand?: string;
+    /** Brand domain */
+    brandDomain?: string;
+    /** Language for keyword seeds (default: 'english') */
+    language?: string;
+    /** Language for persona descriptions (default: same as language) */
+    userLanguage?: string | null;
+    /** Number of personas to generate (default: 5) */
+    count?: number;
+    /** Brand briefing context */
+    briefing?: string;
+    /** Additional instructions */
+    instructions?: string | null;
+}
+/**
+ * A tool that generates customer personas for a brand.
+ */
+export declare class PersonaGenerator extends Tool<Array<Persona> | null, PersonasResponse, PersonasResponse> {
+    private readonly promptTemplate;
+    constructor(config: PersonaGeneratorConfig, modelConfig: ModelConfig);
+    protected schema(): import("../../deps/jsr.io/@zod/zod/4.3.6/src/index.js").ZodObject<{
+        personas: 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;
+            description: import("../../deps/jsr.io/@zod/zod/4.3.6/src/index.js").ZodString;
+            keywordSeeds: 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").ZodString>;
+        }, import("../../deps/jsr.io/@zod/zod/4.3.6/src/v4/core/schemas.js").$strip>>;
+        explanation: 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>;
+    protected prompt(existingPersonas: Array<Persona> | null): string;
+    protected isEmpty(_input: Array<Persona> | null): boolean;
+    /**
+     * Not supported. PersonaGenerator is configured for a specific brand context
+     * and generates personas in a single call. Use invoke() instead.
+     */
+    batch(): never;
+}
+export type { Persona, PersonasResponse, PersonasOptions } from '../schemas/persona.schema.js';
+export { PersonaSchema, PersonasResponseSchema } from '../schemas/persona.schema.js';
 //# sourceMappingURL=personas.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"personas.d.ts","sourceRoot":"","sources":["../../../src/src/tools/personas.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAkDtF,wBAAsB,gBAAgB,CAAC,EACtC,MAAM,EACN,MAAM,EACN,KAAK,EACL,WAAW,EACX,QAAoB,EACpB,YAAmB,EACnB,KAAS,EACT,KAAiB,EACjB,QAAQ,EACR,YAAY,EACZ,QAAe,EACf,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC,CA4C7C"}
+{"version":3,"file":"personas.d.ts","sourceRoot":"","sources":["../../../src/src/tools/personas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AAEpD,OAAO,KAAK,EAAE,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAsD9E;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACtC,4CAA4C;IAC5C,MAAM,EAAE,MAAM,CAAC;IACf,oCAAoC;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,iBAAiB;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,mBAAmB;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,sDAAsD;IACtD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oEAAoE;IACpE,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,kDAAkD;IAClD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,6BAA6B;IAC7B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,8BAA8B;IAC9B,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAED;;GAEG;AACH,qBAAa,gBAAiB,SAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,IAAI,EAAE,gBAAgB,EAAE,gBAAgB,CAAC;IACpG,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;gBAE5B,MAAM,EAAE,sBAAsB,EAAE,WAAW,EAAE,WAAW;cAgDjD,MAAM;;;;;;;;IAIzB,SAAS,CAAC,MAAM,CAAC,gBAAgB,EAAE,KAAK,CAAC,OAAO,CAAC,GAAG,IAAI,GAAG,MAAM;cAW9C,OAAO,CAAC,MAAM,EAAE,KAAK,CAAC,OAAO,CAAC,GAAG,IAAI,GAAG,OAAO;IAKlE;;;OAGG;IACM,KAAK,IAAI,KAAK;CAOvB;AAGD,YAAY,EAAE,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAC/F,OAAO,EAAE,aAAa,EAAE,sBAAsB,EAAE,MAAM,8BAA8B,CAAC"}

package/esm/src/tools/personas.js

@@ -1,7 +1,7 @@
-import { askOpenAISafe } from '../openai.js';
+import { Tool } from '../tool.js';
 import { buildBrandContext } from './brands.js';
 import { PersonasResponseSchema } from '../schemas/persona.schema.js';
-import { dedent } from '../utils.js';
+import { dedent } from '../helpers/utils.js';
 const PROMPT = dedent(`
 You're a marketing expert identifying typical profiles/personas of people searching
 for brands, products or services. Generate {count} detailed customer personas for a brand
@@ -46,43 +46,67 @@ from this list, you MUST return at least all the same competitors that are alrea
 current data. If no modification instructions are provided, maintain the existing list and only add
 new competitors if they are relevant.
 `);
-export async function generatePersonas({ sector, market, brand, brandDomain, language = 'english', userLanguage = null, count = 5, model = 'gpt-4.1', briefing, instructions, personas = null }) {
-    if (!brand && !brandDomain) {
-        throw new Error('Either brand or brandDomain must be provided');
-    }
-    const brandContext = buildBrandContext({
-        brand,
-        brandDomain,
-        sector,
-        market,
-        briefing
-    });
-    let brandExclusion;
-    if (brandDomain) {
-        if (brand) {
-            brandExclusion = ` "${brand}" or the domain`;
+/**
+ * A tool that generates customer personas for a brand.
+ */
+export class PersonaGenerator extends Tool {
+    promptTemplate;
+    constructor(config, modelConfig) {
+        super(modelConfig);
+        const { sector, market, brand, brandDomain, language = 'english', userLanguage = null, count = 5, briefing, instructions } = config;
+        if (!brand && !brandDomain) {
+            throw new Error('Either brand or brandDomain must be provided');
+        }
+        const brandContext = buildBrandContext({
+            brand,
+            brandDomain,
+            sector,
+            market,
+            briefing
+        });
+        let brandExclusion;
+        if (brandDomain) {
+            if (brand) {
+                brandExclusion = ` "${brand}" or the domain`;
+            }
+            else {
+                brandExclusion = ' or domain';
+            }
         }
         else {
-            brandExclusion = ' or domain';
+            brandExclusion = ` "${brand}"`;
         }
+        this.promptTemplate = PROMPT
+            .replace('{count}', count.toString())
+            .replaceAll('{sector}', sector)
+            .replaceAll('{market}', market)
+            .replaceAll('{brand_context}', brandContext)
+            .replaceAll('{brand_exclusion}', brandExclusion)
+            .replaceAll('{language}', language)
+            .replaceAll('{userLanguage}', userLanguage ?? language)
+            .replaceAll('{instructions}', instructions || '');
+    }
+    schema() {
+        return PersonasResponseSchema;
+    }
+    prompt(existingPersonas) {
+        const currentData = existingPersonas && existingPersonas.length > 0
+            ? CURRENT_DATA_CLAUSE.replace('{currentData}', JSON.stringify({ personas: existingPersonas }, null, 2))
+            : '';
+        return this.promptTemplate.replace('{currentPersonasInfo}', currentData);
     }
-    else {
-        brandExclusion = ` "${brand}"`;
+    isEmpty(_input) {
+        // Never skip - null means generate fresh personas
+        return false;
     }
-    const currentData = personas && personas.length > 0 ? CURRENT_DATA_CLAUSE.replace('{currentData}', JSON.stringify({ personas }, null, 2)) : null;
-    const content = PROMPT
-        .replace('{count}', count.toString())
-        .replaceAll('{sector}', sector)
-        .replaceAll('{market}', market)
-        .replaceAll('{brand_context}', brandContext)
-        .replaceAll('{brand_exclusion}', brandExclusion)
-        .replaceAll('{language}', language)
-        .replaceAll('{userLanguage}', userLanguage ?? language)
-        .replaceAll('{instructions}', instructions || '')
-        .replaceAll('{currentPersonasInfo}', currentData || '');
-    const { parsed } = await askOpenAISafe(content, model, PersonasResponseSchema);
-    if (!parsed) {
-        throw new Error('Failed to parse response from OpenAI');
+    /**
+     * Not supported. PersonaGenerator is configured for a specific brand context
+     * and generates personas in a single call. Use invoke() instead.
+     */
+    batch() {
+        throw new Error('PersonaGenerator.batch() is not supported. ' +
+            'This tool generates personas for a specific brand context. ' +
+            'Use invoke() instead.');
     }
-    return parsed;
 }
+export { PersonaSchema, PersonasResponseSchema } from '../schemas/persona.schema.js';

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

@@ -1,14 +1,32 @@
 import { z } from '../../deps/jsr.io/@zod/zod/4.3.6/src/index.js';
-export type ScoreSchema = z.ZodObject<{
+import { Tool, type ModelConfig } from '../tool.js';
+type ScoreSchema = z.ZodObject<{
     value: z.ZodNumber;
 }>;
 /**
- * Dynamically create a Zod schema for a score based on provided parameters.
+ * Configuration for the Scorer tool.
  */
-export declare function makeScoreSchema(type: 'integer' | 'number', min: number, max: number, description: string): ScoreSchema;
+export interface ScorerConfig {
+    name: string;
+    description: string;
+    type: 'integer' | 'number';
+    min: number;
+    max: number;
+}
 /**
- * Assumes only remaining placeholder in prompt is {record}
+ * A tool that scores records based on configured criteria.
  */
-export declare function score(record: Record<string, unknown>, prompt: string, schema: ScoreSchema, model?: string): Promise<number>;
-export declare function scoreBatch(records: Array<Record<string, unknown>>, name: string, description: string, type: 'integer' | 'number', min: number, max: number, model?: string, maxConcurrency?: number): Promise<Array<number>>;
+export declare class Scorer extends Tool<Record<string, unknown> | null, {
+    value: number;
+}, number> {
+    private readonly scoreSchema;
+    private readonly promptTemplate;
+    constructor(config: ScorerConfig, modelConfig: ModelConfig);
+    protected schema(): ScoreSchema;
+    protected prompt(record: Record<string, unknown> | null): string;
+    protected extractResult(parsed: {
+        value: number;
+    }): number;
+}
+export {};
 //# sourceMappingURL=scorer.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"scorer.d.ts","sourceRoot":"","sources":["../../../src/src/tools/scorer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,+CAA+C,CAAC;AAqBlE,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,SAAS,CAAC;IAAE,KAAK,EAAE,CAAC,CAAC,SAAS,CAAA;CAAE,CAAC,CAAC;AAE9D;;GAEG;AACH,wBAAgB,eAAe,CAC9B,IAAI,EAAE,SAAS,GAAG,QAAQ,EAC1B,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,EACX,WAAW,EAAE,MAAM,GACjB,WAAW,CAWb;AAED;;GAEG;AACH,wBAAsB,KAAK,CAC1B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,WAAW,EACnB,KAAK,GAAE,MAAuB,GAC5B,OAAO,CAAC,MAAM,CAAC,CAajB;AAED,wBAAsB,UAAU,CAC/B,OAAO,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACvC,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,SAAS,GAAG,QAAQ,EAC1B,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,EACX,KAAK,GAAE,MAAuB,EAC9B,cAAc,GAAE,MAAY,GAC1B,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAcxB"}
+{"version":3,"file":"scorer.d.ts","sourceRoot":"","sources":["../../../src/src/tools/scorer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,+CAA+C,CAAC;AAClE,OAAO,EAAE,IAAI,EAAE,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AAkBpD,KAAK,WAAW,GAAG,CAAC,CAAC,SAAS,CAAC;IAAE,KAAK,EAAE,CAAC,CAAC,SAAS,CAAA;CAAE,CAAC,CAAC;AAuBvD;;GAEG;AACH,MAAM,WAAW,YAAY;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,SAAS,GAAG,QAAQ,CAAC;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;CACZ;AAED;;GAEG;AACH,qBAAa,MAAO,SAAQ,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,EAAE;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,EAAE,MAAM,CAAC;IAC1F,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAc;IAC1C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;gBAE5B,MAAM,EAAE,YAAY,EAAE,WAAW,EAAE,WAAW;cAYvC,MAAM;IAIzB,SAAS,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;cAIpC,aAAa,CAAC,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE;CAG1D"}

package/esm/src/tools/scorer.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 } from '../utils.js';
+import { Tool } from '../tool.js';
+import { dedent } from '../helpers/utils.js';
 const PROMPT = dedent(`
 # Instructions
 
@@ -19,7 +18,7 @@ based on the content of the attributes.
 /**
  * Dynamically create a Zod schema for a score based on provided parameters.
  */
-export function makeScoreSchema(type, min, max, description) {
+function makeScoreSchema(type, min, max, description) {
     let schema;
     if (type === 'integer') {
         schema = z.number().int().min(min).max(max).describe(description);
@@ -28,27 +27,33 @@ export function makeScoreSchema(type, min, max, description) {
         schema = z.number().min(min).max(max).describe(description);
     }
     return z.object({
-        value: schema
+        value: schema,
     });
 }
 /**
- * Assumes only remaining placeholder in prompt is {record}
+ * A tool that scores records based on configured criteria.
  */
-export async function score(record, prompt, schema, model = 'gpt-4.1-mini') {
-    const renderedPrompt = prompt.replace('record', JSON.stringify(record, null, 2));
-    const response = await askOpenAISafe(renderedPrompt, model, schema);
-    if (response.parsed == null) {
-        throw new Error('Failed to parse score from OpenAI response');
+export class Scorer extends Tool {
+    scoreSchema;
+    promptTemplate;
+    constructor(config, modelConfig) {
+        super(modelConfig);
+        const { name, description, type, min, max } = config;
+        this.scoreSchema = makeScoreSchema(type, min, max, description);
+        this.promptTemplate = PROMPT
+            .replace('{name}', name)
+            .replace('{type}', type)
+            .replace('{min}', min.toString())
+            .replace('{max}', max.toString())
+            .replace('{description}', description);
+    }
+    schema() {
+        return this.scoreSchema;
+    }
+    prompt(record) {
+        return this.promptTemplate.replace('{record}', JSON.stringify(record, null, 2));
+    }
+    extractResult(parsed) {
+        return parsed.value;
     }
-    return response.parsed.value;
-}
-export async function scoreBatch(records, name, description, type, min, max, model = 'gpt-4.1-mini', maxConcurrency = 100) {
-    const schema = makeScoreSchema(type, min, max, description);
-    const prompt = PROMPT
-        .replace('{name}', name)
-        .replace('{type}', type)
-        .replace('{min}', min.toString())
-        .replace('{max}', max.toString())
-        .replace('{description}', description);
-    return mapParallel(records, maxConcurrency, (record) => score(record, prompt, schema, model));
 }

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

@@ -1 +1 @@
-{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../../src/src/tools/search.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAK3H,YAAY,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAEhE;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,EAClC,MAAM,EACN,KAAsB,EACtB,SAAgB,EAChB,cAAqB,EACrB,WAAmB,EACnB,eAAuB,EACvB,UAAyB,EACzB,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,CAqBvC;AAqED;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,CAAC,CAAC,EAAE,EACzC,MAAM,EACN,KAAK,EACL,cAAc,EACd,SAAgB,EAChB,cAAqB,EACrB,WAAsB,EACtB,eAAuB,EACvB,EAAE,sBAAsB,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CA0BxC;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,EAC3B,OAAO,EACP,KAAsB,EACtB,SAAgB,EAChB,cAAqB,EACrB,WAAsB,EACtB,eAAuB,EACvB,cAAoB,EACpB,EAAE,kBAAkB,GAAG,OAAO,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,CAanD"}
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../../src/src/tools/search.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AA0B3H,YAAY,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAEhE;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,EAClC,MAAM,EACN,KAAsB,EACtB,SAAgB,EAChB,cAAqB,EACrB,WAAmB,EACnB,eAAuB,EACvB,UAAyB,EACzB,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,CA4BvC;AAqED;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,CAAC,CAAC,EAAE,EACzC,MAAM,EACN,KAAK,EACL,cAAc,EACd,SAAgB,EAChB,cAAqB,EACrB,WAAsB,EACtB,eAAuB,EACvB,EAAE,sBAAsB,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CA0BxC;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,EAC3B,OAAO,EACP,KAAsB,EACtB,SAAgB,EAChB,cAAqB,EACrB,WAAsB,EACtB,eAAuB,EACvB,cAAoB,EACpB,EAAE,kBAAkB,GAAG,OAAO,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,CAanD"}

package/esm/src/tools/search.js

@@ -1,7 +1,25 @@
-import { mapParallel } from '../async.js';
-import { askOpenAISafe } from '../openai.js';
-import { extractDomain } from '../urls.js';
-import { dedent } from '../utils.js';
+import * as dntShim from "../../_dnt.shims.js";
+import OpenAI from 'openai';
+import { mapParallel } from '../helpers/async.js';
+import { askLLMSafe } from '../llm.js';
+import { extractDomain } from '../helpers/urls.js';
+import { dedent } from '../helpers/utils.js';
+// Lazy-initialized OpenAI client for web search functionality
+let openaiClient = null;
+function getOpenAIClient() {
+    if (!openaiClient) {
+        const fetchOptions = {};
+        const abortSignal = dntShim.dntGlobalThis.abortSignal;
+        if (abortSignal) {
+            fetchOptions.signal = abortSignal;
+        }
+        openaiClient = new OpenAI({
+            apiKey: dntShim.Deno.env.get('OPENAI_API_KEY'),
+            fetchOptions,
+        });
+    }
+    return openaiClient;
+}
 /**
  * Call OpenAI Responses API with Web Search enabled (async).
  *
@@ -21,11 +39,17 @@ export async function searchOpenAI({ prompt, model = 'gpt-4.1-mini', useSearch =
             }];
         params.tool_choice = 'required';
     }
-    const { output } = await askOpenAISafe(prompt, model, undefined, params);
-    if (!output) {
+    const client = getOpenAIClient();
+    const response = await client.responses.create({
+        ...params,
+        model,
+        input: [{ role: 'user', content: prompt }],
+        stream: false,
+    });
+    if (!response.output) {
         throw new Error('No output from OpenAI');
     }
-    return validateOpenAI(output);
+    return validateOpenAI(response.output);
 }
 /**
  * Convert a raw web search response into a SearchResult instance.
@@ -109,9 +133,9 @@ export async function searchWithFormat({ prompt, model, responseSchema, useSearc
         .replace('{prompt}', prompt)
         .replace('{answer}', searchResult.answer)
         .replace('{sources}', sources);
-    const { parsed } = await askOpenAISafe(formattedPrompt, 'gpt-4.1-mini', responseSchema);
+    const { parsed } = await askLLMSafe({ prompt: formattedPrompt, model: 'gpt-4.1-mini', schema: responseSchema });
     if (!parsed) {
-        throw new Error('Failed to parse structured response from OpenAI');
+        throw new Error('Failed to parse structured response from LLM');
     }
     return parsed;
 }

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

@@ -1,11 +1,33 @@
-import { type BrandContext } from '../schemas/brand.schema.js';
-import { type ABSentiment } from '../schemas/sentiment.schema.js';
+import { Tool, type ModelConfig } from '../tool.js';
+import type { Message } from '../llm.js';
+import type { BrandContext } from '../schemas/brand.schema.js';
+import { type ABSentiment, type ABSentiments } from '../schemas/sentiment.schema.js';
+export interface SentimentExtractorConfig {
+    /** Additional instructions for sentiment extraction */
+    instructions?: string;
+    /** Brand context for focused analysis */
+    brand?: BrandContext | null;
+}
 /**
- * Extracts aspect-based sentiments from a text.
+ * A tool that extracts aspect-based sentiments from text.
  */
-export declare function extractAspectBasedSentiments(text: string | null, instructions?: string, model?: string): Promise<Array<ABSentiment>>;
-/**
- * Classifies multiple data records concurrently while preserving order.
- */
-export declare function extractABSForBrandBatch(texts: Array<string | null>, brand?: BrandContext | null, model?: string, maxConcurrency?: number): Promise<Array<Array<ABSentiment>>>;
+export declare class SentimentExtractor extends Tool<string | null, ABSentiments, Array<ABSentiment>> {
+    private readonly systemPrompt;
+    constructor(config: SentimentExtractorConfig | undefined, modelConfig: ModelConfig);
+    protected schema(): import("../../deps/jsr.io/@zod/zod/4.3.6/src/index.js").ZodObject<{
+        aspects: 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<{
+            aspect: import("../../deps/jsr.io/@zod/zod/4.3.6/src/index.js").ZodString;
+            sentiment: import("../../deps/jsr.io/@zod/zod/4.3.6/src/index.js").ZodEnum<{
+                positive: "positive";
+                negative: "negative";
+            }>;
+            reason: 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): Message[];
+    protected isEmpty(text: string | null): boolean;
+    protected extractResult(parsed: ABSentiments): Array<ABSentiment>;
+}
+export type { ABSentiment, ABSentiments } from '../schemas/sentiment.schema.js';
+export { ABSentimentSchema, ABSentimentsSchema } from '../schemas/sentiment.schema.js';
 //# sourceMappingURL=sentiment.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"sentiment.d.ts","sourceRoot":"","sources":["../../../src/src/tools/sentiment.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC/D,OAAO,EAAsB,KAAK,WAAW,EAAE,MAAM,gCAAgC,CAAC;AAwCtF;;GAEG;AACH,wBAAsB,4BAA4B,CACjD,IAAI,EAAE,MAAM,GAAG,IAAI,EACnB,YAAY,GAAE,MAAW,EACzB,KAAK,GAAE,MAAuB,GAC5B,OAAO,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,CAoB7B;AAED;;GAEG;AACH,wBAAsB,uBAAuB,CAC5C,KAAK,EAAE,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC,EAC3B,KAAK,GAAE,YAAY,GAAG,IAAW,EACjC,KAAK,GAAE,MAAuB,EAC9B,cAAc,GAAE,MAAY,GAC1B,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,CAAC,CAYpC"}
+{"version":3,"file":"sentiment.d.ts","sourceRoot":"","sources":["../../../src/src/tools/sentiment.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AACpD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC/D,OAAO,EAAsB,KAAK,WAAW,EAAE,KAAK,YAAY,EAAE,MAAM,gCAAgC,CAAC;AAwCzG,MAAM,WAAW,wBAAwB;IACxC,uDAAuD;IACvD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,yCAAyC;IACzC,KAAK,CAAC,EAAE,YAAY,GAAG,IAAI,CAAC;CAC5B;AAED;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,IAAI,CAAC,MAAM,GAAG,IAAI,EAAE,YAAY,EAAE,KAAK,CAAC,WAAW,CAAC,CAAC;IAC5F,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;gBAE1B,MAAM,EAAE,wBAAwB,YAAK,EAAE,WAAW,EAAE,WAAW;cAgBxD,MAAM;;;;;;;;;;IAIzB,SAAS,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,EAAE;cAQ7B,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO;cAIrC,aAAa,CAAC,MAAM,EAAE,YAAY,GAAG,KAAK,CAAC,WAAW,CAAC;CAG1E;AAED,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,gCAAgC,CAAC;AAChF,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC"}

package/esm/src/tools/sentiment.js

@@ -1,7 +1,6 @@
-import { mapParallel } from '../async.js';
-import { askOpenAISafe } from '../openai.js';
+import { Tool } from '../tool.js';
 import { ABSentimentsSchema } from '../schemas/sentiment.schema.js';
-import { dedent } from '../utils.js';
+import { dedent } from '../helpers/utils.js';
 const ABS_PROMPT_SYSTEM = dedent(`
 You're an expert in Aspect-Based Sentiment Analysis. Your task involves identifying specific
 entities mentioned in a text (e.g. a person, product, service, or experience) and determining the
@@ -37,32 +36,38 @@ Return the entities and their sentiments with reasons from the following text se
 {text}
 `);
 /**
- * Extracts aspect-based sentiments from a text.
+ * A tool that extracts aspect-based sentiments from text.
  */
-export async function extractAspectBasedSentiments(text, instructions = '', model = 'gpt-4.1-mini') {
-    if (text == null || text.trim() === '') {
-        return [];
+export class SentimentExtractor extends Tool {
+    systemPrompt;
+    constructor(config = {}, modelConfig) {
+        super(modelConfig);
+        const { instructions = '', brand = null } = config;
+        const brandInstructions = brand
+            ? dedent(`
+				When analyzing the text, pay special attention to any mentions of the brand "${brand.shortName}"
+				or its products/services (${brand.portfolio}). Ensure that any sentiments expressed toward this
+				brand or its offerings are accurately captured in your output. Respond in language code ${brand.language}.
+			`)
+            : '';
+        const combinedInstructions = [instructions, brandInstructions].filter(Boolean).join('\n\n');
+        this.systemPrompt = ABS_PROMPT_SYSTEM.replace('{instructions}', combinedInstructions);
     }
-    const promptSystem = ABS_PROMPT_SYSTEM.replace('{instructions}', instructions);
-    const promptUser = ABS_PROMPT_USER.replace('{text}', text);
-    const conversation = [
-        { role: 'system', content: promptSystem },
-        { role: 'user', content: promptUser }
-    ];
-    const { parsed } = await askOpenAISafe(conversation, model, ABSentimentsSchema);
-    if (!parsed) {
-        throw new Error('Failed to parse response from OpenAI');
+    schema() {
+        return ABSentimentsSchema;
+    }
+    prompt(text) {
+        const userPrompt = ABS_PROMPT_USER.replace('{text}', text ?? '');
+        return [
+            { role: 'system', content: this.systemPrompt },
+            { role: 'user', content: userPrompt }
+        ];
+    }
+    isEmpty(text) {
+        return text == null || text.trim() === '';
+    }
+    extractResult(parsed) {
+        return parsed.aspects;
     }
-    return parsed.aspects;
-}
-/**
- * Classifies multiple data records concurrently while preserving order.
- */
-export async function extractABSForBrandBatch(texts, brand = null, model = 'gpt-4.1-mini', maxConcurrency = 100) {
-    const instructions = brand ? dedent(`
-    When analyzing the text, pay special attention to any mentions of the brand "${brand.shortName}"
-    or its products/services (${brand.portfolio}). Ensure that any sentiments expressed toward this
-    brand or its offerings are accurately captured in your output. Respond in language code ${brand.language}.
-    `) : '';
-    return mapParallel(texts, maxConcurrency, (text) => extractAspectBasedSentiments(text, instructions, model));
 }
+export { ABSentimentSchema, ABSentimentsSchema } from '../schemas/sentiment.schema.js';

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

@@ -1,7 +1,7 @@
-import { type FlaggedBrand } from '../schemas/brand.schema.js';
+import type { FlaggedBrand } from '../schemas/brand.schema.js';
 import type { CategorizedSource, EnrichedSource, Source } from '../schemas/sources.schema.js';
 import { type TopicLabel } from './topics.js';
-import type { AIParams } from '../openai.js';
+import type { ProviderParams } from '../llm.js';
 import type { Entity } from './entities.js';
 export type { Source, EnrichedSource, CategorizedSource } from '../schemas/sources.schema.js';
 /**
@@ -27,13 +27,13 @@ export declare function collectURLs(sourceLists: Array<Array<Source>>, domains?:
 /**
  * Classifies an array of URLs into categories based on WEB_TAXONOMY.
  */
-export declare function classifyURLs(urls: Array<string>, model?: string, modelParams?: AIParams, maxConcurrency?: number): Promise<Record<string, TopicLabel | null>>;
+export declare function classifyURLs(urls: Array<string>, model?: string, modelParams?: ProviderParams, maxConcurrency?: number): Promise<Record<string, TopicLabel | null>>;
 /**
  * Creates a category mapper for sources by collecting unique URLs/domains and classifying them.
  */
-export declare function makeCategoryMapper(sourceLists: Array<Array<Source>>, domains?: boolean, model?: string, modelParams?: AIParams, maxConcurrency?: number): Promise<Record<string, TopicLabel | null>>;
+export declare function makeCategoryMapper(sourceLists: Array<Array<Source>>, domains?: boolean, model?: string, modelParams?: ProviderParams, maxConcurrency?: number): Promise<Record<string, TopicLabel | null>>;
 /**
  * Categorizes sources by assigning topic and subtopic to each EnrichedSource in-place(!).
  */
-export declare function categorizeSources(sourceLists: Array<Array<EnrichedSource>>, domains?: boolean, model?: string, modelParams?: AIParams, maxConcurrency?: number): Promise<Array<Array<CategorizedSource>>>;
+export declare function categorizeSources(sourceLists: Array<Array<EnrichedSource>>, domains?: boolean, model?: string, modelParams?: ProviderParams, maxConcurrency?: number): Promise<Array<Array<CategorizedSource>>>;
 //# sourceMappingURL=sources.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"sources.d.ts","sourceRoot":"","sources":["../../../src/src/tools/sources.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC/D,OAAO,KAAK,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,8BAA8B,CAAC;AAC9F,OAAO,EAA4C,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AACxF,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAE5C,YAAY,EAAE,MAAM,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AAE9F;;GAEG;AACH,wBAAgB,YAAY,CAC3B,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,KAAK,CAAC,YAAY,CAAC,EAC3B,QAAQ,GAAE,KAAK,CAAC,MAAM,CAAM,GAC1B,cAAc,CAoEhB;AAED,wBAAsB,aAAa,CAClC,OAAO,EAAE,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC,EACpC,MAAM,EAAE,KAAK,CAAC,YAAY,CAAC,EAC3B,QAAQ,GAAE,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAM,GACjC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC,CAAC,CAIvC;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CACtC,OAAO,EAAE,KAAK,CAAC,cAAc,CAAC,GAC5B;IAAE,eAAe,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAAC,YAAY,EAAE,KAAK,CAAC,MAAM,CAAC,CAAA;CAAE,CA8DjE;AAED,wBAAgB,qBAAqB,CACpC,OAAO,EAAE,KAAK,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC,GACnC;IAAE,eAAe,EAAE,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC;IAAC,YAAY,EAAE,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAA;CAAE,CAc/E;AAED;;GAEG;AACH,wBAAgB,WAAW,CAC1B,WAAW,EAAE,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,EACjC,OAAO,GAAE,OAAe,GACtB,KAAK,CAAC,MAAM,CAAC,CAgBf;AAiED;;GAEG;AACH,wBAAsB,YAAY,CACjC,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,EACnB,KAAK,GAAE,MAAkB,EACzB,WAAW,GAAE,QAA4C,EACzD,cAAc,GAAE,MAAY,GAC1B,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI,CAAC,CAAC,CAa5C;AAED;;GAEG;AACH,wBAAsB,kBAAkB,CACvC,WAAW,EAAE,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,EACjC,OAAO,GAAE,OAAe,EACxB,KAAK,GAAE,MAAkB,EACzB,WAAW,GAAE,QAA4C,EACzD,cAAc,GAAE,MAAY,GAC1B,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI,CAAC,CAAC,CAI5C;AAED;;GAEG;AACH,wBAAsB,iBAAiB,CACtC,WAAW,EAAE,KAAK,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC,EACzC,OAAO,GAAE,OAAe,EACxB,KAAK,GAAE,MAAkB,EACzB,WAAW,GAAE,QAA4C,EACzD,cAAc,GAAE,MAAY,GAC1B,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAiB1C"}
+{"version":3,"file":"sources.d.ts","sourceRoot":"","sources":["../../../src/src/tools/sources.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC/D,OAAO,KAAK,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,8BAA8B,CAAC;AAC9F,OAAO,EAA2B,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AACvE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAChD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAE5C,YAAY,EAAE,MAAM,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AAE9F;;GAEG;AACH,wBAAgB,YAAY,CAC3B,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,KAAK,CAAC,YAAY,CAAC,EAC3B,QAAQ,GAAE,KAAK,CAAC,MAAM,CAAM,GAC1B,cAAc,CAoEhB;AAED,wBAAsB,aAAa,CAClC,OAAO,EAAE,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC,EACpC,MAAM,EAAE,KAAK,CAAC,YAAY,CAAC,EAC3B,QAAQ,GAAE,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAM,GACjC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC,CAAC,CAIvC;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CACtC,OAAO,EAAE,KAAK,CAAC,cAAc,CAAC,GAC5B;IAAE,eAAe,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAAC,YAAY,EAAE,KAAK,CAAC,MAAM,CAAC,CAAA;CAAE,CA8DjE;AAED,wBAAgB,qBAAqB,CACpC,OAAO,EAAE,KAAK,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC,GACnC;IAAE,eAAe,EAAE,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC;IAAC,YAAY,EAAE,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAA;CAAE,CAc/E;AAED;;GAEG;AACH,wBAAgB,WAAW,CAC1B,WAAW,EAAE,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,EACjC,OAAO,GAAE,OAAe,GACtB,KAAK,CAAC,MAAM,CAAC,CAgBf;AA+DD;;GAEG;AACH,wBAAsB,YAAY,CACjC,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,EACnB,KAAK,GAAE,MAAkB,EACzB,WAAW,GAAE,cAAkD,EAC/D,cAAc,GAAE,MAAY,GAC1B,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI,CAAC,CAAC,CAc5C;AAED;;GAEG;AACH,wBAAsB,kBAAkB,CACvC,WAAW,EAAE,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,EACjC,OAAO,GAAE,OAAe,EACxB,KAAK,GAAE,MAAkB,EACzB,WAAW,GAAE,cAAkD,EAC/D,cAAc,GAAE,MAAY,GAC1B,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI,CAAC,CAAC,CAI5C;AAED;;GAEG;AACH,wBAAsB,iBAAiB,CACtC,WAAW,EAAE,KAAK,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC,EACzC,OAAO,GAAE,OAAe,EACxB,KAAK,GAAE,MAAkB,EACzB,WAAW,GAAE,cAAkD,EAC/D,cAAc,GAAE,MAAY,GAC1B,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAiB1C"}

package/esm/src/tools/sources.js

@@ -1,6 +1,5 @@
-import { mapParallel } from '../async.js';
 import { createBrandMatchKey } from './brands.js';
-import { assignTopic, createLabelSchema, toTopics } from './topics.js';
+import { TopicAssigner, toTopics } from './topics.js';
 /**
  * Checks if brand or competitor is mentioned in the source title or URL.
  */
@@ -222,16 +221,16 @@ const WEB_TAXONOMY = {
         'Personal / Portfolio Site'
     ]
 };
-const WEB_LABEL_SCHEMA = createLabelSchema({ topics: toTopics(WEB_TAXONOMY) });
-const WEB_TAXONOMY_SERIALIZED = JSON.stringify(WEB_TAXONOMY, null, 2);
+const WEB_TAXONOMY_TOPICS = toTopics(WEB_TAXONOMY);
 /**
  * Classifies an array of URLs into categories based on WEB_TAXONOMY.
  */
 export async function classifyURLs(urls, model = 'gpt-5.1', modelParams = { reasoning: { effort: 'none' } }, maxConcurrency = 100) {
-    const labels = await mapParallel(urls, maxConcurrency, url => assignTopic(url, WEB_TAXONOMY_SERIALIZED, WEB_LABEL_SCHEMA, model, modelParams));
+    const assigner = new TopicAssigner({ taxonomy: WEB_TAXONOMY_TOPICS }, { model, modelParams, maxConcurrency });
+    const results = await assigner.batch(urls);
     const urlToCategory = {};
     urls.forEach((url, index) => {
-        urlToCategory[url] = labels[index];
+        urlToCategory[url] = results.toArray()[index];
     });
     return urlToCategory;
 }