Skip to content
CapitalOne-ResearchPublic

About

This is affiliated with a paper that was approved for submission at NeurIPS. The intent of this is for further experimentation/reproducibility in the field.

Resources

Contributing

Stars

4 stars

Watchers

0 watching

Forks

Repository files navigation

FINESSE: Financial Agent-Based Model

An agent-based simulation framework for modeling credit card account behavior and merchant interactions.

🚀 Quick Start

Installation

  1. Create Python environment:
conda create -n finesse python=3.9 -y
conda activate finesse
pip install -r requirements.txt
  1. Generate merchant data:
python generate_merchants.py --n_per_mcc 10
  1. Run simulation:
python run.py --N 100 --total_days 365 --output_dir ./results

📊 Generating Merchant Data

The simulation requires synthetic merchant data. Generate it before running simulations:

# Generate default dataset (10 merchants per MCC)
python generate_merchants.py

# Generate larger dataset (100 merchants per MCC)
python generate_merchants.py --n_per_mcc 100

# Specify custom output file
python generate_merchants.py --output my_merchants.yaml 

Important: The merchant generation uses synthetic risk rules that are arbitrary and do not reflect real-world patterns. See generate_merchants.py for details.

🎯 Running Simulations

Basic Usage

python run.py --N 1000 --total_days 365 --output_dir ./output

Parameters

Parameter Description Default
--N Number of agents 100
--total_days Simulation length in days 365
--merchant_data_path Path to merchant data YAML merchants.yaml
--output_dir Output directory ./output
--warmup Gradual agent addition False

Example Workflows

# Quick test run (small scale, 30 days)
python run.py --N 10 --total_days 30 --output_dir ./test

# Full year simulation with 1000 agents
python run.py --N 1000 --total_days 365 --output_dir ./full_sim

# Warmup simulation (agents added gradually)
python run.py --N 1000 --total_days 365 --warmup --output_dir ./warmup_sim

📁 Output Files

The simulation generates CSV files in the output directory:

File Description
transactions_log.csv All transaction records
payments_log.csv Payment history
account_state_log.csv Daily account snapshots
hidden_state_log.csv Internal agent states
interventions_log.csv Policy interventions
environment_log.csv Environment parameters

🏗️ Project Structure

FINESSE/
├── finagent.py              # Agent behavior logic
├── finmodel.py              # Model orchestration
├── generate_merchants.py    # Merchant data generation
├── run.py                   # Simulation runner
├── utils.py                 # Utility functions
├── merchant_affinities.py   # Spending preferences
├── payment_strategies.py    # Payment behaviors
├── mcc_ranges.yaml          # Merchant category codes
└── requirements.txt         # Python dependencies

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

📄 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

⚠️ Disclaimer

This is a synthetic simulation framework for research purposes. The risk rules and patterns in merchant generation are arbitrary and do not reflect real-world financial behaviors, fraud patterns, or business characteristics. This software is provided for educational and research use only.

About

This is affiliated with a paper that was approved for submission at NeurIPS. The intent of this is for further experimentation/reproducibility in the field.

Resources

Contributing

Stars

4 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages