active-inference 0.0.1

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

@@ -0,0 +1,67 @@
+import { Belief, Distribution } from './belief.model';
+/**
+ * State transition matrix (B matrix in Active Inference notation).
+ * Defines P(s'|s, a) - probability of transitioning to state s'
+ * given current state s and action a.
+ *
+ * Structure: action → current_state → next_state → probability
+ *
+ * @typeParam A - Union type of possible action names
+ * @typeParam S - Union type of possible state names
+ *
+ * @example
+ * ```typescript
+ * const B: TransitionMatrix<'move' | 'stay', 'left' | 'right'> = {
+ *   move: {
+ *     left: { left: 0.1, right: 0.9 },   // move from left → mostly goes right
+ *     right: { left: 0.9, right: 0.1 }   // move from right → mostly goes left
+ *   },
+ *   stay: {
+ *     left: { left: 1.0, right: 0.0 },   // stay at left
+ *     right: { left: 0.0, right: 1.0 }   // stay at right
+ *   }
+ * };
+ * ```
+ */
+export type TransitionMatrix<A extends string = string, S extends string = string> = Record<A, Record<S, Distribution<S>>>;
+/**
+ * Interface for state transition models.
+ *
+ * In Active Inference, the transition model (B) captures the agent's
+ * beliefs about how the world state changes in response to actions.
+ * It's a key component of the generative model used for planning.
+ *
+ * The transition model enables:
+ * - Predicting future states given current beliefs and actions
+ * - Evaluating action sequences (policies) by simulating outcomes
+ * - Computing Expected Free Energy for action selection
+ *
+ * @typeParam A - Union type of possible action names
+ * @typeParam S - Union type of possible state names
+ *
+ * @example
+ * ```typescript
+ * class MyTransition implements ITransitionModel<'up' | 'down', 'top' | 'bottom'> {
+ *   get actions() { return ['up', 'down'] as const; }
+ *   predict(belief, action) { // ... return predicted belief }
+ * }
+ * ```
+ */
+export interface ITransitionModel<A extends string = string, S extends string = string> {
+    /**
+     * List of all possible actions the agent can take.
+     */
+    readonly actions: A[];
+    /**
+     * Predict the belief state after taking an action.
+     * Computes: P(s') = Σ_s P(s'|s, a) × P(s)
+     *
+     * This is belief propagation through the transition model,
+     * used during planning to simulate future states.
+     *
+     * @param belief - Current belief over states
+     * @param action - Action to simulate
+     * @returns Predicted belief after the action
+     */
+    predict(belief: Belief<S>, action: A): Belief<S>;
+}

package/dist/models/transition.model.js

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

package/dist/observation/discrete.observation.d.ts

