@higher.archi/boe 1.0.25 → 1.0.27

package/dist/engines/sentiment/compiler.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Sentiment Engine Compiler
+ *
+ * Validates sentiment rulesets, normalizes lexicon keys to lowercase,
+ * and resolves config defaults.
+ */
+import type { SentimentRuleSet, CompiledSentimentRuleSet } from './types';
+/**
+ * Compile and validate a sentiment ruleset.
+ */
+export declare function compileSentimentRuleSet(ruleSet: SentimentRuleSet): CompiledSentimentRuleSet;
+//# sourceMappingURL=compiler.d.ts.map

package/dist/engines/sentiment/compiler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compiler.d.ts","sourceRoot":"","sources":["../../../src/engines/sentiment/compiler.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EACV,gBAAgB,EAChB,wBAAwB,EAKzB,MAAM,SAAS,CAAC;AAGjB;;GAEG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,gBAAgB,GACxB,wBAAwB,CAuE1B"}

package/dist/engines/sentiment/compiler.js

@@ -0,0 +1,111 @@
+"use strict";
+/**
+ * Sentiment Engine Compiler
+ *
+ * Validates sentiment rulesets, normalizes lexicon keys to lowercase,
+ * and resolves config defaults.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.compileSentimentRuleSet = compileSentimentRuleSet;
+const errors_1 = require("../../core/errors");
+const types_1 = require("./types");
+/**
+ * Compile and validate a sentiment ruleset.
+ */
+function compileSentimentRuleSet(ruleSet) {
+    if (!ruleSet.id) {
+        throw new errors_1.CompilationError('Sentiment ruleset requires an id');
+    }
+    if (ruleSet.mode !== 'sentiment') {
+        throw new errors_1.CompilationError(`Expected mode 'sentiment', got '${ruleSet.mode}'`);
+    }
+    if (!ruleSet.lexiconConfig || !ruleSet.lexiconConfig.lexicon) {
+        throw new errors_1.CompilationError('Sentiment ruleset requires a lexiconConfig with a lexicon');
+    }
+    const lexiconKeys = Object.keys(ruleSet.lexiconConfig.lexicon);
+    if (lexiconKeys.length === 0) {
+        throw new errors_1.CompilationError('Lexicon must contain at least one entry');
+    }
+    // Compile the lexicon
+    const lexicon = compileLexicon(ruleSet.lexiconConfig);
+    // Resolve config defaults
+    const config = {
+        capsBoost: ruleSet.config?.capsBoost ?? types_1.SENTIMENT_DEFAULTS.capsBoost,
+        exclamationBoost: ruleSet.config?.exclamationBoost ?? types_1.SENTIMENT_DEFAULTS.exclamationBoost,
+        negationWindow: ruleSet.config?.negationWindow ?? types_1.SENTIMENT_DEFAULTS.negationWindow
+    };
+    switch (ruleSet.strategy) {
+        case 'token-level':
+            return {
+                id: ruleSet.id,
+                name: ruleSet.name,
+                mode: 'sentiment',
+                strategy: 'token-level',
+                lexicon,
+                config
+            };
+        case 'document-level': {
+            const pattern = ruleSet.sentenceSplitPattern ?? '[.!?]+';
+            return {
+                id: ruleSet.id,
+                name: ruleSet.name,
+                mode: 'sentiment',
+                strategy: 'document-level',
+                lexicon,
+                config,
+                sentenceSplitPattern: new RegExp(pattern)
+            };
+        }
+        case 'aspect-based': {
+            if (!ruleSet.aspects || ruleSet.aspects.length === 0) {
+                throw new errors_1.CompilationError('Aspect-based strategy requires at least one aspect');
+            }
+            const aspects = ruleSet.aspects.map(a => a.toLowerCase());
+            return {
+                id: ruleSet.id,
+                name: ruleSet.name,
+                mode: 'sentiment',
+                strategy: 'aspect-based',
+                lexicon,
+                config,
+                aspects
+            };
+        }
+        default:
+            throw new errors_1.CompilationError(`Unknown sentiment strategy: '${ruleSet.strategy}'`);
+    }
+}
+function compileLexicon(input) {
+    // Normalize all keys to lowercase
+    const lexicon = {};
+    for (const [key, value] of Object.entries(input.lexicon)) {
+        lexicon[key.toLowerCase()] = value;
+    }
+    const boosters = {};
+    if (input.boosters) {
+        for (const [key, value] of Object.entries(input.boosters)) {
+            boosters[key.toLowerCase()] = value;
+        }
+    }
+    const negation = new Set((input.negation ?? []).map(w => w.toLowerCase()));
+    const idioms = {};
+    let idiomMaxLength = 0;
+    if (input.idioms) {
+        for (const [key, value] of Object.entries(input.idioms)) {
+            const normalized = key.toLowerCase();
+            idioms[normalized] = value;
+            const wordCount = normalized.split(/\s+/).length;
+            if (wordCount > idiomMaxLength) {
+                idiomMaxLength = wordCount;
+            }
+        }
+    }
+    return {
+        lexicon,
+        boosters,
+        negation,
+        idioms,
+        _idiomMaxLength: idiomMaxLength
+    };
+}
+//# sourceMappingURL=compiler.js.map

