@graphext/cuery 0.2.0

package/esm/src/tools/classifier.js

@@ -0,0 +1,135 @@
+import { z } from '../../deps/jsr.io/@zod/zod/4.1.12/src/index.js';
+import { mapParallel } from '../async.js';
+import { askOpenAISafe } from '../openai.js';
+import { dedent } from '../utils.js';
+const PROMPT_TEMPLATE = dedent(`
+# Instructions
+
+You're task is to classify the data record below into one of the following categories:
+
+{labels}
+
+Make sure to consider all the attributes of the data record, and assign the class
+based on the content of the attributes.
+
+{instructions}
+
+# Data Record
+
+{record}
+`);
+const MULTI_LABEL_PROMPT_TEMPLATE = dedent(`
+# Instructions
+
+You're task is to assign one or more labels to the data record below from the following options:
+
+{labels}
+
+Make sure to consider all the attributes of the data record. A record can have multiple labels
+if it matches multiple categories. Assign all relevant labels that apply to the record.
+
+{instructions}
+
+# Data Record
+
+{record}
+`);
+/**
+ * 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)
+        .map(([key, value]) => `${key}: ${JSON.stringify(value, null, 2)}`)
+        .join('\n\n');
+}
+/**
+ * Generates the labels definition section for the classification prompt.
+ */
+function formatLabels(labels) {
+    return Object.entries(labels)
+        .map(([label, description]) => `- "${label}": ${description}`)
+        .join('\n');
+}
+/**
+ * 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);
+    if (entries.length === 0) {
+        throw new Error('At least one category must be provided');
+    }
+    if (entries.length === 1) {
+        const [label, description] = entries[0];
+        return z.object({
+            label: z.literal(label).describe(description)
+        });
+    }
+    // TypeScript now knows entries.length >= 2
+    const literals = entries.map(([label, description]) => z.literal(label).describe(description));
+    return z.object({
+        label: z.union(literals)
+    });
+}
+/**
+ * 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);
+    const labelType = singleLabelSchema.shape.label;
+    return z.object({
+        labels: z.array(labelType)
+            .min(0)
+            .describe('Array of assigned labels')
+    });
+}
+/**
+ * Classifies a single data record into one of the provided categories using an LLM call.
+ */
+export async function classify(record, labels, instructions = '', model = 'gpt-4.1-mini') {
+    if (record == null || Object.keys(record).length === 0) {
+        return null;
+    }
+    const categorySchema = createLabelSchema(labels);
+    const prompt = PROMPT_TEMPLATE
+        .replace('{labels}', formatLabels(labels))
+        .replace('{instructions}', instructions)
+        .replace('{record}', formatRecord(record));
+    const { parsed } = await askOpenAISafe(prompt, model, categorySchema);
+    if (!parsed) {
+        throw new Error('Failed to parse response from OpenAI');
+    }
+    return parsed.label;
+}
+/**
+ * Classifies multiple data records concurrently while preserving order.
+ */
+export function classifyBatch(records, labels, instructions = '', model = 'gpt-4.1-mini', maxConcurrency = 100) {
+    return mapParallel(records, maxConcurrency, record => classify(record, labels, instructions, model));
+}
+/**
+ * Assigns one or more labels to a single data record using an LLM call.
+ */
+export async function label(record, labels, instructions = '', model = 'gpt-4.1-mini') {
+    if (record == null || Object.keys(record).length === 0) {
+        return null;
+    }
+    const multiLabelSchema = createMultiLabelSchema(labels);
+    const prompt = MULTI_LABEL_PROMPT_TEMPLATE
+        .replace('{labels}', formatLabels(labels))
+        .replace('{instructions}', instructions)
+        .replace('{record}', formatRecord(record));
+    const { parsed } = await askOpenAISafe(prompt, model, multiLabelSchema);
+    if (!parsed) {
+        throw new Error('Failed to parse response from OpenAI');
+    }
+    return parsed.labels;
+}
+/**
+ * Assigns labels to multiple data records concurrently while preserving order.
+ */
+export function labelBatch(records, labels, instructions = '', model = 'gpt-4.1-mini', maxConcurrency = 100) {
+    return mapParallel(records, maxConcurrency, record => label(record, labels, instructions, model));
+}

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

