Appendix B: Settings Reference

The settings.json file controls all framework-level configuration. It is loaded by ABMSettings.from_file() and injected into the runtime by ABMRuntime. All fields have sensible defaults; an empty {} produces a working local-mode configuration.

Complete Schema

{
  "orchestration": {
    "mode": "local",
    "max_workers": 4,
    "async_semaphore_limit": 128,
    "pregel_mode": false,
    "mcp_config": {
      "endpoints": {},
      "a2a_protocol": "http",
      "timeout_seconds": 30.0,
      "retry_count": 3,
      "partition_strategy": "type_based",
      "manual_partition": null,
      "emulate_locally": true
    }
  },
  "output": {
    "dir": "output/",
    "levels": ["model", "agent_group"],
    "format": "csv.gz",
    "plots": true,
    "plot_style": "seaborn",
    "plot_dpi": 200,
    "agent_sample_rate": 1.0
  },
  "llm": {
    "default_model": "claude-sonnet-4-6",
    "default_max_tokens": 200,
    "default_temperature": 0.0,
    "cache_identical_prompts": true,
    "cost_budget_per_step": 0.01,
    "cost_budget_total": 10.0,
    "api_key_env": "ANTHROPIC_API_KEY",
    "agent_overrides": {},
    "cache": {
      "enabled": false,
      "backend": "memory",
      "path": ".cache/llm_responses.db"
    }
  },
  "logging": {
    "level": "INFO",
    "log_llm_calls": true,
    "log_messages": false,
    "log_state_changes": false
  },
  "mc": {
    "default_seeds": 100,
    "default_steps": 100,
    "default_burn_in": 10,
    "parallel_seeds": true,
    "max_workers": 0,
    "batch_size": 0,
    "global_seed": 42
  },
  "checkpoint": {
    "enabled": false,
    "interval": 0,
    "directory": "checkpoints/",
    "max_kept": 5
  },
  "telemetry": {
    "otel_enabled": false,
    "service_name": "abm-lab",
    "endpoint": "http://localhost:4317",
    "export_protocol": "grpc",
    "export_interval_ms": 60000,
    "trace_sample_rate": 1.0,
    "trace_llm_calls": true,
    "trace_messages": false,
    "trace_actions": true,
    "collect_agent_counts": true,
    "collect_message_counts": true,
    "collect_step_timing": true,
    "collect_llm_metrics": true
  },
  "api": {
    "host": "0.0.0.0",
    "port": 8000,
    "cors_origins": ["*"]
  }
}

Field Descriptions

orchestration

Controls the execution backend and distributed computation.

Field	Type	Default	Description
mode	str	"local"	Backend selection: "local", "threaded", "multiprocess", "async", "mcp", "dask"
max_workers	int	4	Thread/process count for parallel backends. 0 = auto-detect CPU count.
async_semaphore_limit	int	128	Maximum concurrent LLM calls in async mode. Prevents API rate limiting.
pregel_mode	bool	false	Enable Pregel BSP execution with vote-to-halt convergence.
mcp_config.endpoints	Dict	{}	Map of partition index to MCP server URL for distributed mode.
mcp_config.a2a_protocol	str	"http"	Transport for agent-to-agent cross-partition messages.
mcp_config.timeout_seconds	float	30.0	HTTP timeout for cross-partition calls.
mcp_config.retry_count	int	3	Retry count for failed cross-partition calls.
mcp_config.partition_strategy	str	"type_based"	Partition strategy: "type_based", "topology_aware", "manual".
mcp_config.emulate_locally	bool	true	Run distributed mode in-process for testing.

output

Controls the SimulationRecorder and output formatting.

Field	Type	Default	Description
dir	str	"output/"	Output directory for CSV, plots, and recordings.
levels	List[str]	["model", "agent_group"]	Recording levels: "model", "agent_group", "agent", "environment".
format	str	"csv.gz"	Output format: "csv", "csv.gz", "parquet", "json".
plots	bool	true	Generate PNG time series plots automatically.
plot_style	str	"seaborn"	Matplotlib style for plots.
plot_dpi	int	200	Plot resolution in dots per inch.
agent_sample_rate	float	1.0	Fraction of agents to record at AGENT level. 1.0 = all, 0.1 = 10% sample.

