hey# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

This is an agent-based modeling (ABM) framework designed for social systems and public health applications. The framework targets academic researchers in epidemiology and public health, supporting medium-scale simulations (1,000 to 1 million agents).

**Key Features:**
- Heterogeneous agents with diverse attributes and behaviors
- Network-based modeling of complex social interactions
- Event-driven simulation architecture
- Parameter exploration, calibration, and scenario analysis
- Extensible design for custom agent types and behaviors

## Commands

Since this is an early-stage project, there are no specific build/test/lint commands defined yet. The project uses Python with a basic pyproject.toml configuration.

To run the main module:
```bash
python main.py
```

To explore the demo files:
```bash
python demos/networkx_demo.py
python demos/networkx_demo_agents.py
python demos/networkx_demo_edge_agents.py
python demos/networkx_demo_multigraph.py
python demos/networkx_demo_simulation.py
```

## Architecture and Design

The framework follows a layered architecture with four distinct layers:

### Layer 1: Core Management
- **Agent**: Base class for all entities (individuals, diseases, institutions) - primarily data/state containers
- **Edge**: Base class for relationships between agents (friendship, work, contact)
- **Service**: Base class for services that contain all behavior logic and act on agents
- **ServiceRegistry**: Manages and provides access to services by type or ID
- **Observer**: Base class for monitoring and data collection during simulation
- **Collective**: Generic base class for managing agent collections with `Population` as a simple subclass
- **NetworkManager**: Manages multiple graphs, one for each relationship type
- **Scheduler**: Manages discrete time stepping and event execution

### Layer 2: Simulation Coordination  
- **WorldBuilder**: Configures initial state, collectives, and networks based on parameters
- **Simulation**: Orchestrates a single model run, managing collectives, networks, time progression, and data collection
- **Parameters**: Manages and validates simulation parameters in a structured way

### Layer 3: Parallel Execution
- **Batch**: Runs multiple simulations in parallel with different parameter configurations

### Layer 4: Workflow & Analysis
- **ParameterSweep**: Generates parameter configurations for exploration
- **Experiment**: Compares scenarios using calibrated parameters
- **Calibrator**: Performs statistical inference to fit model parameters to observed data
- **Analysis**: Post-simulation analysis, metrics computation, and visualization
- **Workflow**: High-level orchestration of complex multi-step analyses

## Key Design Principles

1. **Service-Centric Architecture**:
   - **Agents are data containers**: Hold state (age, mood, race, etc.) with minimal behavior
   - **Services contain all behavior logic**: All actions, interactions, and computations happen in services
   - **Services schedule events**: Only services add events to the schedule; agents are passed as arguments
   - **Zero circular dependencies**: Agents don't import or reference services or world objects
   - See `demos/school_demo/SERVICE_CENTRIC_ARCHITECTURE.md` for detailed explanation

2. **Event-Driven Architecture**: Agents don't execute synchronous step() methods. Instead, behaviors are defined through events scheduled by services.

3. **Network-Centric Modeling**: Rather than explicit spatial representation, agents interact through multiple typed networks (friendship, contact, work, etc.).

4. **Generic Collective Abstraction**: Agents are organized into `Collectives` - a flexible base class that can be subclassed for domain-specific groupings.

5. **Pluggable Graph Backends**: Supports NetworkX by default with optional igraph backend for performance-critical scenarios.

6. **Separation of Concerns**:
   - Agents = State/Data
   - Services = Behavior/Logic
   - World = Orchestration
   - Schedule = Execution

## Technology Stack

- Python 3.9+
- NetworkX 3.0+ for graph operations
- Built-in Python collections for agent and event management
- Optional: NumPy, SciPy, Pandas for statistical analysis
- Multiprocessing for parallel simulation execution

## Current State

This is an early-stage framework with:
- Comprehensive design documentation in `/design/`
- Demo files using NetworkX in `/demos/`
- Basic project structure with `pyproject.toml`
- Minimal implementation (only `main.py` with hello world)

The framework is primarily in the design and planning phase, with detailed API specifications documented but core implementation still needed.