@@ -0,0 +1,134 @@
+import { Distribution } from '../models/belief.model';
+import { IObservationModel, ObservationMatrix } from '../models/observation.model';
+/**
+ * Discrete observation model implementing the A matrix in Active Inference.
+ *
+ * This class represents P(o|s) - the probability of receiving observation o
+ * given the hidden state s. It's a core component of the agent's generative
+ * model used for perception and planning.
+ *
+ * ## Matrix Structure
+ *
+ * The observation matrix is organized as: `observation → state → probability`
+ *
+ * For each observation, you specify the probability of that observation
+ * occurring given each possible hidden state. Each column (observation
+ * conditional on all states) defines a likelihood function.
+ *
+ * ## Usage in Active Inference
+ *
+ * The observation model enables:
+ * - **Perception**: Bayesian belief updates when observations are received
+ * - **Ambiguity computation**: Expected uncertainty about observations
+ * - **Policy evaluation**: Predicting what observations actions will cause
+ *
+ * ## Sensor Accuracy
+ *
+ * The observation matrix encodes sensor reliability:
+ * - Perfect sensor: P(o|s) = 1 for matching state, 0 otherwise
+ * - Noisy sensor: Some probability mass spreads to wrong observations
+ * - Ambiguous sensor: Multiple states produce similar observations
+ *
+ * @typeParam O - Union type of possible observation names
+ * @typeParam S - Union type of possible state names
+ *
+ * @example
+ * ```typescript
+ * // 90% accurate sensor for detecting danger
+ * const observation = new DiscreteObservation({
+ *   see_safe: { safe: 0.9, danger: 0.1 },    // see_safe mostly in safe state
+ *   see_danger: { safe: 0.1, danger: 0.9 }   // see_danger mostly in danger state
+ * });
+ *
+ * // Use for Bayesian update
+ * const likelihood = observation.getLikelihood('see_danger');
+ * const posterior = belief.update(likelihood);
+ * ```
+ *
+ * @see {@link IObservationModel} - Interface this class implements
+ * @see {@link ObservationMatrix} - Type definition for the matrix structure
+ */
+export declare class DiscreteObservation<O extends string = string, S extends string = string> implements IObservationModel<O, S> {
+    matrix: ObservationMatrix<O, S>;
+    /**
+     * Create a discrete observation model from an observation matrix.
+     *
+     * @param matrix - Observation matrix defining P(o|s) for all observation-state pairs.
+     *                 Structure: observation → state → probability
+     *
+     * @example
+     * ```typescript
+     * const observation = new DiscreteObservation({
+     *   bright: { light_on: 0.95, light_off: 0.05 },
+     *   dim: { light_on: 0.05, light_off: 0.95 }
+     * });
+     * ```
+     */
+    constructor(matrix: ObservationMatrix<O, S>);
+    /**
+     * List of all possible observations in this model.
+     *
+     * Observations are extracted from the keys of the observation matrix.
+     *
+     * @returns Array of observation names
+     *
+     * @example
+     * ```typescript
+     * observation.observations; // ['bright', 'dim']
+     * ```
+     */
+    get observations(): O[];
+    /**
+     * List of all possible hidden states in this model.
+     *
+     * States are extracted from the first observation's state mappings.
+     * Assumes all observations have the same state space.
+     *
+     * @returns Array of state names
+     *
+     * @example
+     * ```typescript
+     * observation.states; // ['light_on', 'light_off']
+     * ```
+     */
+    get states(): S[];
+    /**
+     * Get the likelihood function for a specific observation.
+     *
+     * Returns P(o|s) for all states - this is the key function for
+     * Bayesian belief updates during perception.
+     *
+     * When the agent receives an observation, it uses this likelihood
+     * to update its beliefs: P(s|o) ∝ P(o|s) × P(s)
+     *
+     * @param observation - The observation received
+     * @returns Distribution mapping each state to its likelihood
+     *
+     * @example
+     * ```typescript
+     * const likelihood = observation.getLikelihood('see_reward');
+     * // { good_state: 0.8, bad_state: 0.1 }
+     *
+     * // Use for belief update
+     * const posterior = belief.update(likelihood);
+     * ```
+     */
+    getLikelihood(observation: O): Distribution<S>;
+    /**
+     * Get the probability of a specific observation given a state.
+     *
+     * Returns P(o|s) - the probability of observing o when the
+     * true hidden state is s.
+     *
+     * @param observation - The observation
+     * @param state - The hidden state
+     * @returns Probability between 0 and 1
+     *
+     * @example
+     * ```typescript
+     * observation.probability('see_safe', 'danger'); // 0.1 (unlikely)
+     * observation.probability('see_safe', 'safe');   // 0.9 (likely)
+     * ```
+     */
+    probability(observation: O, state: S): number;
+}

package/dist/observation/discrete.observation.js

