@higher.archi/boe 1.0.26 → 1.0.28

package/src/engines/negotiation/types.ts

@@ -0,0 +1,244 @@
+/**
+ * Negotiation Engine Types
+ *
+ * Two-party negotiation engine that analyzes zones of possible agreement,
+ * plans concession strategies, and optimizes deal packages across
+ * multiple dimensions.
+ */
+
+import type { SemanticPriority } from '../utility/types';
+
+// ========================================
+// Semantic Types
+// ========================================
+
+/** Negotiation algorithm to use */
+export type NegotiationStrategy = 'zopa-analysis' | 'concession-planning' | 'package-optimization';
+
+/** Concession aggressiveness style */
+export type ConcessionStyle = 'aggressive' | 'moderate' | 'collaborative';
+
+/** Outcome of a negotiation analysis */
+export type DealOutcome = 'agreed' | 'no-zopa' | 'batna-preferred';
+
+/** Whether higher or lower values are preferred for a dimension */
+export type DimensionDirection = 'higher-is-better' | 'lower-is-better';
+
+// ========================================
+// Dimension & Party Types
+// ========================================
+
+/** A single negotiable dimension (e.g. price, delivery time) */
+export type NegotiationDimension = {
+  id: string;
+  name?: string;
+  unit?: string;
+  direction: DimensionDirection;
+};
+
+/** A party's position on a single dimension */
+export type PartyPosition = {
+  dimensionId: string;
+  ideal: number;
+  acceptable: number;
+  walkaway: number;
+};
+
+/** A negotiating party with positions across all dimensions */
+export type PartyProfile = {
+  id: string;
+  name?: string;
+  positions: PartyPosition[];
+  batna?: number;
+};
+
+/** Weight function mapping a dimension to its importance for a party */
+export type ValueFunction = {
+  dimensionId: string;
+  weight: number | SemanticPriority;
+};
+
+// ========================================
+// Compiled Dimension & Party Types
+// ========================================
+
+/** Compiled value function with resolved numeric weight */
+export type CompiledValueFunction = {
+  dimensionId: string;
+  weight: number;           // normalized to sum to 1.0 per party
+};
+
+/** Compiled party profile with resolved weights */
+export type CompiledPartyProfile = {
+  id: string;
+  name?: string;
+  positions: PartyPosition[];
+  batna?: number;
+};
+
+// ========================================
+// Strategy-Specific Config Types
+// ========================================
+
+export type ZopaAnalysisConfig = {
+  resolution?: number;                    // default: 100
+};
+
+export type ConcessionPlanningConfig = {
+  style?: ConcessionStyle;               // default: 'moderate'
+  rounds?: number;                        // default: 5
+  startingPosition?: 'ideal' | 'midpoint'; // default: 'ideal'
+};
+
+export type PackageOptimizationConfig = {
+  sampleSize?: number;                    // default: 1000
+  objectiveWeights?: {
+    closeProb: number;
+    margin: number;
+  };                                      // default: { closeProb: 0.6, margin: 0.4 }
+};
+
+// ========================================
+// Source RuleSet Types (Discriminated Union)
+// ========================================
+
+type NegotiationRuleSetBase = {
+  id: string;
+  name?: string;
+  mode: 'negotiation';
+  dimensions: NegotiationDimension[];
+  parties: [PartyProfile, PartyProfile];
+  valueWeights: Record<string, ValueFunction[]>;
+};
+
+/** ZOPA analysis: compute zones of possible agreement per dimension */
+export type ZopaAnalysisRuleSet = NegotiationRuleSetBase & {
+  strategy: 'zopa-analysis';
+  config?: ZopaAnalysisConfig;
+};
+
+/** Concession planning: simulate round-by-round concession trajectories */
+export type ConcessionPlanningRuleSet = NegotiationRuleSetBase & {
+  strategy: 'concession-planning';
+  config?: ConcessionPlanningConfig;
+};
+
+/** Package optimization: find optimal deal packages within the ZOPA */
+export type PackageOptimizationRuleSet = NegotiationRuleSetBase & {
+  strategy: 'package-optimization';
+  config?: PackageOptimizationConfig;
+};
+
+export type NegotiationRuleSet =
+  | ZopaAnalysisRuleSet
+  | ConcessionPlanningRuleSet
+  | PackageOptimizationRuleSet;
+
+// ========================================
+// Compiled RuleSet Types
+// ========================================
+
+type CompiledNegotiationRuleSetBase = {
+  id: string;
+  name?: string;
+  mode: 'negotiation';
+  dimensions: NegotiationDimension[];
+  parties: [CompiledPartyProfile, CompiledPartyProfile];
+  valueWeights: Record<string, CompiledValueFunction[]>;
+};
+
+export type CompiledZopaAnalysisRuleSet = CompiledNegotiationRuleSetBase & {
+  strategy: 'zopa-analysis';
+  config: {
+    resolution: number;
+  };
+};
+
+export type CompiledConcessionPlanningRuleSet = CompiledNegotiationRuleSetBase & {
+  strategy: 'concession-planning';
+  config: {
+    style: ConcessionStyle;
+    rounds: number;
+    startingPosition: 'ideal' | 'midpoint';
+  };
+};
+
+export type CompiledPackageOptimizationRuleSet = CompiledNegotiationRuleSetBase & {
+  strategy: 'package-optimization';
+  config: {
+    sampleSize: number;
+    objectiveWeights: {
+      closeProb: number;
+      margin: number;
+    };
+  };
+};
+
+export type CompiledNegotiationRuleSet =
+  | CompiledZopaAnalysisRuleSet
+  | CompiledConcessionPlanningRuleSet
+  | CompiledPackageOptimizationRuleSet;
+
+// ========================================
+// Result Types
+// ========================================
+
+/** Range of agreement for a single dimension */
+export type ZopaRange = {
+  dimensionId: string;
+  lower: number;
+  upper: number;
+  size: number;
+};
+
+/** A single round's concession step for one party */
+export type ConcessionStep = {
+  round: number;
+  partyId: string;
+  offers: Record<string, number>;
+  totalValue: number;
+};
+
+/** A candidate deal package */
+export type PackageCandidate = {
+  dimensions: Record<string, number>;
+  partyAValue: number;
+  partyBValue: number;
+  closeProbability: number;
+  marginScore: number;
+  compositeScore: number;
+};
+
+/** Full negotiation result */
+export type NegotiationResult = {
+  outcome: DealOutcome;
+  zopa?: {
+    ranges: ZopaRange[];
+    hasAgreement: boolean;
+    zopaVolume: number;
+  };
+  concessionPlan?: {
+    steps: ConcessionStep[];
+    convergenceRound?: number;
+    finalDeal?: Record<string, number>;
+  };
+  recommendedPackage?: PackageCandidate;
+  allPackages?: PackageCandidate[];
+  batnaComparison: Record<string, {
+    dealValue: number;
+    batnaValue: number;
+    surplus: number;
+  }>;
+  strategy: NegotiationStrategy;
+  executionTimeMs: number;
+};
+
+// ========================================
+// Runtime Types
+// ========================================
+
+/** Runtime options for negotiation execution */
+export type NegotiationOptions = {
+  onStep?: (step: ConcessionStep) => void;
+  onPackage?: (candidate: PackageCandidate) => void;
+};

