active-inference 0.0.1 → 0.2.1

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/beliefs/gaussian.belief.d.ts

@@ -0,0 +1,31 @@
+/**
+ * A 1-dimensional Gaussian (Normal) belief over a continuous hidden state.
+ *
+ * Represents the agent's uncertainty about a single real-valued state
+ * as a Normal distribution N(μ, σ²).
+ *
+ * Used in continuous Active Inference where states live on the real line
+ * rather than in a finite set.
+ *
+ * @example
+ * ```typescript
+ * const belief = new GaussianBelief(2.0, 0.5);
+ * console.log(belief.mean);     // 2.0
+ * console.log(belief.variance); // 0.5
+ * console.log(belief.entropy()); // ≈ 1.07
+ * ```
+ */
+export declare class GaussianBelief {
+    readonly mean: number;
+    readonly variance: number;
+    constructor(mean: number, variance: number);
+    /**
+     * Shannon entropy of the Gaussian in nats.
+     * H = ½ log(2πeσ²)
+     */
+    entropy(): number;
+    /**
+     * Create an independent copy.
+     */
+    copy(): GaussianBelief;
+}

package/dist/beliefs/gaussian.belief.js

@@ -0,0 +1,36 @@
+/**
+ * A 1-dimensional Gaussian (Normal) belief over a continuous hidden state.
+ *
+ * Represents the agent's uncertainty about a single real-valued state
+ * as a Normal distribution N(μ, σ²).
+ *
+ * Used in continuous Active Inference where states live on the real line
+ * rather than in a finite set.
+ *
+ * @example
+ * ```typescript
+ * const belief = new GaussianBelief(2.0, 0.5);
+ * console.log(belief.mean);     // 2.0
+ * console.log(belief.variance); // 0.5
+ * console.log(belief.entropy()); // ≈ 1.07
+ * ```
+ */
+export class GaussianBelief {
+    constructor(mean, variance) {
+        this.mean = mean;
+        this.variance = variance;
+    }
+    /**
+     * Shannon entropy of the Gaussian in nats.
+     * H = ½ log(2πeσ²)
+     */
+    entropy() {
+        return 0.5 * Math.log(2 * Math.PI * Math.E * this.variance);
+    }
+    /**
+     * Create an independent copy.
+     */
+    copy() {
+        return new GaussianBelief(this.mean, this.variance);
+    }
+}

package/dist/factory.d.ts

@@ -1,168 +1,64 @@
-import { Belief, Preferences } from './models/belief.model';
+import { Belief, Distribution, Preferences } from './models/belief.model';
 import { ITransitionModel } from './models/transition.model';
 import { IObservationModel } from './models/observation.model';
 import { Agent, Habits } from './models/agent.model';
