@graphext/cuery 0.2.0

package/esm/src/tools/seedKeywords.js

@@ -0,0 +1,214 @@
+/**
+ * Seed Keyword Functions
+ *
+ * Pure functions for collecting and grouping seed keywords.
+ * No external dependencies - safe to import in both frontend and backend.
+ */
+/**
+ * Collects seed keywords from all sources and creates SeedKeyword objects
+ * with proper metadata (id, source, sourceId, sourceName).
+ */
+export 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)
+ */
+export 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).
+ */
+export 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)
+ */
+export function collectAndGroupKeywordStrings(params, generateIdeasFromSeeds = true) {
+    const seedKeywords = collectSeedKeywords(params);
+    return groupKeywordStrings(seedKeywords, generateIdeasFromSeeds);
+}

package/esm/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/esm/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"}

package/esm/src/tools/sentiment.js

@@ -0,0 +1,68 @@
+import { mapParallel } from '../async.js';
+import { askOpenAISafe } from '../openai.js';
+import { ABSentimentsSchema } from '../schemas/sentiment.schema.js';
+import { dedent } from '../utils.js';
+const ABS_PROMPT_SYSTEM = dedent(`
+You're an expert in Aspect-Based Sentiment Analysis. Your task involves identifying specific
+entities mentioned in a text (e.g. a person, product, service, or experience) and determining the
+polarity of the sentiment expressed toward each.
+
+Specifically:
+
+1. Identify aspects in the text that have either a positive or negative sentiment expressed toward them.
+2. Ignore(!) all aspects that do not have a sentiment associated with them or where the sentiment is neutral.
+3. Output a list of objects, where each object contains
+    a. the aspect as it occurs in the text (key "aspect")
+    b. the sentiment label as either "positive" or "negative" (key "sentiment")
+    c. the reason for the sentiment assignment as a short text (key "reason")
+4. If there are no sentiment-bearing aspects in the text, the output should be an empty list
+
+Example Output format:
+[{"aspect": "room service", "sentiment": "negative", "reason": "Room service was mentioned being rude."}, ...]
+
+Only extract aspects that have an explicitly expressed sentiment associated with them, i.e.
+subjective opinions, feelings, or evaluations. Do not infer sentiment from factual statements,
+e.g. just because a feature is mentioned as "new", a product or service is mentioned as having
+a certain feature, or because something is mentioned as "modern", "efficient" etc. it shouldn't be
+considered a sentiment. Look for explicit expressions of positive or negative feelings, especially
+adjectives or adverbs that indicate a sentiment.
+
+{instructions}
+`);
+const ABS_PROMPT_USER = dedent(`
+Return the entities and their sentiments with reasons from the following text section.
+
+# Text
+
+{text}
+`);
+/**
+ * Extracts aspect-based sentiments from a text.
+ */
+export async function extractAspectBasedSentiments(text, instructions = '', model = 'gpt-4.1-mini') {
+    if (text == null || text.trim() === '') {
+        return [];
+    }
+    const promptSystem = ABS_PROMPT_SYSTEM.replace('{instructions}', instructions);
+    const promptUser = ABS_PROMPT_USER.replace('{text}', text);
+    const conversation = [
+        { role: 'system', content: promptSystem },
+        { role: 'user', content: promptUser }
+    ];
+    const { parsed } = await askOpenAISafe(conversation, model, ABSentimentsSchema);
+    if (!parsed) {
+        throw new Error('Failed to parse response from OpenAI');
+    }
+    return parsed.aspects;
+}
+/**
+ * Classifies multiple data records concurrently while preserving order.
+ */
+export async function extractABSForBrandBatch(texts, brand = null, model = 'gpt-4.1-mini', maxConcurrency = 100) {
+    const instructions = brand ? dedent(`
+    When analyzing the text, pay special attention to any mentions of the brand "${brand.shortName}"
+    or its products/services (${brand.portfolio}). Ensure that any sentiments expressed toward this
+    brand or its offerings are accurately captured in your output. Respond in language code ${brand.language}.
+    `) : '';
+    return mapParallel(texts, maxConcurrency, (text) => extractAspectBasedSentiments(text, instructions, model));
+}

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

