active-inference 0.0.1 → 0.1.0

package/README.md

@@ -9,7 +9,7 @@ Active Inference is a theory of how biological agents perceive and act in the wo
 - **Risk**: avoiding unpreferred outcomes
 - **Ambiguity**: seeking informative observations
 
-This library provides building blocks for creating agents that learn from observations and plan actions using these principles.
+This library provides building blocks for creating agents that perceive, learn, plan, and act using these principles.
 
 ## Installation
 
@@ -61,6 +61,7 @@ const action = agent.step('see_reward');
 | `preferences` | Log probabilities of preferred observations |
 | `planningHorizon` | Steps to look ahead (default: 1) |
 | `precision` | Action selection temperature (default: 1) |
+| `habits` | Prior over actions / E matrix (default: uniform) |
 | `seed` | Random seed for reproducibility |
 
 ### Agent
@@ -75,6 +76,58 @@ const action = agent.step('see_reward');
 | `freeEnergy` | Variational Free Energy |
 | `exportBelief()` | Get full belief distribution |
 
+## Learning
+
+The library supports **Dirichlet-categorical learning** — agents that update their generative models from experience. Instead of fixed probability matrices, learnable models maintain pseudo-count concentrations that are refined over time.
+
+- `DirichletObservation` and `DirichletTransition` are drop-in replacements for their Discrete counterparts. Learning happens automatically on every `step()` call.
+- `DirichletPreferences` provides learnable preferred observations — call `.learn()` manually and pass `.preferences` to the agent config.
+
+Low concentrations encode weak priors (learns fast). High concentrations encode strong priors (resists change).
+
+```typescript
+import {
+    createAgent,
+    DiscreteBelief,
+    DirichletTransition,
+    DirichletObservation,
+} from 'active-inference';
+
+const agent = createAgent({
+    belief: new DiscreteBelief({ safe: 0.5, danger: 0.5 }),
+    transitionModel: new DirichletTransition({
+        flee: {
+            safe:   { safe: 1, danger: 1 },
+            danger: { safe: 1, danger: 1 },
+        },
+        stay: {
+            safe:   { safe: 1, danger: 1 },
+            danger: { safe: 1, danger: 1 },
+        },
+    }),
+    observationModel: new DirichletObservation({
+        see_safe:   { safe: 1, danger: 1 },
+        see_danger: { safe: 1, danger: 1 },
+    }),
+    preferences: { see_safe: 0, see_danger: -5 },
+    seed: 42,
+});
+
+// Models update automatically on each step
+const action = agent.step('see_safe');
+```
+
+## Examples
+
+### Cart-Pole Balancing
+
+Interactive browser demo — an Active Inference agent balances an inverted pendulum using a 49-state generative model with 3-step planning horizon.
+
+```bash
+npm run build:examples
+open examples/cart-pole/index.html
+```
+
 ## Contributing
 
 ```bash

package/dist/index.d.ts

@@ -2,4 +2,8 @@ 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 { DirichletObservation } from './observation/dirichlet.observation';
+export { DirichletTransition } from './transition/dirichlet.transition';
+export { DirichletPreferences } from './preferences/dirichlet.preferences';
 export { createAgent, AgentConfig } from './factory';
+export type { ILearnable } from './models/learnable.model';

package/dist/index.js

@@ -2,4 +2,7 @@ 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 { DirichletObservation } from './observation/dirichlet.observation';
+export { DirichletTransition } from './transition/dirichlet.transition';
+export { DirichletPreferences } from './preferences/dirichlet.preferences';
 export { createAgent } from './factory';

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

@@ -82,6 +82,8 @@ export declare class Agent<A extends string = string, O extends string = string,
     private _planningHorizon;
     private _precision;
     private _habits;
+    private _previousBelief;
+    private _previousAction;
     /**
      * Create a new Active Inference agent.
      *
@@ -95,6 +97,7 @@ export declare class Agent<A extends string = string, O extends string = string,
      * @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>>);
+    private get resolvedPreferences();
     /**
      * Most likely hidden state (Maximum A Posteriori estimate).
      */
@@ -205,6 +208,14 @@ export declare class Agent<A extends string = string, O extends string = string,
      * @returns Variational Free Energy (can be negative)
      */
     get freeEnergy(): number;
+    /**
+     * Update learnable models from the current observation and belief.
+     *
+     * Called after observe() so the posterior belief is available.
+     * - A-learning: update observation model with (observation, posterior)
+     * - B-learning: update transition model with (previous_action, previous_belief, posterior)
+     */
+    private updateModels;
     /**
      * Generate all possible policies (action sequences) of given depth.
      * For depth=2 with actions [a,b]: [[a,a], [a,b], [b,a], [b,b]]

package/dist/models/agent.model.js

@@ -1,4 +1,5 @@
 import { LinearAlgebra, Random } from '../helpers/math.helpers';
+import { isLearnable } from './learnable.model';
 /**
  * Active Inference agent implementing the Free Energy Principle.
  *
@@ -68,12 +69,17 @@ export class Agent {
         this.transitionModel = transitionModel;
         this.observationModel = observationModel;
         this.preferences = preferences;
+        this._previousBelief = null;
+        this._previousAction = null;
         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;
     }
+    get resolvedPreferences() {
+        return this.preferences;
+    }
     /**
      * Most likely hidden state (Maximum A Posteriori estimate).
      */
@@ -168,7 +174,11 @@ export class Agent {
      */
     step(observation) {
         this.observe(observation);
-        return this.act();
+        this.updateModels(observation);
+        const action = this.act();
+        this._previousBelief = this._belief;
+        this._previousAction = action;
+        return action;
     }
     /**
      * Export current belief as a plain object for serialization.
@@ -217,6 +227,30 @@ export class Agent {
     get freeEnergy() {
         return -this._belief.entropy() + this.computeAmbiguity(this._belief);
     }
+    /**
+     * Update learnable models from the current observation and belief.
+     *
+     * Called after observe() so the posterior belief is available.
+     * - A-learning: update observation model with (observation, posterior)
+     * - B-learning: update transition model with (previous_action, previous_belief, posterior)
+     */
+    updateModels(observation) {
+        const posteriorDist = this.exportBelief();
+        // A-matrix: P(o|s)
+        if (isLearnable(this.observationModel)) {
+            this.observationModel.learn(observation, posteriorDist);
+        }
+        // B-matrix: P(s'|s,a) — only after at least one action
+        if (isLearnable(this.transitionModel) &&
+            this._previousAction !== null &&
+            this._previousBelief !== null) {
+            const prevDist = {};
+            for (const state of this._previousBelief.states) {
+                prevDist[state] = this._previousBelief.probability(state);
+            }
+            this.transitionModel.learn(this._previousAction, prevDist, posteriorDist);
+        }
+    }
     /**
      * Generate all possible policies (action sequences) of given depth.
      * For depth=2 with actions [a,b]: [[a,a], [a,b], [b,a], [b,b]]
@@ -288,6 +322,7 @@ export class Agent {
      */
     computeRisk(predictedBelief) {
         let risk = 0;
+        const prefs = this.resolvedPreferences;
         for (const obs of this.observationModel.observations) {
             let expectedObsProb = 0;
             for (const state of predictedBelief.states) {
@@ -295,7 +330,7 @@ export class Agent {
                     this.observationModel.probability(obs, state) *
                         predictedBelief.probability(state);
             }
-            const preferredLogProb = this.preferences[obs] ?? -10;
+            const preferredLogProb = prefs[obs] ?? -10;
             if (expectedObsProb > 0) {
                 risk -= expectedObsProb * preferredLogProb;
             }

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

@@ -0,0 +1,15 @@
+/**
+ * Interface for models that support Dirichlet concentration-based learning.
+ *
+ * Models implementing this interface maintain Dirichlet concentration
+ * parameters (pseudo-counts) that are updated from experience.
+ * The underlying probability matrices are derived by normalizing
+ * concentrations.
+ */
+export interface ILearnable {
+    readonly learnable: true;
+}
+/**
+ * Type guard to check if a model supports learning.
+ */
+export declare function isLearnable(obj: unknown): obj is ILearnable;

package/dist/models/learnable.model.js

@@ -0,0 +1,9 @@
+/**
+ * Type guard to check if a model supports learning.
+ */
+export function isLearnable(obj) {
+    return (typeof obj === 'object' &&
+        obj !== null &&
+        'learnable' in obj &&
+        obj.learnable === true);
+}

package/dist/observation/dirichlet.observation.d.ts

@@ -0,0 +1,83 @@
+import { Distribution } from '../models/belief.model';
+import { IObservationModel, ObservationMatrix } from '../models/observation.model';
+import { ILearnable } from '../models/learnable.model';
+/**
+ * Dirichlet concentration parameters for observation model.
+ * Same structure as ObservationMatrix: observation → state → concentration.
+ *
+ * Each value is a positive pseudo-count. Higher values encode stronger
+ * prior beliefs about the observation-state mapping.
+ */
+export type ObservationConcentrations<O extends string = string, S extends string = string> = Record<O, Record<S, number>>;
+/**
+ * Learnable observation model using Dirichlet concentrations.
+ *
+ * Instead of a fixed A matrix, this model maintains Dirichlet pseudo-counts
+ * from which the probability matrix P(o|s) is derived by normalization:
+ *
+ *   P(o|s) = a[o][s] / Σ_o' a[o'][s]
+ *
+ * After each observation, concentrations are updated using the posterior
+ * belief about states (Dirichlet-categorical conjugate update):
+ *
+ *   a[o*][s] += Q(s)   for the observed o*
+ *
+ * @typeParam O - Union type of possible observation names
+ * @typeParam S - Union type of possible state names
+ *
+ * @example
+ * ```typescript
+ * // Weak prior: agent is uncertain about observation-state mapping
+ * const obs = new DirichletObservation({
+ *   see_safe:   { safe: 2, danger: 1 },
+ *   see_danger: { safe: 1, danger: 2 },
+ * });
+ *
+ * // Strong prior: agent has confident beliefs (equivalent to scale * probabilities)
+ * const obs = new DirichletObservation({
+ *   see_safe:   { safe: 90, danger: 10 },
+ *   see_danger: { safe: 10, danger: 90 },
+ * });
+ * ```
+ */
+export declare class DirichletObservation<O extends string = string, S extends string = string> implements IObservationModel<O, S>, ILearnable {
+    concentrations: ObservationConcentrations<O, S>;
+    readonly learnable: true;
+    private _matrix;
+    /**
+     * @param concentrations - Dirichlet pseudo-counts a[o][s].
+     *   Each value must be > 0. Higher values encode stronger prior beliefs.
+     */
+    constructor(concentrations: ObservationConcentrations<O, S>);
+    get observations(): O[];
+    get states(): S[];
+    /**
+     * Normalized probability matrix derived from concentrations.
+     * Lazily computed and cached; invalidated on learn().
+     *
+     * Column-wise normalization (per state s):
+     *   P(o|s) = a[o][s] / Σ_o' a[o'][s]
+     */
+    get matrix(): ObservationMatrix<O, S>;
+    getLikelihood(observation: O): Distribution<S>;
+    probability(observation: O, state: S): number;
+    /**
+     * Update concentrations from an observation and posterior belief.
+     *
+     * Dirichlet-categorical conjugate update:
+     *   a[o*][s] += posteriorBelief[s]   for the observed o*
+     *
+     * The belief-weighting handles state uncertainty: if the agent
+     * is 80% sure it's in state A, the count for (o*, A) increases
+     * by 0.8 and (o*, B) by 0.2.
+     *
+     * @param observation - The observation that was received
+     * @param posteriorBelief - Posterior belief distribution over states
+     */
+    learn(observation: O, posteriorBelief: Distribution<S>): void;
+    /**
+     * Column-wise normalization of concentrations.
+     * For each state s: P(o|s) = a[o][s] / Σ_o' a[o'][s]
+     */
+    private normalize;
+}

package/dist/observation/dirichlet.observation.js

@@ -0,0 +1,119 @@
+/**
+ * Learnable observation model using Dirichlet concentrations.
+ *
+ * Instead of a fixed A matrix, this model maintains Dirichlet pseudo-counts
+ * from which the probability matrix P(o|s) is derived by normalization:
+ *
+ *   P(o|s) = a[o][s] / Σ_o' a[o'][s]
+ *
+ * After each observation, concentrations are updated using the posterior
+ * belief about states (Dirichlet-categorical conjugate update):
+ *
+ *   a[o*][s] += Q(s)   for the observed o*
+ *
+ * @typeParam O - Union type of possible observation names
+ * @typeParam S - Union type of possible state names
+ *
+ * @example
+ * ```typescript
+ * // Weak prior: agent is uncertain about observation-state mapping
+ * const obs = new DirichletObservation({
+ *   see_safe:   { safe: 2, danger: 1 },
+ *   see_danger: { safe: 1, danger: 2 },
+ * });
+ *
+ * // Strong prior: agent has confident beliefs (equivalent to scale * probabilities)
+ * const obs = new DirichletObservation({
+ *   see_safe:   { safe: 90, danger: 10 },
+ *   see_danger: { safe: 10, danger: 90 },
+ * });
+ * ```
+ */
+export class DirichletObservation {
+    /**
+     * @param concentrations - Dirichlet pseudo-counts a[o][s].
+     *   Each value must be > 0. Higher values encode stronger prior beliefs.
+     */
+    constructor(concentrations) {
+        this.concentrations = concentrations;
+        this.learnable = true;
+        this._matrix = null;
+        // Deep copy to avoid aliasing
+        this.concentrations = {};
+        for (const obs of Object.keys(concentrations)) {
+            this.concentrations[obs] = { ...concentrations[obs] };
+        }
+    }
+    get observations() {
+        return Object.keys(this.concentrations);
+    }
+    get states() {
+        const firstObs = this.observations[0];
+        return Object.keys(this.concentrations[firstObs] || {});
+    }
+    /**
+     * Normalized probability matrix derived from concentrations.
+     * Lazily computed and cached; invalidated on learn().
+     *
+     * Column-wise normalization (per state s):
+     *   P(o|s) = a[o][s] / Σ_o' a[o'][s]
+     */
+    get matrix() {
+        if (this._matrix === null) {
+            this._matrix = this.normalize();
+        }
+        return this._matrix;
+    }
+    getLikelihood(observation) {
+        return this.matrix[observation] ?? {};
+    }
+    probability(observation, state) {
+        return this.matrix[observation]?.[state] ?? 0;
+    }
+    /**
+     * Update concentrations from an observation and posterior belief.
+     *
+     * Dirichlet-categorical conjugate update:
+     *   a[o*][s] += posteriorBelief[s]   for the observed o*
+     *
+     * The belief-weighting handles state uncertainty: if the agent
+     * is 80% sure it's in state A, the count for (o*, A) increases
+     * by 0.8 and (o*, B) by 0.2.
+     *
+     * @param observation - The observation that was received
+     * @param posteriorBelief - Posterior belief distribution over states
+     */
+    learn(observation, posteriorBelief) {
+        for (const state of this.states) {
+            this.concentrations[observation][state] +=
+                posteriorBelief[state] ?? 0;
+        }
+        this._matrix = null;
+    }
+    /**
+     * Column-wise normalization of concentrations.
+     * For each state s: P(o|s) = a[o][s] / Σ_o' a[o'][s]
+     */
+    normalize() {
+        const matrix = {};
+        const observations = this.observations;
+        const states = this.states;
+        const colSums = {};
+        for (const s of states) {
+            colSums[s] = 0;
+            for (const o of observations) {
+                colSums[s] += this.concentrations[o][s];
+            }
+        }
+        for (const o of observations) {
+            matrix[o] = {};
+            for (const s of states) {
+                matrix[o][s] =
+                    colSums[s] > 0
+                        ? this.concentrations[o][s] / colSums[s]
+                        : 0;
+            }
+        }
+        return matrix;
+    }
+}

package/dist/preferences/dirichlet.preferences.d.ts

@@ -0,0 +1,62 @@
+import { ILearnable } from '../models/learnable.model';
+/**
+ * Dirichlet concentration parameters for preferences.
+ * Maps each observation to a positive pseudo-count.
+ */
+export type PreferenceConcentrations<O extends string = string> = Record<O, number>;
+/**
+ * Learnable preferences using Dirichlet concentrations.
+ *
+ * Instead of fixed log-probability preferences, this class maintains
+ * Dirichlet pseudo-counts from which log-preferences are derived:
+ *
+ *   P_preferred(o) = c[o] / Σ_o' c[o']
+ *   preferences[o] = log(P_preferred(o))
+ *
+ * Higher concentration → higher preferred probability → less negative log → more preferred.
+ *
+ * After each observation, concentrations can be reinforced:
+ *   c[o*] += 1
+ *
+ * This allows preferences to drift based on experience.
+ *
+ * @typeParam O - Union type of possible observation names
+ *
+ * @example
+ * ```typescript
+ * // Strongly prefer reward over no_reward
+ * const prefs = new DirichletPreferences({
+ *   reward: 10,      // log(10/11) ≈ -0.095
+ *   no_reward: 1,    // log(1/11) ≈ -2.398
+ * });
+ * ```
+ */
+export declare class DirichletPreferences<O extends string = string> implements ILearnable {
+    concentrations: PreferenceConcentrations<O>;
+    readonly learnable: true;
+    private _preferences;
+    /**
+     * @param concentrations - Pseudo-counts c[o] for each observation.
+     *   Higher values indicate more preferred observations.
+     *   All values must be > 0.
+     */
+    constructor(concentrations: PreferenceConcentrations<O>);
+    get observations(): O[];
+    /**
+     * Log-preference values derived from concentrations.
+     *
+     *   P(o) = c[o] / Σ_o' c[o']
+     *   preferences[o] = log(P(o))
+     *
+     * Returns a plain Record<O, number> compatible with Preferences<O>.
+     */
+    get preferences(): Record<O, number>;
+    /**
+     * Reinforce an observation's preference.
+     *
+     * @param observation - The observation to reinforce
+     * @param amount - Amount to add to the concentration (default: 1)
+     */
+    learn(observation: O, amount?: number): void;
+    private normalize;
+}

package/dist/preferences/dirichlet.preferences.js

@@ -0,0 +1,79 @@
+/**
+ * Learnable preferences using Dirichlet concentrations.
+ *
+ * Instead of fixed log-probability preferences, this class maintains
+ * Dirichlet pseudo-counts from which log-preferences are derived:
+ *
+ *   P_preferred(o) = c[o] / Σ_o' c[o']
+ *   preferences[o] = log(P_preferred(o))
+ *
+ * Higher concentration → higher preferred probability → less negative log → more preferred.
+ *
+ * After each observation, concentrations can be reinforced:
+ *   c[o*] += 1
+ *
+ * This allows preferences to drift based on experience.
+ *
+ * @typeParam O - Union type of possible observation names
+ *
+ * @example
+ * ```typescript
+ * // Strongly prefer reward over no_reward
+ * const prefs = new DirichletPreferences({
+ *   reward: 10,      // log(10/11) ≈ -0.095
+ *   no_reward: 1,    // log(1/11) ≈ -2.398
+ * });
+ * ```
+ */
+export class DirichletPreferences {
+    /**
+     * @param concentrations - Pseudo-counts c[o] for each observation.
+     *   Higher values indicate more preferred observations.
+     *   All values must be > 0.
+     */
+    constructor(concentrations) {
+        this.concentrations = concentrations;
+        this.learnable = true;
+        this._preferences = null;
+        this.concentrations = { ...concentrations };
+    }
+    get observations() {
+        return Object.keys(this.concentrations);
+    }
+    /**
+     * Log-preference values derived from concentrations.
+     *
+     *   P(o) = c[o] / Σ_o' c[o']
+     *   preferences[o] = log(P(o))
+     *
+     * Returns a plain Record<O, number> compatible with Preferences<O>.
+     */
+    get preferences() {
+        if (this._preferences === null) {
+            this._preferences = this.normalize();
+        }
+        return this._preferences;
+    }
+    /**
+     * Reinforce an observation's preference.
+     *
+     * @param observation - The observation to reinforce
+     * @param amount - Amount to add to the concentration (default: 1)
+     */
+    learn(observation, amount = 1) {
+        this.concentrations[observation] += amount;
+        this._preferences = null;
+    }
+    normalize() {
+        const result = {};
+        let sum = 0;
+        for (const o of this.observations) {
+            sum += this.concentrations[o];
+        }
+        for (const o of this.observations) {
+            const p = this.concentrations[o] / sum;
+            result[o] = Math.log(Math.max(p, 1e-16));
+        }
+        return result;
+    }
+}

package/dist/transition/dirichlet.transition.d.ts

@@ -0,0 +1,82 @@
+import { Distribution } from '../models/belief.model';
+import type { Belief } from '../models/belief.model';
+import { ITransitionModel, TransitionMatrix } from '../models/transition.model';
+import { ILearnable } from '../models/learnable.model';
+/**
+ * Dirichlet concentration parameters for transition model.
+ * Same structure as TransitionMatrix: action → current_state → next_state → concentration.
+ */
+export type TransitionConcentrations<A extends string = string, S extends string = string> = Record<A, Record<S, Record<S, number>>>;
+/**
+ * Learnable transition model using Dirichlet concentrations.
+ *
+ * Instead of a fixed B matrix, this model maintains Dirichlet pseudo-counts
+ * from which the probability matrix P(s'|s,a) is derived by normalization:
+ *
+ *   P(s'|s,a) = b[a][s][s'] / Σ_s'' b[a][s][s'']
+ *
+ * After each state transition, concentrations are updated using the
+ * outer product of prior and posterior beliefs:
+ *
+ *   b[a][s][s'] += Q_prior(s) × Q_posterior(s')
+ *
+ * @typeParam A - Union type of possible action names
+ * @typeParam S - Union type of possible state names
+ *
+ * @example
+ * ```typescript
+ * const transition = new DirichletTransition({
+ *   move: {
+ *     here: { here: 1, there: 5 },  // move from here → likely end up there
+ *     there: { here: 1, there: 5 },
+ *   },
+ *   stay: {
+ *     here: { here: 5, there: 1 },
+ *     there: { here: 1, there: 5 },
+ *   },
+ * });
+ * ```
+ */
+export declare class DirichletTransition<A extends string = string, S extends string = string> implements ITransitionModel<A, S>, ILearnable {
+    concentrations: TransitionConcentrations<A, S>;
+    readonly learnable: true;
+    private _matrix;
+    /**
+     * @param concentrations - Dirichlet pseudo-counts b[a][s][s'].
+     *   Structure: action → current_state → next_state → count.
+     *   Each value must be > 0.
+     */
+    constructor(concentrations: TransitionConcentrations<A, S>);
+    get actions(): A[];
+    get states(): S[];
+    /**
+     * Normalized probability matrix derived from concentrations.
+     * Lazily computed and cached; invalidated on learn().
+     *
+     * Row-wise normalization (per action a, per current state s):
+     *   P(s'|s,a) = b[a][s][s'] / Σ_s'' b[a][s][s'']
+     */
+    get matrix(): TransitionMatrix<A, S>;
+    getTransition(state: S, action: A): Distribution<S>;
+    predict(belief: Belief<S>, action: A): Belief<S>;
+    /**
+     * Update concentrations from a state transition.
+     *
+     * Uses outer product of prior and posterior beliefs:
+     *   b[a][s][s'] += Q_prior(s) × Q_posterior(s')
+     *
+     * This encodes the agent's best estimate of the transition
+     * that occurred, weighted by uncertainty in both states.
+     *
+     * @param action - The action that was taken
+     * @param priorBelief - Belief distribution before the action
+     * @param posteriorBelief - Belief distribution after observing the outcome
+     */
+    learn(action: A, priorBelief: Distribution<S>, posteriorBelief: Distribution<S>): void;
+    /**
+     * Row-wise normalization of concentrations.
+     * For each (action, current_state):
+     *   P(s'|s,a) = b[a][s][s'] / Σ_s'' b[a][s][s'']
+     */
+    private normalize;
+}

package/dist/transition/dirichlet.transition.js

@@ -0,0 +1,135 @@
+import { DiscreteBelief } from '../beliefs/discrete.belief';
+/**
+ * Learnable transition model using Dirichlet concentrations.
+ *
+ * Instead of a fixed B matrix, this model maintains Dirichlet pseudo-counts
+ * from which the probability matrix P(s'|s,a) is derived by normalization:
+ *
+ *   P(s'|s,a) = b[a][s][s'] / Σ_s'' b[a][s][s'']
+ *
+ * After each state transition, concentrations are updated using the
+ * outer product of prior and posterior beliefs:
+ *
+ *   b[a][s][s'] += Q_prior(s) × Q_posterior(s')
+ *
+ * @typeParam A - Union type of possible action names
+ * @typeParam S - Union type of possible state names
+ *
+ * @example
+ * ```typescript
+ * const transition = new DirichletTransition({
+ *   move: {
+ *     here: { here: 1, there: 5 },  // move from here → likely end up there
+ *     there: { here: 1, there: 5 },
+ *   },
+ *   stay: {
+ *     here: { here: 5, there: 1 },
+ *     there: { here: 1, there: 5 },
+ *   },
+ * });
+ * ```
+ */
+export class DirichletTransition {
+    /**
+     * @param concentrations - Dirichlet pseudo-counts b[a][s][s'].
+     *   Structure: action → current_state → next_state → count.
+     *   Each value must be > 0.
+     */
+    constructor(concentrations) {
+        this.concentrations = concentrations;
+        this.learnable = true;
+        this._matrix = null;
+        // Deep copy to avoid aliasing
+        this.concentrations = {};
+        for (const a of Object.keys(concentrations)) {
+            this.concentrations[a] = {};
+            for (const s of Object.keys(concentrations[a])) {
+                this.concentrations[a][s] = { ...concentrations[a][s] };
+            }
+        }
+    }
+    get actions() {
+        return Object.keys(this.concentrations);
+    }
+    get states() {
+        const firstAction = this.actions[0];
+        return Object.keys(this.concentrations[firstAction] || {});
+    }
+    /**
+     * Normalized probability matrix derived from concentrations.
+     * Lazily computed and cached; invalidated on learn().
+     *
+     * Row-wise normalization (per action a, per current state s):
+     *   P(s'|s,a) = b[a][s][s'] / Σ_s'' b[a][s][s'']
+     */
+    get matrix() {
+        if (this._matrix === null) {
+            this._matrix = this.normalize();
+        }
+        return this._matrix;
+    }
+    getTransition(state, action) {
+        return this.matrix[action]?.[state] ?? {};
+    }
+    predict(belief, action) {
+        const newDist = {};
+        for (const state of this.states) {
+            newDist[state] = 0;
+        }
+        for (const currentState of belief.states) {
+            const transition = this.getTransition(currentState, action);
+            const currentProb = belief.probability(currentState);
+            for (const nextState of Object.keys(transition)) {
+                newDist[nextState] += transition[nextState] * currentProb;
+            }
+        }
+        return new DiscreteBelief(newDist);
+    }
+    /**
+     * Update concentrations from a state transition.
+     *
+     * Uses outer product of prior and posterior beliefs:
+     *   b[a][s][s'] += Q_prior(s) × Q_posterior(s')
+     *
+     * This encodes the agent's best estimate of the transition
+     * that occurred, weighted by uncertainty in both states.
+     *
+     * @param action - The action that was taken
+     * @param priorBelief - Belief distribution before the action
+     * @param posteriorBelief - Belief distribution after observing the outcome
+     */
+    learn(action, priorBelief, posteriorBelief) {
+        for (const s of this.states) {
+            for (const sPrime of this.states) {
+                this.concentrations[action][s][sPrime] +=
+                    (priorBelief[s] ?? 0) * (posteriorBelief[sPrime] ?? 0);
+            }
+        }
+        this._matrix = null;
+    }
+    /**
+     * Row-wise normalization of concentrations.
+     * For each (action, current_state):
+     *   P(s'|s,a) = b[a][s][s'] / Σ_s'' b[a][s][s'']
+     */
+    normalize() {
+        const matrix = {};
+        for (const a of this.actions) {
+            matrix[a] = {};
+            for (const s of this.states) {
+                matrix[a][s] = {};
+                let rowSum = 0;
+                for (const sPrime of this.states) {
+                    rowSum += this.concentrations[a][s][sPrime];
+                }
+                for (const sPrime of this.states) {
+                    matrix[a][s][sPrime] =
+                        rowSum > 0
+                            ? this.concentrations[a][s][sPrime] / rowSum
+                            : 0;
+                }
+            }
+        }
+        return matrix;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "active-inference",
-    "version": "0.0.1",
+    "version": "0.1.0",
     "description": "Active Inference Framework implementation for JavaScript/TypeScript",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",
@@ -11,7 +11,8 @@
         "test": "vitest run",
         "test:watch": "vitest",
         "build": "tsc",
-        "prepublishOnly": "npm run build"
+        "prepublish": "npm run build",
+        "build:examples": "npx esbuild src/index.ts --bundle --format=esm --outfile=examples/cart-pole/active-inference.bundle.js"
     },
     "keywords": [
         "active-inference",