@graphext/cuery 0.6.3 → 0.7.0

package/esm/src/schemas/sentiment.schema.d.ts

@@ -6,6 +6,8 @@ export declare const ABSentimentSchema: z.ZodObject<{
         negative: "negative";
     }>;
     reason: z.ZodString;
+    quote: z.ZodString;
+    context: z.ZodNullable<z.ZodString>;
 }, z.core.$strip>;
 export declare const ABSentimentsSchema: z.ZodObject<{
     aspects: z.ZodArray<z.ZodObject<{
@@ -15,6 +17,8 @@ export declare const ABSentimentsSchema: z.ZodObject<{
             negative: "negative";
         }>;
         reason: z.ZodString;
+        quote: z.ZodString;
+        context: z.ZodNullable<z.ZodString>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export type ABSentiment = z.infer<typeof ABSentimentSchema>;

package/esm/src/schemas/sentiment.schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sentiment.schema.d.ts","sourceRoot":"","sources":["../../../src/src/schemas/sentiment.schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,+CAA+C,CAAC;AAElE,eAAO,MAAM,iBAAiB;;;;;;;iBAI5B,CAAC;AAEH,eAAO,MAAM,kBAAkB;;;;;;;;;iBAE7B,CAAC;AAEH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAC5D,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC"}
+{"version":3,"file":"sentiment.schema.d.ts","sourceRoot":"","sources":["../../../src/src/schemas/sentiment.schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,+CAA+C,CAAC;AAElE,eAAO,MAAM,iBAAiB;;;;;;;;;iBAc5B,CAAC;AAEH,eAAO,MAAM,kBAAkB;;;;;;;;;;;iBAE7B,CAAC;AAEH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAC5D,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC"}

package/esm/src/schemas/sentiment.schema.js

@@ -2,8 +2,12 @@ import { z } from '../../deps/jsr.io/@zod/zod/4.3.6/src/index.js';
 export const ABSentimentSchema = z.object({
     aspect: z.string().describe('The specific entity or aspect mentioned in the text.'),
     sentiment: z.enum(['positive', 'negative']).describe('The sentiment expressed toward the aspect, either positive or negative.'),
-    reason: z.string().describe('A brief explanation of why this sentiment was assigned to the aspect.')
+    reason: z.string().describe('A brief explanation of why this sentiment was assigned to the aspect.'),
+    quote: z.string().min(1).refine((val) => val.trim().length > 0, {
+        message: 'Quote must not be empty or whitespace-only',
+    }).describe('The exact text fragment from the input containing both the aspect and the sentiment expressed about it.'),
+    context: z.string().nullable().describe('Optional contextual information about the aspect, such as the brand or entity it relates to.'),
 });
 export const ABSentimentsSchema = z.object({
-    aspects: z.array(ABSentimentSchema).describe('A list of aspects with their associated sentiments and reasons.')
+    aspects: z.array(ABSentimentSchema).describe('A list of aspects with their associated sentiments, reasons, quotes, and optional context.')
 });

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

@@ -1,7 +1,7 @@
-import type { Message } from '../llm.js';
+import type { LLMResponse, Message } from '../llm.js';
 import type { BrandContext } from '../schemas/brand.schema.js';
 import { type ABSentiment, type ABSentiments } from '../schemas/sentiment.schema.js';
-import { Tool, type ModelConfig } from '../tool.js';
+import { type ModelConfig, Tool } from '../tool.js';
 import { Classifier } from './classifier.js';
 export interface SentimentExtractorConfig {
     /** Additional instructions for sentiment extraction */
@@ -23,11 +23,17 @@ export declare class SentimentExtractor extends Tool<string | null, ABSentiments
                 negative: "negative";
             }>;
             reason: import("../../deps/jsr.io/@zod/zod/4.3.6/src/index.js").ZodString;
+            quote: import("../../deps/jsr.io/@zod/zod/4.3.6/src/index.js").ZodString;
+            context: import("../../deps/jsr.io/@zod/zod/4.3.6/src/index.js").ZodNullable<import("../../deps/jsr.io/@zod/zod/4.3.6/src/index.js").ZodString>;
         }, import("../../deps/jsr.io/@zod/zod/4.3.6/src/v4/core/schemas.js").$strip>>;
     }, import("../../deps/jsr.io/@zod/zod/4.3.6/src/v4/core/schemas.js").$strip>;
     protected prompt(text: string | null): Message[];
     protected isEmpty(text: string | null): boolean;
     protected extractResult(parsed: ABSentiments): Array<ABSentiment>;
+    /**
+     * Override invoke to add quote validation
+     */
+    invoke(input: string | null, options?: Partial<ModelConfig>): Promise<LLMResponse<Array<ABSentiment> | null>>;
 }
 /**
  * Sentiment polarity labels for classification.

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

@@ -1 +1 @@
-{"version":3,"file":"sentiment.d.ts","sourceRoot":"","sources":["../../../src/src/tools/sentiment.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC/D,OAAO,EAAsB,KAAK,WAAW,EAAE,KAAK,YAAY,EAAE,MAAM,gCAAgC,CAAC;AACzG,OAAO,EAAE,IAAI,EAAE,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AACpD,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAwC7C,MAAM,WAAW,wBAAwB;IACxC,uDAAuD;IACvD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,yCAAyC;IACzC,KAAK,CAAC,EAAE,YAAY,GAAG,IAAI,CAAC;CAC5B;AAED;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,IAAI,CAAC,MAAM,GAAG,IAAI,EAAE,YAAY,EAAE,KAAK,CAAC,WAAW,CAAC,CAAC;IAC5F,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;gBAE1B,MAAM,EAAE,wBAAwB,YAAK,EAAE,WAAW,EAAE,WAAW;cAgBxD,MAAM;;;;;;;;;;IAIzB,SAAS,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,EAAE;cAQ7B,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO;cAIrC,aAAa,CAAC,MAAM,EAAE,YAAY,GAAG,KAAK,CAAC,WAAW,CAAC;CAG1E;AAMD;;GAEG;AACH,eAAO,MAAM,yBAAyB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAI5D,CAAC;AAWF;;GAEG;AACH,MAAM,WAAW,iCAAiC;IACjD,iDAAiD;IACjD,YAAY,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,qBAAa,2BAA4B,SAAQ,UAAU;gBAC9C,MAAM,EAAE,iCAAiC,YAAK,EAAE,WAAW,EAAE,WAAW;CAOpF;AAED,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AACvF,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,gCAAgC,CAAC"}
+{"version":3,"file":"sentiment.d.ts","sourceRoot":"","sources":["../../../src/src/tools/sentiment.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACtD,OAAO,KAAK,EAAE,YAAY,EAAW,MAAM,4BAA4B,CAAC;AACxE,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,YAAY,EAAsB,MAAM,gCAAgC,CAAC;AACzG,OAAO,EAAE,KAAK,WAAW,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AACpD,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AA6D7C,MAAM,WAAW,wBAAwB;IACxC,uDAAuD;IACvD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,yCAAyC;IACzC,KAAK,CAAC,EAAE,YAAY,GAAG,IAAI,CAAC;CAC5B;AAED;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,IAAI,CAAC,MAAM,GAAG,IAAI,EAAE,YAAY,EAAE,KAAK,CAAC,WAAW,CAAC,CAAC;IAC5F,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;gBAE1B,MAAM,EAAE,wBAAwB,YAAK,EAAE,WAAW,EAAE,WAAW;cAuBxD,MAAM;;;;;;;;;;;;IAIzB,SAAS,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,EAAE;cAQ7B,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO;cAIrC,aAAa,CAAC,MAAM,EAAE,YAAY,GAAG,KAAK,CAAC,WAAW,CAAC;IAI1E;;OAEG;IACY,MAAM,CACpB,KAAK,EAAE,MAAM,GAAG,IAAI,EACpB,OAAO,GAAE,OAAO,CAAC,WAAW,CAAM,GAChC,OAAO,CAAC,WAAW,CAAC,KAAK,CAAC,WAAW,CAAC,GAAG,IAAI,CAAC,CAAC;CA+BlD;AAMD;;GAEG;AACH,eAAO,MAAM,yBAAyB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAI5D,CAAC;AAWF;;GAEG;AACH,MAAM,WAAW,iCAAiC;IACjD,iDAAiD;IACjD,YAAY,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,qBAAa,2BAA4B,SAAQ,UAAU;gBAC9C,MAAM,EAAE,iCAAiC,YAAK,EAAE,WAAW,EAAE,WAAW;CAOpF;AAED,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AACvF,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,gCAAgC,CAAC"}

package/esm/src/tools/sentiment.js

@@ -2,6 +2,15 @@ import { dedent } from '../helpers/utils.js';
 import { ABSentimentsSchema } from '../schemas/sentiment.schema.js';
 import { Tool } from '../tool.js';
 import { Classifier } from './classifier.js';
+/**
+ * Formats a portfolio array as a comma-separated list of product/service names.
+ * Includes category in parentheses if available.
+ */
+function formatPortfolio(portfolio) {
+    return portfolio
+        .map((p) => (p.category ? `${p.name} (${p.category})` : p.name))
+        .join(', ');
+}
 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