package/dist/engines/sentiment/compiler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compiler.js","sourceRoot":"","sources":["../../../src/engines/sentiment/compiler.ts"],"names":[],"mappings":"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"}

package/dist/engines/sentiment/engine.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Sentiment Engine
+ *
+ * Text sentiment analysis engine that scores text using dictionary-lookup
+ * and heuristic rules. Supports token-level, document-level, and aspect-based
+ * analysis strategies with injectable lexicon configuration.
+ *
+ * @example
+ * ```typescript
+ * const engine = new SentimentEngine();
+ * engine.add({ type: 'Review', data: { text: 'The product is absolutely fantastic!' } });
+ *
+ * const result = engine.execute(compiledRuleset);
+ * console.log(result.compound); // 0.85 (positive)
+ * ```
+ */
+import { WorkingMemory, Fact, FactInput, FactChange } from '../../core';
+import type { CompiledSentimentRuleSet, SentimentOptions, SentimentResult, IngestResult } from './types';
+export declare class SentimentEngine {
+    private wm;
+    private strategy;
+    private _stream;
+    constructor(workingMemory?: WorkingMemory);
+    add<T = Record<string, any>>(input: FactInput<T>): Fact<T>;
+    remove(factId: string): Fact | undefined;
+    update<T = Record<string, any>>(input: FactInput<T>): Fact<T>;
+    get(factId: string): Fact | undefined;
+    getByType(type: string): Fact[];
+    getAll(): Fact[];
+    has(factId: string): boolean;
+    size(): number;
+    clear(): void;
+    getChanges(): FactChange[];
+    clearChanges(): void;
+    /**
+     * Execute a sentiment analysis ruleset.
+     *
+     * Extracts text from all facts in working memory, applies the configured
+     * sentiment strategy, and returns compound scores with token-level detail.
+     *
+     * @param ruleSet - Compiled sentiment ruleset
+     * @param options - Runtime options (onToken callback)
+     * @returns Sentiment result with compound score, label, and detail
+     */
+    execute(ruleSet: CompiledSentimentRuleSet, options?: SentimentOptions): SentimentResult;
+    /**
+     * Score a single text incrementally without touching working memory.
+     *
+     * Each call scores the provided text, updates a running accumulator,
+     * and returns both the individual score and the current aggregate.
+     * The compiled ruleset must stay the same across calls (matched by id).
+     * Call `resetStream()` to start a new stream.
+     *
+     * @param text - Raw text to score
+     * @param ruleSet - Compiled sentiment ruleset
+     * @param options - Runtime options (onToken callback)
+     * @returns IngestResult with item-level and aggregate scores
+     */
+    ingest(text: string, ruleSet: CompiledSentimentRuleSet, options?: SentimentOptions): IngestResult;
+    /**
+     * Get the current streaming aggregate without ingesting new text.
+     * Returns null if no texts have been ingested yet.
+     */
+    getStreamResult(): SentimentResult | null;
+    /**
+     * Reset the streaming accumulator. Does not affect working memory.
+     */
+    resetStream(): void;
+    getWorkingMemory(): WorkingMemory;
+}
+//# sourceMappingURL=engine.d.ts.map