@@ -0,0 +1,19 @@
+import { type AIParams } from '../openai.js';
+import { type Entity } from '../schemas/entity.schema.js';
+export declare const PROMPT: string;
+/**
+ *
+ * Extracts free-form entities from the given text (without enforced entity types).
+ */
+export declare function extractAnyEntities(body: string, instructions: string | undefined, model: string, modelParams?: AIParams): Promise<Array<Entity>>;
+/**
+ * Extracts entities in pre-specified categories from a single 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 type { Entity, Entities } from '../schemas/entity.schema.js';
+export { EntitySchema, EntitiesSchema } from '../schemas/entity.schema.js';
+//# sourceMappingURL=entities.d.ts.map

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

@@ -0,0 +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"}

package/esm/src/tools/entities.js

@@ -0,0 +1,80 @@
+import { mapParallel } from '../async.js';
+import { askOpenAISafe } from '../openai.js';
+import { EntitiesSchema } from '../schemas/entity.schema.js';
+import { dedent } from '../utils.js';
+export const PROMPT = dedent(`
+# Instructions
+
+From the Data Record section below extract entities in the following categories:
+
+{definitions}
+
+For each entity, provide the entity name/text as it appears, and the type/category of entity.
+Ensure to report the names of entities always in lowercase and singular form, even if
+they appear in plural or uppercase in the source titles, to avoid inconsistencies in the output.
+
+Expected output format:
+
+[{"name": "<entity name>", "type": "<entity type>"}, ...]
+
+For example, if the data record contains "Apple iPhone 15 Pro Max Review", and entity
+definitions include a "brand" category and a "product" category, the expected output would be:
+
+[{"name": "apple", "type": "brand"}, {"name": "iphone 15", "type": "product"}]
+
+{instructions}
+
+# Data Record
+
+{text}
+`);
+/**
+ *
+ * Extracts free-form entities from the given text (without enforced entity types).
+ */
+export async function extractAnyEntities(body, instructions = '', model, modelParams = {}) {
+    const prompt = PROMPT
+        .replace('{definitions}', '')
+        .replace('{text}', body)
+        .replace('{instructions}', instructions);
+    const { parsed } = await askOpenAISafe(prompt, model, EntitiesSchema, modelParams);
+    if (!parsed) {
+        throw new Error('Failed to parse response from OpenAI');
+    }
+    return parsed.entities;
+}
+/**
+ * Extracts entities in pre-specified categories from a single text.
+ */
+export async function extractEntitiesFromText(text, entityDefinitions, instructions = '', model = 'gpt-4.1-mini', modelParams = {}) {
+    if (text === null) {
+        return [];
+    }
+    const definitionsText = typeof entityDefinitions === 'string'
+        ? entityDefinitions
+        : Object.entries(entityDefinitions)
+            .map(([type, description]) => `- ${type}: ${description}`)
+            .join('\n');
+    const prompt = PROMPT
+        .replace('{definitions}', definitionsText)
+        .replace('{text}', text)
+        .replace('{instructions}', instructions);
+    const { parsed } = await askOpenAISafe(prompt, model, EntitiesSchema, modelParams);
+    if (!parsed) {
+        throw new Error('Failed to parse response from OpenAI');
+    }
+    return parsed.entities;
+}
+/**
+ * Extracts entities from a batch of texts.
+ */
+export async function extractEntitiesBatch(texts, entityDefinitions, instructions = '', model = 'gpt-4.1-mini', maxConcurrency = 100, modelParams = {}) {
+    // Do this once outside the loop
+    const definitions = typeof entityDefinitions === 'string'
+        ? entityDefinitions
+        : Object.entries(entityDefinitions)
+            .map(([type, description]) => `- ${type}: ${description}`)
+            .join('\n');
+    return mapParallel(texts, maxConcurrency, (text) => extractEntitiesFromText(text, definitions, instructions, model, modelParams));
+}
+export { EntitySchema, EntitiesSchema } from '../schemas/entity.schema.js';

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