llm

Controls LLM agent configuration and cost management.

Field	Type	Default	Description
default_model	str	"claude-sonnet-4-6"	Default LLM model identifier for all LLMAgent/HybridAgent instances.
default_max_tokens	int	200	Maximum response tokens.
default_temperature	float	0.0	Sampling temperature. 0.0 = deterministic (for reproducibility).
cache_identical_prompts	bool	true	Enable ResponseCache for deterministic LLM replay.
cost_budget_per_step	float	0.01	Maximum USD spend per simulation step.
cost_budget_total	float	10.0	Maximum USD spend for entire simulation.
api_key_env	str	"ANTHROPIC_API_KEY"	Environment variable containing the API key.
agent_overrides	Dict	{}	Per-agent-type LLM config overrides (e.g., different model for specific types).
cache.enabled	bool	false	Enable persistent response cache.
cache.backend	str	"memory"	Cache backend: "memory" (in-process) or "sqlite" (persistent).
cache.path	str	".cache/llm_responses.db"	SQLite database path for persistent cache.

logging

Controls structured logging output.

Field	Type	Default	Description
level	str	"INFO"	Log level: "DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL".
log_llm_calls	bool	true	Log every LLM API call (prompt, response, cost, latency).
log_messages	bool	false	Log every agent-to-agent message send/receive. High volume.
log_state_changes	bool	false	Log every agent state field change. Very high volume.

mc

Controls Monte Carlo evaluation defaults (used by MCRunner and CLI evaluate).

Field	Type	Default	Description
default_seeds	int	100	Default number of independent seeds per MC evaluation.
default_steps	int	100	Default steps per seed.
default_burn_in	int	10	Steps to discard as burn-in before recording.
parallel_seeds	bool	true	Run seeds in parallel (using process pool).
max_workers	int	0	Workers for parallel MC. 0 = auto-detect CPU count.
batch_size	int	0	Batch size for distributed MC. 0 = all seeds in one batch.
global_seed	int	42	Global seed for the SeedManager hierarchy.

checkpoint

Controls automatic state checkpointing.

Field	Type	Default	Description
enabled	bool	false	Enable checkpointing.
interval	int	0	Auto-checkpoint every N steps. 0 = disabled (manual only).
directory	str	"checkpoints/"	Directory for checkpoint files.
max_kept	int	5	Maximum checkpoints to retain. Oldest deleted when exceeded. 0 = unlimited.

telemetry

Controls OpenTelemetry distributed tracing and metrics.

Field	Type	Default	Description
otel_enabled	bool	false	Enable OpenTelemetry instrumentation.
service_name	str	"abm-lab"	Service name for traces and metrics.
endpoint	str	"http://localhost:4317"	OTLP collector endpoint.
export_protocol	str	"grpc"	Export protocol: "grpc", "http", "console".
export_interval_ms	int	60000	Metric export interval in milliseconds.
trace_sample_rate	float	1.0	Trace sampling rate (0.0 = none, 1.0 = all).
trace_llm_calls	bool	true	Create spans for LLM API calls.
trace_messages	bool	false	Create spans for message sends. High volume.
trace_actions	bool	true	Create spans for action executions.
collect_agent_counts	bool	true	Emit agent count gauge metric.
collect_message_counts	bool	true	Emit message count metric.
collect_step_timing	bool	true	Emit step duration histogram.
collect_llm_metrics	bool	true	Emit LLM call count, latency, and cost metrics.

api

Controls the FastAPI REST server.

Field	Type	Default	Description
host	str	"0.0.0.0"	Server bind address.
port	int	8000	Server port.
cors_origins	List[str]	["*"]	CORS allowed origins. Restrict in production.