package/dist/engines/sentiment/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../../src/engines/sentiment/engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EACL,aAAa,EACb,IAAI,EACJ,SAAS,EACT,UAAU,EACX,MAAM,YAAY,CAAC;AAEpB,OAAO,KAAK,EACV,wBAAwB,EACxB,gBAAgB,EAChB,eAAe,EAEf,YAAY,EAEb,MAAM,SAAS,CAAC;AA0BjB,qBAAa,eAAe;IAC1B,OAAO,CAAC,EAAE,CAAgB;IAC1B,OAAO,CAAC,QAAQ,CAAoB;IACpC,OAAO,CAAC,OAAO,CAA4B;gBAE/B,aAAa,CAAC,EAAE,aAAa;IASzC,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,KAAK,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC;IAI1D,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS;IAIxC,MAAM,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,KAAK,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC;IAI7D,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS;IAIrC,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE;IAI/B,MAAM,IAAI,IAAI,EAAE;IAIhB,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAI5B,IAAI,IAAI,MAAM;IAId,KAAK,IAAI,IAAI;IAIb,UAAU,IAAI,UAAU,EAAE;IAI1B,YAAY,IAAI,IAAI;IAQpB;;;;;;;;;OASG;IACH,OAAO,CACL,OAAO,EAAE,wBAAwB,EACjC,OAAO,GAAE,gBAAqB,GAC7B,eAAe;IAQlB;;;;;;;;;;;;OAYG;IACH,MAAM,CACJ,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,wBAAwB,EACjC,OAAO,GAAE,gBAAqB,GAC7B,YAAY;IA8Ff;;;OAGG;IACH,eAAe,IAAI,eAAe,GAAG,IAAI;IAIzC;;OAEG;IACH,WAAW,IAAI,IAAI;IAQnB,gBAAgB,IAAI,aAAa;CAGlC"}

package/dist/engines/sentiment/engine.js

