# ABM Framework

[![PyPI version](https://badge.fury.io/py/abm-framework.svg)](https://badge.fury.io/py/abm-framework)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A **service-centric agent-based modeling framework** for social systems and public health applications.

## Features

✨ **Service-Centric Architecture** - Agents are data containers, services contain all behavior logic
🔄 **Event-Driven** - Flexible event scheduling for complex interactions
🕸️ **Network-Based** - Built-in support for social networks using NetworkX
🎯 **Zero Circular Dependencies** - Clean, maintainable architecture
📊 **Research-Ready** - Designed for epidemiology and public health research
🚀 **Extensible** - Easy to add custom agents, services, and behaviors

## Installation

```bash
pip install abm-framework
```

## Quick Example

```python
from layer1_core.entities.agent import Agent
from layer1_core.managers.service import Service
from layer2_simulation.world_builder import WorldBuilder
from layer2_simulation.single_runner import SingleRunner
from layer1_core.managers.schedule import Schedule

# 1. Define agents (data only)
class Student(Agent):
    def __init__(self, agent_id, mood=0.5):
        super().__init__(agent_id)
        self.mood = mood

# 2. Define services (behavior logic)
class InteractionService(Service):
    def interact(self, student1, student2):
        student1.mood += 0.1
        student2.mood += 0.1

    def schedule_interactions(self, schedule, students, steps):
        for step in range(1, steps):
            s1, s2 = random.sample(students, 2)
            schedule.add_event(
                step=step,
                event=lambda: self.interact(s1, s2)
            )

# 3. Build world
class SchoolWorld(WorldBuilder):
    def __init__(self, params):
        super().__init__(params)
        self.schedule = Schedule()

        # Register services
        self.interaction_service = InteractionService()
        self.services.register(self.interaction_service)

        # Create agents
        self.students = [Student(f"s{i}") for i in range(params['n_students'])]

    def setup_events(self):
        self.interaction_service.schedule_interactions(
            self.schedule, self.students, 1000
        )

# 4. Run simulation
world = SchoolWorld({'n_students': 50})
world.setup_events()

runner = SingleRunner(world)
runner.run(stopping_condition=lambda s: s.get_current_step() >= 1000)

print(f"Average mood: {sum(s.mood for s in world.students) / len(world.students):.2f}")
```

## Architecture

The framework follows a **layered service-centric architecture**:

### Core Principles

1. **Agents are data containers** - Hold state (age, mood, etc.) with no behavior methods
2. **Services contain all behavior** - All logic, interactions, and computations
3. **Services schedule events** - Only services add events to the schedule
4. **Zero circular dependencies** - Clean imports and dependencies

### Layers

- **Layer 1: Core** - Agents, Services, Networks, Schedules
- **Layer 2: Simulation** - WorldBuilder, SingleRunner, Parameters
- **Layer 3: Parallel** - Batch execution (planned)
- **Layer 4: Analysis** - Parameter sweeps, calibration, workflows (planned)

## Documentation

- 📘 [Quickstart Guide](QUICKSTART.md)
- 🏗️ [Service-Centric Architecture](demos/school_demo/SERVICE_CENTRIC_ARCHITECTURE.md)
- ⚡ [Quick Reference](SERVICE_PATTERN_QUICK_REFERENCE.md)
- 🏫 [School Demo](demos/school_demo/) - Complete example with students, teachers, friendships

## Use Cases

Perfect for modeling:
- 🏥 Disease transmission and interventions
- 🏫 Educational systems and outcomes
- 🏘️ Neighborhood effects and segregation
- 👥 Social network dynamics
- 📊 Policy impact analysis

## Requirements

- Python 3.9+
- NetworkX 3.0+

## Contributing

Contributions welcome! Please read our contributing guidelines.

## Citation

If you use this framework in your research, please cite:

```bibtex
@software{abm_framework_2026,
  title = {ABM Framework: Service-Centric Agent-Based Modeling},
  author = {Your Name},
  year = {2026},
  url = {https://github.com/yourusername/abm-framework}
}
```

## License

MIT License - see [LICENSE](LICENSE) file for details.

## Support

- 📖 [Documentation](https://abm-framework.readthedocs.io)
- 🐛 [Issue Tracker](https://github.com/yourusername/abm-framework/issues)
- 💬 [Discussions](https://github.com/yourusername/abm-framework/discussions)

---

**Note**: This is an early-stage framework under active development. APIs may change.