@@ -0,0 +1,41 @@
+import type { FunnelOptions } from '../schemas/funnel.schema.js';
+import { FunnelWithExplanationSchema, type Funnel, type FunnelStage, type FunnelCategory, type FunnelWithExplanation } from '../schemas/funnel.schema.js';
+export { FunnelWithExplanationSchema };
+/**
+ * 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.
+ *
+ * @param funnel - The funnel to iterate over (can be a Funnel object or array of stages)
+ * @yields A tuple of [stageName, stageGoal, categoryObject] where categoryObject can be modified in-place
+ */
+export declare function iterateFunnelCategories(funnel: Funnel | FunnelStage[]): Generator<[string, string, FunnelCategory]>;
+/**
+ * Converts a Funnel into a topic taxonomy structure where stages are top-level topics
+ * and categories are subtopics.
+ *
+ * @param funnel - The funnel to convert (can be a Funnel object or array of stages)
+ * @returns An array of topic objects with stage names as topics and category names as subtopics
+ */
+export declare function funnelToTopics(funnel: Funnel | FunnelStage[]): Array<{
+    topic: string;
+    subtopics: Array<string>;
+}>;
+/**
+ * Customize a generic marketing funnel to a specific sector and market using an LLM.
+ */
+export declare function customizeFunnel(sector: string, language: string, userLanguage?: string | null, country?: string, briefing?: string | null, instructions?: string | null, model?: string, funnel?: Funnel | FunnelStage[]): Promise<FunnelWithExplanation>;
+/**
+ * Generate example seed keywords for a specific funnel category using an LLM.
+ */
+export declare function generateSeedKeywords(stage: string, goal: string, category: FunnelCategory, sector: string, language: string, country?: string, model?: string): Promise<Array<string>>;
+/**
+ * Regenerates seed keywords for all categories in a funnel concurrently,
+ * updating the keywordSeeds field in-place for each category.
+ */
+export declare function reseedFunnel(funnel: FunnelWithExplanation | FunnelStage[], sector: string, language: string, country?: string, model?: string, maxConcurrency?: number): Promise<FunnelWithExplanation>;
+/**
+ * Generate a complete customized marketing funnel with seed keywords.
+ * This is a convenience wrapper that combines customizeFunnel and reseedFunnel.
+ */
+export declare function generateFunnel({ sector, language, userLanguage, country, model, funnel, briefing, maxConcurrency, instructions }: FunnelOptions): Promise<FunnelWithExplanation>;
+//# sourceMappingURL=funnel.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"funnel.d.ts","sourceRoot":"","sources":["../../../src/src/tools/funnel.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AACjE,OAAO,EAAE,2BAA2B,EAAe,KAAK,MAAM,EAAE,KAAK,WAAW,EAAE,KAAK,cAAc,EAAE,KAAK,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AAGvK,OAAO,EAAE,2BAA2B,EAAE,CAAC;AAEvC;;;;;;GAMG;AACH,wBAAiB,uBAAuB,CACvC,MAAM,EAAE,MAAM,GAAG,WAAW,EAAE,GAC5B,SAAS,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,cAAc,CAAC,CAAC,CAQ7C;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC7B,MAAM,EAAE,MAAM,GAAG,WAAW,EAAE,GAC5B,KAAK,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,KAAK,CAAC,MAAM,CAAC,CAAA;CAAE,CAAC,CAOpD;AA6PD;;GAEG;AACH,wBAAsB,eAAe,CACpC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,YAAY,GAAE,MAAM,GAAG,IAAW,EAClC,OAAO,GAAE,MAAiB,EAC1B,QAAQ,GAAE,MAAM,GAAG,IAAW,EAC9B,YAAY,GAAE,MAAM,GAAG,IAAW,EAClC,KAAK,GAAE,MAAkB,EACzB,MAAM,GAAE,MAAM,GAAG,WAAW,EAA+B,GACzD,OAAO,CAAC,qBAAqB,CAAC,CAkBhC;AA0BD;;GAEG;AACH,wBAAsB,oBAAoB,CACzC,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,cAAc,EACxB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,MAAiB,EAC1B,KAAK,GAAE,MAAkB,GACvB,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAkBxB;AAED;;;GAGG;AACH,wBAAsB,YAAY,CACjC,MAAM,EAAE,qBAAqB,GAAG,WAAW,EAAE,EAC7C,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,MAAiB,EAC1B,KAAK,GAAE,MAAkB,EACzB,cAAc,GAAE,MAAY,GAC1B,OAAO,CAAC,qBAAqB,CAAC,CAuBhC;AAED;;;GAGG;AACH,wBAAsB,cAAc,CAAC,EACpC,MAAM,EACN,QAAQ,EACR,YAAY,EACZ,OAAO,EACP,KAAK,EACL,MAAM,EACN,QAAQ,EACR,cAAc,EACd,YAAY,EACZ,EAAE,aAAa,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAIhD"}

