@graphext/cuery 0.4.0 → 0.5.2

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

@@ -1,5 +1,6 @@
 import { z } from '../../deps/jsr.io/@zod/zod/4.3.6/src/index.js';
-import { type AIParams } from '../openai.js';
+import { Tool, type ModelConfig } from '../tool.js';
+import type { Message } from '../llm.js';
 import { type TopicType, type TaxonomyType, type TopicLabel } from '../schemas/topics.schema.js';
 export type { TopicType, TaxonomyType, TopicLabel };
 /**
@@ -48,27 +49,54 @@ export declare function createLabelSchema(taxonomy: TaxonomyType): z.ZodObject<{
         [x: string]: string;
     }>;
 }, z.core.$strip>;
-/**
- * Assigns a topic and subtopic to a single text using an LLM call.
- */
-export declare function assignTopic(text: string | null, taxonomy: TaxonomyType | Array<TopicType> | string, labelSchema: z.ZodType<TopicLabel>, model?: string, modelParams?: AIParams): Promise<TopicLabel | null>;
-/**
- * Assigns topics to multiple texts concurrently while preserving order.
- */
-export declare function assignTopics(texts: Array<string | null>, taxonomy: TaxonomyType | Array<TopicType>, model?: string, modelParams?: AIParams, maxConcurrency?: number): Promise<Array<TopicLabel | null>>;
-export interface TopicExtractionOptions {
-    records: Array<Record<string, unknown>>;
+export interface TopicExtractorConfig {
+    /** Maximum number of top-level topics (default: 10) */
     nTopics?: number;
+    /** Maximum number of subtopics per topic (default: 5) */
     nSubtopics?: number;
+    /** Additional instructions */
     instructions?: string;
+    /** Maximum number of records to sample (default: 500) */
     maxSamples?: number;
-    model?: string;
-    modelParams?: AIParams;
-    maxRetries?: number;
+    /** Language for topics (default: same as records) */
     language?: string;
 }
 /**
- * Extracts a topic hierarchy from an array of records using an LLM.
+ * A tool that extracts a topic taxonomy from a set of records.
  */
-export declare function extractTopics({ records, nTopics, nSubtopics, instructions, maxSamples, model, modelParams, maxRetries, language }: TopicExtractionOptions): Promise<TaxonomyType>;
+export declare class TopicExtractor extends Tool<Array<Record<string, unknown>>, TaxonomyType, TaxonomyType> {
+    private readonly maxSamples;
+    private readonly promptTemplate;
+    constructor(config: TopicExtractorConfig | undefined, modelConfig: ModelConfig);
+    protected schema(): z.ZodObject<{
+        topics: z.ZodArray<z.ZodObject<{
+            topic: z.ZodString;
+            subtopics: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    protected prompt(records: Array<Record<string, unknown>>): string;
+    protected isEmpty(records: Array<Record<string, unknown>>): boolean;
+    /**
+     * Not supported. TopicExtractor is an aggregation operation that extracts
+     * a single taxonomy from many records. Use invoke() instead.
+     */
+    batch(): never;
+}
+/**
+ * Configuration for the TopicAssigner tool.
+ */
+export interface TopicAssignerConfig {
+    taxonomy: TaxonomyType | Array<TopicType>;
+}
+/**
+ * A tool that assigns topic and subtopic labels to text based on a taxonomy.
+ */
+export declare class TopicAssigner extends Tool<string | null, TopicLabel, TopicLabel> {
+    private readonly labelSchema;
+    private readonly systemPrompt;
+    constructor(config: TopicAssignerConfig, modelConfig: ModelConfig);
+    protected schema(): z.ZodType<TopicLabel, unknown, z.core.$ZodTypeInternals<TopicLabel, unknown>>;
+    protected prompt(text: string | null): Message[];
+    protected isEmpty(text: string | null): boolean;
+}
 //# sourceMappingURL=topics.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"topics.d.ts","sourceRoot":"","sources":["../../../src/src/tools/topics.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,+CAA+C,CAAC;AAElE,OAAO,EAAsC,KAAK,QAAQ,EAAE,MAAM,cAAc,CAAC;AAEjF,OAAO,EAEN,KAAK,SAAS,EACd,KAAK,YAAY,EACjB,KAAK,UAAU,EACf,MAAM,6BAA6B,CAAC;AAIrC,YAAY,EAAE,SAAS,EAAE,YAAY,EAAE,UAAU,EAAE,CAAC;AAuEpD;;;GAGG;AACH,eAAO,MAAM,KAAK;;;iBAShB,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,YAAY;;;;;iBAEvB,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,QAAQ;;;;;iBAEnB,CAAC;AAEH;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC,GAAG,KAAK,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,KAAK,CAAC,MAAM,CAAC,CAAA;CAAE,CAAC,CAKpH;AACD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,YAAY;;;;;;;kBAmBvD;AA+CD;;GAEG;AACH,wBAAsB,WAAW,CAChC,IAAI,EAAE,MAAM,GAAG,IAAI,EACnB,QAAQ,EAAE,YAAY,GAAG,KAAK,CAAC,SAAS,CAAC,GAAG,MAAM,EAClD,WAAW,EAAE,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC,EAClC,KAAK,GAAE,MAAkB,EACzB,WAAW,GAAE,QAA4C,GACvD,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CA2B5B;AAED;;GAEG;AACH,wBAAgB,YAAY,CAC3B,KAAK,EAAE,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC,EAC3B,QAAQ,EAAE,YAAY,GAAG,KAAK,CAAC,SAAS,CAAC,EACzC,KAAK,GAAE,MAAkB,EACzB,WAAW,GAAE,QAA4C,EACzD,cAAc,GAAE,MAAY,GAC1B,OAAO,CAAC,KAAK,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC,CAgBnC;AAED,MAAM,WAAW,sBAAsB;IACtC,OAAO,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACxC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,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;;GAEG;AACH,wBAAsB,aAAa,CAAC,EACnC,OAAO,EACP,OAAY,EACZ,UAAc,EACd,YAAiB,EACjB,UAAgB,EAChB,KAAiB,EACjB,WAAgB,EAChB,UAAc,EACd,QAA6C,EAC7C,EAAE,sBAAsB,GAAG,OAAO,CAAC,YAAY,CAAC,CAsChD"}
+{"version":3,"file":"topics.d.ts","sourceRoot":"","sources":["../../../src/src/tools/topics.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,+CAA+C,CAAC;AAClE,OAAO,EAAE,IAAI,EAAE,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AACpD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,EAEN,KAAK,SAAS,EACd,KAAK,YAAY,EACjB,KAAK,UAAU,EACf,MAAM,6BAA6B,CAAC;AAIrC,YAAY,EAAE,SAAS,EAAE,YAAY,EAAE,UAAU,EAAE,CAAC;AA+EpD;;;GAGG;AACH,eAAO,MAAM,KAAK;;;iBAShB,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,YAAY;;;;;iBAEvB,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,QAAQ;;;;;iBAEnB,CAAC;AAEH;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC,GAAG,KAAK,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,KAAK,CAAC,MAAM,CAAC,CAAA;CAAE,CAAC,CAKpH;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,YAAY;;;;;;;kBAmBvD;AA+BD,MAAM,WAAW,oBAAoB;IACpC,uDAAuD;IACvD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yDAAyD;IACzD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8BAA8B;IAC9B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,yDAAyD;IACzD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qDAAqD;IACrD,QAAQ,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,qBAAa,cAAe,SAAQ,IAAI,CACvC,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAC9B,YAAY,EACZ,YAAY,CACZ;IACA,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;gBAE5B,MAAM,EAAE,oBAAoB,YAAK,EAAE,WAAW,EAAE,WAAW;cAkBpD,MAAM;;;;;;IAIzB,SAAS,CAAC,MAAM,CAAC,OAAO,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;cAQrC,OAAO,CAAC,OAAO,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,OAAO;IAI5E;;;OAGG;IACM,KAAK,IAAI,KAAK;CAOvB;AAyBD;;GAEG;AACH,MAAM,WAAW,mBAAmB;IACnC,QAAQ,EAAE,YAAY,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC;CAC1C;AAED;;GAEG;AACH,qBAAa,aAAc,SAAQ,IAAI,CAAC,MAAM,GAAG,IAAI,EAAE,UAAU,EAAE,UAAU,CAAC;IAC7E,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAwB;IACpD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;gBAE1B,MAAM,EAAE,mBAAmB,EAAE,WAAW,EAAE,WAAW;cAiB9C,MAAM;IAIzB,SAAS,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,EAAE;cAQ7B,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO;CAGxD"}

package/esm/src/tools/topics.js

@@ -1,9 +1,11 @@
 /* eslint no-console: ["warn", { allow: ["log", "warn", "error"] }] */
 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 { Tool } from '../tool.js';
 import { TopicSchema } from '../schemas/topics.schema.js';
-import { dedent, formatRecordsAttrWise } from '../utils.js';
+import { dedent, formatRecordsAttrWise } from '../helpers/utils.js';
+// =============================================================================
+// Helper Functions
+// =============================================================================
 /**
  * Levenshtein distance implementation for string similarity validation
  */
@@ -61,6 +63,9 @@ function validateSubtopics(topic, subtopics) {
     }
     return errors;
 }
+// =============================================================================
+// Schemas
+// =============================================================================
 /**
  * Topic schema with subtopic validation
  * Validates that subtopics are sufficiently distinct from each other and from the parent topic.
@@ -120,6 +125,9 @@ export function createLabelSchema(taxonomy) {
         }
     });
 }
+// =============================================================================
+// TopicExtractor
+// =============================================================================
 const TOPICS_PROMPT = dedent(`
 # Instructions
 
@@ -144,6 +152,48 @@ The taxonomy should follow the MECE framework (Mutually Exclusive, Collectively
 
 {records}
 `);
+/**
+ * A tool that extracts a topic taxonomy from a set of records.
+ */
+export class TopicExtractor extends Tool {
+    maxSamples;
+    promptTemplate;
+    constructor(config = {}, modelConfig) {
+        super(modelConfig);
+        const { nTopics = 10, nSubtopics = 5, instructions = '', maxSamples = 500, language = 'The same language as the records' } = config;
+        this.maxSamples = maxSamples;
+        this.promptTemplate = TOPICS_PROMPT
+            .replace('{n_topics}', String(nTopics))
+            .replace('{n_subtopics}', String(nSubtopics))
+            .replace('{instructions}', instructions)
+            .replace('{language}', language);
+    }
+    schema() {
+        return Taxonomy;
+    }
+    prompt(records) {
+        const sampledRecords = records.length > this.maxSamples
+            ? records.slice(0, this.maxSamples)
+            : records;
+        const formattedRecords = formatRecordsAttrWise(sampledRecords);
+        return this.promptTemplate.replace('{records}', formattedRecords);
+    }
+    isEmpty(records) {
+        return !records || records.length === 0;
+    }
+    /**
+     * Not supported. TopicExtractor is an aggregation operation that extracts
+     * a single taxonomy from many records. Use invoke() instead.
+     */
+    batch() {
+        throw new Error('TopicExtractor.batch() is not supported. ' +
+            'This tool extracts a single taxonomy from many records (aggregation). ' +
+            'Use invoke() with all records instead.');
+    }
+}
+// =============================================================================
+// TopicAssigner
+// =============================================================================
 const LABEL_PROMPT_SYSTEM = dedent(`
 You're task is to use the following hierarchy of topics and subtopics (in json format),
 to assign the correct topic and subtopic to each text in the input.
@@ -162,74 +212,33 @@ Assign the correct topic and subtopic to the following text.
 {text}
 `);
 /**
- * Assigns a topic and subtopic to a single text using an LLM call.
+ * A tool that assigns topic and subtopic labels to text based on a taxonomy.
  */
-export async function assignTopic(text, taxonomy, labelSchema, model = 'gpt-5.1', modelParams = { reasoning: { effort: 'none' } }) {
-    if (text == null || text.trim() === '') {
-        return null;
-    }
-    const systemPrompt = LABEL_PROMPT_SYSTEM.replace('{taxonomy}', typeof taxonomy === 'string' ? taxonomy : JSON.stringify(taxonomy, null, 2));
-    const userPrompt = LABEL_PROMPT_USER.replace('{text}', text);
-    const prompts = [
-        { role: 'system', content: systemPrompt },
-        { role: 'user', content: userPrompt }
-    ];
-    try {
-        const { parsed, error } = await askOpenAISafe(prompts, model, labelSchema, modelParams);
-        if (error != null || parsed == null) {
-            return null;
-        }
-        return parsed;
+export class TopicAssigner extends Tool {
+    labelSchema;
+    systemPrompt;
+    constructor(config, modelConfig) {
+        super(modelConfig);
+        const { taxonomy } = config;
+        // Normalize taxonomy to TaxonomyType
+        const normalizedTaxonomy = Array.isArray(taxonomy)
+            ? { topics: taxonomy }
+            : taxonomy;
+        // Build schema and system prompt once in constructor
+        this.labelSchema = createLabelSchema(normalizedTaxonomy);
+        this.systemPrompt = LABEL_PROMPT_SYSTEM.replace('{taxonomy}', JSON.stringify(normalizedTaxonomy, null, 2));
     }
-    catch (error) {
-        console.warn(`Failed to assign topic for text "${text.substring(0, 50)}...":`, error);
-        return null;
+    schema() {
+        return this.labelSchema;
     }
-}
-/**
- * Assigns topics to multiple texts concurrently while preserving order.
- */
-export function assignTopics(texts, taxonomy, model = 'gpt-5.1', modelParams = { reasoning: { effort: 'none' } }, maxConcurrency = 100) {
-    // Precompute normalized taxonomy and label schema once for whole batch
-    const normalizedTaxonomy = Array.isArray(taxonomy)
-        ? { topics: taxonomy }
-        : taxonomy;
-    const labelSchema = createLabelSchema(normalizedTaxonomy);
-    const serializedTaxonomy = JSON.stringify(normalizedTaxonomy, null, 2);
-    return mapParallel(texts, maxConcurrency, text => assignTopic(text, serializedTaxonomy, labelSchema, model, modelParams));
-}
-/**
- * Extracts a topic hierarchy from an array of records using an LLM.
- */
-export async function extractTopics({ records, nTopics = 10, nSubtopics = 5, instructions = '', maxSamples = 500, model = 'gpt-4.1', modelParams = {}, maxRetries = 8, language = 'The same language as the records' }) {
-    if (!records || records.length === 0) {
-        return { topics: [] };
-    }
-    const sampledRecords = records.length > maxSamples
-        ? records.slice(0, maxSamples)
-        : records;
-    const formattedRecords = formatRecordsAttrWise(sampledRecords);
-    const prompt = TOPICS_PROMPT
-        .replace('{n_topics}', String(nTopics))
-        .replace('{n_subtopics}', String(nSubtopics))
-        .replace('{instructions}', instructions)
-        .replace('{records}', formattedRecords)
-        .replace('{language}', language);
-    const { parsed, output_text, error } = await askOpenAISafe(prompt, model, Taxonomy, modelParams, maxRetries, 'return');
-    if (error != null) {
-        if (output_text == null) {
-            throw new Error('Failed to get response from OpenAI');
-        }
-        try {
-            const taxonomy = JSON.parse(output_text);
-            return TaxonomyBase.parse(taxonomy);
-        }
-        catch (parseError) {
-            throw new Error(`Failed to parse response even without validation: ${parseError instanceof Error ? parseError.message : String(parseError)}`);
-        }
+    prompt(text) {
+        const userPrompt = LABEL_PROMPT_USER.replace('{text}', text ?? '');
+        return [
+            { role: 'system', content: this.systemPrompt },
+            { role: 'user', content: userPrompt }
+        ];
     }
-    if (parsed == null) {
-        throw new Error('Failed to parse response from OpenAI');
+    isEmpty(text) {
+        return text == null || text.trim() === '';
     }
-    return parsed;
 }

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

@@ -1,44 +1,35 @@
+import { Tool, type ModelConfig } from '../tool.js';
 import type { BrandContext } from '../schemas/brand.schema.js';
-export interface translateParams {
-    keyword: string;
+export interface KeywordTranslatorConfig {
+    /** Brand context for disambiguation */
+    brandContext: BrandContext;
+    /** Language for the output prompt (default: 'en') */
     language?: string;
-    model?: string;
+    /** Additional instructions */
     instructions?: string;
-    brandContext: BrandContext;
 }
 /**
- * Translates a single Google search keyword into an equivalent LLM prompt.
+ * A tool that converts Google search keywords into natural language LLM prompts.
+ * Uses raw text mode (no schema) since the output is plain text.
  */
-export declare function translate({ keyword, language, model, brandContext, instructions }: translateParams): Promise<string>;
-/**
- * Translates multiple Google search keywords to LLM prompts concurrently while preserving order.
- */
-export interface translateBatchParams {
-    keywords: Array<string>;
-    language?: string;
-    model?: string;
-    maxConcurrency?: number;
-    instructions?: string;
-    brandContext: BrandContext;
+export declare class KeywordTranslator extends Tool<string | null, string, string> {
+    private readonly promptTemplate;
+    constructor(config: KeywordTranslatorConfig, modelConfig: ModelConfig);
+    protected prompt(keyword: string | null): string;
+    protected isEmpty(keyword: string | null): boolean;
 }
-export declare function translateBatch(params: translateBatchParams): Promise<Array<string>>;
-export interface reverseTranslateParams {
-    prompt: string;
+export interface PromptToKeywordConfig {
+    /** Language for the output keyword (default: 'en') */
     language?: string;
-    model?: string;
 }
 /**
- * Converts a natural language prompt into an equivalent Google search keyword.
+ * A tool that converts natural language prompts into Google search keywords.
+ * Uses raw text mode (no schema) since the output is plain text.
  */
-export declare function reverseTranslate({ prompt, language, model }: reverseTranslateParams): Promise<string>;
-export interface reverseTranslateBatchParams {
-    prompts: Array<string>;
-    language?: string;
-    model?: string;
-    maxConcurrency?: number;
+export declare class PromptToKeyword extends Tool<string | null, string, string> {
+    private readonly promptTemplate;
+    constructor(config: PromptToKeywordConfig | undefined, modelConfig: ModelConfig);
+    protected prompt(text: string | null): string;
+    protected isEmpty(text: string | null): boolean;
 }
-/**
- * Converts multiple natural language prompts to Google search keywords concurrently while preserving order.
- */
-export declare function reverseTranslateBatch(params: reverseTranslateBatchParams): Promise<Array<string>>;
 //# sourceMappingURL=translate.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"translate.d.ts","sourceRoot":"","sources":["../../../src/src/tools/translate.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AA+C/D,MAAM,WAAW,eAAe;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,YAAY,CAAC;CAC3B;AAED;;GAEG;AACH,wBAAsB,SAAS,CAC9B,EAAE,OAAO,EAAE,QAAe,EAAE,KAAoB,EAAE,YAAY,EAAE,YAAiB,EAAE,EAAE,eAAe,GAClG,OAAO,CAAC,MAAM,CAAC,CAcjB;AAED;;GAEG;AAEH,MAAM,WAAW,oBAAoB;IACpC,QAAQ,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,YAAY,CAAC;CAC3B;AAED,wBAAsB,cAAc,CACnC,MAAM,EAAE,oBAAoB,GAC1B,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAQxB;AA+BD,MAAM,WAAW,sBAAsB;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,wBAAsB,gBAAgB,CACrC,EAAE,MAAM,EAAE,QAAe,EAAE,KAAsB,EAAE,EAAE,sBAAsB,GACzE,OAAO,CAAC,MAAM,CAAC,CAWjB;AAED,MAAM,WAAW,2BAA2B;IAC3C,OAAO,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,cAAc,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;GAEG;AACH,wBAAsB,qBAAqB,CAC1C,MAAM,EAAE,2BAA2B,GACjC,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAQxB"}
+{"version":3,"file":"translate.d.ts","sourceRoot":"","sources":["../../../src/src/tools/translate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AAEpD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AA+C/D,MAAM,WAAW,uBAAuB;IACvC,uCAAuC;IACvC,YAAY,EAAE,YAAY,CAAC;IAC3B,qDAAqD;IACrD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,8BAA8B;IAC9B,YAAY,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;GAGG;AACH,qBAAa,iBAAkB,SAAQ,IAAI,CAAC,MAAM,GAAG,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC;IACzE,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;gBAE5B,MAAM,EAAE,uBAAuB,EAAE,WAAW,EAAE,WAAW;IAarE,SAAS,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;cAIpB,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO;CAG3D;AAmCD,MAAM,WAAW,qBAAqB;IACrC,sDAAsD;IACtD,QAAQ,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,qBAAa,eAAgB,SAAQ,IAAI,CAAC,MAAM,GAAG,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC;IACvE,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;gBAE5B,MAAM,EAAE,qBAAqB,YAAK,EAAE,WAAW,EAAE,WAAW;IASxE,SAAS,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;cAIjB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO;CAGxD"}

package/esm/src/tools/translate.js

@@ -1,6 +1,5 @@
-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 TRANSLATE_PROMPT = dedent(`
 You are an expert in understanding search intent and conversational AI interactions.
 
@@ -33,7 +32,7 @@ You will receive brand context (sector, country). Follow these rules strictly:
 - WRONG: "Tell me about geography" (ignores sector context)
 - CORRECT: "What is GEO in AI visibility and search optimization?" (uses sector to disambiguate the acronym)
 
-{additional_instructions}
+{instructions}
 
 # Keyword
 
@@ -46,25 +45,31 @@ You will receive brand context (sector, country). Follow these rules strictly:
 Return only the converted prompt, nothing else.
 `);
 /**
- * Translates a single Google search keyword into an equivalent LLM prompt.
+ * A tool that converts Google search keywords into natural language LLM prompts.
+ * Uses raw text mode (no schema) since the output is plain text.
  */
-export async function translate({ keyword, language = 'en', model = 'gpt-5-mini', brandContext, instructions = '' }) {
-    const prompt = TRANSLATE_PROMPT
-        .replace('{keyword}', keyword)
-        .replace('{language}', language)
-        .replace('{sector}', brandContext.sector)
-        .replace('{country}', brandContext.country)
-        .replace('{additional_instructions}', instructions);
-    const { parsed } = await askOpenAISafe(prompt, model);
-    if (!parsed) {
-        throw new Error('Failed to parse translation from OpenAI response');
+export class KeywordTranslator extends Tool {
+    promptTemplate;
+    constructor(config, modelConfig) {
+        super(modelConfig);
+        const { brandContext, language = 'en', instructions = '' } = config;
+        this.promptTemplate = TRANSLATE_PROMPT
+            .replace('{language}', language)
+            .replace('{sector}', brandContext.sector)
+            .replace('{country}', brandContext.country)
+            .replace('{instructions}', instructions);
+    }
+    // No schema() override - uses default null for raw text mode
+    prompt(keyword) {
+        return this.promptTemplate.replace('{keyword}', keyword ?? '');
+    }
+    isEmpty(keyword) {
+        return keyword == null || keyword.trim() === '';
     }
-    return parsed;
-}
-export async function translateBatch(params) {
-    const { keywords, language = 'en', model = 'gpt-4.1-mini', maxConcurrency = 100, brandContext, instructions = '' } = params;
-    return mapParallel(keywords, maxConcurrency, kwd => translate({ keyword: kwd, language, model, brandContext, instructions }));
 }
+// =============================================================================
+// PromptToKeyword (LLM prompt → keyword)
+// =============================================================================
 const REVERSE_TRANSLATE_PROMPT = dedent(`
 You are an expert in understanding search intent.
 
@@ -94,22 +99,21 @@ Otherwise, Google keyword planner will not accept it.
 Return only the keyword, nothing else.
 `);
 /**
- * Converts a natural language prompt into an equivalent Google search keyword.
+ * A tool that converts natural language prompts into Google search keywords.
+ * Uses raw text mode (no schema) since the output is plain text.
  */
-export async function reverseTranslate({ prompt, language = 'en', model = 'gpt-4.1-mini' }) {
-    const requestPrompt = REVERSE_TRANSLATE_PROMPT
-        .replace('{prompt}', prompt)
-        .replace('{language}', language);
-    const { parsed } = await askOpenAISafe(requestPrompt, model);
-    if (!parsed) {
-        throw new Error('Failed to parse reverse translation from OpenAI response');
+export class PromptToKeyword extends Tool {
+    promptTemplate;
+    constructor(config = {}, modelConfig) {
+        super(modelConfig);
+        const { language = 'en' } = config;
+        this.promptTemplate = REVERSE_TRANSLATE_PROMPT.replace('{language}', language);
+    }
+    // No schema() override - uses default null for raw text mode
+    prompt(text) {
+        return this.promptTemplate.replace('{prompt}', text ?? '');
+    }
+    isEmpty(text) {
+        return text == null || text.trim() === '';
     }
-    return parsed;
-}
-/**
- * Converts multiple natural language prompts to Google search keywords concurrently while preserving order.
- */
-export async function reverseTranslateBatch(params) {
-    const { prompts, language = 'en', model = 'gpt-5-mini', maxConcurrency = 100 } = params;
-    return mapParallel(prompts, maxConcurrency, p => reverseTranslate({ prompt: p, language, model }));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@graphext/cuery",
-  "version": "0.4.0",
+  "version": "0.5.2",
   "description": "Cuery tools for AI-powered keyword research and brand analysis",
   "repository": {
     "type": "git",
@@ -24,6 +24,7 @@
   },
   "scripts": {},
   "dependencies": {
+    "@google/genai": "^1.37.0",
     "google-auth-library": "^10.4.0",
     "openai": "^6.9.1",
     "tldts": "^6.1.71",

package/script/browser.d.ts

@@ -8,5 +8,5 @@
  * @module
  */
 export * from './src/schemas/index.js';
-export * from './src/tools/seedKeywords.js';
+export * from './src/helpers/seedKeywords.js';
 //# sourceMappingURL=browser.d.ts.map

package/script/browser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,cAAc,wBAAwB,CAAC;AAGvC,cAAc,6BAA6B,CAAC"}
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,cAAc,wBAAwB,CAAC;AAGvC,cAAc,+BAA+B,CAAC"}

package/script/browser.js

@@ -26,4 +26,4 @@ Object.defineProperty(exports, "__esModule", { value: true });
 // Types and schemas (no runtime dependencies)
 __exportStar(require("./src/schemas/index.js"), exports);
 // Pure functions for seed keyword handling (no external dependencies)
-__exportStar(require("./src/tools/seedKeywords.js"), exports);
+__exportStar(require("./src/helpers/seedKeywords.js"), exports);

package/script/mod.d.ts

@@ -3,19 +3,22 @@
  *
  * @module
  */
+export * from './src/llm.js';
+export { BatchResponse } from './src/response.js';
+export { getProvider, getProviderForModel, getModelPricing, getModelInfo, calculateCost, type ModelPricing, type ModelInfo, } from './src/providers/index.js';
 export * from './src/tools/keywords.js';
 export * from './src/tools/classifier.js';
 export * from './src/tools/funnel.js';
 export * from './src/tools/personas.js';
 export * from './src/tools/search.js';
 export * from './src/tools/topics.js';
-export * from './src/utils.js';
+export * from './src/helpers/utils.js';
 export * from './src/tools/brands.js';
 export * from './src/tools/translate.js';
 export * from './src/tools/sentiment.js';
 export * from './src/tools/sources.js';
 export * from './src/tools/entities.js';
-export * from './src/tools/seedKeywords.js';
+export * from './src/helpers/seedKeywords.js';
 export * from './src/tools/generic.js';
 export * from './src/api.js';
 export * from './src/apis/chatgptScraper/index.js';

package/script/mod.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../src/mod.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,yBAAyB,CAAC;AACxC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,uBAAuB,CAAC;AACtC,cAAc,yBAAyB,CAAC;AACxC,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AACtC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,uBAAuB,CAAC;AACtC,cAAc,0BAA0B,CAAC;AACzC,cAAc,0BAA0B,CAAC;AACzC,cAAc,wBAAwB,CAAC;AACvC,cAAc,yBAAyB,CAAC;AACxC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,wBAAwB,CAAC;AACvC,cAAc,cAAc,CAAC;AAC7B,cAAc,oCAAoC,CAAC;AACnD,cAAc,wCAAwC,CAAC;AACvD,cAAc,wBAAwB,CAAC"}
+{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../src/mod.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,cAAc,cAAc,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,EACN,WAAW,EACX,mBAAmB,EACnB,eAAe,EACf,YAAY,EACZ,aAAa,EACb,KAAK,YAAY,EACjB,KAAK,SAAS,GACd,MAAM,0BAA0B,CAAC;AAGlC,cAAc,yBAAyB,CAAC;AACxC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,uBAAuB,CAAC;AACtC,cAAc,yBAAyB,CAAC;AACxC,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AACtC,cAAc,wBAAwB,CAAC;AACvC,cAAc,uBAAuB,CAAC;AACtC,cAAc,0BAA0B,CAAC;AACzC,cAAc,0BAA0B,CAAC;AACzC,cAAc,wBAAwB,CAAC;AACvC,cAAc,yBAAyB,CAAC;AACxC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,wBAAwB,CAAC;AACvC,cAAc,cAAc,CAAC;AAC7B,cAAc,oCAAoC,CAAC;AACnD,cAAc,wCAAwC,CAAC;AACvD,cAAc,wBAAwB,CAAC"}

package/script/mod.js

@@ -19,19 +19,31 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.calculateCost = exports.getModelInfo = exports.getModelPricing = exports.getProviderForModel = exports.getProvider = exports.BatchResponse = void 0;
+// Core LLM interface and types
+__exportStar(require("./src/llm.js"), exports);
+var response_js_1 = require("./src/response.js");
+Object.defineProperty(exports, "BatchResponse", { enumerable: true, get: function () { return response_js_1.BatchResponse; } });
+var index_js_1 = require("./src/providers/index.js");
+Object.defineProperty(exports, "getProvider", { enumerable: true, get: function () { return index_js_1.getProvider; } });
+Object.defineProperty(exports, "getProviderForModel", { enumerable: true, get: function () { return index_js_1.getProviderForModel; } });
+Object.defineProperty(exports, "getModelPricing", { enumerable: true, get: function () { return index_js_1.getModelPricing; } });
+Object.defineProperty(exports, "getModelInfo", { enumerable: true, get: function () { return index_js_1.getModelInfo; } });
+Object.defineProperty(exports, "calculateCost", { enumerable: true, get: function () { return index_js_1.calculateCost; } });
+// Tools
 __exportStar(require("./src/tools/keywords.js"), exports);
 __exportStar(require("./src/tools/classifier.js"), exports);
 __exportStar(require("./src/tools/funnel.js"), exports);
 __exportStar(require("./src/tools/personas.js"), exports);
 __exportStar(require("./src/tools/search.js"), exports);
 __exportStar(require("./src/tools/topics.js"), exports);
-__exportStar(require("./src/utils.js"), exports);
+__exportStar(require("./src/helpers/utils.js"), exports);
 __exportStar(require("./src/tools/brands.js"), exports);
 __exportStar(require("./src/tools/translate.js"), exports);
 __exportStar(require("./src/tools/sentiment.js"), exports);
 __exportStar(require("./src/tools/sources.js"), exports);
 __exportStar(require("./src/tools/entities.js"), exports);
-__exportStar(require("./src/tools/seedKeywords.js"), exports);
+__exportStar(require("./src/helpers/seedKeywords.js"), exports);
 __exportStar(require("./src/tools/generic.js"), exports);
 __exportStar(require("./src/api.js"), exports);
 __exportStar(require("./src/apis/chatgptScraper/index.js"), exports);

package/script/src/api.d.ts

@@ -1,5 +1,4 @@
 import { type JobId } from './apis/chatgptScraper/index.js';
-import { ModelId } from './models.js';
 import { type Entity } from './schemas/entity.schema.js';
 import { type Funnel } from './schemas/funnel.schema.js';
 import type { ModelIdentifier } from './schemas/models.schema.js';
@@ -24,8 +23,40 @@ export type EnrichedModelResponse = {
     rankedBrandsInSourceTitles: Array<string>;
     rankedBrandsInSourceDomains: Array<string>;
 };
-export declare function queryModel(prompts: Array<string | JobId>, model: ModelIdentifier | ModelId, searchCountry?: string | null): Promise<Array<ModelResponse>>;
+export declare function queryModel(prompts: Array<string | JobId>, model: ModelIdentifier, searchCountry?: string | null): Promise<Array<ModelResponse>>;
 export declare function classifyIntent(texts: Array<string>): Promise<Array<string | null>>;
+export declare function extractTopics(params: {
+    records: Array<Record<string, unknown>>;
+    maxSamples?: number;
+    instructions?: string;
+    language?: string;
+    model?: string;
+}): Promise<{
+    topics: {
+        topic: string;
+        subtopics: string[];
+    }[];
+} | null>;
+export declare function generatePersonas(params: {
+    sector: string;
+    market: string;
+    language: string;
+    brand?: string;
+    brandDomain?: string;
+    count?: number;
+    briefing?: string;
+    instructions?: string;
+    userLanguage?: string;
+    personas?: Array<Persona>;
+    model?: string;
+}): Promise<{
+    personas: {
+        name: string;
+        description: string;
+        keywordSeeds: string[];
+    }[];
+    explanation: string;
+} | null>;
 export declare function extractAndAssignTopics(texts: Array<string>): Promise<Array<{
     topic: string | null;
     subtopic: string | null;
@@ -36,7 +67,7 @@ export declare function assignFunnelStages(texts: Array<string>, funnel: Funnel)
 }>>;
 export declare function classifyIntoPersonas(texts: Array<string>, personas: Array<Persona>): Promise<Array<Array<string> | null>>;
 export declare function classifyBrandedNonBranded(texts: Array<string>): Promise<Array<string | null>>;
-export declare function extractEntities(texts: Array<string>): Promise<Array<Array<Entity>>>;
-export declare function scorePurchaseProbability(texts: Array<string>, numDays?: number): Promise<Array<number>>;
-export declare function scoreRelevance(prompts: Array<string>, context: BrandContext): Promise<Array<number>>;
+export declare function extractEntities(texts: Array<string>): Promise<Array<Array<Entity> | null>>;
+export declare function scorePurchaseProbability(texts: Array<string>, numDays?: number): Promise<Array<number | null>>;
+export declare function scoreRelevance(prompts: Array<string>, context: BrandContext): Promise<Array<number | null>>;
 //# sourceMappingURL=api.d.ts.map