Behavioural Engines

Overview

Behavioural Engines was an attempt to challenge myself by bringing together what I have learnt through behavioural science and programming. The idea of a simulator came from an article and subsequent book written by Michael Hallsworth, Behavioural Insights, which discusses the need for a core framework for behavioural science to move forward. This project carries that idea forward by modelling the core frameworks found in behavioural science, using them as tools to experiment with and explore each concept.

Model catalogue

The platform is built around a modular model registry, where Prospect theory and hyperbolic discounting form the initial core, with models such as Diffusion Dynamics and Dual-Process Decisioning being considered as later additions. Each model exists as an independent, versioned unit within a shared architecture.

The system was designed so that new models can be incorporated with minimal friction. Each model defines its own assumptions, structural equations, and parameter boundaries, allowing it to be integrated cleanly without restructuring the wider platform.

Mathematical implementation

The core of the project is mathematical, where models are implemented from first principles in Python using FastAPI as a typed execution layer. Prospect theory value functions, probability weighting curves, and intertemporal discounting functions are computed dynamically rather than hardcoded.

Translating theory into code exposed edge cases that are easy to miss on paper such as scaling behaviour, numerical stability, parameter sensitivity, and boundary constraints. The act of implementation deepened my understanding of the models themselves.

Structured outputs

Outputs are deterministic and structured meaning each simulation produces scalar metrics, interpretable summaries, and versioned logs that can be revisited. The idea was to have the platform be genuinely useful as an educational or experimental tool.

Persisted logs in Neon PostgreSQL allow runs to be stored alongside model versions, creating a foundation for reproducibility and future expansion.

Visual representation

Visualisations are generated directly from computed data structures. Graphs reflect the exact mathematical output of each model such that changing a parameter updates the underlying equations and redraws the curves in real time.

The UI experiments with a more futuristic design language, however every visual element maps to a specific behavioural model and implementation.

Architecture and infrastructure

The platform runs on a distributed architecture, with a Next.js frontend hosted on Vercel communicating with a FastAPI backend deployed on Railway. Authentication is handled via Clerk, and simulation logs are stored in Neon PostgreSQL.

Building this forced me to properly understand CORS policies, token verification, environment configuration, rate limiting, and production debugging.

What this project represents

Building Behavioural Engines has taught me a lot, from a deeper understanding of react effet states and python programming to design and UI, constantly thinking about how to make the platform more accessible, for example, introducing a command+K palette, writing carefully defined support pages, the list goes on! It required careful thinking about modular architecture, model versioning, typed interfaces, and how the platform could scale as new models are introduced.

Building the models in code also strengthened my understanding of them. Translating prospect theory and hyperbolic discounting into formal, executable structures made their assumptions and constraints much clearer than studying them in theory alone.

Where it is going

A changelog page tracks every model addition and update, giving the platform a sense of ongoing development. There are currently six models, each of which took genuine thought to implement correctly. The intention is to keep adding slowly and carefully, making sure each one earns its place in the catalogue rather than padding it out. Stripe has since been integrated to support a subscription mode.