+import { GaussianBelief } from './beliefs/gaussian.belief';
+import { GaussianTransition } from './transition/gaussian.transition';
+import { GaussianObservation } from './observation/gaussian.observation';
 /**
- * Configuration object for creating an Active Inference agent.
- *
- * This interface defines all the components needed to instantiate an agent
- * with its generative model and behavioral parameters.
- *
- * ## Required Components
- *
- * The generative model consists of:
- * - **belief**: Initial prior over hidden states (D matrix)
- * - **transitionModel**: State dynamics P(s'|s,a) (B matrix)
- * - **observationModel**: Observation likelihood P(o|s) (A matrix)
- * - **preferences**: Preferred observations as log probabilities (C vector)
- *
- * ## Optional Parameters
- *
- * Behavioral parameters that tune agent behavior:
- * - **seed**: For reproducible random behavior
- * - **planningHorizon**: How far ahead to plan (default: 1)
- * - **precision**: Action selection temperature (default: 1)
- * - **habits**: Prior action preferences (E matrix)
- *
- * @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 config: AgentConfig<'left' | 'right', 'see_goal' | 'see_wall', 'at_goal' | 'at_start'> = {
- *   belief: new DiscreteBelief({ at_goal: 0.1, at_start: 0.9 }),
- *   transitionModel: myTransitions,
- *   observationModel: myObservations,
- *   preferences: { see_goal: 0, see_wall: -2 },
- *   planningHorizon: 3,
- *   precision: 4
- * };
- * ```
+ * Preference function over predicted observation means (Gaussian models).
+ * Returns a log-preference (0 = neutral, negative = undesired).
+ */
+export type GaussianPreferenceFn = (mean: number) => number;
+/**
+ * Ambiguity = E_Q[H(o|s)] = −Σ_s Q(s) Σ_o P(o|s) log P(o|s)
+ */
+export declare function computeAmbiguity<O extends string, S extends string>(predictedBelief: Belief<S>, observationModel: IObservationModel<O, S>): number;
+/**
+ * Risk = −Σ_o Q(o) log C(o)
+ */
+export declare function computeRisk<O extends string, S extends string>(predictedBelief: Belief<S>, observationModel: IObservationModel<O, S>, preferences: Preferences<O>): number;
+/**
+ * Export a discrete belief as a plain Distribution object.
+ */
+export declare function exportBelief<S extends string>(belief: Belief<S>): Distribution<S>;
+/**
+ * Configuration object for creating a discrete Active Inference agent.
  */
 export interface AgentConfig<A extends string = string, O extends string = string, S extends string = string> {
-    /**
-     * Initial belief distribution over hidden states.
-     *
-     * This is the agent's prior - what it believes about the world
-     * before receiving any observations. Can be uncertain (spread
-     * across states) or confident (concentrated on one state).
-     */
     belief: Belief<S>;
-    /**
-     * State transition model defining P(s'|s, a).
-     *
-     * Encodes how the agent believes actions affect world state.
-     * Used during planning to simulate future states.
-     */
     transitionModel: ITransitionModel<A, S>;
-    /**
-     * Observation model defining P(o|s).
-     *
-     * Encodes how hidden states generate observations.
-     * Used for Bayesian belief updates and computing ambiguity.
-     */
     observationModel: IObservationModel<O, S>;
-    /**
-     * Preferred observations expressed as log probabilities.
-     *
-     * Higher values = more preferred. Typically:
-     * - 0 for neutral/desired observations
-     * - Negative for undesired observations (e.g., -5 for pain)
-     *
-     * These preferences define the agent's "goals" - what observations
-     * it will act to make more likely.
-     */
     preferences: Preferences<O>;
-    /**
-     * Random seed for reproducible behavior.
-     *
-     * When set, the agent's stochastic action selection will be
-     * deterministic given the same sequence of observations.
-     * Useful for testing and debugging.
-     */
     seed?: number;
-    /**
-     * Planning horizon - number of time steps to look ahead.
-     *
-     * - 1 = greedy/reactive (only considers immediate outcomes)
-     * - 2+ = planning (considers future consequences)
-     *
-     * Higher values enable better long-term decisions but increase
-     * computation exponentially (actions^horizon policies to evaluate).
-     *
-     * @default 1
-     */
     planningHorizon?: number;
-    /**
-     * Precision parameter (β) for action selection.
-     *
-     * Controls the "temperature" of the softmax over Expected Free Energy:
-     * - β = 0: Uniform random action selection
-     * - β → ∞: Deterministic selection of best action
-     * - β = 1: Standard softmax (balanced exploration/exploitation)
-     *
-     * @default 1
-     */
     precision?: number;
-    /**
-     * Habitual action preferences (E matrix in Active Inference).
-     *
-     * Biases action selection independently of Expected Free Energy.
-     * Higher values make actions more likely to be selected regardless
-     * of their predicted outcomes.
-     *
-     * Useful for modeling:
-     * - Learned motor habits
-     * - Default behaviors
-     * - Action priors from experience
-     */
     habits?: Partial<Habits<A>>;
+    beamWidth?: number;
 }
 /**
- * Factory function to create an Active Inference agent.
+ * Create a discrete Active Inference agent.
  *
- * This is the recommended way to instantiate agents, as it provides
- * a clean interface with sensible defaults for optional parameters.
- *
- * ## Type Inference
- *
- * TypeScript will automatically infer the type parameters from your
- * configuration objects, providing full type safety for actions,
- * observations, and states throughout your code.
- *
- * @typeParam A - Union type of possible action names (inferred from transitionModel)
- * @typeParam O - Union type of possible observation names (inferred from observationModel)
- * @typeParam S - Union type of possible state names (inferred from belief)
- *
- * @param config - Agent configuration object
- * @returns Configured Active Inference agent ready for use
- *
- * @example
- * ```typescript
- * // Create a simple agent
- * const agent = createAgent({
- *   belief: new DiscreteBelief({ safe: 0.5, danger: 0.5 }),
- *   transitionModel: new DiscreteTransition({
- *     stay: { safe: { safe: 1, danger: 0 }, danger: { safe: 0, danger: 1 } },
- *     flee: { safe: { safe: 0.9, danger: 0.1 }, danger: { safe: 0.7, danger: 0.3 } }
- *   }),
- *   observationModel: new DiscreteObservation({
- *     calm: { safe: 0.9, danger: 0.1 },
- *     alarm: { safe: 0.1, danger: 0.9 }
- *   }),
- *   preferences: { calm: 0, alarm: -5 },
- *   planningHorizon: 2,
- *   precision: 4,
- *   seed: 42  // For reproducibility
- * });
- *
- * // Use the agent
- * const action = agent.step('alarm');  // Types are inferred!
- * // action is typed as 'stay' | 'flee'
- * ```
+ * EFE = ambiguity + risk, computed from the observation model and preferences.
+ * Learning (Dirichlet updates) is handled automatically in step().
+ */
+export declare function createAgent<A extends string = string, O extends string = string, S extends string = string>(config: AgentConfig<A, O, S>): Agent<A, Belief<S>, O>;
+/**
+ * Configuration for creating a Gaussian Active Inference agent.
+ */
+export interface GaussianAgentConfig<A extends string = string> {
+    belief: GaussianBelief;
+    transitionModel: GaussianTransition<A>;
+    observationModel: GaussianObservation;
+    preferences: GaussianPreferenceFn;
+    seed?: number;
+    planningHorizon?: number;
+    precision?: number;
+}
+/**
+ * Create a continuous (Gaussian) Active Inference agent.
  *
- * @see {@link Agent} - The agent class this creates
- * @see {@link AgentConfig} - Configuration interface
+ * EFE = −C(E[y]) where C is the preference function.
+ * Ambiguity is constant for fixed observation noise and does not affect action selection.
  */
