active-inference 0.0.1

package/dist/models/agent.model.js

@@ -0,0 +1,330 @@
+import { LinearAlgebra, Random } from '../helpers/math.helpers';
+/**
+ * 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 class Agent {
+    /**
+     * 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, transitionModel, observationModel, preferences, random, planningHorizon = 1, precision = 1, habits = {}) {
+        this.transitionModel = transitionModel;
+        this.observationModel = observationModel;
+        this.preferences = preferences;
+        this._belief = belief.copy();
+        this._random = random ?? new Random();
+        this._planningHorizon = Math.max(1, Math.floor(planningHorizon));
+        this._precision = Math.max(0, precision);
+        this._habits = habits;
+    }
+    /**
+     * Most likely hidden state (Maximum A Posteriori estimate).
+     */
+    get state() {
+        return this._belief.argmax();
+    }
+    /**
+     * Uncertainty in the agent's beliefs (Shannon entropy in nats).
+     * Higher values indicate more uncertainty about the current state.
+     */
+    get uncertainty() {
+        return this._belief.entropy();
+    }
+    /**
+     * 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) {
+        const likelihood = this.observationModel.getLikelihood(observation);
+        this._belief = this._belief.update(likelihood);
+    }
+    /**
+     * 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() {
+        const policies = this.generatePolicies(this._planningHorizon);
+        const policyEFEs = [];
+        for (const policy of policies) {
+            policyEFEs.push(this.evaluatePolicy(policy));
+        }
+        let policyProbs = LinearAlgebra.softmin(policyEFEs, this._precision);
+        if (Object.keys(this._habits).length > 0) {
+            const combined = policyProbs.map((p, i) => {
+                return p * this.getPolicyHabit(policies[i]);
+            });
+            policyProbs = LinearAlgebra.normalize(combined);
+        }
+        const idx = this.sampleIndex(policyProbs);
+        return policies[idx][0];
+    }
+    /**
+     * 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) {
+        this.observe(observation);
+        return this.act();
+    }
+    /**
+     * 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() {
+        const result = {};
+        for (const state of this._belief.states) {
+            result[state] = this._belief.probability(state);
+        }
+        return result;
+    }
+    /**
+     * 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() {
+        return -this._belief.entropy() + this.computeAmbiguity(this._belief);
+    }
+    /**
+     * Generate all possible policies (action sequences) of given depth.
+     * For depth=2 with actions [a,b]: [[a,a], [a,b], [b,a], [b,b]]
+     */
+    generatePolicies(depth) {
+        const actions = this.transitionModel.actions;
+        if (depth <= 1) {
+            return actions.map((a) => [a]);
+        }
+        const policies = [];
+        const subPolicies = this.generatePolicies(depth - 1);
+        for (const action of actions) {
+            for (const sub of subPolicies) {
+                policies.push([action, ...sub]);
+            }
+        }
+        return policies;
+    }
+    /**
+     * Evaluate a policy by computing its Expected Free Energy.
+     * G(π) = Σ_τ G(a_τ | Q_τ) where Q_τ is the predicted belief at time τ
+     */
+    evaluatePolicy(policy) {
+        let totalEFE = 0;
+        let currentBelief = this._belief;
+        for (const action of policy) {
+            const predicted = this.transitionModel.predict(currentBelief, action);
+            totalEFE += this.computeAmbiguity(predicted) + this.computeRisk(predicted);
+            currentBelief = predicted;
+        }
+        return totalEFE;
+    }
+    /**
+     * 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)
+     */
+    computeAmbiguity(predictedBelief) {
+        let ambiguity = 0;
+        for (const state of predictedBelief.states) {
+            const stateProb = predictedBelief.probability(state);
+            for (const obs of this.observationModel.observations) {
+                const obsProb = this.observationModel.probability(obs, state);
+                if (obsProb > 0 && stateProb > 0) {
+                    ambiguity -= stateProb * obsProb * Math.log(obsProb);
+                }
+            }
+        }
+        return ambiguity;
+    }
+    /**
+     * 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)
+     */
+    computeRisk(predictedBelief) {
+        let risk = 0;
+        for (const obs of this.observationModel.observations) {
+            let expectedObsProb = 0;
+            for (const state of predictedBelief.states) {
+                expectedObsProb +=
+                    this.observationModel.probability(obs, state) *
+                        predictedBelief.probability(state);
+            }
+            const preferredLogProb = this.preferences[obs] ?? -10;
+            if (expectedObsProb > 0) {
+                risk -= expectedObsProb * preferredLogProb;
+            }
+        }
+        return risk;
+    }
+    /**
+     * Sample an index from a probability distribution.
+     */
+    sampleIndex(probs) {
+        const rand = this._random.next();
+        let cumulative = 0;
+        for (let i = 0; i < probs.length; i++) {
+            cumulative += probs[i];
+            if (rand < cumulative) {
+                return i;
+            }
+        }
+        return probs.length - 1;
+    }
+    /**
+     * Get habit prior for a policy (product of action habits).
+     */
+    getPolicyHabit(policy) {
+        if (Object.keys(this._habits).length === 0) {
+            return 1;
+        }
+        return policy.reduce((prior, action) => {
+            return prior * (this._habits[action] ?? 1);
+        }, 1);
+    }
+}

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

