@holoscript/framework 6.0.3

package/src/ai/index.ts

@@ -0,0 +1,130 @@
+/**
+ * @holoscript/framework AI Module
+ *
+ * Provider-agnostic AI integration, game AI systems (behavior trees, state machines,
+ * steering, perception, utility AI), and generation pipeline.
+ *
+ * Canonical home for all AI subsystems (moved from @holoscript/core in A.011.02c).
+ *
+ * @packageDocumentation
+ */
+
+// Core adapter interface and registry
+export {
+  // Types
+  type AIAdapter,
+  type GenerateResult,
+  type ExplainResult,
+  type OptimizeResult,
+  type FixResult,
+  type GenerateOptions,
+
+  // Registry functions
+  registerAIAdapter,
+  getAIAdapter,
+  getDefaultAIAdapter,
+  setDefaultAIAdapter,
+  listAIAdapters,
+  unregisterAIAdapter,
+
+  // Convenience functions (use default adapter)
+  generateHoloScript,
+  explainHoloScript,
+  optimizeHoloScript,
+  fixHoloScript,
+} from './AIAdapter';
+
+// Built-in adapters
+export {
+  // Adapter classes
+  OpenAIAdapter,
+  AnthropicAdapter,
+  OllamaAdapter,
+  LMStudioAdapter,
+  GeminiAdapter,
+  XAIAdapter,
+  TogetherAdapter,
+  FireworksAdapter,
+  NVIDIAAdapter,
+
+  // Config types
+  type OpenAIAdapterConfig,
+  type AnthropicAdapterConfig,
+  type OllamaAdapterConfig,
+  type LMStudioAdapterConfig,
+  type GeminiAdapterConfig,
+  type XAIAdapterConfig,
+  type TogetherAdapterConfig,
+  type FireworksAdapterConfig,
+  type NVIDIAAdapterConfig,
+
+  // Factory functions (create + register in one call)
+  useOpenAI,
+  useAnthropic,
+  useOllama,
+  useLMStudio,
+  useGemini,
+  useXAI,
+  useGrok,
+  useTogether,
+  useFireworks,
+  useNVIDIA,
+} from './adapters';
+
+export { SemanticSearchService, type SearchResult } from './SemanticSearchService';
+
+// AI game systems (behavior trees, state machines, blackboards, steering, etc.)
+export { BehaviorTree } from './BehaviorTree';
+export type { BTContext as BTTreeContext, BTTreeDef } from './BehaviorTree';
+
+export {
+  BTNode,
+  SequenceNode,
+  SelectorNode,
+  ParallelNode,
+  InverterNode,
+  RepeaterNode,
+  GuardNode,
+  ActionNode,
+  ConditionNode,
+  WaitNode,
+} from './BTNodes';
+export type { BTStatus } from './BTNodes';
+
+export { Blackboard } from './Blackboard';
+
+export { StateMachine } from './StateMachine';
+export type { StateConfig, TransitionConfig, StateAction, GuardFn } from './StateMachine';
+
+// Steering & navigation
+export { SteeringBehavior } from './SteeringBehavior';
+export { SteeringBehaviors } from './SteeringBehaviors';
+export { NavMesh } from './NavMesh';
+
+// Perception & influence
+export { PerceptionSystem } from './PerceptionSystem';
+export { InfluenceMap } from './InfluenceMap';
+
+// Utility AI & behavior selection
+export { UtilityAI } from './UtilityAI';
+export { BehaviorSelector } from './BehaviorSelector';
+
+// Goal planning
+export { GoalPlanner } from './GoalPlanner';
+
+// Generation pipeline
+export {
+  HoloScriptGenerator,
+  generateHoloScript as generateHoloScriptWithAdapter,
+  generateBatch,
+  validateBatch,
+} from './HoloScriptGenerator';
+export { GenerationCache, cachedGenerate } from './GenerationCache';
+export { GenerationAnalytics, createAnalytics } from './GenerationAnalytics';
+export { TrainingDataGenerator, createTrainingDataGenerator, ALL_CATEGORIES } from './TrainingDataGenerator';
+export { PromptTemplateSystem, QuickPrompts } from './PromptTemplates';
+export type { PromptTemplate, TemplateContext } from './PromptTemplates';
+
+// AI copilot & validation
+export { AICopilot } from './AICopilot';
+export { validateAIOutput, isAISafe } from './AIOutputValidator';