@@ -0,0 +1,208 @@
+"use strict";
+/**
+ * Sentiment Engine
+ *
+ * Text sentiment analysis engine that scores text using dictionary-lookup
+ * and heuristic rules. Supports token-level, document-level, and aspect-based
+ * analysis strategies with injectable lexicon configuration.
+ *
+ * @example
+ * ```typescript
+ * const engine = new SentimentEngine();
+ * engine.add({ type: 'Review', data: { text: 'The product is absolutely fantastic!' } });
+ *
+ * const result = engine.execute(compiledRuleset);
+ * console.log(result.compound); // 0.85 (positive)
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SentimentEngine = void 0;
+const core_1 = require("../../core");
+const types_1 = require("./types");
+const strategy_1 = require("./strategy");
+function round(value, decimals) {
+    const factor = Math.pow(10, decimals);
+    return Math.round(value * factor) / factor;
+}
+class SentimentEngine {
+    wm;
+    strategy;
+    _stream = null;
+    constructor(workingMemory) {
+        this.wm = workingMemory ?? new core_1.WorkingMemory();
+        this.strategy = new strategy_1.SentimentExecutor();
+    }
+    // ========================================
+    // IWorkingMemory Implementation
+    // ========================================
+    add(input) {
+        return this.wm.add(input);
+    }
+    remove(factId) {
+        return this.wm.remove(factId);
+    }
+    update(input) {
+        return this.wm.update(input);
+    }
+    get(factId) {
+        return this.wm.get(factId);
+    }
+    getByType(type) {
+        return this.wm.getByType(type);
+    }
+    getAll() {
+        return this.wm.getAll();
+    }
+    has(factId) {
+        return this.wm.has(factId);
+    }
+    size() {
+        return this.wm.size();
+    }
+    clear() {
+        this.wm.clear();
+    }
+    getChanges() {
+        return this.wm.getChanges();
+    }
+    clearChanges() {
+        this.wm.clearChanges();
+    }
+    // ========================================
+    // Engine Execution
+    // ========================================
+    /**
+     * Execute a sentiment analysis ruleset.
+     *
+     * Extracts text from all facts in working memory, applies the configured
+     * sentiment strategy, and returns compound scores with token-level detail.
+     *
+     * @param ruleSet - Compiled sentiment ruleset
+     * @param options - Runtime options (onToken callback)
+     * @returns Sentiment result with compound score, label, and detail
+     */
+    execute(ruleSet, options = {}) {
+        return this.strategy.run(ruleSet, this.wm, options);
+    }
+    // ========================================
+    // Streaming Ingest
+    // ========================================
+    /**
+     * Score a single text incrementally without touching working memory.
+     *
+     * Each call scores the provided text, updates a running accumulator,
+     * and returns both the individual score and the current aggregate.
+     * The compiled ruleset must stay the same across calls (matched by id).
+     * Call `resetStream()` to start a new stream.
+     *
+     * @param text - Raw text to score
+     * @param ruleSet - Compiled sentiment ruleset
+     * @param options - Runtime options (onToken callback)
+     * @returns IngestResult with item-level and aggregate scores
+     */
+    ingest(text, ruleSet, options = {}) {
+        // Initialize or validate stream state
+        if (!this._stream || this._stream.ruleSetId !== ruleSet.id) {
+            this._stream = {
+                ruleSetId: ruleSet.id,
+                strategy: ruleSet.strategy,
+                compoundSum: 0,
+                count: 0,
+                posTokens: 0,
+                negTokens: 0,
+                neuTokens: 0,
+                totalTokens: 0,
+                aspectAccumulators: new Map(),
+                lastResult: null
+            };
+        }
+        // Score just this text
+        const itemResult = this.strategy.scoreText(ruleSet, text, options);
+        // Update running accumulators
+        const s = this._stream;
+        s.compoundSum += itemResult.compound;
+        s.count++;
+        // Update token proportion accumulators
+        const itemTokenTotal = itemResult.tokens?.length
+            ?? itemResult.sentences?.reduce((n, sent) => n + sent.tokens.length, 0)
+            ?? itemResult.aspects?.reduce((n, a) => n + a.sentences.reduce((m, sent) => m + sent.tokens.length, 0), 0)
+            ?? 0;
+        if (itemTokenTotal > 0) {
+            s.posTokens += Math.round(itemResult.positive * itemTokenTotal);
+            s.negTokens += Math.round(itemResult.negative * itemTokenTotal);
+            s.neuTokens += Math.round(itemResult.neutral * itemTokenTotal);
+            s.totalTokens += itemTokenTotal;
+        }
+        // Update aspect accumulators if aspect-based
+        if (itemResult.aspects) {
+            for (const aspect of itemResult.aspects) {
+                if (aspect.sentences.length === 0)
+                    continue;
+                let acc = s.aspectAccumulators.get(aspect.aspect);
+                if (!acc) {
+                    acc = { compoundSum: 0, count: 0 };
+                    s.aspectAccumulators.set(aspect.aspect, acc);
+                }
+                acc.compoundSum += aspect.compound;
+                acc.count++;
+            }
+        }
+        // Compute aggregate
+        const aggCompound = round(s.compoundSum / s.count, 4);
+        const aggPositive = s.totalTokens > 0 ? round(s.posTokens / s.totalTokens, 4) : 0;
+        const aggNegative = s.totalTokens > 0 ? round(s.negTokens / s.totalTokens, 4) : 0;
+        const aggNeutral = s.totalTokens > 0 ? round(s.neuTokens / s.totalTokens, 4) : 0;
+        // Build aggregate aspect results if applicable
+        let aggAspects;
+        if (s.aspectAccumulators.size > 0) {
+            aggAspects = [];
+            for (const [aspect, acc] of s.aspectAccumulators) {
+                const aspectCompound = round(acc.compoundSum / acc.count, 4);
+                aggAspects.push({
+                    aspect,
+                    compound: aspectCompound,
+                    label: (0, types_1.resolveSentimentLabel)(aspectCompound),
+                    sentences: []
+                });
+            }
+        }
+        const aggregate = {
+            compound: aggCompound,
+            label: (0, types_1.resolveSentimentLabel)(aggCompound),
+            positive: aggPositive,
+            negative: aggNegative,
+            neutral: aggNeutral,
+            aspects: aggAspects,
+            strategy: ruleSet.strategy,
+            executionTimeMs: itemResult.executionTimeMs
+        };
+        s.lastResult = aggregate;
+        return {
+            ...aggregate,
+            itemCompound: itemResult.compound,
+            itemLabel: itemResult.label,
+            totalIngested: s.count
+        };
+    }
+    /**
+     * Get the current streaming aggregate without ingesting new text.
+     * Returns null if no texts have been ingested yet.
+     */
+    getStreamResult() {
+        return this._stream?.lastResult ?? null;
+    }
+    /**
+     * Reset the streaming accumulator. Does not affect working memory.
+     */
+    resetStream() {
+        this._stream = null;
+    }
+    // ========================================
+    // Utility Methods
+    // ========================================
+    getWorkingMemory() {
+        return this.wm;
+    }
+}
+exports.SentimentEngine = SentimentEngine;
+//# sourceMappingURL=engine.js.map