@@ -15,10 +24,23 @@ Specifically:
     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")
+    d. the exact text fragment containing both the aspect and what is said about it (key "quote") - must be a verbatim substring
+    e. optional contextual information about the aspect, such as the brand or entity it relates to (key "context") - use null if not applicable
 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."}, ...]
+IMPORTANT: The "quote" field must be an EXACT verbatim substring from the input text. It should
+include the complete phrase mentioning both the aspect and the sentiment expressed about it.
+
+Example:
+
+Input text: "The room service at the Grand Hotel was absolutely terrible and the staff were rude, but the view from our room was breathtaking."
+
+Output:
+[
+  {"aspect": "The room service at the Grand Hotel", "sentiment": "negative", "reason": "Described as terrible.", "quote": "The room service at the Grand Hotel was absolutely terrible", "context": "Grand Hotel"},
+  {"aspect": "the staff", "sentiment": "negative", "reason": "Described as rude.", "quote": "the staff were rude", "context": "Grand Hotel"},
+  {"aspect": "the view from our room", "sentiment": "positive", "reason": "Described as breathtaking.", "quote": "the view from our room was breathtaking", "context": "Grand Hotel"}
+]
 
 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,
@@ -45,11 +67,18 @@ export class SentimentExtractor extends Tool {
         super(modelConfig);
         const { instructions = '', brand = null } = config;
         const brandInstructions = 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}.