@@ -0,0 +1,142 @@
+/**
+ * Discrete observation model implementing the A matrix in Active Inference.
+ *
+ * This class represents P(o|s) - the probability of receiving observation o
+ * given the hidden state s. It's a core component of the agent's generative
+ * model used for perception and planning.
+ *
+ * ## Matrix Structure
+ *
+ * The observation matrix is organized as: `observation → state → probability`
+ *
+ * For each observation, you specify the probability of that observation
+ * occurring given each possible hidden state. Each column (observation
+ * conditional on all states) defines a likelihood function.
+ *
+ * ## Usage in Active Inference
+ *
+ * The observation model enables:
+ * - **Perception**: Bayesian belief updates when observations are received
+ * - **Ambiguity computation**: Expected uncertainty about observations
+ * - **Policy evaluation**: Predicting what observations actions will cause
+ *
+ * ## Sensor Accuracy
+ *
+ * The observation matrix encodes sensor reliability:
+ * - Perfect sensor: P(o|s) = 1 for matching state, 0 otherwise
+ * - Noisy sensor: Some probability mass spreads to wrong observations
+ * - Ambiguous sensor: Multiple states produce similar observations
+ *
+ * @typeParam O - Union type of possible observation names
+ * @typeParam S - Union type of possible state names
+ *
+ * @example
+ * ```typescript
+ * // 90% accurate sensor for detecting danger
+ * const observation = new DiscreteObservation({
+ *   see_safe: { safe: 0.9, danger: 0.1 },    // see_safe mostly in safe state
+ *   see_danger: { safe: 0.1, danger: 0.9 }   // see_danger mostly in danger state
+ * });
+ *
+ * // Use for Bayesian update
+ * const likelihood = observation.getLikelihood('see_danger');
+ * const posterior = belief.update(likelihood);
+ * ```
+ *
+ * @see {@link IObservationModel} - Interface this class implements
+ * @see {@link ObservationMatrix} - Type definition for the matrix structure
+ */
+export class DiscreteObservation {
+    /**
+     * Create a discrete observation model from an observation matrix.
+     *
+     * @param matrix - Observation matrix defining P(o|s) for all observation-state pairs.
+     *                 Structure: observation → state → probability
+     *
+     * @example
+     * ```typescript
+     * const observation = new DiscreteObservation({
+     *   bright: { light_on: 0.95, light_off: 0.05 },
+     *   dim: { light_on: 0.05, light_off: 0.95 }
+     * });
+     * ```
+     */
+    constructor(matrix) {
+        this.matrix = matrix;
+    }
+    /**
+     * List of all possible observations in this model.
+     *
+     * Observations are extracted from the keys of the observation matrix.
+     *
+     * @returns Array of observation names
+     *
+     * @example
+     * ```typescript
+     * observation.observations; // ['bright', 'dim']
+     * ```
+     */
+    get observations() {
+        return Object.keys(this.matrix);
+    }
+    /**
+     * List of all possible hidden states in this model.
+     *
+     * States are extracted from the first observation's state mappings.
+     * Assumes all observations have the same state space.
+     *
+     * @returns Array of state names
+     *
+     * @example
+     * ```typescript
+     * observation.states; // ['light_on', 'light_off']
+     * ```
+     */
+    get states() {
+        const firstObs = this.observations[0];
+        return Object.keys(this.matrix[firstObs] || {});
+    }
+    /**
+     * Get the likelihood function for a specific observation.
+     *
+     * Returns P(o|s) for all states - this is the key function for
+     * Bayesian belief updates during perception.
+     *
+     * When the agent receives an observation, it uses this likelihood
+     * to update its beliefs: P(s|o) ∝ P(o|s) × P(s)
+     *
+     * @param observation - The observation received
+     * @returns Distribution mapping each state to its likelihood
+     *
+     * @example
+     * ```typescript
+     * const likelihood = observation.getLikelihood('see_reward');
+     * // { good_state: 0.8, bad_state: 0.1 }
+     *
+     * // Use for belief update
+     * const posterior = belief.update(likelihood);
+     * ```
+     */
+    getLikelihood(observation) {
+        return this.matrix[observation] ?? {};
+    }
+    /**
+     * Get the probability of a specific observation given a state.
+     *
+     * Returns P(o|s) - the probability of observing o when the
+     * true hidden state is s.
+     *
+     * @param observation - The observation
+     * @param state - The hidden state
+     * @returns Probability between 0 and 1
+     *
+     * @example
+     * ```typescript
+     * observation.probability('see_safe', 'danger'); // 0.1 (unlikely)
+     * observation.probability('see_safe', 'safe');   // 0.9 (likely)
+     * ```
+     */
+    probability(observation, state) {
+        return this.matrix[observation]?.[state] ?? 0;
+    }
+}

