active-inference 0.0.1

package/dist/helpers/math.helpers.js

@@ -0,0 +1,168 @@
+/**
+ * Seeded pseudo-random number generator using the Mulberry32 algorithm.
+ *
+ * Provides reproducible random sequences when initialized with the same seed.
+ * This is essential for testing and debugging Active Inference agents,
+ * as it allows deterministic replay of stochastic action selection.
+ *
+ * Mulberry32 is a fast, high-quality 32-bit PRNG with a period of 2^32.
+ *
+ * @example
+ * ```typescript
+ * const rng = new Random(42);
+ * console.log(rng.next()); // 0.8817... (always same for seed 42)
+ * console.log(rng.next()); // 0.3951...
+ *
+ * // Reset to get same sequence again
+ * rng.reset(42);
+ * console.log(rng.next()); // 0.8817... (same as before)
+ * ```
+ */
+export class Random {
+    /**
+     * Create a new random number generator.
+     *
+     * @param seed - Initial seed value. Defaults to current timestamp
+     *               for non-reproducible behavior.
+     */
+    constructor(seed = Date.now()) {
+        this.state = seed;
+    }
+    /**
+     * Generate the next random number in [0, 1).
+     *
+     * Works like Math.random() but with deterministic sequence
+     * based on the seed.
+     *
+     * @returns Random number between 0 (inclusive) and 1 (exclusive)
+     */
+    next() {
+        this.state |= 0;
+        this.state = (this.state + 0x6d2b79f5) | 0;
+        let t = Math.imul(this.state ^ (this.state >>> 15), 1 | this.state);
+        t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    }
+    /**
+     * Generate a random number from standard normal distribution N(0, 1).
+     *
+     * Uses the Box-Muller transform to convert uniform random numbers
+     * into normally distributed values.
+     *
+     * @returns Random number from standard normal distribution
+     *
+     * @example
+     * ```typescript
+     * const rng = new Random(42);
+     * const samples = Array.from({ length: 1000 }, () => rng.gaussian());
+     * // samples will have mean ≈ 0 and std ≈ 1
+     * ```
+     */
+    gaussian() {
+        const u1 = this.next();
+        const u2 = this.next();
+        return Math.sqrt(-2 * Math.log(u1)) * Math.cos(2 * Math.PI * u2);
+    }
+    /**
+     * Reset the generator to a new seed.
+     *
+     * Useful for replaying random sequences from a known state.
+     *
+     * @param seed - New seed value
+     */
+    reset(seed) {
+        this.state = seed;
+    }
+}
+/**
+ * Linear algebra utilities for Active Inference computations.
+ *
+ * Provides common operations needed for probability manipulation,
+ * including softmax/softmin for converting values to probabilities.
+ */
+export class LinearAlgebra {
+    /**
+     * Softmin function - converts values to probabilities inversely.
+     *
+     * Lower values get higher probabilities. Used in Active Inference
+     * to convert Expected Free Energy (where lower is better) into
+     * action probabilities.
+     *
+     * Formula: P(i) = exp(-β × x_i) / Σ exp(-β × x_j)
+     *
+     * @param arr - Array of values to convert
+     * @param beta - Precision/temperature parameter (default: 1).
+     *               Higher β = more deterministic (concentrates on minimum).
+     *               β = 0 gives uniform distribution.
+     * @returns Normalized probability distribution
+     *
+     * @example
+     * ```typescript
+     * const efe = [2.5, 1.0, 3.0];  // Policy EFEs (lower is better)
+     * const probs = LinearAlgebra.softmin(efe, 4);
+     * // probs ≈ [0.05, 0.93, 0.02] - strongly prefers policy with EFE=1.0
+     * ```
+     */
+    static softmin(arr, beta = 1) {
+        return this.softmax(arr.map((x) => -x), beta);
+    }
+    /**
+     * Softmax function - converts values to probabilities.
+     *
+     * Higher values get higher probabilities. Standard operation for
+     * converting logits or preferences into a probability distribution.
+     *
+     * Formula: P(i) = exp(β × x_i) / Σ exp(β × x_j)
+     *
+     * Uses numerical stability trick of subtracting max before exp.
+     *
+     * @param arr - Array of values to convert
+     * @param beta - Precision/temperature parameter (default: 1).
+     *               Higher β = more deterministic (concentrates on maximum).
+     *               β = 0 gives uniform distribution.
+     * @returns Normalized probability distribution
+     *
+     * @example
+     * ```typescript
+     * const logits = [1.0, 2.0, 0.5];
+     * const probs = LinearAlgebra.softmax(logits);
+     * // probs ≈ [0.24, 0.67, 0.09]
+     * ```
+     */
+    static softmax(arr, beta = 1) {
+        const max = Math.max(...arr);
+        const exp = arr.map((x) => Math.exp(beta * (x - max)));
+        const sum = exp.reduce((a, b) => a + b);
+        return exp.map((x) => x / sum);
+    }
+    /**
+     * Normalize an array to sum to 1.
+     *
+     * @param arr - Array of non-negative values
+     * @returns Normalized array summing to 1
+     *
+     * @example
+     * ```typescript
+     * LinearAlgebra.normalize([2, 3, 5]); // [0.2, 0.3, 0.5]
+     * ```
+     */
+    static normalize(arr) {
+        const sum = arr.reduce((a, b) => a + b, 0);
+        return arr.map((x) => x / sum);
+    }
+    /**
+     * Compute dot product of two arrays.
+     *
+     * @param a - First array
+     * @param b - Second array (must be same length as a)
+     * @returns Sum of element-wise products
+     *
+     * @example
+     * ```typescript
+     * LinearAlgebra.dotProduct([1, 2, 3], [4, 5, 6]); // 32
+     * ```
+     */
+    static dotProduct(a, b) {
+        return a.reduce((sum, x, i) => sum + x * b[i], 0);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { Agent } from './models/agent.model';
+export { DiscreteBelief } from './beliefs/discrete.belief';
+export { DiscreteTransition } from './transition/discrete.transition';
+export { DiscreteObservation } from './observation/discrete.observation';
+export { createAgent, AgentConfig } from './factory';

package/dist/index.js

@@ -0,0 +1,5 @@
+export { Agent } from './models/agent.model';
+export { DiscreteBelief } from './beliefs/discrete.belief';
+export { DiscreteTransition } from './transition/discrete.transition';
+export { DiscreteObservation } from './observation/discrete.observation';
+export { createAgent } from './factory';

package/dist/models/agent.model.d.ts

@@ -0,0 +1,252 @@
+import { Belief, Distribution, Preferences } from './belief.model';
+import { ITransitionModel } from './transition.model';
+import { IObservationModel } from './observation.model';
+import { Random } from '../helpers/math.helpers';
+/**
+ * Prior probability over actions, representing habitual action tendencies.
+ * In Active Inference notation, this is the E matrix.
+ *
+ * Habits bias action selection independently of Expected Free Energy.
+ * They model learned action preferences or "default" behaviors.
+ *
+ * @typeParam A - Union type of possible action names
+ *
+ * @example
+ * ```typescript
+ * // Agent has a habit of staying still
+ * const habits: Habits<'move' | 'stay'> = {
+ *   move: 0.3,
+ *   stay: 0.7
+ * };
+ * ```
+ */
+export type Habits<A extends string = string> = Record<A, number>;
+/**
+ * Active Inference agent implementing the Free Energy Principle.
+ *
+ * This agent perceives the world through observations, maintains beliefs
+ * about hidden states, and selects actions to minimize Expected Free Energy.
+ *
+ * ## Core Concepts
+ *
+ * **Generative Model**: The agent has an internal model of how the world works:
+ * - Transition model (B): How states change given actions
+ * - Observation model (A): How states generate observations
+ * - Preferences (C): What observations the agent "wants" to experience
+ *
+ * **Perception**: When the agent observes something, it updates its beliefs
+ * using Bayesian inference: P(state|obs) ∝ P(obs|state) × P(state)
+ *
+ * **Action Selection**: The agent evaluates possible action sequences (policies)
+ * by computing Expected Free Energy, which balances:
+ * - **Risk**: Avoiding unpreferred observations
+ * - **Ambiguity**: Seeking informative states
+ *
+ * ## Key Parameters
+ *
+ * - `planningHorizon`: How many steps ahead to plan (1 = greedy/reactive)
+ * - `precision` (β): Temperature for action selection (higher = more deterministic)
+ * - `habits` (E): Prior preferences over actions independent of goals
+ *
+ * @typeParam A - Union type of possible action names
+ * @typeParam O - Union type of possible observation names
+ * @typeParam S - Union type of possible state names
+ *
+ * @example
+ * ```typescript
+ * const agent = createAgent({
+ *   belief: new DiscreteBelief({ safe: 0.5, danger: 0.5 }),
+ *   transitionModel: myTransitions,
+ *   observationModel: myObservations,
+ *   preferences: { good: 0, bad: -5 },
+ *   planningHorizon: 2,
+ *   precision: 4
+ * });
+ *
+ * // Perception-action loop
+ * while (running) {
+ *   const observation = environment.getObservation();
+ *   const action = agent.step(observation);
+ *   environment.execute(action);
+ * }
+ * ```
+ *
+ * @see {@link https://www.fil.ion.ucl.ac.uk/~karl/The%20free-energy%20principle%20A%20unified%20brain%20theory.pdf | Friston (2010) - The Free Energy Principle}
+ */
+export declare class Agent<A extends string = string, O extends string = string, S extends string = string> {
+    private transitionModel;
+    private observationModel;
+    private preferences;
+    private _belief;
+    private _random;
+    private _planningHorizon;
+    private _precision;
+    private _habits;
+    /**
+     * Create a new Active Inference agent.
+     *
+     * @param belief - Initial belief over hidden states
+     * @param transitionModel - Model of state transitions P(s'|s,a)
+     * @param observationModel - Model of observations P(o|s)
+     * @param preferences - Preferred observations (log probabilities)
+     * @param random - Random number generator (optional, for reproducibility)
+     * @param planningHorizon - Steps to plan ahead (default: 1)
+     * @param precision - Action selection temperature (default: 1)
+     * @param habits - Prior over actions (default: uniform)
+     */
+    constructor(belief: Belief<S>, transitionModel: ITransitionModel<A, S>, observationModel: IObservationModel<O, S>, preferences: Preferences<O>, random?: Random, planningHorizon?: number, precision?: number, habits?: Partial<Habits<A>>);
+    /**
+     * Most likely hidden state (Maximum A Posteriori estimate).
+     */
+    get state(): S;
+    /**
+     * Uncertainty in the agent's beliefs (Shannon entropy in nats).
+     * Higher values indicate more uncertainty about the current state.
+     */
+    get uncertainty(): number;
+    /**
+     * Update beliefs based on a new observation (perception).
+     *
+     * Performs Bayesian inference:
+     * posterior ∝ likelihood × prior
+     * P(s|o) ∝ P(o|s) × P(s)
+     *
+     * This is the "perception" step of the Active Inference loop,
+     * where the agent updates its model of the world state.
+     *
+     * @param observation - The observation received from the environment
+     *
+     * @example
+     * ```typescript
+     * agent.observe('see_reward');
+     * console.log(agent.belief.argmax()); // Most likely state after observation
+     * ```
+     */
+    observe(observation: O): void;
+    /**
+     * Select an action by minimizing Expected Free Energy.
+     *
+     * The agent:
+     * 1. Generates all possible policies (action sequences) up to the planning horizon
+     * 2. Evaluates each policy's Expected Free Energy: G(π) = ambiguity + risk
+     * 3. Computes policy probabilities: P(π) ∝ E(π) × exp(-β × G(π))
+     * 4. Samples a policy and returns its first action
+     *
+     * Expected Free Energy (G) combines:
+     * - **Ambiguity**: Expected uncertainty about observations (epistemic)
+     * - **Risk**: Expected deviation from preferred observations (pragmatic)
+     *
+     * @returns The selected action to execute
+     *
+     * @example
+     * ```typescript
+     * const action = agent.act();
+     * environment.execute(action);
+     * ```
+     */
+    act(): A;
+    /**
+     * Complete perception-action cycle: observe then act.
+     *
+     * Convenience method that combines observe() and act() into
+     * a single call, representing one full cycle of the Active
+     * Inference loop.
+     *
+     * @param observation - The observation received from the environment
+     * @returns The selected action to execute
+     *
+     * @example
+     * ```typescript
+     * // Main loop
+     * let obs = environment.reset();
+     * while (!done) {
+     *   const action = agent.step(obs);
+     *   obs = environment.execute(action);
+     * }
+     * ```
+     */
+    step(observation: O): A;
+    /**
+     * Export current belief as a plain object for serialization.
+     *
+     * Useful for:
+     * - Saving agent state to storage
+     * - Transferring beliefs between agents
+     * - Debugging/visualization
+     *
+     * @returns Plain object mapping states to probabilities
+     *
+     * @example
+     * ```typescript
+     * const saved = agent.exportBelief();
+     * localStorage.setItem('belief', JSON.stringify(saved));
+     *
+     * // Later: restore
+     * const loaded = JSON.parse(localStorage.getItem('belief'));
+     * const newAgent = createAgent({
+     *   belief: new DiscreteBelief(loaded),
+     *   // ... other config
+     * });
+     * ```
+     */
+    exportBelief(): Distribution<S>;
+    /**
+     * Variational Free Energy of the current belief state.
+     *
+     * F = -H(Q) + E_Q[H(o|s)]
+     *   = negative_entropy + ambiguity
+     *
+     * This is a measure of "surprise" or model-data mismatch.
+     * The Free Energy Principle states that agents act to minimize
+     * this quantity over time.
+     *
+     * Note: This is VFE (perception), not EFE (action selection).
+     *
+     * @returns Variational Free Energy (can be negative)
+     */
+    get freeEnergy(): number;
+    /**
+     * Generate all possible policies (action sequences) of given depth.
+     * For depth=2 with actions [a,b]: [[a,a], [a,b], [b,a], [b,b]]
+     */
+    private generatePolicies;
+    /**
+     * Evaluate a policy by computing its Expected Free Energy.
+     * G(π) = Σ_τ G(a_τ | Q_τ) where Q_τ is the predicted belief at time τ
+     */
+    private evaluatePolicy;
+    /**
+     * Compute ambiguity term of Expected Free Energy.
+     *
+     * Ambiguity = E_Q[H(o|s)] = -Σ_s Q(s) Σ_o P(o|s) log P(o|s)
+     *
+     * High ambiguity means the agent is uncertain about what
+     * observations to expect - the state-observation mapping is noisy.
+     * Minimizing ambiguity drives epistemic/exploratory behavior.
+     *
+     * @param predictedBelief - Predicted belief state
+     * @returns Ambiguity (non-negative)
+     */
+    private computeAmbiguity;
+    /**
+     * Compute risk term of Expected Free Energy.
+     *
+     * Risk = -E_Q[log P(o)] = -Σ_o Q(o) log C(o)
+     * where Q(o) = Σ_s P(o|s)Q(s) and C(o) = preferred observations
+     *
+     * High risk means expected observations are far from preferences.
+     * Minimizing risk drives pragmatic/goal-directed behavior.
+     *
+     * @param predictedBelief - Predicted belief state
+     * @returns Risk (higher = worse outcomes expected)
+     */
+    private computeRisk;
+    /**
+     * Sample an index from a probability distribution.
+     */
+    private sampleIndex;
+    /**
+     * Get habit prior for a policy (product of action habits).
+     */
+    private getPolicyHabit;
+}