-export declare function createAgent<A extends string = string, O extends string = string, S extends string = string>(config: AgentConfig<A, O, S>): Agent<A, O, S>;
+export declare function createGaussianAgent<A extends string = string>(config: GaussianAgentConfig<A>): Agent<A, GaussianBelief, number>;

package/dist/factory.js

@@ -1,52 +1,82 @@
 import { Agent } from './models/agent.model';
 import { Random } from './helpers/math.helpers';
+// ── Discrete EFE helpers (exported for advanced use) ─────────────
 /**
- * Factory function to create an Active Inference agent.
- *
- * This is the recommended way to instantiate agents, as it provides
- * a clean interface with sensible defaults for optional parameters.
- *
- * ## Type Inference
- *
- * TypeScript will automatically infer the type parameters from your
- * configuration objects, providing full type safety for actions,
- * observations, and states throughout your code.
- *
- * @typeParam A - Union type of possible action names (inferred from transitionModel)
- * @typeParam O - Union type of possible observation names (inferred from observationModel)
- * @typeParam S - Union type of possible state names (inferred from belief)
- *
- * @param config - Agent configuration object
- * @returns Configured Active Inference agent ready for use
- *
- * @example
- * ```typescript
- * // Create a simple agent
- * const agent = createAgent({
- *   belief: new DiscreteBelief({ safe: 0.5, danger: 0.5 }),
- *   transitionModel: new DiscreteTransition({
- *     stay: { safe: { safe: 1, danger: 0 }, danger: { safe: 0, danger: 1 } },
- *     flee: { safe: { safe: 0.9, danger: 0.1 }, danger: { safe: 0.7, danger: 0.3 } }
- *   }),
- *   observationModel: new DiscreteObservation({
- *     calm: { safe: 0.9, danger: 0.1 },
- *     alarm: { safe: 0.1, danger: 0.9 }
- *   }),
- *   preferences: { calm: 0, alarm: -5 },
- *   planningHorizon: 2,
- *   precision: 4,
- *   seed: 42  // For reproducibility
- * });
- *
- * // Use the agent
- * const action = agent.step('alarm');  // Types are inferred!
- * // action is typed as 'stay' | 'flee'
- * ```
+ * Ambiguity = E_Q[H(o|s)] = −Σ_s Q(s) Σ_o P(o|s) log P(o|s)
+ */
+export function computeAmbiguity(predictedBelief, observationModel) {
+    let ambiguity = 0;
+    for (const state of predictedBelief.states) {
+        const stateProb = predictedBelief.probability(state);
+        for (const obs of observationModel.observations) {
+            const obsProb = observationModel.probability(obs, state);
+            if (obsProb > 0 && stateProb > 0) {
+                ambiguity -= stateProb * obsProb * Math.log(obsProb);
+            }
+        }
+    }
+    return ambiguity;
+}
+/**
+ * Risk = −Σ_o Q(o) log C(o)
+ */
+export function computeRisk(predictedBelief, observationModel, preferences) {
+    let risk = 0;
+    for (const obs of observationModel.observations) {
+        let expectedObsProb = 0;
+        for (const state of predictedBelief.states) {
+            expectedObsProb +=
+                observationModel.probability(obs, state) *
+                    predictedBelief.probability(state);
+        }
+        const preferredLogProb = preferences[obs] ?? -10;
+        if (expectedObsProb > 0) {
+            risk -= expectedObsProb * preferredLogProb;
+        }
+    }
+    return risk;
+}
+/**
+ * Export a discrete belief as a plain Distribution object.
+ */
+export function exportBelief(belief) {
+    const result = {};
+    for (const state of belief.states) {
+        result[state] = belief.probability(state);
+    }
+    return result;
+}
+/**
+ * Create a discrete Active Inference agent.
  *
- * @see {@link Agent} - The agent class this creates
- * @see {@link AgentConfig} - Configuration interface
+ * EFE = ambiguity + risk, computed from the observation model and preferences.
+ * Learning (Dirichlet updates) is handled automatically in step().
  */
 export function createAgent(config) {
     const random = config.seed !== undefined ? new Random(config.seed) : new Random();
-    return new Agent(config.belief, config.transitionModel, config.observationModel, config.preferences, random, config.planningHorizon ?? 1, config.precision ?? 1, config.habits ?? {});
+    const computeEFE = (predicted) => computeAmbiguity(predicted, config.observationModel) +
+        computeRisk(predicted, config.observationModel, config.preferences);
+    const afterObserve = (observation, belief, previousAction, previousBelief) => {
+        const posteriorDist = exportBelief(belief);
+        config.observationModel.learn?.(observation, posteriorDist);
+        if (previousAction !== null && previousBelief !== null) {
+            const prevDist = exportBelief(previousBelief);
+            config.transitionModel.learn?.(previousAction, prevDist, posteriorDist);
+        }
+    };
+    return new Agent(config.belief, config.transitionModel, config.observationModel, computeEFE, random, config.planningHorizon ?? 1, config.precision ?? 1, config.habits ?? {}, config.beamWidth ?? 0, afterObserve);
+}
+/**
+ * Create a continuous (Gaussian) Active Inference agent.
+ *
+ * EFE = −C(E[y]) where C is the preference function.
+ * Ambiguity is constant for fixed observation noise and does not affect action selection.
+ */
+export function createGaussianAgent(config) {
+    const random = config.seed !== undefined ? new Random(config.seed) : new Random();
+    const computeEFE = (predicted) => {
+        const obsMean = config.observationModel.expectedObservation(predicted);
+        return -config.preferences(obsMean);
+    };
+    return new Agent(config.belief, config.transitionModel, config.observationModel, computeEFE, random, config.planningHorizon ?? 1, config.precision ?? 1);
 }

