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. 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. 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: 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. 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. Changing a parameter updates the underlying equations and redraws the curves in real time.

This tight coupling between mathematics and interface was deliberate. The UI experiments with a more futuristic design language, but every visual element maps to a behavioural assumption.

Architecture and infrastructure

The platform runs on a distributed architecture: 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

Behavioural Engines marked a shift for me from building isolated features to designing a coherent system. 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.