@@ -0,0 +1,39 @@
+import { type FlaggedBrand } from '../schemas/brand.schema.js';
+import type { CategorizedSource, EnrichedSource, Source } from '../schemas/sources.schema.js';
+import { type TopicLabel } from './topics.js';
+import type { AIParams } from '../openai.js';
+import type { Entity } from './entities.js';
+export type { Source, EnrichedSource, CategorizedSource } from '../schemas/sources.schema.js';
+/**
+ * Checks if brand or competitor is mentioned in the source title or URL.
+ */
+export declare function enrichSource(source: Source, brands: Array<FlaggedBrand>, entities?: Array<Entity>): EnrichedSource;
+export declare function enrichSources(sources: Array<Array<Source> | null>, brands: Array<FlaggedBrand>, entities?: Array<Array<Entity>>): Promise<Array<Array<EnrichedSource>>>;
+/**
+ * Ranks brand mentions in an array of enriched sources.
+ */
+export declare function rankBrandsInSourceArray(sources: Array<EnrichedSource>): {
+    mentionedBrands: Array<string>;
+    linkedBrands: Array<string>;
+};
+export declare function rankedBrandsInSources(sources: Array<Array<EnrichedSource>>): {
+    mentionedBrands: Array<Array<string>>;
+    linkedBrands: Array<Array<string>>;
+};
+/**
+ * Collects unique URLs or domains from nested lists of Sources.
+ */
+export declare function collectURLs(sourceLists: Array<Array<Source>>, domains?: boolean): Array<string>;
+/**
+ * Classifies an array of URLs into categories based on WEB_TAXONOMY.
+ */
+export declare function classifyURLs(urls: Array<string>, model?: string, modelParams?: AIParams, maxConcurrency?: number): Promise<Record<string, TopicLabel | null>>;
+/**
+ * Creates a category mapper for sources by collecting unique URLs/domains and classifying them.
+ */
+export declare function makeCategoryMapper(sourceLists: Array<Array<Source>>, domains?: boolean, model?: string, modelParams?: AIParams, maxConcurrency?: number): Promise<Record<string, TopicLabel | null>>;
+/**
+ * Categorizes sources by assigning topic and subtopic to each EnrichedSource in-place(!).
+ */
+export declare function categorizeSources(sourceLists: Array<Array<EnrichedSource>>, domains?: boolean, model?: string, modelParams?: AIParams, maxConcurrency?: number): Promise<Array<Array<CategorizedSource>>>;
+//# sourceMappingURL=sources.d.ts.map

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

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

package/esm/src/tools/sources.js