package/dist/transition/discrete.transition.d.ts

@@ -0,0 +1,139 @@
+import { Distribution } from '../models/belief.model';
+import type { Belief } from '../models/belief.model';
+import { ITransitionModel, TransitionMatrix } from '../models/transition.model';
+/**
+ * Discrete state transition model implementing the B matrix in Active Inference.
+ *
+ * This class represents P(s'|s, a) - the probability of transitioning to
+ * a new state s' given the current state s and action a. It's a core
+ * component of the agent's generative model used for planning.
+ *
+ * ## Matrix Structure
+ *
+ * The transition matrix is organized as: `action → current_state → next_state → probability`
+ *
+ * For each action, you specify how each current state transitions to next states.
+ * Each row (current state) should sum to 1.0 (valid probability distribution).
+ *
+ * ## Usage in Active Inference
+ *
+ * The transition model enables:
+ * - **Planning**: Simulating future states to evaluate action sequences
+ * - **Policy evaluation**: Computing Expected Free Energy over time horizons
+ * - **State prediction**: Propagating beliefs through time
+ *
+ * @typeParam A - Union type of possible action names
+ * @typeParam S - Union type of possible state names
+ *
+ * @example
+ * ```typescript
+ * // Light switch model: actions affect the light state
+ * const transition = new DiscreteTransition({
+ *   turn_on: {
+ *     dark: { dark: 0.1, light: 0.9 },   // turn_on in dark → 90% light
+ *     light: { dark: 0.0, light: 1.0 }   // turn_on in light → stays light
+ *   },
+ *   turn_off: {
+ *     dark: { dark: 1.0, light: 0.0 },   // turn_off in dark → stays dark
+ *     light: { dark: 0.9, light: 0.1 }   // turn_off in light → 90% dark
+ *   }
+ * });
+ *
+ * // Predict state after action
+ * const currentBelief = new DiscreteBelief({ dark: 1.0, light: 0.0 });
+ * const predicted = transition.predict(currentBelief, 'turn_on');
+ * // predicted: { dark: 0.1, light: 0.9 }
+ * ```
+ *
+ * @see {@link ITransitionModel} - Interface this class implements
+ * @see {@link TransitionMatrix} - Type definition for the matrix structure
+ */
+export declare class DiscreteTransition<A extends string = string, S extends string = string> implements ITransitionModel<A, S> {
+    matrix: TransitionMatrix<A, S>;
+    /**
+     * Create a discrete transition model from a transition matrix.
+     *
+     * @param matrix - Transition matrix defining P(s'|s, a) for all state-action pairs.
+     *                 Structure: action → current_state → next_state → probability
+     *
+     * @example
+     * ```typescript
+     * const transition = new DiscreteTransition({
+     *   move_left: {
+     *     left: { left: 1.0, right: 0.0 },
+     *     right: { left: 0.8, right: 0.2 }
+     *   },
+     *   move_right: {
+     *     left: { left: 0.2, right: 0.8 },
+     *     right: { left: 0.0, right: 1.0 }
+     *   }
+     * });
+     * ```
+     */
+    constructor(matrix: TransitionMatrix<A, S>);
+    /**
+     * List of all possible actions in this model.
+     *
+     * Actions are extracted from the keys of the transition matrix.
+     *
+     * @returns Array of action names
+     *
+     * @example
+     * ```typescript
+     * transition.actions; // ['move_left', 'move_right', 'stay']
+     * ```
+     */
+    get actions(): A[];
+    /**
+     * List of all possible states in this model.
+     *
+     * States are extracted from the first action's state mappings.
+     * Assumes all actions have the same state space.
+     *
+     * @returns Array of state names
+     *
+     * @example
+     * ```typescript
+     * transition.states; // ['left', 'center', 'right']
+     * ```
+     */
+    get states(): S[];
+    /**
+     * Get the transition distribution for a specific state-action pair.
+     *
+     * Returns P(s'|s, a) - the probability distribution over next states
+     * given the current state and action.
+     *
+     * @param state - The current state
+     * @param action - The action being taken
+     * @returns Distribution over next states
+     *
+     * @example
+     * ```typescript
+     * const dist = transition.getTransition('left', 'move_right');
+     * // { left: 0.2, right: 0.8 }
+     * ```
+     */
+    getTransition(state: S, action: A): Distribution<S>;
+    /**
+     * Predict the belief state after taking an action.
+     *
+     * Performs belief propagation through the transition model:
+     * P(s') = Σ_s P(s'|s, a) × P(s)
+     *
+     * This is the core function used during planning to simulate
+     * what the agent's beliefs would be after taking an action.
+     *
+     * @param belief - Current belief distribution over states
+     * @param action - Action to simulate
+     * @returns Predicted belief after the action
+     *
+     * @example
+     * ```typescript
+     * const current = new DiscreteBelief({ left: 0.8, right: 0.2 });
+     * const predicted = transition.predict(current, 'move_right');
+     * // Belief shifts toward 'right' based on transition probabilities
+     * ```
+     */
+    predict(belief: Belief<S>, action: A): Belief<S>;
+}