package/dist/engines/sentiment/engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.js","sourceRoot":"","sources":["../../../src/engines/sentiment/engine.ts"],"names":[],"mappings":"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"}

package/dist/engines/sentiment/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Sentiment Engine -- Text Sentiment Analysis
+ */
+export type { SentimentStrategy, SentimentLabel, SentimentLexicon, CompiledSentimentLexicon, SentimentConfig, TokenLevelSentimentRuleSet, DocumentLevelSentimentRuleSet, AspectBasedSentimentRuleSet, SentimentRuleSet, CompiledTokenLevelSentimentRuleSet, CompiledDocumentLevelSentimentRuleSet, CompiledAspectBasedSentimentRuleSet, CompiledSentimentRuleSet, TokenModifier, TokenScore, SentenceResult, AspectResult, SentimentResult, SentimentOptions, IngestResult } from './types';
+export { SENTIMENT_DEFAULTS, resolveSentimentLabel } from './types';
+export { compileSentimentRuleSet } from './compiler';
+export { SentimentExecutor, sentimentStrategy } from './strategy';
+export { SentimentEngine } from './engine';
+//# sourceMappingURL=index.d.ts.map

package/dist/engines/sentiment/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/engines/sentiment/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,YAAY,EACV,iBAAiB,EACjB,cAAc,EACd,gBAAgB,EAChB,wBAAwB,EACxB,eAAe,EACf,0BAA0B,EAC1B,6BAA6B,EAC7B,2BAA2B,EAC3B,gBAAgB,EAChB,kCAAkC,EAClC,qCAAqC,EACrC,mCAAmC,EACnC,wBAAwB,EACxB,aAAa,EACb,UAAU,EACV,cAAc,EACd,YAAY,EACZ,eAAe,EACf,gBAAgB,EAChB,YAAY,EACb,MAAM,SAAS,CAAC;AAGjB,OAAO,EACL,kBAAkB,EAClB,qBAAqB,EACtB,MAAM,SAAS,CAAC;AAGjB,OAAO,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAGrD,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAGlE,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC"}

package/dist/engines/sentiment/index.js

