# 24/7 Agent Farm Uptime Simulator

## PURPOSE
A SimPy + NumPy discrete-event simulation of the always-on agent farm the video describes on a Hostinger VPS. It models tasks arriving from several agents — a stock-trading bot, an Instagram-reels/carousel bot, a research digest, an inbox triage routine — that run "24/7 even if the laptop is closed," and measures throughput, queue latency, and how hard the box is actually working.

## WHY THIS MATTERS
Nateherk calls the VPS "probably the most boring tool on the list, but it's where a lot of my stuff actually lives," and mentions Hermes and OpenClaw agents plus the fear of "something shutting down while I sleep." This simulation lets students reason about capacity and reliability BEFORE renting a server: how many agents fit on two CPUs, and what happens to latency when the box saturates.

## HOW TO BUILD
1. `pip install simpy numpy`.
2. Model agents as SimPy processes that periodically generate tasks.
3. Add a shared `simpy.Resource(env, capacity=N_CPU)` so tasks contend for CPU like co-hosted agents really do.
4. Draw service times from a seeded NumPy RNG so runs are deterministic and comparable.
5. Track wait and turnaround, then summarize utilization and p95 latency.

Key snippet:
```python
cpu = simpy.Resource(env, capacity=cpus)
def agent(env, spec, cpu, stats):
    while True:
        yield env.timeout(spec.interval_min)
        env.process(task(env, spec, cpu, stats))
```

## WHEN TO USE IN PRODUCTION
Use it to size a VPS before paying for one, to justify adding a second worker, or to model an always-on vs scheduled-routine tradeoff. Do NOT use it when the workload is dominated by external API latency rather than local CPU, or when you already have real production telemetry — observability beats simulation there.

## HOW IT HELPS STUDENTS
Students learn discrete-event modeling, resource contention, and the utilization-vs-latency law (why running ten agents at 100% CPU destroys responsiveness) — core SRE reasoning every automation builder needs.

## STARTER CODE
`starter/main.py` contains a seeded, runnable simulation with `# TODO` markers for failure modeling and cost-per-run reporting.