@@ -0,0 +1,132 @@
+/**
+ * Probability distribution over states.
+ * Maps each state to its probability value (0 to 1).
+ *
+ * @typeParam S - Union type of possible state names
+ *
+ * @example
+ * ```typescript
+ * const dist: Distribution<'sunny' | 'rainy'> = {
+ *   sunny: 0.7,
+ *   rainy: 0.3
+ * };
+ * ```
+ */
+export type Distribution<S extends string = string> = Record<S, number>;
+/**
+ * Agent's preferences over observations expressed as log probabilities.
+ * Higher values indicate more preferred observations.
+ * Typically 0 for neutral, negative for undesired outcomes.
+ *
+ * In Active Inference, preferences define the "goal" of the agent -
+ * what observations it wants to experience.
+ *
+ * @typeParam O - Union type of possible observation names
+ *
+ * @example
+ * ```typescript
+ * const prefs: Preferences<'reward' | 'punishment'> = {
+ *   reward: 0,      // neutral/desired
+ *   punishment: -5  // strongly undesired
+ * };
+ * ```
+ */
+export type Preferences<O extends string = string> = Record<O, number>;
+/**
+ * Abstract base class representing an agent's beliefs about the world state.
+ *
+ * In Active Inference, beliefs (denoted Q(s) or sometimes D) represent
+ * the agent's probability distribution over hidden states of the world.
+ * The agent cannot directly observe the true state - it must infer it
+ * from observations.
+ *
+ * Beliefs are updated via Bayesian inference when new observations arrive,
+ * and used to predict future states when planning actions.
+ *
+ * @typeParam S - Union type of possible state names
+ *
+ * @example
+ * ```typescript
+ * class MyBelief extends Belief<'hot' | 'cold'> {
+ *   // ... implement abstract methods
+ * }
+ * ```
+ */
+export declare abstract class Belief<S extends string = string> {
+    /**
+     * List of all possible states in this belief's state space.
+     * @returns Array of state names
+     */
+    abstract get states(): S[];
+    /**
+     * Get the probability of a specific state.
+     * @param state - The state to query
+     * @returns Probability value between 0 and 1
+     */
+    abstract probability(state: S): number;
+    /**
+     * Perform Bayesian update given observation likelihood.
+     * Computes posterior: P(state|obs) ∝ P(obs|state) × P(state)
+     *
+     * @param likelihood - P(observation|state) for each state
+     * @returns New belief representing the posterior distribution
+     */
+    abstract update(likelihood: Distribution<S>): Belief<S>;
+    /**
+     * Create a deep copy of this belief.
+     * @returns Independent copy with same probability distribution
+     */
+    abstract copy(): Belief<S>;
+    /**
+     * Find the most likely state (Maximum A Posteriori estimate).
+     *
+     * @returns The state with highest probability
+     *
+     * @example
+     * ```typescript
+     * const belief = new DiscreteBelief({ sunny: 0.8, rainy: 0.2 });
+     * belief.argmax(); // 'sunny'
+     * ```
+     */
+    argmax(): S;
+    /**
+     * Compute Kullback-Leibler divergence from another belief.
+     * KL(P||Q) = Σ P(s) × log(P(s)/Q(s))
+     *
+     * Measures how different this distribution (P) is from another (Q).
+     * Used in Active Inference to quantify epistemic value - how much
+     * information an action would provide.
+     *
+     * @param other - The reference distribution Q
+     * @returns KL divergence (non-negative, 0 if identical)
+     *
+     * @example
+     * ```typescript
+     * const prior = new DiscreteBelief({ a: 0.5, b: 0.5 });
+     * const posterior = new DiscreteBelief({ a: 0.9, b: 0.1 });
+     * posterior.kl(prior); // Information gained from update
+     * ```
+     */
+    kl(other: Belief<S>): number;
+    /**
+     * Compute Shannon entropy of the belief distribution.
+     * H(P) = -Σ P(s) × log(P(s))
+     *
+     * Measures uncertainty in the belief. High entropy means
+     * the agent is uncertain about the true state.
+     *
+     * In Active Inference, entropy relates to expected surprise
+     * and is minimized through perception and action.
+     *
+     * @returns Entropy in nats (natural log units), non-negative
+     *
+     * @example
+     * ```typescript
+     * const uncertain = new DiscreteBelief({ a: 0.5, b: 0.5 });
+     * const certain = new DiscreteBelief({ a: 0.99, b: 0.01 });
+     * uncertain.entropy(); // ~0.693 (high uncertainty)
+     * certain.entropy();   // ~0.056 (low uncertainty)
+     * ```
+     */
+    entropy(): number;
+}