package/dist/index.d.ts

@@ -2,4 +2,13 @@ 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';
+export { DirichletObservation } from './observation/dirichlet.observation';
+export { DirichletTransition } from './transition/dirichlet.transition';
+export { DirichletPreferences } from './preferences/dirichlet.preferences';
+export { GaussianBelief } from './beliefs/gaussian.belief';
+export { GaussianTransition } from './transition/gaussian.transition';
+export { GaussianObservation } from './observation/gaussian.observation';
+export { createAgent, createGaussianAgent, computeAmbiguity, computeRisk, exportBelief, } from './factory';
+export type { AgentConfig, GaussianAgentConfig, GaussianPreferenceFn, } from './factory';
+export type { Habits } from './models/agent.model';
+export type { ILearnable } from './models/learnable.model';

package/dist/index.js

@@ -2,4 +2,10 @@ 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';
+export { DirichletObservation } from './observation/dirichlet.observation';
+export { DirichletTransition } from './transition/dirichlet.transition';
+export { DirichletPreferences } from './preferences/dirichlet.preferences';
+export { GaussianBelief } from './beliefs/gaussian.belief';
+export { GaussianTransition } from './transition/gaussian.transition';
+export { GaussianObservation } from './observation/gaussian.observation';
+export { createAgent, createGaussianAgent, computeAmbiguity, computeRisk, exportBelief, } from './factory';