package/src/behavior/BehaviorPresets.ts

@@ -0,0 +1,140 @@
+/**
+ * BehaviorPresets.ts
+ *
+ * Pre-built behavior tree patterns for common NPC and object behaviors.
+ */
+
+import {
+  BTNode,
+  ActionNode,
+  ConditionNode,
+  WaitNode,
+  SequenceNode,
+  SelectorNode,
+  RepeaterNode,
+  InverterNode,
+} from './BehaviorTree';
+
+/**
+ * Patrol: Move between waypoints with pauses.
+ */
+export function createPatrolBehavior(
+  waypointCount: number = 3,
+  pauseDuration: number = 2.0
+): BTNode {
+  return new RepeaterNode(
+    new SequenceNode([
+      new ActionNode('selectNextWaypoint', (ctx) => {
+        ctx.waypointIndex = ((ctx.waypointIndex || 0) + 1) % waypointCount;
+        ctx.targetReached = false;
+        return 'success';
+      }),
+      new ActionNode('moveToWaypoint', (ctx, delta) => {
+        ctx.moveProgress = (ctx.moveProgress || 0) + delta * 0.5;
+        if (ctx.moveProgress >= 1) {
+          ctx.moveProgress = 0;
+          ctx.targetReached = true;
+          return 'success';
+        }
+        return 'running';
+      }),
+      new WaitNode(pauseDuration),
+    ]),
+    -1 // Infinite loop
+  );
+}
+
+/**
+ * Idle: Wait, look around, repeat.
+ */
+export function createIdleBehavior(idleDuration: number = 3.0): BTNode {
+  return new RepeaterNode(
+    new SequenceNode([
+      new WaitNode(idleDuration),
+      new ActionNode('lookAround', (ctx) => {
+        ctx.lookAngle = Math.random() * Math.PI * 2;
+        return 'success';
+      }),
+    ]),
+    -1
+  );
+}
+
+/**
+ * Interact: Approach target, interact, return to origin.
+ */
+export function createInteractBehavior(): BTNode {
+  return new SequenceNode([
+    new ConditionNode('hasTarget', (ctx) => !!ctx.interactTarget),
+    new ActionNode('approach', (ctx, delta) => {
+      ctx.approachProgress = (ctx.approachProgress || 0) + delta;
+      if (ctx.approachProgress >= 1.5) {
+        ctx.approachProgress = 0;
+        return 'success';
+      }
+      return 'running';
+    }),
+    new ActionNode('interact', (ctx) => {
+      ctx.interactionCount = (ctx.interactionCount || 0) + 1;
+      ctx.interactTarget = null;
+      return 'success';
+    }),
+  ]);
+}
+
+/**
+ * Follow: Follow a target entity, maintaining distance.
+ */
+export function createFollowBehavior(minDist: number = 1.5): BTNode {
+  return new RepeaterNode(
+    new SelectorNode([
+      // If close enough, idle
+      new SequenceNode([
+        new ConditionNode('closeEnough', (ctx) => {
+          const dist = ctx.distanceToTarget || 0;
+          return dist <= minDist;
+        }),
+        new WaitNode(0.5),
+      ]),
+      // Otherwise, move toward target
+      new ActionNode('moveToTarget', (ctx, delta) => {
+        ctx.distanceToTarget = Math.max(0, (ctx.distanceToTarget || 5) - delta * 2);
+        return ctx.distanceToTarget <= minDist ? 'success' : 'running';
+      }),
+    ]),
+    -1
+  );
+}
+
+/**
+ * Alert: Check for threats, flee or fight.
+ */
+export function createAlertBehavior(): BTNode {
+  return new SelectorNode([
+    // Fight if brave
+    new SequenceNode([
+      new ConditionNode('isBrave', (ctx) => ctx.courage > 0.5),
+      new ConditionNode('hasThreat', (ctx) => !!ctx.threat),
+      new ActionNode('fight', (ctx) => {
+        ctx.fightCount = (ctx.fightCount || 0) + 1;
+        ctx.threat = null;
+        return 'success';
+      }),
+    ]),
+    // Flee if threatened
+    new SequenceNode([
+      new ConditionNode('hasThreat', (ctx) => !!ctx.threat),
+      new ActionNode('flee', (ctx, delta) => {
+        ctx.fleeProgress = (ctx.fleeProgress || 0) + delta;
+        if (ctx.fleeProgress >= 2.0) {
+          ctx.fleeProgress = 0;
+          ctx.threat = null;
+          return 'success';
+        }
+        return 'running';
+      }),
+    ]),
+    // Default: idle
+    new WaitNode(1.0),
+  ]);
+}