-			`)
+            ? (() => {
+                const portfolio = formatPortfolio(brand.portfolio);
+                const portfolioText = portfolio
+                    ? ` or its products/services (${portfolio})`
+                    : '';
+                return dedent(`
+					Pay special attention to mentions of "${brand.shortName}"${portfolioText}.
+					When an aspect relates to a brand/entity, set the "context" field to "${brand.shortName}".
+					Keep aspect names and quoted text exactly as they appear in the original input.
+					Respond in language code ${brand.language}.
+				`);
+            })()
             : '';
         const combinedInstructions = [instructions, brandInstructions].filter(Boolean).join('\n\n');
         this.systemPrompt = ABS_PROMPT_SYSTEM.replace('{instructions}', combinedInstructions);
@@ -61,7 +90,7 @@ export class SentimentExtractor extends Tool {
         const userPrompt = ABS_PROMPT_USER.replace('{text}', text ?? '');
         return [
             { role: 'system', content: this.systemPrompt },
-            { role: 'user', content: userPrompt }
+            { role: 'user', content: userPrompt },
         ];
     }
     isEmpty(text) {
@@ -70,6 +99,33 @@ export class SentimentExtractor extends Tool {
     extractResult(parsed) {
         return parsed.aspects;
     }
+    /**
+     * Override invoke to add quote validation
+     */
+    async invoke(input, options = {}) {
+        const response = await super.invoke(input, options);
+        // If we have a successful result and non-empty input, validate quotes
+        if (response.parsed && input && input.trim() !== '') {
+            const validatedResult = response.parsed.filter((sentiment) => {
+                // Check that quote is non-empty and not just whitespace
+                if (!sentiment.quote || sentiment.quote.trim().length === 0) {
+                    console.warn(`Empty or whitespace-only quote for aspect "${sentiment.aspect}"`);
+                    return false;
+                }
+                // Check that quote is a substring of the input
+                if (!input.includes(sentiment.quote)) {
+                    console.warn(`Quote not found in text: "${sentiment.quote}" for aspect "${sentiment.aspect}"`);
+                    return false;
+                }
+                return true;
+            });
+            return {
+                ...response,
+                parsed: validatedResult,
+            };
+        }
+        return response;
+    }
 }
 // =============================================================================
 // SentimentPolarityClassifier (overall sentiment polarity)
@@ -80,7 +136,7 @@ export class SentimentExtractor extends Tool {
 export const SENTIMENT_POLARITY_LABELS = {
     positive: 'Expresses favorable opinions, approval, satisfaction, or optimism.',
     neutral: 'No clear sentiment expressed; factual, balanced, or ambiguous.',
-    negative: 'Expresses unfavorable opinions, criticism, dissatisfaction, or pessimism.'
+    negative: 'Expresses unfavorable opinions, criticism, dissatisfaction, or pessimism.',
 };
 /**
  * Predefined instructions for sentiment polarity classification.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@graphext/cuery",
-  "version": "0.6.3",
+  "version": "0.7.0",
   "description": "Cuery tools for AI-powered keyword research and brand analysis",
   "repository": {
     "type": "git",

package/script/src/schemas/sentiment.schema.d.ts

@@ -6,6 +6,8 @@ export declare const ABSentimentSchema: z.ZodObject<{
         negative: "negative";
     }>;
     reason: z.ZodString;
+    quote: z.ZodString;
+    context: z.ZodNullable<z.ZodString>;
 }, z.core.$strip>;
 export declare const ABSentimentsSchema: z.ZodObject<{
     aspects: z.ZodArray<z.ZodObject<{
@@ -15,6 +17,8 @@ export declare const ABSentimentsSchema: z.ZodObject<{
             negative: "negative";
         }>;
         reason: z.ZodString;
+        quote: z.ZodString;
+        context: z.ZodNullable<z.ZodString>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export type ABSentiment = z.infer<typeof ABSentimentSchema>;

package/script/src/schemas/sentiment.schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sentiment.schema.d.ts","sourceRoot":"","sources":["../../../src/src/schemas/sentiment.schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,+CAA+C,CAAC;AAElE,eAAO,MAAM,iBAAiB;;;;;;;iBAI5B,CAAC;AAEH,eAAO,MAAM,kBAAkB;;;;;;;;;iBAE7B,CAAC;AAEH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAC5D,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC"}
+{"version":3,"file":"sentiment.schema.d.ts","sourceRoot":"","sources":["../../../src/src/schemas/sentiment.schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,+CAA+C,CAAC;AAElE,eAAO,MAAM,iBAAiB;;;;;;;;;iBAc5B,CAAC;AAEH,eAAO,MAAM,kBAAkB;;;;;;;;;;;iBAE7B,CAAC;AAEH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAC5D,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC"}

package/script/src/schemas/sentiment.schema.js

@@ -5,8 +5,12 @@ const index_js_1 = require("../../deps/jsr.io/@zod/zod/4.3.6/src/index.js");
 exports.ABSentimentSchema = index_js_1.z.object({
     aspect: index_js_1.z.string().describe('The specific entity or aspect mentioned in the text.'),
     sentiment: index_js_1.z.enum(['positive', 'negative']).describe('The sentiment expressed toward the aspect, either positive or negative.'),
-    reason: index_js_1.z.string().describe('A brief explanation of why this sentiment was assigned to the aspect.')
+    reason: index_js_1.z.string().describe('A brief explanation of why this sentiment was assigned to the aspect.'),
+    quote: index_js_1.z.string().min(1).refine((val) => val.trim().length > 0, {
+        message: 'Quote must not be empty or whitespace-only',
+    }).describe('The exact text fragment from the input containing both the aspect and the sentiment expressed about it.'),
+    context: index_js_1.z.string().nullable().describe('Optional contextual information about the aspect, such as the brand or entity it relates to.'),
 });
 exports.ABSentimentsSchema = index_js_1.z.object({
-    aspects: index_js_1.z.array(exports.ABSentimentSchema).describe('A list of aspects with their associated sentiments and reasons.')
+    aspects: index_js_1.z.array(exports.ABSentimentSchema).describe('A list of aspects with their associated sentiments, reasons, quotes, and optional context.')
 });

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

@@ -1,7 +1,7 @@
-import type { Message } from '../llm.js';
+import type { LLMResponse, Message } from '../llm.js';
 import type { BrandContext } from '../schemas/brand.schema.js';
 import { type ABSentiment, type ABSentiments } from '../schemas/sentiment.schema.js';
-import { Tool, type ModelConfig } from '../tool.js';
+import { type ModelConfig, Tool } from '../tool.js';
 import { Classifier } from './classifier.js';
 export interface SentimentExtractorConfig {
     /** Additional instructions for sentiment extraction */
@@ -23,11 +23,17 @@ export declare class SentimentExtractor extends Tool<string | null, ABSentiments
                 negative: "negative";
             }>;
             reason: import("../../deps/jsr.io/@zod/zod/4.3.6/src/index.js").ZodString;
+            quote: import("../../deps/jsr.io/@zod/zod/4.3.6/src/index.js").ZodString;
+            context: import("../../deps/jsr.io/@zod/zod/4.3.6/src/index.js").ZodNullable<import("../../deps/jsr.io/@zod/zod/4.3.6/src/index.js").ZodString>;
         }, import("../../deps/jsr.io/@zod/zod/4.3.6/src/v4/core/schemas.js").$strip>>;
     }, import("../../deps/jsr.io/@zod/zod/4.3.6/src/v4/core/schemas.js").$strip>;
     protected prompt(text: string | null): Message[];
     protected isEmpty(text: string | null): boolean;
     protected extractResult(parsed: ABSentiments): Array<ABSentiment>;
+    /**
+     * Override invoke to add quote validation
+     */
+    invoke(input: string | null, options?: Partial<ModelConfig>): Promise<LLMResponse<Array<ABSentiment> | null>>;
 }
 /**
  * Sentiment polarity labels for classification.

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

@@ -1 +1 @@
-{"version":3,"file":"sentiment.d.ts","sourceRoot":"","sources":["../../../src/src/tools/sentiment.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC/D,OAAO,EAAsB,KAAK,WAAW,EAAE,KAAK,YAAY,EAAE,MAAM,gCAAgC,CAAC;AACzG,OAAO,EAAE,IAAI,EAAE,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AACpD,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAwC7C,MAAM,WAAW,wBAAwB;IACxC,uDAAuD;IACvD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,yCAAyC;IACzC,KAAK,CAAC,EAAE,YAAY,GAAG,IAAI,CAAC;CAC5B;AAED;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,IAAI,CAAC,MAAM,GAAG,IAAI,EAAE,YAAY,EAAE,KAAK,CAAC,WAAW,CAAC,CAAC;IAC5F,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;gBAE1B,MAAM,EAAE,wBAAwB,YAAK,EAAE,WAAW,EAAE,WAAW;cAgBxD,MAAM;;;;;;;;;;IAIzB,SAAS,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,EAAE;cAQ7B,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO;cAIrC,aAAa,CAAC,MAAM,EAAE,YAAY,GAAG,KAAK,CAAC,WAAW,CAAC;CAG1E;AAMD;;GAEG;AACH,eAAO,MAAM,yBAAyB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAI5D,CAAC;AAWF;;GAEG;AACH,MAAM,WAAW,iCAAiC;IACjD,iDAAiD;IACjD,YAAY,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,qBAAa,2BAA4B,SAAQ,UAAU;gBAC9C,MAAM,EAAE,iCAAiC,YAAK,EAAE,WAAW,EAAE,WAAW;CAOpF;AAED,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AACvF,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,gCAAgC,CAAC"}
+{"version":3,"file":"sentiment.d.ts","sourceRoot":"","sources":["../../../src/src/tools/sentiment.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACtD,OAAO,KAAK,EAAE,YAAY,EAAW,MAAM,4BAA4B,CAAC;AACxE,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,YAAY,EAAsB,MAAM,gCAAgC,CAAC;AACzG,OAAO,EAAE,KAAK,WAAW,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AACpD,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AA6D7C,MAAM,WAAW,wBAAwB;IACxC,uDAAuD;IACvD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,yCAAyC;IACzC,KAAK,CAAC,EAAE,YAAY,GAAG,IAAI,CAAC;CAC5B;AAED;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,IAAI,CAAC,MAAM,GAAG,IAAI,EAAE,YAAY,EAAE,KAAK,CAAC,WAAW,CAAC,CAAC;IAC5F,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;gBAE1B,MAAM,EAAE,wBAAwB,YAAK,EAAE,WAAW,EAAE,WAAW;cAuBxD,MAAM;;;;;;;;;;;;IAIzB,SAAS,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,EAAE;cAQ7B,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO;cAIrC,aAAa,CAAC,MAAM,EAAE,YAAY,GAAG,KAAK,CAAC,WAAW,CAAC;IAI1E;;OAEG;IACY,MAAM,CACpB,KAAK,EAAE,MAAM,GAAG,IAAI,EACpB,OAAO,GAAE,OAAO,CAAC,WAAW,CAAM,GAChC,OAAO,CAAC,WAAW,CAAC,KAAK,CAAC,WAAW,CAAC,GAAG,IAAI,CAAC,CAAC;CA+BlD;AAMD;;GAEG;AACH,eAAO,MAAM,yBAAyB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAI5D,CAAC;AAWF;;GAEG;AACH,MAAM,WAAW,iCAAiC;IACjD,iDAAiD;IACjD,YAAY,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,qBAAa,2BAA4B,SAAQ,UAAU;gBAC9C,MAAM,EAAE,iCAAiC,YAAK,EAAE,WAAW,EAAE,WAAW;CAOpF;AAED,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AACvF,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,gCAAgC,CAAC"}

package/script/src/tools/sentiment.js

@@ -5,6 +5,15 @@ const utils_js_1 = require("../helpers/utils.js");
 const sentiment_schema_js_1 = require("../schemas/sentiment.schema.js");
 const tool_js_1 = require("../tool.js");
 const classifier_js_1 = require("./classifier.js");
+/**
+ * Formats a portfolio array as a comma-separated list of product/service names.
+ * Includes category in parentheses if available.
+ */
+function formatPortfolio(portfolio) {
+    return portfolio
+        .map((p) => (p.category ? `${p.name} (${p.category})` : p.name))
+        .join(', ');
+}
 const ABS_PROMPT_SYSTEM = (0, utils_js_1.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
@@ -18,10 +27,23 @@ Specifically:
     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")
+    d. the exact text fragment containing both the aspect and what is said about it (key "quote") - must be a verbatim substring
+    e. optional contextual information about the aspect, such as the brand or entity it relates to (key "context") - use null if not applicable
 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."}, ...]
+IMPORTANT: The "quote" field must be an EXACT verbatim substring from the input text. It should
+include the complete phrase mentioning both the aspect and the sentiment expressed about it.
+
+Example:
+
+Input text: "The room service at the Grand Hotel was absolutely terrible and the staff were rude, but the view from our room was breathtaking."
+
+Output:
+[
+  {"aspect": "The room service at the Grand Hotel", "sentiment": "negative", "reason": "Described as terrible.", "quote": "The room service at the Grand Hotel was absolutely terrible", "context": "Grand Hotel"},
+  {"aspect": "the staff", "sentiment": "negative", "reason": "Described as rude.", "quote": "the staff were rude", "context": "Grand Hotel"},
+  {"aspect": "the view from our room", "sentiment": "positive", "reason": "Described as breathtaking.", "quote": "the view from our room was breathtaking", "context": "Grand Hotel"}
+]
 
 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,
@@ -48,11 +70,18 @@ class SentimentExtractor extends tool_js_1.Tool {
         super(modelConfig);
         const { instructions = '', brand = null } = config;
         const brandInstructions = brand
-            ? (0, utils_js_1.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}.
-			`)
+            ? (() => {
+                const portfolio = formatPortfolio(brand.portfolio);
+                const portfolioText = portfolio
+                    ? ` or its products/services (${portfolio})`
+                    : '';
+                return (0, utils_js_1.dedent)(`
+					Pay special attention to mentions of "${brand.shortName}"${portfolioText}.
+					When an aspect relates to a brand/entity, set the "context" field to "${brand.shortName}".
+					Keep aspect names and quoted text exactly as they appear in the original input.
+					Respond in language code ${brand.language}.
+				`);
+            })()
             : '';
         const combinedInstructions = [instructions, brandInstructions].filter(Boolean).join('\n\n');
         this.systemPrompt = ABS_PROMPT_SYSTEM.replace('{instructions}', combinedInstructions);
