@graphext/cuery 0.2.0

package/script/src/tools/personas.js

@@ -0,0 +1,91 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generatePersonas = generatePersonas;
+const openai_js_1 = require("../openai.js");
+const brands_js_1 = require("./brands.js");
+const persona_schema_js_1 = require("../schemas/persona.schema.js");
+const utils_js_1 = require("../utils.js");
+const PROMPT = (0, utils_js_1.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
+in the {sector} sector targeting the {market} market.
+
+For context, the brand being analyzed is{brand_context}. Use this brand as context to better understand
+the specific niche, positioning, and target audience within the {sector} sector. However, you MUST NOT
+mention the brand name{brand_exclusion} anywhere in the persona names or descriptions. The personas should be
+generic profiles that could apply to similar brands in the same space.
+
+Each persona should include:
+- name: A short and catchy name, such as "Tech-Savvy Creative Director", "Gaming Industry Veteran",
+  "Eco-Conscious Millennial", "Budget-Conscious Family Planner", or "Luxury Lifestyle Enthusiast".
+- description: A brief description of the persona's characteristics, needs, and behaviors.
+- keywordSeeds: A list of 5-10 keyword seed phrases in language {language} that this persona would typically search for
+  when looking for products/services in this space. These should be realistic search queries that
+  reflect the persona's language ({language}), intent, and level of expertise. Include a mix of informational
+  and transactional queries. Keywords should be broad (1-3 words) suitable for Google Keyword Planner
+  seed expansion. Do NOT include the brand name {brand_exclusion} in these keywords.
+
+Make sure you're answer is in the language "{userLanguage} except keywordSeeds, that should maintain the original language {language}".
+
+Return the personas as a list of JSON objects.
+
+Also provide an "explanation" field with a brief summary (2-3 sentences) explaining the reasoning behind
+the personas you generated: why these profiles are relevant for this sector and market, and what key
+customer segments they represent.
+
+{instructions}
+
+{currentPersonasInfo}
+`);
+const CURRENT_DATA_CLAUSE = (0, utils_js_1.dedent)(`
+# Current Personas Information
+
+The following is the current information the user has about personas for the brand(s).
+
+{currentData}
+
+IMPORTANT: Unless the instructions explicitly specify to modify, replace, add, or remove competitors
+from this list, you MUST return at least all the same competitors that are already present in the
+current data. If no modification instructions are provided, maintain the existing list and only add
+new competitors if they are relevant.
+`);
+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 = (0, brands_js_1.buildBrandContext)({
+        brand,
+        brandDomain,
+        sector,
+        market,
+        briefing
+    });
+    let brandExclusion;
+    if (brandDomain) {
+        if (brand) {
+            brandExclusion = ` "${brand}" or the domain`;
+        }
+        else {
+            brandExclusion = ' or domain';
+        }
+    }
+    else {
+        brandExclusion = ` "${brand}"`;
+    }
+    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 (0, openai_js_1.askOpenAISafe)(content, model, persona_schema_js_1.PersonasResponseSchema);
+    if (!parsed) {
+        throw new Error('Failed to parse response from OpenAI');
+    }
+    return parsed;
+}

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

@@ -0,0 +1,14 @@
+import { z } from '../../deps/jsr.io/@zod/zod/4.1.12/src/index.js';
+export type ScoreSchema = z.ZodObject<{
+    value: z.ZodNumber;
+}>;
+/**
+ * Dynamically create a Zod schema for a score based on provided parameters.
+ */
+export declare function makeScoreSchema(type: 'integer' | 'number', min: number, max: number, description: string): ScoreSchema;
+/**
+ * Assumes only remaining placeholder in prompt is {record}
+ */
+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>>;
+//# sourceMappingURL=scorer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"scorer.d.ts","sourceRoot":"","sources":["../../../src/src/tools/scorer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,gDAAgD,CAAC;AAqBnE,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"}

package/script/src/tools/scorer.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.makeScoreSchema = makeScoreSchema;
+exports.score = score;
+exports.scoreBatch = scoreBatch;
+const index_js_1 = require("../../deps/jsr.io/@zod/zod/4.1.12/src/index.js");
+const async_js_1 = require("../async.js");
+const openai_js_1 = require("../openai.js");
+const utils_js_1 = require("../utils.js");
+const PROMPT = (0, utils_js_1.dedent)(`
+# Instructions
+
+Assign a {name} ({type} score between {min} and {max}) to the data record below.
+
+Score description: {description}
+
+Make sure to consider all the attributes of the data record, and assign the score
+based on the content of the attributes.
+
+# Data Record
+
+{record}
+`);
+/**
+ * Dynamically create a Zod schema for a score based on provided parameters.
+ */
+function makeScoreSchema(type, min, max, description) {
+    let schema;
+    if (type === 'integer') {
+        schema = index_js_1.z.number().int().min(min).max(max).describe(description);
+    }
+    else {
+        schema = index_js_1.z.number().min(min).max(max).describe(description);
+    }
+    return index_js_1.z.object({
+        value: schema
+    });
+}
+/**
+ * Assumes only remaining placeholder in prompt is {record}
+ */
+async function score(record, prompt, schema, model = 'gpt-4.1-mini') {
+    const renderedPrompt = prompt.replace('record', JSON.stringify(record, null, 2));
+    const response = await (0, openai_js_1.askOpenAISafe)(renderedPrompt, model, schema);
+    if (response.parsed == null) {
+        throw new Error('Failed to parse score from OpenAI response');
+    }
+    return response.parsed.value;
+}
+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 (0, async_js_1.mapParallel)(records, maxConcurrency, (record) => score(record, prompt, schema, model));
+}

package/script/src/tools/search.d.ts

@@ -0,0 +1,24 @@
+import type { BatchSearchOptions, FormattedSearchOptions, SearchOptions, SearchResult } from '../schemas/search.schema.js';
+export type { SearchResult } from '../schemas/search.schema.js';
+/**
+ * Call OpenAI Responses API with Web Search enabled (async).
+ *
+ * API Docs:
+ * - https://platform.openai.com/docs/guides/tools-web-search?api-mode=responses
+ */
+export declare function searchOpenAI({ prompt, model, useSearch, countryISOCode, contextSize, reasoningEffort, searchTool }: SearchOptions): Promise<SearchResult>;
+/**
+ * Perform a web search using searchOpenAI and return structured response.
+ * The OpenAI API doesn't currently allow both web search tool and response format in the same call.
+ *
+ * This function:
+ * 1. Performs a web search using searchOpenAI
+ * 2. Formats the search results using a template
+ * 3. Sends the formatted results to OpenAI with a Zod schema to extract structured information
+ */
+export declare function searchWithFormat<T>({ prompt, model, responseSchema, useSearch, countryISOCode, contextSize, reasoningEffort }: FormattedSearchOptions<T>): Promise<T>;
+/**
+ * Performs web search for multiple prompts concurrently while preserving order.
+ */
+export declare function searchBatch({ prompts, model, useSearch, countryISOCode, contextSize, reasoningEffort, maxConcurrency }: BatchSearchOptions): Promise<Array<SearchResult>>;
+//# sourceMappingURL=search.d.ts.map

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

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

package/script/src/tools/search.js

@@ -0,0 +1,135 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.searchOpenAI = searchOpenAI;
+exports.searchWithFormat = searchWithFormat;
+exports.searchBatch = searchBatch;
+const async_js_1 = require("../async.js");
+const openai_js_1 = require("../openai.js");
+const urls_js_1 = require("../urls.js");
+const utils_js_1 = require("../utils.js");
+/**
+ * Call OpenAI Responses API with Web Search enabled (async).
+ *
+ * API Docs:
+ * - https://platform.openai.com/docs/guides/tools-web-search?api-mode=responses
+ */
+async function searchOpenAI({ prompt, model = 'gpt-4.1-mini', useSearch = true, countryISOCode = null, contextSize = 'low', reasoningEffort = 'low', searchTool = 'web_search' }) {
+    const params = {};
+    if (model.includes('-5')) {
+        params.reasoning = { effort: reasoningEffort };
+    }
+    if (useSearch) {
+        params.tools = [{
+                type: searchTool,
+                search_context_size: contextSize,
+                ...(countryISOCode ? { user_location: { type: 'approximate', country: countryISOCode } } : {})
+            }];
+        params.tool_choice = 'required';
+    }
+    const { output } = await (0, openai_js_1.askOpenAISafe)(prompt, model, undefined, params);
+    if (!output) {
+        throw new Error('No output from OpenAI');
+    }
+    return validateOpenAI(output);
+}
+/**
+ * Convert a raw web search response into a SearchResult instance.
+ */
+function validateOpenAI(response) {
+    let answer = '';
+    let sources = [];
+    // Filter out reasoning elements and find relevant elements
+    const relevantElements = response.filter(item => item.type !== 'reasoning');
+    const messageElement = relevantElements.find(item => item.type === 'message');
+    const hasWebSearch = relevantElements.some(item => item.type === 'web_search_call');
+    if (!messageElement) {
+        throw new Error('No message element found in response');
+    }
+    if (messageElement.type !== 'message') {
+        throw new Error('Message element must be of type "message"');
+    }
+    const content = messageElement.content?.[0];
+    if (!content) {
+        throw new Error('Message element has no content');
+    }
+    if (content.type !== 'output_text') {
+        throw new Error(`Content must be of type "output_text", got "${content.type}"`);
+    }
+    answer = content.text;
+    // Extract sources from annotations if web search was used
+    if (hasWebSearch && content.annotations) {
+        sources = content.annotations
+            .filter(ann => ann.type === 'url_citation')
+            .map(ann => ({
+            title: ann.title,
+            url: ann.url,
+            domain: (0, urls_js_1.extractDomain)(ann.url)
+        }));
+    }
+    return {
+        answer,
+        sources
+    };
+}
+const FORMATTED_SEARCH_PROMPT = (0, utils_js_1.dedent)(`
+Based on the following search results, please format the information according
+to the requested structure:
+
+# Search Query
+
+{prompt}
+
+# Search Results
+
+{answer}
+
+# Sources
+
+{sources}
+
+Please extract and format the relevant information from these search results as a JSON object.
+`);
+/**
+ * Perform a web search using searchOpenAI and return structured response.
+ * The OpenAI API doesn't currently allow both web search tool and response format in the same call.
+ *
+ * This function:
+ * 1. Performs a web search using searchOpenAI
+ * 2. Formats the search results using a template
+ * 3. Sends the formatted results to OpenAI with a Zod schema to extract structured information
+ */
+async function searchWithFormat({ prompt, model, responseSchema, useSearch = true, countryISOCode = null, contextSize = 'medium', reasoningEffort = 'low' }) {
+    const searchResult = await searchOpenAI({
+        prompt,
+        model,
+        useSearch,
+        countryISOCode,
+        contextSize,
+        reasoningEffort
+    });
+    const sources = searchResult.sources
+        .map((source) => `- ${source.title}: ${source.url}`)
+        .join('\n');
+    const formattedPrompt = FORMATTED_SEARCH_PROMPT
+        .replace('{prompt}', prompt)
+        .replace('{answer}', searchResult.answer)
+        .replace('{sources}', sources);
+    const { parsed } = await (0, openai_js_1.askOpenAISafe)(formattedPrompt, 'gpt-4.1-mini', responseSchema);
+    if (!parsed) {
+        throw new Error('Failed to parse structured response from OpenAI');
+    }
+    return parsed;
+}
+/**
+ * Performs web search for multiple prompts concurrently while preserving order.
+ */
+function searchBatch({ prompts, model = 'gpt-4.1-mini', useSearch = true, countryISOCode = null, contextSize = 'medium', reasoningEffort = 'low', maxConcurrency = 100 }) {
+    return (0, async_js_1.mapParallel)(prompts, maxConcurrency, prompt => searchOpenAI({
+        prompt,
+        model,
+        useSearch,
+        countryISOCode: countryISOCode,
+        contextSize: contextSize,
+        reasoningEffort: reasoningEffort
+    }));
+}

package/script/src/tools/seedKeywords.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Seed Keyword Functions
+ *
+ * Pure functions for collecting and grouping seed keywords.
+ * No external dependencies - safe to import in both frontend and backend.
+ */
+export type { SeedKeyword, SeedKeywordSource } from '../schemas/seedKeyword.schema.js';
+import type { SeedKeyword } from '../schemas/seedKeyword.schema.js';
+interface PortfolioItemLike {
+    name: string;
+    keywordSeeds?: Array<string>;
+}
+interface PersonaLike {
+    name: string;
+    keywordSeeds?: Array<string>;
+}
+interface FunnelCategoryLike {
+    name: string;
+    keywordSeeds?: Array<string>;
+}
+interface FunnelStageLike {
+    stage: string;
+    categories?: Array<FunnelCategoryLike>;
+}
+interface CompetitorLike {
+    name: string;
+    portfolio?: Array<PortfolioItemLike>;
+}
+export interface CollectSeedKeywordsParams {
+    brandPortfolio?: Array<PortfolioItemLike>;
+    personas?: Array<PersonaLike>;
+    funnelStages?: Array<FunnelStageLike>;
+    competitors?: Array<CompetitorLike>;
+    customKeywords?: Array<string>;
+}
+/**
+ * Collects seed keywords from all sources and creates SeedKeyword objects
+ * with proper metadata (id, source, sourceId, sourceName).
+ */
+export declare function collectSeedKeywords({ brandPortfolio, personas, funnelStages, competitors, customKeywords }: CollectSeedKeywordsParams): Array<SeedKeyword>;
+/**
+ * Groups seed keywords by their source, maintaining order within each source.
+ * Keywords from the same portfolio item, competitor product, or funnel category
+ * are grouped together.
+ *
+ * @param seedKeywords - Flat array of seed keywords
+ * @param generateIdeasFromSeeds - When true, returns grouped keywords for idea generation.
+ *                                  When false, returns all keywords flattened into a single group.
+ * @returns Array of grouped keywords (arrays for same-source groups, single items for personas/custom)
+ */
+export declare function groupSeedKeywords(seedKeywords: Array<SeedKeyword>, generateIdeasFromSeeds?: boolean): Array<Array<SeedKeyword> | SeedKeyword>;
+/**
+ * Groups seed keywords and extracts just the keyword strings.
+ * Convenience wrapper around groupSeedKeywords for cases where
+ * only the keyword text is needed (not the full metadata).
+ */
+export declare function groupKeywordStrings(seedKeywords: Array<SeedKeyword>, generateIdeasFromSeeds?: boolean): Array<Array<string> | string>;
+/**
+ * Collects and groups seed keywords in one step, returning only keyword strings.
+ * This is a convenience function for pipelines that need grouped keyword strings
+ * without the full SeedKeyword metadata.
+ *
+ * @param params - Same parameters as collectSeedKeywords
+ * @param generateIdeasFromSeeds - When true, returns grouped keywords. When false, returns flat.
+ * @returns Grouped keyword strings (arrays for same-source groups, single strings otherwise)
+ */
+export declare function collectAndGroupKeywordStrings(params: CollectSeedKeywordsParams, generateIdeasFromSeeds?: boolean): Array<Array<string> | string>;
+//# sourceMappingURL=seedKeywords.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"seedKeywords.d.ts","sourceRoot":"","sources":["../../../src/src/tools/seedKeywords.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,YAAY,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,kCAAkC,CAAC;AAGvF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kCAAkC,CAAC;AAOpE,UAAU,iBAAiB;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;CAC7B;AAED,UAAU,WAAW;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;CAC7B;AAED,UAAU,kBAAkB;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;CAC7B;AAED,UAAU,eAAe;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,KAAK,CAAC,kBAAkB,CAAC,CAAC;CACvC;AAED,UAAU,cAAc;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,KAAK,CAAC,iBAAiB,CAAC,CAAC;CACrC;AAMD,MAAM,WAAW,yBAAyB;IACzC,cAAc,CAAC,EAAE,KAAK,CAAC,iBAAiB,CAAC,CAAC;IAC1C,QAAQ,CAAC,EAAE,KAAK,CAAC,WAAW,CAAC,CAAC;IAC9B,YAAY,CAAC,EAAE,KAAK,CAAC,eAAe,CAAC,CAAC;IACtC,WAAW,CAAC,EAAE,KAAK,CAAC,cAAc,CAAC,CAAC;IACpC,cAAc,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;CAC/B;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,EACnC,cAAc,EACd,QAAQ,EACR,YAAY,EACZ,WAAW,EACX,cAAc,EACd,EAAE,yBAAyB,GAAG,KAAK,CAAC,WAAW,CAAC,CA+EhD;AAcD;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAChC,YAAY,EAAE,KAAK,CAAC,WAAW,CAAC,EAChC,sBAAsB,GAAE,OAAc,GACpC,KAAK,CAAC,KAAK,CAAC,WAAW,CAAC,GAAG,WAAW,CAAC,CA8FzC;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAClC,YAAY,EAAE,KAAK,CAAC,WAAW,CAAC,EAChC,sBAAsB,GAAE,OAAc,GACpC,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,CAS/B;AAED;;;;;;;;GAQG;AACH,wBAAgB,6BAA6B,CAC5C,MAAM,EAAE,yBAAyB,EACjC,sBAAsB,GAAE,OAAc,GACpC,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,CAG/B"}

package/script/src/tools/seedKeywords.js

@@ -0,0 +1,220 @@
+"use strict";
+/**
+ * Seed Keyword Functions
+ *
+ * Pure functions for collecting and grouping seed keywords.
+ * No external dependencies - safe to import in both frontend and backend.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.collectSeedKeywords = collectSeedKeywords;
+exports.groupSeedKeywords = groupSeedKeywords;
+exports.groupKeywordStrings = groupKeywordStrings;
+exports.collectAndGroupKeywordStrings = collectAndGroupKeywordStrings;
+/**
+ * Collects seed keywords from all sources and creates SeedKeyword objects
+ * with proper metadata (id, source, sourceId, sourceName).
+ */
+function collectSeedKeywords({ brandPortfolio, personas, funnelStages, competitors, customKeywords }) {
+    const keywords = [];
+    // Brand portfolio keywords
+    brandPortfolio?.forEach((portfolioItem) => {
+        if (portfolioItem.keywordSeeds && portfolioItem.keywordSeeds.length > 0) {
+            portfolioItem.keywordSeeds.forEach((keyword) => {
+                keywords.push({
+                    id: `brand-portfolio-${portfolioItem.name}-${keyword}`,
+                    keyword,
+                    source: 'brand-portfolio',
+                    sourceId: portfolioItem.name,
+                    sourceName: portfolioItem.name
+                });
+            });
+        }
+    });
+    // Persona keywords
+    personas?.forEach((persona) => {
+        if (persona.keywordSeeds && persona.keywordSeeds.length > 0) {
+            persona.keywordSeeds.forEach((keyword) => {
+                keywords.push({
+                    id: `persona-${persona.name}-${keyword}`,
+                    keyword,
+                    source: 'persona',
+                    sourceId: persona.name,
+                    sourceName: persona.name
+                });
+            });
+        }
+    });
+    // Funnel category keywords
+    funnelStages?.forEach((stage) => {
+        stage.categories?.forEach((category) => {
+            if (category.keywordSeeds && category.keywordSeeds.length > 0) {
+                category.keywordSeeds.forEach((example) => {
+                    keywords.push({
+                        id: `funnel-${stage.stage}-${category.name}-${example}`,
+                        keyword: example,
+                        source: 'funnel',
+                        sourceId: `${stage.stage}::${category.name}`,
+                        sourceName: `${stage.stage} > ${category.name}`
+                    });
+                });
+            }
+        });
+    });
+    // Competitor portfolio keywords
+    competitors?.forEach((competitor) => {
+        if (competitor.portfolio && competitor.portfolio.length > 0) {
+            competitor.portfolio.forEach((portfolioItem) => {
+                if (portfolioItem.keywordSeeds && portfolioItem.keywordSeeds.length > 0) {
+                    portfolioItem.keywordSeeds.forEach((keyword) => {
+                        keywords.push({
+                            id: `portfolio-${competitor.name}-${portfolioItem.name}-${keyword}`,
+                            keyword,
+                            source: 'portfolio',
+                            sourceId: portfolioItem.name,
+                            sourceName: `${competitor.name} > ${portfolioItem.name}`
+                        });
+                    });
+                }
+            });
+        }
+    });
+    // Custom keywords
+    customKeywords?.forEach((keyword, index) => {
+        keywords.push({
+            id: `custom-${index}-${keyword}`,
+            keyword,
+            source: 'custom'
+        });
+    });
+    return keywords;
+}
+/**
+ * Groups seed keywords by their source, maintaining order within each source.
+ * Keywords from the same portfolio item, competitor product, or funnel category
+ * are grouped together.
+ *
+ * @param seedKeywords - Flat array of seed keywords
+ * @param generateIdeasFromSeeds - When true, returns grouped keywords for idea generation.
+ *                                  When false, returns all keywords flattened into a single group.
+ * @returns Array of grouped keywords (arrays for same-source groups, single items for personas/custom)
+ */
+function groupSeedKeywords(seedKeywords, generateIdeasFromSeeds = true) {
+    let group;
+    const keywords = seedKeywords.reduce((acc, item) => {
+        if (item.source === 'brand-portfolio') {
+            if (item.sourceName === group) {
+                acc.brandInfoKeywords[acc.brandInfoKeywords.length - 1].push(item);
+                return acc;
+            }
+            else {
+                group = item.sourceName;
+                acc.brandInfoKeywords.push([item]);
+            }
+        }
+        else if (item.source === 'portfolio') {
+            if (item.sourceName === group) {
+                acc.competitorKeywords[acc.competitorKeywords.length - 1].push(item);
+                return acc;
+            }
+            else {
+                group = item.sourceName;
+                acc.competitorKeywords.push([item]);
+            }
+        }
+        else if (item.source === 'persona') {
+            group = undefined;
+            acc.personasKeywords.push(item);
+        }
+        else if (item.source === 'funnel') {
+            if (item.sourceName === group) {
+                acc.funnelKeywords[acc.funnelKeywords.length - 1].push(item);
+                return acc;
+            }
+            else {
+                group = item.sourceName;
+                acc.funnelKeywords.push([item]);
+            }
+        }
+        else if (item.source === 'custom') {
+            group = undefined;
+            acc.customKeywords.push(item);
+        }
+        return acc;
+    }, {
+        brandInfoKeywords: [],
+        competitorKeywords: [],
+        personasKeywords: [],
+        funnelKeywords: [],
+        customKeywords: []
+    });
+    const groupedKeywords = [
+        ...keywords.brandInfoKeywords,
+        ...keywords.competitorKeywords,
+        ...keywords.personasKeywords,
+        ...keywords.funnelKeywords,
+        ...keywords.customKeywords
+    ];
+    if (!generateIdeasFromSeeds) {
+        return [[...new Set(groupedKeywords.flat())]].filter(g => g.length > 0);
+    }
+    const normalizeKeyword = (keyword) => ({
+        ...keyword,
+        keyword: keyword.keyword.trim().toLowerCase()
+    });
+    const dedupeKeywordArray = (kws) => {
+        const seen = new Set();
+        return kws.filter(kw => {
+            const normalized = normalizeKeyword(kw);
+            if (seen.has(normalized.keyword)) {
+                return false;
+            }
+            seen.add(normalized.keyword);
+            return true;
+        });
+    };
+    const uniqueKeywordsSet = new Set();
+    const deduplicatedGroupedKeywords = groupedKeywords.reduce((acc, item) => {
+        if (Array.isArray(item)) {
+            const deduped = dedupeKeywordArray(item);
+            if (deduped.length > 0) {
+                acc.push(deduped);
+            }
+            return acc;
+        }
+        const normalized = normalizeKeyword(item);
+        if (uniqueKeywordsSet.has(normalized.keyword)) {
+            return acc;
+        }
+        uniqueKeywordsSet.add(normalized.keyword);
+        acc.push(item);
+        return acc;
+    }, []);
+    return deduplicatedGroupedKeywords;
+}
+/**
+ * Groups seed keywords and extracts just the keyword strings.
+ * Convenience wrapper around groupSeedKeywords for cases where
+ * only the keyword text is needed (not the full metadata).
+ */
+function groupKeywordStrings(seedKeywords, generateIdeasFromSeeds = true) {
+    const groupedSeedKeywords = groupSeedKeywords(seedKeywords, generateIdeasFromSeeds);
+    return groupedSeedKeywords.map(g => {
+        if (Array.isArray(g)) {
+            return g.map(kw => kw.keyword);
+        }
+        return g.keyword;
+    });
+}
+/**
+ * Collects and groups seed keywords in one step, returning only keyword strings.
+ * This is a convenience function for pipelines that need grouped keyword strings
+ * without the full SeedKeyword metadata.
+ *
+ * @param params - Same parameters as collectSeedKeywords
+ * @param generateIdeasFromSeeds - When true, returns grouped keywords. When false, returns flat.
+ * @returns Grouped keyword strings (arrays for same-source groups, single strings otherwise)
+ */
+function collectAndGroupKeywordStrings(params, generateIdeasFromSeeds = true) {
+    const seedKeywords = collectSeedKeywords(params);
+    return groupKeywordStrings(seedKeywords, generateIdeasFromSeeds);
+}

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

@@ -0,0 +1,11 @@
+import { type BrandContext } from '../schemas/brand.schema.js';
+import { type ABSentiment } from '../schemas/sentiment.schema.js';
+/**
+ * Extracts aspect-based sentiments from a 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>>>;
+//# sourceMappingURL=sentiment.d.ts.map

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

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