package/dist/transition/discrete.transition.js

@@ -0,0 +1,158 @@
+import { DiscreteBelief } from '../beliefs/discrete.belief';
+/**
+ * Discrete state transition model implementing the B matrix in Active Inference.
+ *
+ * This class represents P(s'|s, a) - the probability of transitioning to
+ * a new state s' given the current state s and action a. It's a core
+ * component of the agent's generative model used for planning.
+ *
+ * ## Matrix Structure
+ *
+ * The transition matrix is organized as: `action → current_state → next_state → probability`
+ *
+ * For each action, you specify how each current state transitions to next states.
+ * Each row (current state) should sum to 1.0 (valid probability distribution).
+ *
+ * ## Usage in Active Inference
+ *
+ * The transition model enables:
+ * - **Planning**: Simulating future states to evaluate action sequences
+ * - **Policy evaluation**: Computing Expected Free Energy over time horizons
+ * - **State prediction**: Propagating beliefs through time
+ *
+ * @typeParam A - Union type of possible action names
+ * @typeParam S - Union type of possible state names
+ *
+ * @example
+ * ```typescript
+ * // Light switch model: actions affect the light state
+ * const transition = new DiscreteTransition({
+ *   turn_on: {
+ *     dark: { dark: 0.1, light: 0.9 },   // turn_on in dark → 90% light
+ *     light: { dark: 0.0, light: 1.0 }   // turn_on in light → stays light
+ *   },
+ *   turn_off: {
+ *     dark: { dark: 1.0, light: 0.0 },   // turn_off in dark → stays dark
+ *     light: { dark: 0.9, light: 0.1 }   // turn_off in light → 90% dark
+ *   }
+ * });
+ *
+ * // Predict state after action
+ * const currentBelief = new DiscreteBelief({ dark: 1.0, light: 0.0 });
+ * const predicted = transition.predict(currentBelief, 'turn_on');
+ * // predicted: { dark: 0.1, light: 0.9 }
+ * ```
+ *
+ * @see {@link ITransitionModel} - Interface this class implements
+ * @see {@link TransitionMatrix} - Type definition for the matrix structure
+ */
+export class DiscreteTransition {
+    /**
+     * Create a discrete transition model from a transition matrix.
+     *
+     * @param matrix - Transition matrix defining P(s'|s, a) for all state-action pairs.
+     *                 Structure: action → current_state → next_state → probability
+     *
+     * @example
+     * ```typescript
+     * const transition = new DiscreteTransition({
+     *   move_left: {
+     *     left: { left: 1.0, right: 0.0 },
+     *     right: { left: 0.8, right: 0.2 }
+     *   },
+     *   move_right: {
+     *     left: { left: 0.2, right: 0.8 },
+     *     right: { left: 0.0, right: 1.0 }
+     *   }
+     * });
+     * ```
+     */
+    constructor(matrix) {
+        this.matrix = matrix;
+    }
+    /**
+     * List of all possible actions in this model.
+     *
+     * Actions are extracted from the keys of the transition matrix.
+     *
+     * @returns Array of action names
+     *
+     * @example
+     * ```typescript
+     * transition.actions; // ['move_left', 'move_right', 'stay']
+     * ```
+     */
+    get actions() {
+        return Object.keys(this.matrix);
+    }
+    /**
+     * List of all possible states in this model.
+     *
+     * States are extracted from the first action's state mappings.
+     * Assumes all actions have the same state space.
+     *
+     * @returns Array of state names
+     *
+     * @example
+     * ```typescript
+     * transition.states; // ['left', 'center', 'right']
+     * ```
+     */
+    get states() {
+        const firstAction = this.actions[0];
+        return Object.keys(this.matrix[firstAction] || {});
+    }
+    /**
+     * Get the transition distribution for a specific state-action pair.
+     *
+     * Returns P(s'|s, a) - the probability distribution over next states
+     * given the current state and action.
+     *
+     * @param state - The current state
+     * @param action - The action being taken
+     * @returns Distribution over next states
+     *
+     * @example
+     * ```typescript
+     * const dist = transition.getTransition('left', 'move_right');
+     * // { left: 0.2, right: 0.8 }
+     * ```
+     */
+    getTransition(state, action) {
+        return this.matrix[action]?.[state] ?? {};
+    }
+    /**
+     * Predict the belief state after taking an action.
+     *
+     * Performs belief propagation through the transition model:
+     * P(s') = Σ_s P(s'|s, a) × P(s)
+     *
+     * This is the core function used during planning to simulate
+     * what the agent's beliefs would be after taking an action.
+     *
+     * @param belief - Current belief distribution over states
+     * @param action - Action to simulate
+     * @returns Predicted belief after the action
+     *
+     * @example
+     * ```typescript
+     * const current = new DiscreteBelief({ left: 0.8, right: 0.2 });
+     * const predicted = transition.predict(current, 'move_right');
+     * // Belief shifts toward 'right' based on transition probabilities
+     * ```
+     */
+    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);
+    }
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+    "name": "active-inference",
+    "version": "0.0.1",
+    "description": "Active Inference Framework implementation for JavaScript/TypeScript",
+    "main": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "files": [
+        "dist"
+    ],
+    "scripts": {
+        "test": "vitest run",
+        "test:watch": "vitest",
+        "build": "tsc",
+        "prepublishOnly": "npm run build"
+    },
+    "keywords": [
+        "active-inference",
+        "free-energy",
+        "bayesian",
+        "agent",
+        "friston",
+        "ai",
+        "machine-learning"
+    ],
+    "author": "Igor Rybakov <codevanger@gmail.com>",
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/codevanger/active-inference"
+    },
+    "bugs": {
+        "url": "https://github.com/codevanger/active-inference/issues"
+    },
+    "homepage": "https://github.com/codevanger/active-inference#readme",
+    "devDependencies": {
+        "prettier": "^3.8.1",
+        "typescript": "^5.9.3",
+        "vitest": "^3.2.4"
+    }
+}