@@ -64,7 +93,7 @@ class SentimentExtractor extends tool_js_1.Tool {
         const userPrompt = ABS_PROMPT_USER.replace('{text}', text ?? '');
         return [
             { role: 'system', content: this.systemPrompt },
-            { role: 'user', content: userPrompt }
+            { role: 'user', content: userPrompt },
         ];
     }
     isEmpty(text) {
@@ -73,6 +102,33 @@ class SentimentExtractor extends tool_js_1.Tool {
     extractResult(parsed) {
         return parsed.aspects;
     }
+    /**
+     * Override invoke to add quote validation
+     */
+    async invoke(input, options = {}) {
+        const response = await super.invoke(input, options);
+        // If we have a successful result and non-empty input, validate quotes
+        if (response.parsed && input && input.trim() !== '') {
+            const validatedResult = response.parsed.filter((sentiment) => {
+                // Check that quote is non-empty and not just whitespace
+                if (!sentiment.quote || sentiment.quote.trim().length === 0) {
+                    console.warn(`Empty or whitespace-only quote for aspect "${sentiment.aspect}"`);
+                    return false;
+                }
+                // Check that quote is a substring of the input
+                if (!input.includes(sentiment.quote)) {
+                    console.warn(`Quote not found in text: "${sentiment.quote}" for aspect "${sentiment.aspect}"`);
+                    return false;
+                }
+                return true;
+            });
+            return {
+                ...response,
+                parsed: validatedResult,
+            };
+        }
+        return response;
+    }
 }
 exports.SentimentExtractor = SentimentExtractor;
 // =============================================================================
@@ -84,7 +140,7 @@ exports.SentimentExtractor = SentimentExtractor;
 exports.SENTIMENT_POLARITY_LABELS = {
     positive: 'Expresses favorable opinions, approval, satisfaction, or optimism.',
     neutral: 'No clear sentiment expressed; factual, balanced, or ambiguous.',
-    negative: 'Expresses unfavorable opinions, criticism, dissatisfaction, or pessimism.'
+    negative: 'Expresses unfavorable opinions, criticism, dissatisfaction, or pessimism.',
 };
 /**
  * Predefined instructions for sentiment polarity classification.