@@ -0,0 +1,263 @@
+import { mapParallel } from '../async.js';
+import { createBrandMatchKey } from './brands.js';
+import { assignTopic, createLabelSchema, toTopics } from './topics.js';
+/**
+ * Checks if brand or competitor is mentioned in the source title or URL.
+ */
+export function enrichSource(source, brands, entities = []) {
+    const mentionedBrandsMap = new Map(); // norm -> display
+    const mentionedCompetitorsMap = new Map(); // norm -> display
+    let linkedBrand = null;
+    let linkedCompetitor = null;
+    const title = source.title.toLowerCase();
+    const url = source.url.toLowerCase();
+    // Map de nombre normalizado -> nombre legible canonico (shortName) para favorecer la marca
+    const brandDisplayByNorm = new Map();
+    for (const brand of brands) {
+        const norm = createBrandMatchKey(brand.shortName);
+        if (norm) {
+            brandDisplayByNorm.set(norm, brand.shortName);
+        }
+    }
+    for (const brand of brands) {
+        const brandName = brand.shortName;
+        const nameLower = brandName.toLowerCase();
+        const isMentioned = title.includes(nameLower) || url.includes(nameLower);
+        const isLinked = source.domain === brand.domain;
+        const normName = createBrandMatchKey(brandName);
+        if (!brand.isCompetitor) {
+            if (isMentioned) {
+                if (normName && !mentionedBrandsMap.has(normName)) {
+                    mentionedBrandsMap.set(normName, brandName);
+                }
+            }
+            if (isLinked) {
+                linkedBrand = brandName;
+            }
+        }
+        else {
+            if (isMentioned) {
+                if (normName && !mentionedCompetitorsMap.has(normName)) {
+                    mentionedCompetitorsMap.set(normName, brandName);
+                }
+            }
+            if (isLinked) {
+                linkedCompetitor = brandName;
+            }
+        }
+    }
+    for (const entity of entities) {
+        if (entity.type.toLowerCase() !== 'brand')
+            continue;
+        const entityNameLower = entity.name.toLowerCase();
+        const isMentioned = title.includes(entityNameLower) || url.includes(entityNameLower);
+        const normEntity = createBrandMatchKey(entity.name);
+        const displayName = normEntity && brandDisplayByNorm.get(normEntity) ?
+            brandDisplayByNorm.get(normEntity) : entity.name;
+        if (isMentioned) {
+            if (normEntity && !mentionedCompetitorsMap.has(normEntity)) {
+                // keep a readable display while deduping on normalized form
+                mentionedCompetitorsMap.set(normEntity, displayName);
+            }
+        }
+    }
+    return {
+        ...source,
+        mentionedBrands: Array.from(mentionedBrandsMap.values()),
+        mentionedCompetitors: Array.from(mentionedCompetitorsMap.values()),
+        linkedBrand,
+        linkedCompetitor
+    };
+}
+export async function enrichSources(sources, brands, entities = []) {
+    return sources.map((sourceList, index) => sourceList == null ? [] : sourceList.map(source => enrichSource(source, brands, entities[index] ?? [])));
+}
+/**
+ * Ranks brand mentions in an array of enriched sources.
+ */
+export function rankBrandsInSourceArray(sources) {
+    const rankedMentions = [];
+    const rankedLinks = [];
+    const seenMentions = new Set();
+    const seenLinks = new Set();
+    sources.forEach((source, sourceIndex) => {
+        // Process mentioned brands (both brands and competitors)
+        source.mentionedBrands.forEach(brandName => {
+            const norm = createBrandMatchKey(brandName);
+            if (norm && !seenMentions.has(norm)) {
+                seenMentions.add(norm);
+                rankedMentions.push({
+                    name: brandName,
+                    position: sourceIndex
+                });
+            }
+        });
+        source.mentionedCompetitors.forEach(competitorName => {
+            const norm = createBrandMatchKey(competitorName);
+            if (norm && !seenMentions.has(norm)) {
+                seenMentions.add(norm);
+                rankedMentions.push({
+                    name: competitorName,
+                    position: sourceIndex
+                });
+            }
+        });
+        // Process linked brands (singular - only one brand can be linked per source)
+        if (source.linkedBrand != null) {
+            const norm = createBrandMatchKey(source.linkedBrand);
+            if (norm && !seenLinks.has(norm)) {
+                seenLinks.add(norm);
+                rankedLinks.push({
+                    name: source.linkedBrand,
+                    position: sourceIndex
+                });
+            }
+        }
+        if (source.linkedCompetitor != null) {
+            const norm = createBrandMatchKey(source.linkedCompetitor);
+            if (norm && !seenLinks.has(norm)) {
+                seenLinks.add(norm);
+                rankedLinks.push({
+                    name: source.linkedCompetitor,
+                    position: sourceIndex
+                });
+            }
+        }
+    });
+    return {
+        mentionedBrands: rankedMentions
+            .sort((a, b) => a.position - b.position)
+            .map(item => item.name),
+        linkedBrands: rankedLinks
+            .sort((a, b) => a.position - b.position)
+            .map(item => item.name)
+    };
+}
+export function rankedBrandsInSources(sources) {
+    const allMentioned = [];
+    const allLinked = [];
+    for (const sourceList of sources) {
+        const { mentionedBrands, linkedBrands } = rankBrandsInSourceArray(sourceList);
+        allMentioned.push(mentionedBrands);
+        allLinked.push(linkedBrands);
+    }
+    return {
+        mentionedBrands: allMentioned,
+        linkedBrands: allLinked
+    };
+}
+/**
+ * Collects unique URLs or domains from nested lists of Sources.
+ */
+export function collectURLs(sourceLists, domains = false) {
+    const collected = new Set();
+    for (const sources of sourceLists) {
+        if (sources == null)
+            continue;
+        for (const source of sources) {
+            const value = domains ? source.domain : source.url;
+            if (value.length > 400) {
+                console.warn(`Skipping overly long ${domains ? 'domain' : 'URL'}: ${value}`);
+                continue;
+            }
+            collected.add(value);
+        }
+    }
+    return Array.from(collected);
+}
+const WEB_TAXONOMY = {
+    'Authority & Ownership': [
+        'Brand / Corporate Site',
+        'Product / Microsite',
+        'Government / Public Sector',
+        'Education / Academic',
+        'Non-Profit / NGO',
+        'Religious / Faith-Based'
+    ],
+    'News & Media': [
+        'Mainstream News Outlet',
+        'Trade / Niche Publication',
+        'Local / Regional News',
+        'Press Release Distribution'
+    ],
+    'Reference & Knowledge': [
+        'Encyclopedic Reference',
+        'Data / Statistics Portal',
+        'Guides & Tutorials',
+        'Educational Content Hub'
+    ],
+    'Content & Community': [
+        'Blog',
+        'Forum / Message Board',
+        'Social Network',
+        'Aggregator / Q&A Platform',
+        'User Review Site'
+    ],
+    'Commercial': [
+        'E-Commerce / Retailer',
+        'Marketplace',
+        'Affiliate / Comparison Site',
+        'Classifieds / Listings',
+        'Travel / Booking Platform',
+        'Job Board / Recruitment'
+    ],
+    'Professional & B2B': [
+        'Consultancy / Agency',
+        'Professional Services (Legal, Medical, Financial)',
+        'SaaS Product Site',
+        'B2B Marketplace / Vendor Directory',
+        'Technology Documentation (APIs, GitHub, OSS)',
+        'Online Tool / Calculator',
+        'Tech Blog / Knowledge Hub'
+    ],
+    'Lifestyle & Entertainment': [
+        'Streaming Platform',
+        'Sports Site / Gaming Site',
+        'Lifestyle & Culture (Food, Fashion, Travel, Hobbies)',
+        'Events & Ticketing'
+    ],
+    'Low-Value / Edge Cases': [
+        'Parked / Placeholder Domain',
+        'Spam / Low-Quality SEO Site',
+        'Personal / Portfolio Site'
+    ]
+};
+const WEB_LABEL_SCHEMA = createLabelSchema({ topics: toTopics(WEB_TAXONOMY) });
+const WEB_TAXONOMY_SERIALIZED = JSON.stringify(WEB_TAXONOMY, null, 2);
+/**
+ * Classifies an array of URLs into categories based on WEB_TAXONOMY.
+ */
+export async function classifyURLs(urls, model = 'gpt-5.1', modelParams = { reasoning: { effort: 'none' } }, maxConcurrency = 100) {
+    const labels = await mapParallel(urls, maxConcurrency, url => assignTopic(url, WEB_TAXONOMY_SERIALIZED, WEB_LABEL_SCHEMA, model, modelParams));
+    const urlToCategory = {};
+    urls.forEach((url, index) => {
+        urlToCategory[url] = labels[index];
+    });
+    return urlToCategory;
+}
+/**
+ * Creates a category mapper for sources by collecting unique URLs/domains and classifying them.
+ */
+export async function makeCategoryMapper(sourceLists, domains = false, model = 'gpt-5.1', modelParams = { reasoning: { effort: 'none' } }, maxConcurrency = 100) {
+    const urls = collectURLs(sourceLists, domains);
+    const categoryMapping = await classifyURLs(urls, model, modelParams, maxConcurrency);
+    return categoryMapping;
+}
+/**
+ * Categorizes sources by assigning topic and subtopic to each EnrichedSource in-place(!).
+ */
+export async function categorizeSources(sourceLists, domains = false, model = 'gpt-5.1', modelParams = { reasoning: { effort: 'none' } }, maxConcurrency = 100) {
+    const categoryMapper = await makeCategoryMapper(sourceLists, domains, model, modelParams, maxConcurrency);
+    for (const sources of sourceLists) {
+        if (sources == null)
+            continue;
+        for (const source of sources) {
+            const key = domains ? source.domain : source.url;
+            const label = categoryMapper[key];
+            source.category = label?.topic ?? null;
+            source.subcategory = label?.subtopic ?? null;
+        }
+    }
+    const categorizedSources = sourceLists;
+    return categorizedSources;
+}

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