@@ -0,0 +1,21 @@
+"use strict";
+/**
+ * Sentiment Engine -- Text Sentiment Analysis
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SentimentEngine = exports.sentimentStrategy = exports.SentimentExecutor = exports.compileSentimentRuleSet = exports.resolveSentimentLabel = exports.SENTIMENT_DEFAULTS = void 0;
+// Constants & utilities
+var types_1 = require("./types");
+Object.defineProperty(exports, "SENTIMENT_DEFAULTS", { enumerable: true, get: function () { return types_1.SENTIMENT_DEFAULTS; } });
+Object.defineProperty(exports, "resolveSentimentLabel", { enumerable: true, get: function () { return types_1.resolveSentimentLabel; } });
+// Compiler
+var compiler_1 = require("./compiler");
+Object.defineProperty(exports, "compileSentimentRuleSet", { enumerable: true, get: function () { return compiler_1.compileSentimentRuleSet; } });
+// Strategy
+var strategy_1 = require("./strategy");
+Object.defineProperty(exports, "SentimentExecutor", { enumerable: true, get: function () { return strategy_1.SentimentExecutor; } });
+Object.defineProperty(exports, "sentimentStrategy", { enumerable: true, get: function () { return strategy_1.sentimentStrategy; } });
+// Engine
+var engine_1 = require("./engine");
+Object.defineProperty(exports, "SentimentEngine", { enumerable: true, get: function () { return engine_1.SentimentEngine; } });
+//# sourceMappingURL=index.js.map

package/dist/engines/sentiment/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/engines/sentiment/index.ts"],"names":[],"mappings":";AAAA;;GAEG;;;AA0BH,wBAAwB;AACxB,iCAGiB;AAFf,2GAAA,kBAAkB,OAAA;AAClB,8GAAA,qBAAqB,OAAA;AAGvB,WAAW;AACX,uCAAqD;AAA5C,mHAAA,uBAAuB,OAAA;AAEhC,WAAW;AACX,uCAAkE;AAAzD,6GAAA,iBAAiB,OAAA;AAAE,6GAAA,iBAAiB,OAAA;AAE7C,SAAS;AACT,mCAA2C;AAAlC,yGAAA,eAAe,OAAA"}

package/dist/engines/sentiment/strategy.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Sentiment Engine Strategy
+ *
+ * Core execution logic for all sentiment strategies:
+ * - token-level: Score individual tokens in the full text
+ * - document-level: Split into sentences, score each, average compounds
+ * - aspect-based: Match sentences to aspect terms, score per aspect
+ */
+import type { IWorkingMemory } from '../../core';
+import type { CompiledSentimentRuleSet, SentimentOptions, SentimentResult } from './types';
+export declare class SentimentExecutor {
+    run(ruleSet: CompiledSentimentRuleSet, wm: IWorkingMemory, options?: SentimentOptions): SentimentResult;
+    /** Score a single text string directly (no WorkingMemory involved) */
+    scoreText(ruleSet: CompiledSentimentRuleSet, text: string, options?: SentimentOptions, startTime?: number): SentimentResult;
+    private runTokenLevel;
+    private runDocumentLevel;
+    private runAspectBased;
+}
+/** Singleton instance */
+export declare const sentimentStrategy: SentimentExecutor;
+//# sourceMappingURL=strategy.d.ts.map

package/dist/engines/sentiment/strategy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"strategy.d.ts","sourceRoot":"","sources":["../../../src/engines/sentiment/strategy.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAQ,MAAM,YAAY,CAAC;AAEvD,OAAO,KAAK,EACV,wBAAwB,EAKxB,gBAAgB,EAChB,eAAe,EAKhB,MAAM,SAAS,CAAC;AAiQjB,qBAAa,iBAAiB;IAC5B,GAAG,CACD,OAAO,EAAE,wBAAwB,EACjC,EAAE,EAAE,cAAc,EAClB,OAAO,GAAE,gBAAqB,GAC7B,eAAe;IAWlB,sEAAsE;IACtE,SAAS,CACP,OAAO,EAAE,wBAAwB,EACjC,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,gBAAqB,EAC9B,SAAS,GAAE,MAA0B,GACpC,eAAe;IAiBlB,OAAO,CAAC,aAAa;IAiCrB,OAAO,CAAC,gBAAgB;IAiExB,OAAO,CAAC,cAAc;CAoEvB;AA0BD,yBAAyB;AACzB,eAAO,MAAM,iBAAiB,mBAA0B,CAAC"}