package/src/engines/sentiment/engine.ts

@@ -25,14 +25,40 @@ import {
 import type {
   CompiledSentimentRuleSet,
   SentimentOptions,
-  SentimentResult
+  SentimentResult,
+  SentimentStrategy,
+  IngestResult,
+  AspectResult
 } from './types';
+import { resolveSentimentLabel } from './types';
 
 import { SentimentExecutor } from './strategy';
 
+function round(value: number, decimals: number): number {
+  const factor = Math.pow(10, decimals);
+  return Math.round(value * factor) / factor;
+}
+
+/** Internal accumulator for streaming ingest */
+type StreamState = {
+  ruleSetId: string;
+  strategy: SentimentStrategy;
+  compoundSum: number;
+  count: number;
+  posTokens: number;
+  negTokens: number;
+  neuTokens: number;
+  totalTokens: number;
+  /** Per-aspect accumulators (aspect-based only) */
+  aspectAccumulators: Map<string, { compoundSum: number; count: number }>;
+  /** Last computed aggregate result (without item-specific fields) */
+  lastResult: SentimentResult | null;
+};
+
 export class SentimentEngine {
   private wm: WorkingMemory;
   private strategy: SentimentExecutor;
+  private _stream: StreamState | null = null;
 
   constructor(workingMemory?: WorkingMemory) {
     this.wm = workingMemory ?? new WorkingMemory();
@@ -108,6 +134,136 @@ export class SentimentEngine {
     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: string,
+    ruleSet: CompiledSentimentRuleSet,
+    options: SentimentOptions = {}
+  ): IngestResult {
+    // 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: AspectResult[] | undefined;
+    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: resolveSentimentLabel(aspectCompound),
+          sentences: []
+        });
+      }
+    }
+
+    const aggregate: SentimentResult = {
+      compound: aggCompound,
+      label: 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(): SentimentResult | null {
+    return this._stream?.lastResult ?? null;
+  }
+
+  /**
+   * Reset the streaming accumulator. Does not affect working memory.
+   */
+  resetStream(): void {
+    this._stream = null;
+  }
+
   // ========================================
   // Utility Methods
   // ========================================

package/src/engines/sentiment/index.ts

@@ -22,7 +22,8 @@ export type {
   SentenceResult,
   AspectResult,
   SentimentResult,
-  SentimentOptions
+  SentimentOptions,
+  IngestResult
 } from './types';
 
 // Constants & utilities

package/src/engines/sentiment/strategy.ts

@@ -291,23 +291,26 @@ export class SentimentExecutor {
     const texts = extractTexts(facts);
     const fullText = texts.join(' ');
 
-    let result: SentimentResult;
+    return this.scoreText(ruleSet, fullText, options, startTime);
+  }
 
+  /** Score a single text string directly (no WorkingMemory involved) */
+  scoreText(
+    ruleSet: CompiledSentimentRuleSet,
+    text: string,
+    options: SentimentOptions = {},
+    startTime: number = performance.now()
+  ): SentimentResult {
     switch (ruleSet.strategy) {
       case 'token-level':
-        result = this.runTokenLevel(ruleSet, fullText, options, startTime);
-        break;
+        return this.runTokenLevel(ruleSet, text, options, startTime);
       case 'document-level':
-        result = this.runDocumentLevel(ruleSet, fullText, options, startTime);
-        break;
+        return this.runDocumentLevel(ruleSet, text, options, startTime);
       case 'aspect-based':
-        result = this.runAspectBased(ruleSet, fullText, options, startTime);
-        break;
+        return this.runAspectBased(ruleSet, text, options, startTime);
       default:
         throw new Error(`Unknown sentiment strategy: '${(ruleSet as any).strategy}'`);
     }
-
-    return result;
   }
 
   // ========================================

package/src/engines/sentiment/types.ts

@@ -176,6 +176,16 @@ export type SentimentOptions = {
   onToken?: (token: TokenScore) => void;
 };
 
+/** Result from ingest() -- includes both the individual text score and the running aggregate */
+export type IngestResult = SentimentResult & {
+  /** Compound score for just the ingested text (not the aggregate) */
+  itemCompound: number;
+  /** Label for just the ingested text */
+  itemLabel: SentimentLabel;
+  /** Total number of texts ingested so far */
+  totalIngested: number;
+};
+
 // ========================================
 // Resolver Functions
 // ========================================

package/src/index.ts

@@ -32,6 +32,8 @@ export { UtilityEngine } from './engines/utility';
 export { PricingEngine } from './engines/pricing';
 export { EnsembleEngine } from './engines/ensemble';
 export { SentimentEngine } from './engines/sentiment';
+export { NegotiationEngine } from './engines/negotiation';
+export { DecayEngine } from './engines/decay';
 
 // ========================================
 // Core Types & Utilities
@@ -512,9 +514,76 @@ export type {
   SentenceResult,
   AspectResult,
   SentimentResult,
-  SentimentOptions
+  SentimentOptions,
+  IngestResult
 } from './engines/sentiment';
 
+// Negotiation
+export {
+  NegotiationExecutor,
+  compileNegotiationRuleSet,
+  negotiationStrategy
+} from './engines/negotiation';
+export type {
+  NegotiationStrategy,
+  ConcessionStyle,
+  DealOutcome,
+  DimensionDirection,
+  NegotiationDimension,
+  PartyPosition,
+  PartyProfile,
+  ValueFunction,
+  CompiledValueFunction,
+  CompiledPartyProfile,
+  ZopaAnalysisConfig,
+  ConcessionPlanningConfig,
+  PackageOptimizationConfig,
+  ZopaAnalysisRuleSet,
+  ConcessionPlanningRuleSet,
+  PackageOptimizationRuleSet,
+  NegotiationRuleSet,
+  CompiledZopaAnalysisRuleSet,
+  CompiledConcessionPlanningRuleSet,
+  CompiledPackageOptimizationRuleSet,
+  CompiledNegotiationRuleSet,
+  ZopaRange,
+  ConcessionStep,
+  PackageCandidate,
+  NegotiationResult,
+  NegotiationOptions
+} from './engines/negotiation';
+
+// Decay
+export {
+  DecayExecutor,
+  compileDecayRuleSet,
+  decayStrategy,
+  URGENCY_THRESHOLDS,
+  resolveUrgencyTier
+} from './engines/decay';
+export type {
+  DecayStrategy,
+  UrgencyTier,
+  ReEngagementEffect,
+  DecayAggregation,
+  DecayDimension,
+  CompiledDecayDimension,
+  ReEngagementRule,
+  SingleDimensionDecayRuleSet,
+  MultiDimensionDecayRuleSet,
+  EventDrivenDecayRuleSet,
+  DecayRuleSet,
+  CompiledSingleDimensionDecayRuleSet,
+  CompiledMultiDimensionDecayRuleSet,
+  CompiledEventDrivenDecayRuleSet,
+  CompiledDecayRuleSet,
+  DimensionDecayResult,
+  ReEngagementEvent,
+  EntityDecayResult,
+  DecayResult,
+  DecayOptions
+} from './engines/decay';
+
 // ========================================
 // Utility Functions (from old modules, re-exported for convenience)
 // ========================================