@@ -0,0 +1,74 @@
+import { z } from '../../deps/jsr.io/@zod/zod/4.1.12/src/index.js';
+import { type AIParams } from '../openai.js';
+import { type TopicType, type TaxonomyType, type TopicLabel } from '../schemas/topics.schema.js';
+export type { TopicType, TaxonomyType, TopicLabel };
+/**
+ * Topic schema with subtopic validation
+ * Validates that subtopics are sufficiently distinct from each other and from the parent topic.
+ */
+export declare const Topic: z.ZodObject<{
+    topic: z.ZodString;
+    subtopics: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Taxonomy schema WITHOUT validation for fallback parsing
+ */
+export declare const TaxonomyBase: z.ZodObject<{
+    topics: z.ZodArray<z.ZodObject<{
+        topic: z.ZodString;
+        subtopics: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/**
+ * Taxonomy schema with topic validation
+ */
+export declare const Taxonomy: z.ZodObject<{
+    topics: z.ZodArray<z.ZodObject<{
+        topic: z.ZodString;
+        subtopics: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/**
+ * Converts a taxonomy in the format Record<string, Array<string>> to an array
+ * of topic objects compatible with the Topic schema.
+ */
+export declare function toTopics(taxonomy: Record<string, Array<string>>): Array<{
+    topic: string;
+    subtopics: Array<string>;
+}>;
+/**
+ * Creates a dynamic TopicLabel schema based on a topic hierarchy
+ * Validates that subtopic belongs to the correct topic
+ */
+export declare function createLabelSchema(taxonomy: TaxonomyType): z.ZodObject<{
+    topic: z.ZodEnum<{
+        [x: string]: string;
+    }>;
+    subtopic: z.ZodEnum<{
+        [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>>;
+    nTopics?: number;
+    nSubtopics?: number;
+    instructions?: string;
+    maxSamples?: number;
+    model?: string;
+    modelParams?: AIParams;
+    maxRetries?: number;
+    language?: string;
+}
+/**
+ * Extracts a topic hierarchy from an array of records using an LLM.
+ */
+export declare function extractTopics({ records, nTopics, nSubtopics, instructions, maxSamples, model, modelParams, maxRetries, language }: TopicExtractionOptions): Promise<TaxonomyType>;
+//# sourceMappingURL=topics.d.ts.map