TokenLab: Advanced Economic Systems Simulation Library

A Python library for modeling complex economic systems, agent behaviors, and incentive mechanisms across traditional and digital economies. Developed by Dr. Stylianos Kampakis (PhD, CStat) and the research team at Tesseract Academy.

Core Capabilities

TokenLab is a comprehensive economic simulation framework built on agent-based modeling principles. Originally developed for digital economies, it has evolved into a versatile platform for analyzing any complex economic system where incentives, behaviors, and mechanisms interact dynamically.

Design Principles

1. Modularity: Components can be combined flexibly to model diverse economic scenarios - from traditional market dynamics to innovative digital incentive systems.

2. Explicitness: All modeling assumptions, limitations, and methodological choices are clearly documented, ensuring academic rigor and reproducibility.

3. Intermediate Abstraction: Focuses on aggregate agent cohorts (user segments, market participants, policy groups) rather than individual actors, enabling scalable economic analysis.

4. Systems-First Approach: Designed to answer fundamental questions about economic system stability, sustainability, and optimization through comprehensive stress testing.

5. Maximum Flexibility: Supports arbitrary logical flows and mechanisms, accommodating everything from traditional market models to experimental incentive designs.

Applications

• Government & Policy: Economic impact assessment, regulatory scenario modeling, public incentive design
• Enterprise: Market dynamics simulation, pricing mechanism optimization, organizational incentive analysis
• Financial Services: Risk modeling, algorithmic trading backtesting, DeFi integration planning
• Web3 Protocols: Tokenomics design, governance mechanism testing, economic security analysis
• Academic Research: Complex systems studies, behavioral economics experiments, econometric validation

Why TokenLab

Built by economists and data scientists with deep expertise in both traditional econometrics and digital economic systems, TokenLab bridges academic rigor with practical implementation. The platform has been validated through government consultations, enterprise deployments, and peer-reviewed research.

Getting Started

Installation & Prerequisites

TokenLab currently supports Python 3.10. The core numerical dependency stack is pinned to preserve the existing simulation contract.

Install the core library and command-line tools:

python -m pip install .

Public demo — the best place to start

Run the reviewed, self-contained scenario from an installed package:

tokenlab-demo --output-dir outputs/demo --run-id public-demo
tokenlab-dashboard outputs/demo/public-demo

The first command prints a six-line result and writes a non-overwriting evidence bundle containing manifest.json, raw and summary CSV tables, the full captured diagnostics.log, and a validated artifact_profile.json. The profile declares six metrics that are actually present and explicitly marks emissions, unlocks, liquidity, treasury, governance, staking yield, FDV, and APY unavailable.

The second command serves a dependency-free, read-only dashboard at http://127.0.0.1:8765. It charts only profile-declared metrics, keeps absent concepts visible, provides the exact source-table downloads, and shows run provenance. The server accepts loopback hosts only, has no upload or mutation routes, makes no remote request, and stops with Ctrl-C.

The scenario is deterministic and illustrative: repeated paths do not represent statistical uncertainty, and the output is not investment, launch, legal, financial, forecast, or decision-grade advice. See the three-minute presenter guide for the recommended talk track and reproducibility check.

For repository development, including the Z1, reporting, and test extras:

python -m pip install -r requirements.txt

Declarative scenario runner

TokenLab can run a complete simulation from a reviewed YAML or JSON scenario—no notebook editing or client-project code is required. From a repository checkout:

python -m TokenLab.agentic.runner \
  examples/scenarios/notebook_01_simple_fiat.yaml \
  --output-dir outputs/agentic \
  --run-id quickstart

The command publishes one non-overwriting bundle at outputs/agentic/quickstart/ containing:

• manifest.json with scenario hash, seed, run lineage, and output checksums;
• results.csv with repetition-level simulation output; and
• iteration_summary.csv with per-iteration summary statistics.

The supplied reference scenario proves deterministic execution and lineage. It is not an investment forecast or a substitute for model, financial, or legal review. The public demo and local dashboard above are the recommended presentation flow.

Directory Structure & Organization

The repository is organized to maintain a clean layout while keeping all client projects perfectly isolated:

• src/: Core Python package TokenLab containing the modular simulation framework.
• projects/: Client-specific simulation directories (e.g. friendocash/, andromeda/) containing their respective Python scripts and custom datasets.
• resources/: Persistent asset repository (archives, prompt templates, and logos).
• tokenlab: The installed CLI for listing and executing simulations from an external projects/ directory.
• run_sim.py: The backwards-compatible source-checkout wrapper for the same CLI.

Unified Simulation Runner (tokenlab)

The tokenlab command discovers, inspects, and runs simulations while cleanly resolving library imports and project-relative data paths. By default it uses ./projects; use --projects-dir <path> or TOKENLAB_PROJECTS_DIR for an external project root.

1. List all available simulations:

   tokenlab --list

2. Execute a client simulation (Headless / Non-blocking - Recommended): Runs the simulation with a headless matplotlib backend (MPLBACKEND=Agg) to ensure it executes to completion in background/headless setups:

   tokenlab --project friendocash

3. Execute in Interactive mode (GUI Plot Popups): Runs the simulation and opens interactive GUI windows to display plots on your desktop:

   tokenlab --project friendocash --interactive

4. Specify a specific script: If a client folder contains multiple simulation scripts, specify the target file:

   tokenlab --project footboard --script footboard_tokenomics_2.py

Existing source-checkout commands such as python run_sim.py --list remain supported and use the repository's own projects/ directory.

Repository status, generated-artifact policy, and the legacy GitBook status are documented in Repository governance.

Notebook execution is optional and requires python -m pip install ".[notebook]".

Contact & Collaboration

For research partnerships, custom modeling projects, or technical support:

• Dr. Stylianos Kampakis: https://thedatascientist.com/contact-dr-kampakis/
• Tesseract Academy Research Team: https://tesseract.academy/contact/

---

TokenLab is open-source software supporting the advancement of quantitative economic analysis across traditional and digital systems.