package/dist/models/belief.model.js

@@ -0,0 +1,104 @@
+/**
+ * Abstract base class representing an agent's beliefs about the world state.
+ *
+ * In Active Inference, beliefs (denoted Q(s) or sometimes D) represent
+ * the agent's probability distribution over hidden states of the world.
+ * The agent cannot directly observe the true state - it must infer it
+ * from observations.
+ *
+ * Beliefs are updated via Bayesian inference when new observations arrive,
+ * and used to predict future states when planning actions.
+ *
+ * @typeParam S - Union type of possible state names
+ *
+ * @example
+ * ```typescript
+ * class MyBelief extends Belief<'hot' | 'cold'> {
+ *   // ... implement abstract methods
+ * }
+ * ```
+ */
+export class Belief {
+    /**
+     * Find the most likely state (Maximum A Posteriori estimate).
+     *
+     * @returns The state with highest probability
+     *
+     * @example
+     * ```typescript
+     * const belief = new DiscreteBelief({ sunny: 0.8, rainy: 0.2 });
+     * belief.argmax(); // 'sunny'
+     * ```
+     */
+    argmax() {
+        let maxState = this.states[0];
+        let maxProb = 0;
+        for (const state of this.states) {
+            const prob = this.probability(state);
+            if (prob > maxProb) {
+                maxProb = prob;
+                maxState = state;
+            }
+        }
+        return maxState;
+    }
+    /**
+     * Compute Kullback-Leibler divergence from another belief.
+     * KL(P||Q) = Σ P(s) × log(P(s)/Q(s))
+     *
+     * Measures how different this distribution (P) is from another (Q).
+     * Used in Active Inference to quantify epistemic value - how much
+     * information an action would provide.
+     *
+     * @param other - The reference distribution Q
+     * @returns KL divergence (non-negative, 0 if identical)
+     *
+     * @example
+     * ```typescript
+     * const prior = new DiscreteBelief({ a: 0.5, b: 0.5 });
+     * const posterior = new DiscreteBelief({ a: 0.9, b: 0.1 });
+     * posterior.kl(prior); // Information gained from update
+     * ```
+     */
+    kl(other) {
+        let result = 0;
+        for (const state of this.states) {
+            const p = this.probability(state);
+            const q = other.probability(state) || 1e-10;
+            if (p > 0) {
+                result += p * Math.log(p / q);
+            }
+        }
+        return result;
+    }
+    /**
+     * Compute Shannon entropy of the belief distribution.
+     * H(P) = -Σ P(s) × log(P(s))
+     *
+     * Measures uncertainty in the belief. High entropy means
+     * the agent is uncertain about the true state.
+     *
+     * In Active Inference, entropy relates to expected surprise
+     * and is minimized through perception and action.
+     *
+     * @returns Entropy in nats (natural log units), non-negative
+     *
+     * @example
+     * ```typescript
+     * const uncertain = new DiscreteBelief({ a: 0.5, b: 0.5 });
+     * const certain = new DiscreteBelief({ a: 0.99, b: 0.01 });
+     * uncertain.entropy(); // ~0.693 (high uncertainty)
+     * certain.entropy();   // ~0.056 (low uncertainty)
+     * ```
+     */
+    entropy() {
+        let result = 0;
+        for (const state of this.states) {
+            const p = this.probability(state);
+            if (p > 0) {
+                result -= p * Math.log(p);
+            }
+        }
+        return result;
+    }
+}

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

