# Public Code Bundle

This folder contains the minimal code used to explain the distributed simulation workflow.

No API keys are included. In actual runs, secrets are loaded from environment variables or from a user-local file such as `~/.aisim_simulation_env`, which must stay outside the repository.

## Files

- `run_simulation_batch_v1.py`  
  Runs one JSONL shard against an OpenAI-compatible chat completion API. It validates model output and writes JSONL records.

- `start_simulation_worker_v1.sh`  
  Starts one worker process with a fixed input shard, output file, report file, and cache directory.

- `supervise_generic_simulation_workers_v1.py`  
  Monitors worker PID/log/output/report state and restarts stopped or stale workers.

- `merge_simulation_shards_v1.py`  
  Merges worker outputs and produces a validation report.

- `build_pending_shards_example.py`  
  Example script for building non-overlapping pending shards after excluding already completed persona-report pairs.

- `simulation_output_schema_v1_1.json`  
  JSON Schema for large-scale standard simulation outputs.

## Secret Handling

Expected environment variables:

```sh
export LLM_BASE_URL="https://ollama.com/v1"
export LLM_MODEL="deepseek-v4-flash"
export LLM_API_KEY_ENV="OLLAMA_CLOUD_API_KEY"
export OLLAMA_CLOUD_API_KEY="..."
```

Do not commit the API key or `.aisim_simulation_env`.

## Minimal Run Example

```sh
python3 run_simulation_batch_v1.py \
  --simulation-run-id example_run \
  --input data/simulations/shards/example_run/worker-a-01.jsonl \
  --output data/simulations/runs/example_run/worker-a-01.outputs.jsonl \
  --report data/simulations/runs/example_run/worker-a-01.report.json \
  --cache-dir data/cache/simulation_runs/example_run/worker-a-01
```

## Recovery Principle

Always restart with the same:

- input shard
- output JSONL
- report JSON
- cache directory

This makes the run resumable and avoids regenerating completed rows.