Urban Observation Simulator

This repository creates synthetic multimodal incident data. It is standalone: it does not need the Urban Observations collector or any collected data.

It has no Docker containers. Generation is one host-side Python command after setup. A first installation uses the six setup commands below; a routine run is one command (python -m simulator.simulator).

Setup

python3.10 -m venv .venv
. .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .
cp config.example.json config.json
chmod 600 config.json

Edit config.json and set:

• openai.api: OpenAI API key used to plan and generate synthetic records.
• google_places_key.key: Google Maps key used to resolve incident locations.
• google.api: Google AI Studio API key used for Google image editing. This is only required when simulation.simulate_images is true.

config.json, generated datasets, caches, and virtual environments are ignored by Git.

Setting	Meaning	Required change?
paths.simulator_output_root	Parent directory for generated batches.	Safe default provided
simulation.incident_types	Incident types to generate.	Choose for the experiment
simulation.runs_per_incident	Independent runs per type.	Safe default provided
simulation.max_iterations	Simulated time steps per run.	Safe default provided
simulation.sources	Modalities to generate; omit to let planning choose.	Safe default provided
simulation.simulate_images	Enable reference-based image editing.	Optional; defaults off
openai.api, openai.model	Planning and synthetic record generation.	API key required
google_places_key.key	Resolve incident locations.	Required for location lookup
google.api	Google AI Studio image-editing key.	Only when images are enabled

The checked-in example uses non-secret placeholders and safe small-run defaults.

The repository includes a roughly 6 MiB snapshot of 300 daytime camera images, so it never needs access to the real collection machine. Google image editing uses a reference image from that snapshot and may require billing to be enabled for the selected model.

Choose what to generate

The normal batch is controlled by one section:

{
  "simulation": {
    "incident_types": ["wildfire"],
    "runs_per_incident": 1,
    "max_iterations": 1,
    "output_folder": "batch_incident_runs",
    "sources": ["weather", "news"],
    "simulate_images": false
  }
}

• incident_types selects what to simulate.
• runs_per_incident selects how many independent runs to create for each type.
• max_iterations selects the number of simulated time steps in each run.
• sources fixes the modalities. Remove it to let the model choose them.
• Keep simulate_images false unless the Google AI Studio key is configured.
• Leave fast_mode true for the normal standalone workflow.

Run

Preview the configured batch without API calls or file writes:

python -m simulator.simulator --dry-run

Generate it:

python -m simulator.simulator

CLI options can temporarily override the config. For example:

python -m simulator.simulator \
  --incident-types wildfire urban_fire \
  --runs-per-incident 5 --max-iterations 3

Output is written below paths.simulator_output_root:

batch_incident_runs/
├── batch_run_schedule.json
└── wildfire1/
    ├── observations.txt
    ├── *_plan.json
    ├── *_gt_*.json
    └── generated text, image, and time-series files

A nonzero exit status means at least one requested run failed.

Replay completed data

Replay is provided by the separate urban-observation-processing repository. From that repository, run:

python -m replay.synthetic /path/to/batch_incident_runs

Replay discovers the completed runs and sends them through the common observation pipeline. It does not generate new incidents.