hoi4-agent-tools 2.2.0 → 2.3.0

package/dist/hoi4_agent_tools/probability/sweep.js

@@ -0,0 +1,265 @@
+import { ServiceError } from '../core/result.js';
+import { conditionBreakpointValues, evaluateSurfaceScenarios } from './evaluation.js';
+const MAX_SWEEP_POINTS = 250_000;
+function declaredValues(surface, scenario, path, steps) {
+    const uncertain = scenario.uncertainInputs?.find((input) => input.path === path);
+    if (uncertain?.range !== undefined)
+        return [
+            ...new Set([
+                ...values(uncertain.range, steps),
+                ...conditionBreakpointValues(surface, uncertain.range.min, uncertain.range.max),
+            ]),
+        ].sort((left, right) => left - right);
+    if (uncertain?.alternatives !== undefined) {
+        const values = uncertain.alternatives.filter((value) => typeof value === 'number');
+        if (values.length > 0)
+            return [...new Set(values)].sort((left, right) => left - right);
+    }
+    const current = scenario.state[path];
+    if (typeof current === 'number')
+        return [current];
+    throw new ServiceError('PROBABILITY_SWEEP_RANGE_REQUIRED', 'Every sweep path requires a scenario range, numeric alternatives, or numeric state value', { scenarioId: scenario.id, path });
+}
+function values(range, steps) {
+    if (range.min === range.max)
+        return [range.min];
+    return Array.from({ length: steps }, (_, index) => range.min + ((range.max - range.min) * index) / (steps - 1));
+}
+function point(surface, scenario, definitions, path, value, assigned) {
+    const evaluated = evaluateSurfaceScenarios(surface, [{ ...scenario, state: { ...scenario.state, ...assigned }, uncertainInputs: [] }], definitions)[0];
+    return {
+        scenarioId: scenario.id,
+        path,
+        value,
+        ...(Object.keys(assigned).length > 1 ? { values: assigned } : {}),
+        candidates: evaluated.candidates.map((candidate) => ({
+            id: candidate.id,
+            ...(typeof candidate.rawValue === 'object' && candidate.rawValue !== null
+                ? { rawValue: candidate.rawValue.value }
+                : {}),
+            ...(candidate.conditionalProbability === undefined ||
+                candidate.conditionalProbability === null
+                ? {}
+                : { conditionalProbability: candidate.conditionalProbability }),
+            ...(candidate.rank === undefined || candidate.rank === null ? {} : { rank: candidate.rank }),
+        })),
+    };
+}
+function leader(point) {
+    return point.candidates.find(({ rank }) => rank === 1)?.id;
+}
+function discoverReversals(points) {
+    const output = [];
+    const groups = new Map();
+    for (const item of points) {
+        const key = `${item.scenarioId}:${item.path}`;
+        const group = groups.get(key) ?? [];
+        group.push(item);
+        groups.set(key, group);
+    }
+    for (const group of groups.values()) {
+        group.sort((left, right) => left.value - right.value);
+        for (let index = 1; index < group.length; index += 1) {
+            const before = group[index - 1];
+            const after = group[index];
+            const beforeLeader = leader(before);
+            const afterLeader = leader(after);
+            if (beforeLeader === undefined || afterLeader === undefined || beforeLeader === afterLeader)
+                continue;
+            output.push({
+                scenarioId: before.scenarioId,
+                path: before.path,
+                between: [before.value, after.value],
+                beforeLeader,
+                afterLeader,
+            });
+        }
+    }
+    return output;
+}
+const pointCandidateMaps = new WeakMap();
+function candidateMetrics(point, candidateId) {
+    let candidates = pointCandidateMaps.get(point);
+    if (candidates === undefined) {
+        candidates = new Map(point.candidates.map((candidate) => [candidate.id, candidate]));
+        pointCandidateMaps.set(point, candidates);
+    }
+    const candidate = candidates.get(candidateId);
+    if (candidate === undefined)
+        return [];
+    return [
+        ...(candidate.rawValue === undefined
+            ? []
+            : [{ metric: 'raw_value', value: candidate.rawValue }]),
+        ...(candidate.conditionalProbability === undefined
+            ? []
+            : [
+                {
+                    metric: 'conditional_probability',
+                    value: candidate.conditionalProbability,
+                },
+            ]),
+    ];
+}
+function localElasticities(points) {
+    const output = [];
+    const groups = new Map();
+    for (const point of points) {
+        if (point.values !== undefined)
+            continue;
+        const key = `${point.scenarioId}\0${point.path}`;
+        groups.set(key, [...(groups.get(key) ?? []), point]);
+    }
+    for (const group of groups.values()) {
+        group.sort((left, right) => left.value - right.value);
+        for (let index = 1; index < group.length; index += 1) {
+            const before = group[index - 1];
+            const after = group[index];
+            const deltaInput = after.value - before.value;
+            if (deltaInput === 0)
+                continue;
+            for (const candidate of after.candidates) {
+                const afterMetrics = candidateMetrics(after, candidate.id);
+                const beforeMetrics = new Map(candidateMetrics(before, candidate.id).map(({ metric, value }) => [metric, value]));
+                for (const { metric, value: afterValue } of afterMetrics) {
+                    const beforeValue = beforeMetrics.get(metric);
+                    if (beforeValue === undefined)
+                        continue;
+                    const slope = (afterValue - beforeValue) / deltaInput;
+                    const midpointInput = (before.value + after.value) / 2;
+                    const midpointOutput = (beforeValue + afterValue) / 2;
+                    output.push({
+                        scenarioId: after.scenarioId,
+                        path: after.path,
+                        candidateId: candidate.id,
+                        metric,
+                        between: [before.value, after.value],
+                        slope,
+                        ...(midpointInput === 0 || midpointOutput === 0
+                            ? {}
+                            : { elasticity: (slope * midpointInput) / midpointOutput }),
+                    });
+                }
+            }
+        }
+    }
+    return output;
+}
+function pairwiseInteractions(points) {
+    const output = [];
+    const groups = new Map();
+    for (const point of points) {
+        if (point.values === undefined)
+            continue;
+        const key = `${point.scenarioId}\0${point.path}`;
+        groups.set(key, [...(groups.get(key) ?? []), point]);
+    }
+    for (const group of groups.values()) {
+        const first = group[0];
+        if (first === undefined)
+            continue;
+        const paths = first.path.split('|');
+        if (paths.length !== 2)
+            continue;
+        const [leftPath, rightPath] = paths;
+        const leftValues = [...new Set(group.map(({ values }) => values[leftPath]))].sort((left, right) => left - right);
+        const rightValues = [...new Set(group.map(({ values }) => values[rightPath]))].sort((left, right) => left - right);
+        const byCoordinates = new Map(group.map((point) => [`${point.values[leftPath]}\0${point.values[rightPath]}`, point]));
+        for (let leftIndex = 1; leftIndex < leftValues.length; leftIndex += 1) {
+            for (let rightIndex = 1; rightIndex < rightValues.length; rightIndex += 1) {
+                const leftLow = leftValues[leftIndex - 1];
+                const leftHigh = leftValues[leftIndex];
+                const rightLow = rightValues[rightIndex - 1];
+                const rightHigh = rightValues[rightIndex];
+                const lowLow = byCoordinates.get(`${leftLow}\0${rightLow}`);
+                const highLow = byCoordinates.get(`${leftHigh}\0${rightLow}`);
+                const lowHigh = byCoordinates.get(`${leftLow}\0${rightHigh}`);
+                const highHigh = byCoordinates.get(`${leftHigh}\0${rightHigh}`);
+                for (const candidate of highHigh.candidates) {
+                    for (const { metric, value: highHighValue } of candidateMetrics(highHigh, candidate.id)) {
+                        const lowLowValue = candidateMetrics(lowLow, candidate.id).find((item) => item.metric === metric)?.value;
+                        const highLowValue = candidateMetrics(highLow, candidate.id).find((item) => item.metric === metric)?.value;
+                        const lowHighValue = candidateMetrics(lowHigh, candidate.id).find((item) => item.metric === metric)?.value;
+                        if (lowLowValue === undefined ||
+                            highLowValue === undefined ||
+                            lowHighValue === undefined)
+                            continue;
+                        const mixedDifference = highHighValue - highLowValue - lowHighValue + lowLowValue;
+                        output.push({
+                            scenarioId: highHigh.scenarioId,
+                            paths: [leftPath, rightPath],
+                            candidateId: candidate.id,
+                            metric,
+                            cell: { left: [leftLow, leftHigh], right: [rightLow, rightHigh] },
+                            mixedDifference,
+                            mixedDifferencePerUnit: mixedDifference / ((leftHigh - leftLow) * (rightHigh - rightLow)),
+                        });
+                    }
+                }
+            }
+        }
+    }
+    return output;
+}
+export function sweepSurface(surface, scenarios, definitions, request, signal) {
+    const estimate = request.pairwise
+        ? scenarios.length *
+            Math.max(1, (request.paths.length * (request.paths.length - 1)) / 2) *
+            request.steps ** 2
+        : scenarios.length * request.paths.length * request.steps;
+    if (estimate > MAX_SWEEP_POINTS)
+        throw new ServiceError('PROBABILITY_SWEEP_LIMIT', 'Requested sweep exceeds the analysis point limit', {
+            estimatedPoints: estimate,
+            limit: MAX_SWEEP_POINTS,
+        });
+    const points = [];
+    for (const scenario of scenarios) {
+        if (request.pairwise && request.paths.length > 1) {
+            for (let leftIndex = 0; leftIndex < request.paths.length; leftIndex += 1) {
+                for (let rightIndex = leftIndex + 1; rightIndex < request.paths.length; rightIndex += 1) {
+                    const leftPath = request.paths[leftIndex];
+                    const rightPath = request.paths[rightIndex];
+                    const leftValues = declaredValues(surface, scenario, leftPath, request.steps);
+                    const rightValues = declaredValues(surface, scenario, rightPath, request.steps);
+                    for (const left of leftValues) {
+                        for (const right of rightValues) {
+                            if ((points.length & 1023) === 0)
+                                signal?.throwIfAborted();
+                            if (points.length >= MAX_SWEEP_POINTS)
+                                throw new ServiceError('PROBABILITY_SWEEP_LIMIT', 'Expanded threshold-aware sweep exceeds the analysis point limit', { limit: MAX_SWEEP_POINTS });
+                            points.push(point(surface, scenario, definitions, `${leftPath}|${rightPath}`, left, {
+                                [leftPath]: left,
+                                [rightPath]: right,
+                            }));
+                        }
+                    }
+                }
+            }
+        }
+        else {
+            for (const path of request.paths) {
+                for (const value of declaredValues(surface, scenario, path, request.steps)) {
+                    if ((points.length & 1023) === 0)
+                        signal?.throwIfAborted();
+                    if (points.length >= MAX_SWEEP_POINTS)
+                        throw new ServiceError('PROBABILITY_SWEEP_LIMIT', 'Expanded threshold-aware sweep exceeds the analysis point limit', { limit: MAX_SWEEP_POINTS });
+                    points.push(point(surface, scenario, definitions, path, value, { [path]: value }));
+                }
+            }
+        }
+    }
+    const rankReversals = request.findRankReversals ? discoverReversals(points) : [];
+    const breakpoints = rankReversals.flatMap((reversal) => {
+        const [low, high] = reversal.between;
+        return points.filter(({ scenarioId, path, value }) => scenarioId === reversal.scenarioId &&
+            path === reversal.path &&
+            (value === low || value === high));
+    });
+    return {
+        points,
+        rankReversals,
+        breakpoints,
+        localElasticities: localElasticities(points),
+        pairwiseInteractions: pairwiseInteractions(points),
+    };
+}