package/src/behavior/BehaviorTree.ts

@@ -0,0 +1,236 @@
+/**
+ * BehaviorTree.ts
+ *
+ * Lightweight behavior tree for NPC AI and complex decision-making.
+ * Supports: Sequence, Selector, Inverter, Repeater, Action, Condition nodes.
+ */
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+export type NodeStatus = 'success' | 'failure' | 'running';
+
+export interface BTContext {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- dynamic context bag for behavior tree state
+  [key: string]: any;
+}
+
+export interface BTNode {
+  type: string;
+  tick(context: BTContext, delta: number): NodeStatus;
+  reset?(): void;
+}
+
+// =============================================================================
+// LEAF NODES
+// =============================================================================
+
+/**
+ * Action: Executes a function. Returns success/failure/running.
+ */
+export class ActionNode implements BTNode {
+  type = 'action';
+  constructor(
+    public name: string,
+    private fn: (ctx: BTContext, delta: number) => NodeStatus
+  ) {}
+
+  tick(context: BTContext, delta: number): NodeStatus {
+    return this.fn(context, delta);
+  }
+}
+
+/**
+ * Condition: Checks a predicate. Returns success/failure.
+ */
+export class ConditionNode implements BTNode {
+  type = 'condition';
+  constructor(
+    public name: string,
+    private predicate: (ctx: BTContext) => boolean
+  ) {}
+
+  tick(context: BTContext): NodeStatus {
+    return this.predicate(context) ? 'success' : 'failure';
+  }
+}
+
+/**
+ * Wait: Returns 'running' for a specified duration, then 'success'.
+ */
+export class WaitNode implements BTNode {
+  type = 'wait';
+  private elapsed: number = 0;
+  constructor(public duration: number) {}
+
+  tick(_context: BTContext, delta: number): NodeStatus {
+    this.elapsed += delta;
+    if (this.elapsed >= this.duration) {
+      return 'success';
+    }
+    return 'running';
+  }
+
+  reset(): void {
+    this.elapsed = 0;
+  }
+}
+
+// =============================================================================
+// COMPOSITE NODES
+// =============================================================================
+
+/**
+ * Sequence: Runs children in order. Fails on first failure.
+ * Returns 'running' if a child is running.
+ */
+export class SequenceNode implements BTNode {
+  type = 'sequence';
+  private currentIndex: number = 0;
+
+  constructor(public children: BTNode[]) {}
+
+  tick(context: BTContext, delta: number): NodeStatus {
+    while (this.currentIndex < this.children.length) {
+      const status = this.children[this.currentIndex].tick(context, delta);
+
+      if (status === 'failure') {
+        this.currentIndex = 0;
+        return 'failure';
+      }
+      if (status === 'running') {
+        return 'running';
+      }
+      // success -> next child
+      this.currentIndex++;
+    }
+    this.currentIndex = 0;
+    return 'success';
+  }
+
+  reset(): void {
+    this.currentIndex = 0;
+    for (const child of this.children) child.reset?.();
+  }
+}
+
+/**
+ * Selector: Tries children in order. Succeeds on first success.
+ * Falls through to next child on failure.
+ */
+export class SelectorNode implements BTNode {
+  type = 'selector';
+  private currentIndex: number = 0;
+
+  constructor(public children: BTNode[]) {}
+
+  tick(context: BTContext, delta: number): NodeStatus {
+    while (this.currentIndex < this.children.length) {
+      const status = this.children[this.currentIndex].tick(context, delta);
+
+      if (status === 'success') {
+        this.currentIndex = 0;
+        return 'success';
+      }
+      if (status === 'running') {
+        return 'running';
+      }
+      // failure -> try next child
+      this.currentIndex++;
+    }
+    this.currentIndex = 0;
+    return 'failure';
+  }
+
+  reset(): void {
+    this.currentIndex = 0;
+    for (const child of this.children) child.reset?.();
+  }
+}
+
+// =============================================================================
+// DECORATOR NODES
+// =============================================================================
+
+/**
+ * Inverter: Flips success/failure.
+ */
+export class InverterNode implements BTNode {
+  type = 'inverter';
+  constructor(public child: BTNode) {}
+
+  tick(context: BTContext, delta: number): NodeStatus {
+    const status = this.child.tick(context, delta);
+    if (status === 'success') return 'failure';
+    if (status === 'failure') return 'success';
+    return 'running';
+  }
+
+  reset(): void {
+    this.child.reset?.();
+  }
+}
+
+/**
+ * Repeater: Repeats a child N times (or infinitely if count = -1).
+ */
+export class RepeaterNode implements BTNode {
+  type = 'repeater';
+  private count: number = 0;
+  constructor(
+    public child: BTNode,
+    public maxCount: number = -1
+  ) {}
+
+  tick(context: BTContext, delta: number): NodeStatus {
+    const status = this.child.tick(context, delta);
+
+    if (status === 'running') return 'running';
+
+    this.count++;
+    this.child.reset?.();
+
+    if (this.maxCount !== -1 && this.count >= this.maxCount) {
+      this.count = 0;
+      return 'success';
+    }
+    return 'running';
+  }
+
+  reset(): void {
+    this.count = 0;
+    this.child.reset?.();
+  }
+}
+
+// =============================================================================
+// BEHAVIOR TREE
+// =============================================================================
+
+export class BehaviorTree {
+  private root: BTNode;
+  private context: BTContext;
+
+  constructor(root: BTNode, context: BTContext = {}) {
+    this.root = root;
+    this.context = context;
+  }
+
+  tick(delta: number): NodeStatus {
+    return this.root.tick(this.context, delta);
+  }
+
+  getContext(): BTContext {
+    return this.context;
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- matches BTContext index signature
+  setContext(key: string, value: any): void {
+    this.context[key] = value;
+  }
+
+  reset(): void {
+    this.root.reset?.();
+  }
+}

package/src/behavior/StateMachine.ts

@@ -0,0 +1,176 @@
+/**
+ * StateMachine.ts
+ *
+ * Finite State Machine (FSM) for game logic, NPC AI, and UI state management.
+ * Supports:
+ * - Named states with enter/update/exit callbacks
+ * - Guarded transitions (conditions that must be true to transition)
+ * - Transition actions (side effects on transition)
+ * - Event-driven and tick-driven transitions
+ * - State history tracking
+ */
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+export interface StateConfig {
+  name: string;
+  onEnter?: (context: Record<string, unknown>) => void;
+  onUpdate?: (context: Record<string, unknown>, delta: number) => void;
+  onExit?: (context: Record<string, unknown>) => void;
+}
+
+export interface TransitionConfig {
+  from: string;
+  to: string;
+  event?: string; // Trigger on event
+  guard?: (context: Record<string, unknown>) => boolean; // Must return true to allow
+  action?: (context: Record<string, unknown>) => void; // Side effect on transition
+}
+
+export interface StateMachineConfig {
+  initialState: string;
+  states: StateConfig[];
+  transitions: TransitionConfig[];
+  context?: Record<string, unknown>;
+}
+
+// =============================================================================
+// STATE MACHINE
+// =============================================================================
+
+export class StateMachine {
+  private states: Map<string, StateConfig> = new Map();
+  private transitions: TransitionConfig[] = [];
+  private currentStateName: string = '';
+  private previousStateName: string = '';
+  private context: Record<string, unknown>;
+  private history: string[] = [];
+  private maxHistory: number = 50;
+
+  constructor(config: StateMachineConfig) {
+    this.context = config.context || {};
+
+    for (const state of config.states) {
+      this.states.set(state.name, state);
+    }
+
+    this.transitions = config.transitions;
+
+    // Enter initial state
+    this.enterState(config.initialState);
+  }
+
+  /**
+   * Get the current state name.
+   */
+  getCurrentState(): string {
+    return this.currentStateName;
+  }
+
+  /**
+   * Get the previous state name.
+   */
+  getPreviousState(): string {
+    return this.previousStateName;
+  }
+
+  /**
+   * Get the shared context.
+   */
+  getContext(): Record<string, unknown> {
+    return this.context;
+  }
+
+  /**
+   * Get state transition history.
+   */
+  getHistory(): string[] {
+    return [...this.history];
+  }
+
+  /**
+   * Send an event to the state machine. May trigger a transition.
+   */
+  send(event: string): boolean {
+    const transition = this.transitions.find(
+      (t) =>
+        t.from === this.currentStateName && t.event === event && (!t.guard || t.guard(this.context))
+    );
+
+    if (!transition) return false;
+
+    this.executeTransition(transition);
+    return true;
+  }
+
+  /**
+   * Try to transition based on guards (no event, just check conditions).
+   * Called automatically during update, or manually.
+   */
+  evaluate(): boolean {
+    const transition = this.transitions.find(
+      (t) => t.from === this.currentStateName && !t.event && t.guard && t.guard(this.context)
+    );
+
+    if (!transition) return false;
+
+    this.executeTransition(transition);
+    return true;
+  }
+
+  /**
+   * Force a transition to a specific state (bypasses guards).
+   */
+  forceTransition(stateName: string): void {
+    if (!this.states.has(stateName)) return;
+
+    const currentState = this.states.get(this.currentStateName);
+    if (currentState?.onExit) currentState.onExit(this.context);
+
+    this.enterState(stateName);
+  }
+
+  /**
+   * Update the state machine. Call every frame.
+   */
+  update(delta: number): void {
+    const state = this.states.get(this.currentStateName);
+    if (state?.onUpdate) {
+      state.onUpdate(this.context, delta);
+    }
+
+    // Auto-evaluate guard-based transitions
+    this.evaluate();
+  }
+
+  /**
+   * Check if we're in a specific state.
+   */
+  isInState(stateName: string): boolean {
+    return this.currentStateName === stateName;
+  }
+
+  private executeTransition(transition: TransitionConfig): void {
+    const fromState = this.states.get(this.currentStateName);
+    if (fromState?.onExit) fromState.onExit(this.context);
+
+    if (transition.action) transition.action(this.context);
+
+    this.enterState(transition.to);
+  }
+
+  private enterState(stateName: string): void {
+    this.previousStateName = this.currentStateName;
+    this.currentStateName = stateName;
+
+    this.history.push(stateName);
+    if (this.history.length > this.maxHistory) {
+      this.history.shift();
+    }
+
+    const state = this.states.get(stateName);
+    if (state?.onEnter) state.onEnter(this.context);
+  }
+}