AgentFarm

AgentFarm — a research workbench for agent-based simulation.

Python-first tools for agent-based modeling, reinforcement learning, and emergent-behavior research. Build environments, run experiments, and persist structured data for reproducible analysis.

Documentation GitHub Quick start
Python 3.10+ PyTorch + Tianshou SQLite-backed runs structlog

What's in the box

Composable primitives for simulation, learning, and analysis — wired together with structured logging and reproducible run artifacts.

Agent-based modeling

Compose adaptive agents, environments, and rules. Track interactions, resources, and emergent dynamics over time.

Architecture

Reinforcement learning

PyTorch + Tianshou-backed decision modules with prioritized experience replay and evolvable hyperparameters.

Deep Q-learning

Hyperparameter evolution

Genetics-inspired chromosomes for learning hyperparameters with mutation, crossover, and adaptive rates.

Chromosomes

Spatial indexing

KD-tree, Quadtree, and Spatial Hash Grid backends with dirty-region tracking — thousands of agents, fast.

Spatial indexing

Data & analysis

Repository-backed databases, behavioral clustering, causal analysis, and experiment-level comparisons.

Data API Genetics

Structured logging

structlog-powered, context-rich, machine-readable logs with sampling and sensitive-data censoring.

Logging

Quick start

Clone the repository, create a virtualenv, install AgentFarm, and run your first simulation.

  1. Clone & create a virtualenv

    AgentFarm targets Python 3.10+. A virtualenv keeps experiment dependencies isolated.

  2. Install in editable mode

    Editable installs make it easy to extend agents, environments, or analysis pipelines.

  3. Run a simulation

    The CLI emits a SQLite .db under simulations/ for downstream analysis.

  4. Open the docs

    Browse getting started and the documentation hub.

shell bash 
# 1. Clone
git clone https://github.com/Dooders/AgentFarm.git
cd AgentFarm

# 2. Virtualenv + install
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
pip install -e .

# 3. Run a small simulation
python run_simulation.py \
  --environment development \
  --steps 500

# 4. Run the test suite
pytest -q

From the devlog

Build notes, design decisions, and experiment outcomes from the AgentFarm team.

All devlog posts