ABM JSON Schema

A comprehensive Pydantic-based validation schema for Agent-Based Models (ABM) defined in JSON format.

Overview

This project provides a robust schema for defining agent-based models in JSON, with full validation support through Pydantic. The schema enables:

• JSON-based ABM definitions that can be validated and type-checked
• LLM-friendly format for AI-assisted model generation
• Backend pipeline support for converting validated JSON to executable Mesa Python code

Project Structure

abm_json_round2/
├── README.md                    # This file
├── abm_json_schema.py          # Main Pydantic schema definition
├── abm_json_schema.json        # JSON schema reference (draft)
├── sir_example.json            # Complete SIR epidemiological model
├── test_sir_schema.py          # SIR example validation script
├── requirements.txt            # Python dependencies
├── pyproject.toml             # Project configuration
└── tests/                     # Test suite directory
    ├── README.md              # Test documentation
    ├── test_validator.py      # Main test runner
    ├── test_*.json            # Test cases
    └── *.md                   # Feature documentation

Quick Start

Installation

# Install dependencies
pip install -r requirements.txt

Validate a Model

from abm_json_schema import ABMJsonSchema
import json

# Load and validate an ABM model
with open('sir_example.json') as f:
    model = ABMJsonSchema(**json.load(f))
    print("✅ Model is valid!")

Run Tests

cd tests
python3 test_validator.py

Key Features

🎯 Comprehensive Validation

• Function call validation (existence, argument counts, types)
• Source reference validation (all references must exist)
• Optional parameter support with proper ordering
• Unused resource detection (functions, variables)
• Scheduler reference validation

🔧 Flexible Design

• Support for global functions, variables, and behaviors
• Agent-based and environment-based components
• Multiple agent types per model
• Customizable initialization and scheduling
• Data analytics tracking

📊 Optional Parameters

• Functions can have optional parameters with defaults
• Proper validation of parameter ordering
• Flexible function calls (min to max arguments)

✨ Clean Architecture

• Function parameters don't have source_name (determined at call site)
• Separation of function signatures from data flow
• Reusable function definitions

Core Concepts

Agent-Based Model Components

1. Global Functions - Reusable helper functions
2. Global Variables - Model-wide state
3. Environment - The world/context
   • Environment Attributes
   • Environment Behaviors
4. Agents - Active entities
   • Agent Attributes
   • Agent Behaviors
5. Scheduler - Execution order
   • Initialization order
   • Step-by-step schedule
6. Termination Criteria - When to stop
7. Data Analytics - What to track

Source Names

The schema uses a source naming convention for clarity:

• globalVariable.name - Global variables
• globalFunction.name - Global functions
• environment.environmentAttribute.name - Environment attributes
• environment.environmentBehavior.name - Environment behaviors
• agent.AgentType.agentAttribute.name - Agent attributes
• agent.AgentType.agentBehavior.name - Agent behaviors

Example: SIR Model

See sir_example.json for a complete epidemiological SIR (Susceptible-Infected-Recovered) model demonstrating:

• Network-based agent interactions
• State transitions (S → I → R)
• Global variable tracking
• Termination conditions
• Deterministic initialization
• Bidirectional network connections

Run the SIR example:

python3 test_sir_schema.py

Validation Features

What Gets Validated

✅ Function Calls

{
  "function": "randomInt",
  "args": [1, 10]  // Must match function signature
}

✅ Optional Parameters

{
  "functionInputs": [{
    "name": "distance",
    "type": "float",
    "optional": true,
    "defaultValue": 1.0  // Required for optional params
  }]
}

✅ Source References

{
  "source_name": "globalVariable.population"  // Must exist
}

✅ Resource Usage

• Warns if functions are defined but never called
• Warns if variables are defined but never used

Documentation

• README.md (this file) - Main project documentation
• tests/README.md - Test suite documentation
• tests/TEST_VALIDATOR_README.md - Detailed test case descriptions and validation rules

Dependencies

• Python 3.8+
• Pydantic 2.0+

Development Workflow

1. Define Your Model

Create a JSON file following the schema structure (see sir_example.json).

2. Validate

from abm_json_schema import ABMJsonSchema
import json

with open('my_model.json') as f:
    model = ABMJsonSchema(**json.load(f))

3. Handle Errors

The validator provides detailed error messages:

• Invalid function calls
• Missing source references
• Unused resources
• Parameter ordering issues
• Argument count mismatches

4. Convert to Mesa (Future)

The validated JSON can be used as input for a backend pipeline that generates executable Mesa Python code.

Design Philosophy

1. Validation First - Catch errors before execution
2. LLM-Friendly - Structured format for AI-assisted generation
3. Explicit Over Implicit - Clear naming and references
4. Reusable Components - Functions and behaviors are truly reusable
5. Type Safety - Strong type checking throughout

Common Patterns

Defining a Function

{
  "functionInputs": [
    {
      "name": "param1",
      "description": "Required parameter",
      "type": "integer"
    },
    {
      "name": "param2",
      "description": "Optional parameter",
      "type": "float",
      "optional": true,
      "defaultValue": 1.0
    }
  ]
}

Calling a Function

{
  "initialValue": {
    "function": "functionName",
    "args": [10, 2.5]
  }
}

Referencing Sources

{
  "args": [
    "globalVariable.count",     // Reference a variable
    "agent.Person.age",         // Reference an agent attribute
    5                           // Or use a literal
  ]
}

Testing

The test suite includes 17 comprehensive tests organized into 3 categories:

• ✅ Basic tests (6) - Core validation functionality including library compatibility
• ✅ Reference validation (4) - Source names, scheduler references, formatting
• ✅ Advanced tests (7) - Optional parameters, edge cases, type checking
• ✅ SIR example validation - Complete epidemiological model
• ✅ Combined multi-error test - 15+ error types detected simultaneously

Run all tests:

cd tests && python3 test_validator.py

Expected output: 17/17 tests passed

Future Enhancements

• Mesa code generation pipeline
• Additional visualization support
• Network topology validation
• Spatial grid validation
• Parameter sweep support

Contributing

When making changes:

1. Update the schema in abm_json_schema.py
2. Update test cases as needed
3. Run the full test suite
4. Update documentation

License

[Your License Here]

Authors

[Your Name/Team]

Acknowledgments

Built with Pydantic for robust validation and type safety.