@graphext/cuery 0.2.0

package/script/src/tools/classifier.js

@@ -0,0 +1,141 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.classify = classify;
+exports.classifyBatch = classifyBatch;
+exports.label = label;
+exports.labelBatch = labelBatch;
+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_TEMPLATE = (0, utils_js_1.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 = (0, utils_js_1.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 index_js_1.z.object({
+            label: index_js_1.z.literal(label).describe(description)
+        });
+    }
+    // TypeScript now knows entries.length >= 2
+    const literals = entries.map(([label, description]) => index_js_1.z.literal(label).describe(description));
+    return index_js_1.z.object({
+        label: index_js_1.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 index_js_1.z.object({
+        labels: index_js_1.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.
+ */
+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 (0, openai_js_1.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.
+ */
+function classifyBatch(records, labels, instructions = '', model = 'gpt-4.1-mini', maxConcurrency = 100) {
+    return (0, async_js_1.mapParallel)(records, maxConcurrency, record => classify(record, labels, instructions, model));
+}
+/**
+ * Assigns one or more labels to a single data record using an LLM call.
+ */
+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 (0, openai_js_1.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.
+ */
+function labelBatch(records, labels, instructions = '', model = 'gpt-4.1-mini', maxConcurrency = 100) {
+    return (0, async_js_1.mapParallel)(records, maxConcurrency, record => label(record, labels, instructions, model));
+}

package/script/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/script/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/script/src/tools/entities.js

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EntitiesSchema = exports.EntitySchema = exports.PROMPT = void 0;
+exports.extractAnyEntities = extractAnyEntities;
+exports.extractEntitiesFromText = extractEntitiesFromText;
+exports.extractEntitiesBatch = extractEntitiesBatch;
+const async_js_1 = require("../async.js");
+const openai_js_1 = require("../openai.js");
+const entity_schema_js_1 = require("../schemas/entity.schema.js");
+const utils_js_1 = require("../utils.js");
+exports.PROMPT = (0, utils_js_1.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).
+ */
+async function extractAnyEntities(body, instructions = '', model, modelParams = {}) {
+    const prompt = exports.PROMPT
+        .replace('{definitions}', '')
+        .replace('{text}', body)
+        .replace('{instructions}', instructions);
+    const { parsed } = await (0, openai_js_1.askOpenAISafe)(prompt, model, entity_schema_js_1.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.
+ */
+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 = exports.PROMPT
+        .replace('{definitions}', definitionsText)
+        .replace('{text}', text)
+        .replace('{instructions}', instructions);
+    const { parsed } = await (0, openai_js_1.askOpenAISafe)(prompt, model, entity_schema_js_1.EntitiesSchema, modelParams);
+    if (!parsed) {
+        throw new Error('Failed to parse response from OpenAI');
+    }
+    return parsed.entities;
+}
+/**
+ * Extracts entities from a batch of texts.
+ */
+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 (0, async_js_1.mapParallel)(texts, maxConcurrency, (text) => extractEntitiesFromText(text, definitions, instructions, model, modelParams));
+}
+var entity_schema_js_2 = require("../schemas/entity.schema.js");
+Object.defineProperty(exports, "EntitySchema", { enumerable: true, get: function () { return entity_schema_js_2.EntitySchema; } });
+Object.defineProperty(exports, "EntitiesSchema", { enumerable: true, get: function () { return entity_schema_js_2.EntitiesSchema; } });

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