@@ -0,0 +1,76 @@
+import { Distribution } from './belief.model';
+/**
+ * Observation likelihood matrix (A matrix in Active Inference notation).
+ * Defines P(o|s) - probability of observing o given hidden state s.
+ *
+ * Structure: observation → state → probability
+ *
+ * The observation model captures how hidden states generate observable
+ * outcomes. Since the agent cannot directly perceive the true state,
+ * it must infer it from observations using this mapping.
+ *
+ * @typeParam O - Union type of possible observation names
+ * @typeParam S - Union type of possible state names
+ *
+ * @example
+ * ```typescript
+ * // A sensor that's 90% accurate
+ * const A: ObservationMatrix<'see_light' | 'see_dark', 'light' | 'dark'> = {
+ *   see_light: { light: 0.9, dark: 0.1 },  // P(see_light | state)
+ *   see_dark: { light: 0.1, dark: 0.9 }    // P(see_dark | state)
+ * };
+ * ```
+ */
+export type ObservationMatrix<O extends string = string, S extends string = string> = Record<O, Distribution<S>>;
+/**
+ * Interface for observation models (likelihood models).
+ *
+ * In Active Inference, the observation model (A) defines the relationship
+ * between hidden states and observations. It serves two purposes:
+ *
+ * 1. **Perception**: Given an observation, compute the likelihood for
+ *    Bayesian belief update (what states could have caused this?)
+ *
+ * 2. **Prediction**: Given predicted future states, compute expected
+ *    observations for evaluating action outcomes
+ *
+ * The observation model is crucial for:
+ * - Bayesian inference during perception
+ * - Computing ambiguity (uncertainty about observations)
+ * - Evaluating Expected Free Energy for action selection
+ *
+ * @typeParam O - Union type of possible observation names
+ * @typeParam S - Union type of possible state names
+ */
+export interface IObservationModel<O extends string = string, S extends string = string> {
+    /**
+     * List of all possible observations the agent can receive.
+     */
+    readonly observations: O[];
+    /**
+     * Get likelihood function for Bayesian update.
+     * Returns P(observation | state) for all states.
+     *
+     * This is the key function for perception - it tells
+     * the agent how likely each state is given what it observed.
+     *
+     * @param observation - The observation received
+     * @returns Distribution over states given the observation
+     *
+     * @example
+     * ```typescript
+     * const likelihood = model.getLikelihood('see_reward');
+     * // { good_state: 0.9, bad_state: 0.1 }
+     * ```
+     */
+    getLikelihood(observation: O): Distribution<S>;
+    /**
+     * Get probability of a specific observation given a state.
+     * Returns P(observation | state).
+     *
+     * @param observation - The observation
+     * @param state - The hidden state
+     * @returns Probability between 0 and 1
+     */
+    probability(observation: O, state: S): number;
+}

package/dist/models/observation.model.js

@@ -0,0 +1 @@
+export {};