package/dist/hoi4_agent_tools/probability/trigger-evaluator.js

@@ -0,0 +1,280 @@
+import { assignments, astPathFor, firstScalar, nodeLocation, } from '../core/source/index.js';
+function combineAnd(values) {
+    if (values.includes('false'))
+        return 'false';
+    return values.includes('unresolved') ? 'unresolved' : 'true';
+}
+function combineOr(values) {
+    if (values.includes('true'))
+        return 'true';
+    return values.includes('unresolved') ? 'unresolved' : 'false';
+}
+function invert(value) {
+    return value === 'true' ? 'false' : value === 'false' ? 'true' : 'unresolved';
+}
+function bool(value) {
+    if (typeof value === 'boolean')
+        return value;
+    if (value === 'yes' || value === 'true')
+        return true;
+    if (value === 'no' || value === 'false')
+        return false;
+    return undefined;
+}
+function numeric(value) {
+    if (typeof value === 'number' && Number.isFinite(value))
+        return value;
+    if (typeof value === 'string' && value.trim() !== '' && Number.isFinite(Number(value)))
+        return Number(value);
+    return undefined;
+}
+function compare(left, right, operator) {
+    if (typeof left === 'number' && typeof right === 'number') {
+        if (operator === '>')
+            return left > right;
+        if (operator === '<')
+            return left < right;
+    }
+    return operator === '!=' ? left !== right : left === right;
+}
+function unresolved(assignment, candidate, reason) {
+    return {
+        state: 'unresolved',
+        unresolved: [
+            {
+                code: 'TRIGGER_UNRESOLVED',
+                message: reason,
+                path: assignment.key.value,
+                candidateId: candidate.id,
+                ...(candidate.provenance[0] === undefined ? {} : { provenance: candidate.provenance[0] }),
+            },
+        ],
+    };
+}
+function stateValue(scenario, key) {
+    if (Object.hasOwn(scenario.state, key))
+        return scenario.state[key];
+    if (Object.hasOwn(scenario.state, `trigger.${key}`))
+        return scenario.state[`trigger.${key}`];
+    return undefined;
+}
+function evaluateCheckVariable(block, scenario, candidate, assignment) {
+    const variable = firstScalar(block, 'var')?.value;
+    const target = firstScalar(block, 'value')?.value;
+    if (variable === undefined || target === undefined)
+        return unresolved(assignment, candidate, 'check_variable requires declared var and value');
+    const left = stateValue(scenario, `variable.${variable}`) ?? stateValue(scenario, variable);
+    const leftNumber = numeric(left);
+    const rightNumber = numeric(target);
+    if (leftNumber === undefined || rightNumber === undefined)
+        return unresolved(assignment, candidate, `Scenario does not declare numeric variable ${variable}`);
+    const compareName = firstScalar(block, 'compare')?.value ?? 'equals';
+    const result = compareName === 'greater_than'
+        ? leftNumber > rightNumber
+        : compareName === 'greater_than_or_equals'
+            ? leftNumber >= rightNumber
+            : compareName === 'less_than'
+                ? leftNumber < rightNumber
+                : compareName === 'less_than_or_equals'
+                    ? leftNumber <= rightNumber
+                    : compareName === 'not_equals'
+                        ? leftNumber !== rightNumber
+                        : leftNumber === rightNumber;
+    return { state: result ? 'true' : 'false', unresolved: [] };
+}
+function evaluateAssignmentCore(assignment, scenario, candidate, definitions, helperStack) {
+    const key = assignment.key.value;
+    if (assignment.value.type === 'block') {
+        if (key === 'AND')
+            return evaluateTriggerBlock(assignment.value, scenario, candidate, definitions, helperStack);
+        if (key === 'OR') {
+            const children = assignments(assignment.value).map((child) => evaluateAssignment(child, scenario, candidate, definitions, helperStack));
+            return {
+                state: combineOr(children.map(({ state }) => state)),
+                unresolved: children.flatMap(({ unresolved: items }) => items),
+                helperProvenance: children.flatMap(({ helperProvenance }) => helperProvenance ?? []),
+            };
+        }
+        if (key === 'NOT' || key === 'NOR' || key === 'NAND') {
+            const children = assignments(assignment.value).map((child) => evaluateAssignment(child, scenario, candidate, definitions, helperStack));
+            const base = key === 'NAND'
+                ? combineAnd(children.map(({ state }) => state))
+                : combineOr(children.map(({ state }) => state));
+            return {
+                state: invert(base),
+                unresolved: children.flatMap(({ unresolved: items }) => items),
+                helperProvenance: children.flatMap(({ helperProvenance }) => helperProvenance ?? []),
+            };
+        }
+        if (key === 'check_variable')
+            return evaluateCheckVariable(assignment.value, scenario, candidate, assignment);
+        if (key === 'is_in_array' || key === 'is_variable_in_array') {
+            const arrayId = firstScalar(assignment.value, 'array')?.value;
+            const declaredValue = firstScalar(assignment.value, 'value')?.value;
+            if (arrayId === undefined || declaredValue === undefined)
+                return unresolved(assignment, candidate, `${key} requires array and value`);
+            const array = stateValue(scenario, `array.${arrayId}`);
+            if (!Array.isArray(array))
+                return unresolved(assignment, candidate, `Scenario does not declare array ${arrayId}`);
+            const compared = stateValue(scenario, declaredValue) ?? declaredValue;
+            return { state: array.includes(compared) ? 'true' : 'false', unresolved: [] };
+        }
+        const helper = definitions.scriptedTriggers.get(key);
+        if (helper !== undefined) {
+            if (helperStack.includes(key))
+                return unresolved(assignment, candidate, `Scripted trigger recursion detected at ${key}`);
+            if (assignments(assignment.value).length > 0)
+                return unresolved(assignment, candidate, `Parameterized scripted trigger ${key} is not expanded without declared arguments`);
+            const helperProvenance = {
+                path: helper.file.displayPath,
+                rootKind: helper.file.rootKind,
+                loadOrder: helper.file.loadOrder,
+                sourceHash: helper.file.sha256,
+                location: nodeLocation(helper.document, helper.node, key),
+                ...(astPathFor(helper.document, helper.node) === undefined
+                    ? {}
+                    : { astPath: astPathFor(helper.document, helper.node) }),
+                symbol: key,
+                helperChain: [...helperStack, key],
+            };
+            const evaluated = evaluateTriggerBlock(helper.value, scenario, {
+                ...candidate,
+                document: helper.document,
+                provenance: [helperProvenance, ...candidate.provenance],
+            }, definitions, [...helperStack, key]);
+            return {
+                ...evaluated,
+                helperProvenance: [helperProvenance, ...(evaluated.helperProvenance ?? [])],
+            };
+        }
+        const declaredScope = bool(stateValue(scenario, `scope.${key}`));
+        if (declaredScope !== undefined)
+            return { state: declaredScope ? 'true' : 'false', unresolved: [] };
+        return unresolved(assignment, candidate, `Scoped or compound trigger ${key} is not declared by the scenario`);
+    }
+    const right = assignment.value.value;
+    if (key === 'always') {
+        const value = bool(right);
+        return value === undefined
+            ? unresolved(assignment, candidate, 'always trigger is not boolean')
+            : { state: value ? 'true' : 'false', unresolved: [] };
+    }
+    if (key === 'has_country_flag' || key === 'has_global_flag' || key === 'has_state_flag') {
+        return { state: scenario.flags?.includes(right) === true ? 'true' : 'false', unresolved: [] };
+    }
+    if (key === 'has_event_target') {
+        return {
+            state: Object.hasOwn(scenario.eventTargets ?? {}, right) ? 'true' : 'false',
+            unresolved: [],
+        };
+    }
+    if (key === 'tag' || key === 'original_tag') {
+        if (scenario.actor === undefined)
+            return unresolved(assignment, candidate, `Scenario does not declare actor for ${key}`);
+        return {
+            state: compare(scenario.actor, right, assignment.operator.text) ? 'true' : 'false',
+            unresolved: [],
+        };
+    }
+    if (key === 'date') {
+        if (scenario.date === undefined)
+            return unresolved(assignment, candidate, 'Scenario does not declare date');
+        const leftDate = Number(scenario.date.replaceAll('.', ''));
+        const rightDate = Number(right.replaceAll('.', ''));
+        if (!Number.isFinite(leftDate) || !Number.isFinite(rightDate))
+            return unresolved(assignment, candidate, 'Date comparison is not numeric');
+        return {
+            state: compare(leftDate, rightDate, assignment.operator.text) ? 'true' : 'false',
+            unresolved: [],
+        };
+    }
+    const helper = definitions.scriptedTriggers.get(key);
+    if (helper !== undefined && bool(right) === true) {
+        if (helperStack.includes(key))
+            return unresolved(assignment, candidate, `Scripted trigger recursion detected at ${key}`);
+        const helperProvenance = {
+            path: helper.file.displayPath,
+            rootKind: helper.file.rootKind,
+            loadOrder: helper.file.loadOrder,
+            sourceHash: helper.file.sha256,
+            location: nodeLocation(helper.document, helper.node, key),
+            ...(astPathFor(helper.document, helper.node) === undefined
+                ? {}
+                : { astPath: astPathFor(helper.document, helper.node) }),
+            symbol: key,
+            helperChain: [...helperStack, key],
+        };
+        const evaluated = evaluateTriggerBlock(helper.value, scenario, {
+            ...candidate,
+            document: helper.document,
+            provenance: [helperProvenance, ...candidate.provenance],
+        }, definitions, [...helperStack, key]);
+        return {
+            ...evaluated,
+            helperProvenance: [helperProvenance, ...(evaluated.helperProvenance ?? [])],
+        };
+    }
+    const declared = stateValue(scenario, key);
+    if (declared === undefined)
+        return unresolved(assignment, candidate, `Scenario does not declare trigger ${key}`);
+    const expectedBoolean = bool(right);
+    const actualBoolean = bool(declared);
+    if (expectedBoolean !== undefined && actualBoolean !== undefined)
+        return { state: expectedBoolean === actualBoolean ? 'true' : 'false', unresolved: [] };
+    const leftNumber = numeric(declared);
+    const rightNumber = numeric(right);
+    if (leftNumber !== undefined && rightNumber !== undefined)
+        return {
+            state: compare(leftNumber, rightNumber, assignment.operator.text) ? 'true' : 'false',
+            unresolved: [],
+        };
+    if (typeof declared === 'string')
+        return {
+            state: compare(declared, right, assignment.operator.text) ? 'true' : 'false',
+            unresolved: [],
+        };
+    return unresolved(assignment, candidate, `Trigger ${key} cannot compare the declared scenario value`);
+}
+function evaluateAssignment(assignment, scenario, candidate, definitions, helperStack) {
+    const evaluated = evaluateAssignmentCore(assignment, scenario, candidate, definitions, helperStack);
+    const source = candidate.provenance[0];
+    const provenance = candidate.document === undefined || source === undefined
+        ? source
+        : {
+            ...source,
+            location: nodeLocation(candidate.document, assignment, assignment.key.value),
+            ...(astPathFor(candidate.document, assignment) === undefined
+                ? {}
+                : { astPath: astPathFor(candidate.document, assignment) }),
+            symbol: assignment.key.value,
+        };
+    const expression = assignment.value.type === 'scalar'
+        ? `${assignment.key.value} ${assignment.operator.text} ${assignment.value.value}`
+        : assignment.key.value;
+    return {
+        ...evaluated,
+        trace: [
+            {
+                operation: 'eligibility',
+                expression,
+                applied: evaluated.state,
+                ...(provenance === undefined ? {} : { provenance }),
+            },
+            ...(evaluated.trace ?? []),
+        ],
+    };
+}
+export function evaluateTriggerBlock(block, scenario, candidate, definitions, helperStack = []) {
+    const override = scenario.candidateOverrides?.[candidate.id];
+    if (override !== undefined)
+        return { state: override ? 'true' : 'false', unresolved: [] };
+    if (block === undefined)
+        return { state: 'true', unresolved: [] };
+    const children = assignments(block).map((assignment) => evaluateAssignment(assignment, scenario, candidate, definitions, helperStack));
+    return {
+        state: combineAnd(children.map(({ state }) => state)),
+        unresolved: children.flatMap(({ unresolved: items }) => items),
+        helperProvenance: children.flatMap(({ helperProvenance }) => helperProvenance ?? []),
+        trace: children.flatMap(({ trace }) => trace ?? []),
+    };
+}