package/esm/src/tools/funnel.js

@@ -0,0 +1,372 @@
+import { mapParallel } from '../async.js';
+import { askOpenAISafe } from '../openai.js';
+import { FunnelWithExplanationSchema, SeedsSchema } from '../schemas/funnel.schema.js';
+import { dedent } from '../utils.js';
+export { FunnelWithExplanationSchema };
+/**
+ * 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.
+ *
+ * @param funnel - The funnel to iterate over (can be a Funnel object or array of stages)
+ * @yields A tuple of [stageName, stageGoal, categoryObject] where categoryObject can be modified in-place
+ */
+export function* iterateFunnelCategories(funnel) {
+    const stages = Array.isArray(funnel) ? funnel : funnel.stages;
+    for (const stageData of stages) {
+        for (const category of stageData.categories) {
+            yield [stageData.stage, stageData.goal, category];
+        }
+    }
+}
+/**
+ * Converts a Funnel into a topic taxonomy structure where stages are top-level topics
+ * and categories are subtopics.
+ *
+ * @param funnel - The funnel to convert (can be a Funnel object or array of stages)
+ * @returns An array of topic objects with stage names as topics and category names as subtopics
+ */
+export function funnelToTopics(funnel) {
+    const stages = Array.isArray(funnel) ? funnel : funnel.stages;
+    return stages.map(stage => ({
+        topic: stage.stage,
+        subtopics: stage.categories.map(category => category.name)
+    }));
+}
+const GENERIC_FUNNEL = [
+    {
+        'stage': 'Awareness / Discovery',
+        'goal': 'Problem recognition, education.',
+        'categories': [
+            {
+                'name': 'Problem Identification',
+                'description': 'User searches to understand or define their problem or need.',
+                'keywordPatterns': ['questions', 'how-to', 'why', 'tips', 'guides'],
+                'keywordSeeds': [
+                    'why does my back hurt when running',
+                    'how to organize customer data'
+                ],
+                'intent': 'Informational'
+            },
+            {
+                'name': 'Category Education',
+                'description': 'Exploring broad product/service categories without specific brands.',
+                'keywordPatterns': ['types of', 'what is', 'overview', 'guide to'],
+                'keywordSeeds': ['types of running shoes', 'what is CRM software'],
+                'intent': 'Informational'
+            },
+            {
+                'name': 'Trends & Inspiration',
+                'description': 'Looking for ideas, new trends, or general inspiration.',
+                'keywordPatterns': [
+                    'trends',
+                    'ideas',
+                    'inspiration',
+                    'popular',
+                    'latest'
+                ],
+                'keywordSeeds': [
+                    'latest running shoe trends 2025',
+                    'popular small business tools'
+                ],
+                'intent': 'Informational'
+            }
+        ]
+    },
+    {
+        'stage': 'Consideration / Research',
+        'goal': 'Compare options, evaluate solutions.',
+        'categories': [
+            {
+                'name': 'Features & Specifications',
+                'description': 'Interest in specific attributes or capabilities.',
+                'keywordPatterns': [
+                    'feature',
+                    'specifications',
+                    'capabilities',
+                    'functions'
+                ],
+                'keywordSeeds': [
+                    'running shoes with arch support',
+                    'CRM with email automation'
+                ],
+                'intent': 'Commercial / Research'
+            },
+            {
+                'name': 'Comparisons',
+                'description': 'Directly comparing brands, products, or categories.',
+                'keywordPatterns': ['vs', 'comparison', 'alternatives', 'best of'],
+                'keywordSeeds': ['Nike vs Adidas', 'HubSpot vs Salesforce'],
+                'intent': 'Commercial / Research'
+            },
+            {
+                'name': 'Suitability & Use Cases',
+                'description': 'Evaluating how well a solution fits specific needs or contexts.',
+                'keywordPatterns': ['best for', 'ideal for', 'use case', 'fit for'],
+                'keywordSeeds': ['best shoes for marathon training', 'CRM for freelancers'],
+                'intent': 'Commercial / Research'
+            },
+            {
+                'name': 'Social Proof & Reviews',
+                'description': 'Looking for recommendations, opinions, ratings, testimonials. Often includes temporal modifiers like "2024".',
+                'keywordPatterns': [
+                    'review',
+                    'rating',
+                    'top-rated',
+                    'best',
+                    'customer feedback'
+                ],
+                'keywordSeeds': ['best CRM software', 'best rated running shoes 2025', 'HubSpot reviews'],
+                'intent': 'Commercial / Research'
+            }
+        ]
+    },
+    {
+        'stage': 'Decision / Evaluation',
+        'goal': 'Prospect is close to acting but still evaluating options.',
+        'categories': [
+            {
+                'name': 'Pricing & Packages',
+                'description': 'Researching cost, plans, discounts, promotions.',
+                'keywordPatterns': [
+                    'price',
+                    'pricing',
+                    'cost',
+                    'plan',
+                    'tier',
+                    'discount'
+                ],
+                'keywordSeeds': ['Nike Pegasus price', 'HubSpot CRM pricing tiers'],
+                'intent': 'Commercial / Research'
+            },
+            {
+                'name': 'Availability & Location',
+                'description': 'Where or how to obtain the product/service.',
+                'keywordPatterns': [
+                    'buy near me',
+                    'availability',
+                    'store',
+                    'online purchase'
+                ],
+                'keywordSeeds': ['buy running shoes near me', 'best CRM free trial'],
+                'intent': 'Commercial / Research'
+            },
+            {
+                'name': 'Intent-to-Act Signals',
+                'description': 'Keywords showing strong intent to act soon but still evaluating options.',
+                'keywordPatterns': [
+                    'sign up trial',
+                    'get started demo',
+                    'order sample',
+                    'try now'
+                ],
+                'keywordSeeds': ['sign up for HubSpot demo', 'get started with CRM trial'],
+                'intent': 'Commercial / Research'
+            }
+        ]
+    },
+    {
+        'stage': 'Conversion / Action',
+        'goal': 'Prospect decides to purchase or take desired action (checkout, demo, signup).',
+        'categories': [
+            {
+                'name': 'Purchase / Signup',
+                'description': 'Final action: completing a purchase, signing up, or starting a trial.',
+                'keywordPatterns': ['buy', 'checkout', 'signup', 'register', 'demo'],
+                'keywordSeeds': ['buy Nike Pegasus online', 'HubSpot CRM demo signup'],
+                'intent': 'Transactional'
+            },
+            {
+                'name': 'Immediate Offers & Promotions',
+                'description': 'Using discounts, coupon codes, or limited-time deals to convert.',
+                'keywordPatterns': [
+                    'discount',
+                    'promo code',
+                    'deal',
+                    'offer',
+                    'coupon'
+                ],
+                'keywordSeeds': ['Nike Pegasus 20% off', 'HubSpot CRM free trial code'],
+                'intent': 'Transactional'
+            }
+        ]
+    },
+    {
+        'stage': 'Post-Purchase / Retention & Advocacy',
+        'goal': 'Support existing customers, encourage loyalty or advocacy.',
+        'categories': [
+            {
+                'name': 'Usage & How-To',
+                'description': 'Guides, tutorials, setup instructions.',
+                'keywordPatterns': [
+                    'how to',
+                    'tutorial',
+                    'setup',
+                    'guide',
+                    'instructions'
+                ],
+                'keywordSeeds': ['how to break in running shoes', 'HubSpot CRM tutorial'],
+                'intent': 'Retention / Post-Purchase'
+            },
+            {
+                'name': 'Troubleshooting & Support',
+                'description': 'Fixing problems, maintenance, FAQs.',
+                'keywordPatterns': ['help', 'troubleshoot', 'issue', 'problem', 'FAQ'],
+                'keywordSeeds': ['Nike Pegasus sizing issues', 'HubSpot login help'],
+                'intent': 'Retention / Post-Purchase'
+            },
+            {
+                'name': 'Upgrades & Add-ons',
+                'description': 'Expanding or enhancing existing purchase.',
+                'keywordPatterns': [
+                    'upgrade',
+                    'add-on',
+                    'extension',
+                    'premium features'
+                ],
+                'keywordSeeds': [
+                    'best insoles for running shoes',
+                    'HubSpot premium features'
+                ],
+                'intent': 'Retention / Post-Purchase'
+            },
+            {
+                'name': 'Community & Advocacy',
+                'description': 'Engagement, referrals, sharing experiences.',
+                'keywordPatterns': [
+                    'forum',
+                    'community',
+                    'refer',
+                    'share',
+                    'testimonial'
+                ],
+                'keywordSeeds': [
+                    'running shoe user forum',
+                    'refer a friend HubSpot discount'
+                ],
+                'intent': 'Retention / Post-Purchase'
+            }
+        ]
+    }
+];
+const CUSTOMIZE_PROMPT = dedent(`
+Adapt this marketing funnel for sector '{sector}', market '{market}', language '{language}'.
+{briefing}
+
+RULES:
+1. Keep the same funnel stages (translate names if needed) - only customize categories within stages
+2. Adjust categories to fit the sector: modify names, descriptions, or replace irrelevant ones
+3. "keywordPatterns": Abstract types/themes (e.g., "questions", "comparisons", "pricing")
+4. "keywordSeeds": Real Google searches users actually type - NOT forced combinations of patterns
+   - Think: What would someone naturally search at this stage?
+   - Keep broad (1-3 words) to seed Google Keyword Planner for 100s-1000s of ideas
+   - Generate 3-10 keywordSeeds per category
+5. Patterns and keywordSeeds should align thematically but DON'T force pattern words into keywordSeeds. Focus on the category "description" to guide relevant keywordSeeds.
+
+Example for running shoes:
+- Category description: "Palabras clave que muestran alta intención de compra, aunque todavía evaluando la mejor opción",
+- Keyword Patterns: ["probar", "reservar", "solicitar prueba", "más info"]
+- GOOD keywordSeeds: ["elegir talla zapatilla", "analisis de pisada"]
+  BAD: ["probar zapatillas", "reservar zapatillas"] (unnatural search)
+- Pattern: ["comparativas"] → KeywordSeeds: ["nike vs adidas", "mejores zapatillas 2025"]
+
+Return the customized funnel in language {userLanguage} except keywordSeeds, that should maintain the original language.
+
+Also provide an "explanation" field with a brief summary (2-3 sentences) explaining the reasoning behind
+the funnel customization: how the stages and categories were adapted for this sector and market,
+and what customer journey they represent.
+
+{instructions}
+
+# Generic funnel structure
+
+{funnel}
+`);
+/**
+ * Customize a generic marketing funnel to a specific sector and market using an LLM.
+ */
+export async function customizeFunnel(sector, language, userLanguage = null, country = 'global', briefing = null, instructions = null, model = 'gpt-4.1', funnel = { stages: GENERIC_FUNNEL }) {
+    const funnelData = Array.isArray(funnel) ? funnel : funnel.stages;
+    const prompt = CUSTOMIZE_PROMPT
+        .replace('{sector}', sector)
+        .replace('{briefing}', briefing || '')
+        .replace('{instructions}', instructions || '')
+        .replace('{market}', country)
+        .replace('{language}', language)
+        .replace('{userLanguage}', userLanguage ?? language)
+        .replace('{funnel}', JSON.stringify(funnelData, null, 2));
+    const { parsed } = await askOpenAISafe(prompt, model, FunnelWithExplanationSchema);
+    if (!parsed) {
+        throw new Error('Failed to parse response from OpenAI');
+    }
+    return parsed;
+}
+const GENERATE_SEEDS_PROMPT = dedent(`
+Generate 3-10 Google search keywords that real users type when researching {sector} at this funnel stage.
+
+Stage: {stage} ({goal})
+Category: {category} - {description}
+Intent: {intent}
+Theme indicators: {patterns}
+
+CRITICAL: Generate what people ACTUALLY search, NOT literal combinations of theme words.
+
+Example for running shoes / "Señales de Intención" / themes ["probar", "reservar"]:
+✅ GOOD: "elegir talla zapatilla", "analisis de pisada"
+❌ BAD: "probar zapatillas", "reservar zapatillas" (unnatural, nobody searches this)
+
+Requirements:
+- Broad queries (1-3 words) suitable for Google Keyword Planner seed expansion
+- Natural language people actually type in search bars
+- Match the stage intent and category purpose
+- Output {language} for {market} market
+- 5-10 keywords (more is better)
+
+What would someone in {market} naturally search when {description}?
+`);
+/**
+ * Generate example seed keywords for a specific funnel category using an LLM.
+ */
+export async function generateSeedKeywords(stage, goal, category, sector, language, country = 'global', model = 'gpt-4.1') {
+    const prompt = GENERATE_SEEDS_PROMPT
+        .replace('{stage}', stage)
+        .replace('{goal}', goal)
+        .replace('{category}', category.name)
+        .replace('{description}', category.description)
+        .replace('{intent}', category.intent)
+        .replace('{patterns}', category.keywordPatterns.join(', '))
+        .replace('{sector}', sector)
+        .replace('{market}', country)
+        .replace('{language}', language);
+    const { parsed } = await askOpenAISafe(prompt, model, SeedsSchema);
+    if (!parsed) {
+        throw new Error('Failed to parse seed keywords from OpenAI');
+    }
+    return parsed.seeds;
+}
+/**
+ * Regenerates seed keywords for all categories in a funnel concurrently,
+ * updating the keywordSeeds field in-place for each category.
+ */
+export async function reseedFunnel(funnel, sector, language, country = 'global', model = 'gpt-4.1', maxConcurrency = 100) {
+    const categories = [];
+    for (const categoryTuple of iterateFunnelCategories(funnel)) {
+        categories.push(categoryTuple);
+    }
+    await mapParallel(categories, maxConcurrency, async ([stage, goal, category]) => {
+        const seeds = await generateSeedKeywords(stage, goal, category, sector, language, country, model);
+        category.keywordSeeds = seeds;
+    });
+    if (Array.isArray(funnel)) {
+        return { stages: funnel, explanation: '' };
+    }
+    return funnel;
+}
+/**
+ * Generate a complete customized marketing funnel with seed keywords.
+ * This is a convenience wrapper that combines customizeFunnel and reseedFunnel.
+ */
+export async function generateFunnel({ sector, language, userLanguage, country, model, funnel, briefing, maxConcurrency, instructions }) {
+    const customized = await customizeFunnel(sector, language, userLanguage, country || 'global', briefing, instructions, model || 'gpt-4.1', funnel || { stages: GENERIC_FUNNEL });
+    const reseeded = await reseedFunnel(customized, sector, language, country || 'global', model || 'gpt-4.1', maxConcurrency ?? 100);
+    return reseeded;
+}