# Muse Agency Arbitrage Simulator

## PURPOSE
Models a MetaMuse-powered local-services agency — night nurses in Montreal, plumbers in Phoenix — as a discrete-event queue. Demand (parents posting "need a night nurse") and supply (providers mined from Facebook groups) arrive as Poisson processes; a Muse agent cleans and matches them, and the simulation reports fill rate, success-fee revenue and margin versus a five-person human agency.

## WHY THIS MATTERS
The video contrasts the old model — "a team of five people going and doing all this stuff" that "might have cost you thousands of dollars" — with an agent that "does the matching, the drafting DMs, the calls and texts and booking". Simulation is how you prove that cost structure works before spending a dollar, tying directly to the "one niche, one city, one workflow" framing Greg Isenberg lays out.

## HOW TO BUILD
1. Model arrivals with SimPy stores: demand events and supply events.
2. Give the agent a `match_time` drawn from an exponential distribution.
3. Track bookings, drops, queue length and agent busy time in a metrics dict.
4. Use NumPy seeded random draws so runs are reproducible.
5. Report revenue = bookings x success fee, plus agent utilisation.

```python
def muse_agent(env, demand, supply, m, fee=300.0):
    while True:
        need = yield demand.get()
        prov = yield supply.get()
        yield env.timeout(np.random.exponential(m["match_time"]))
        if prov["hourly_rate"] <= need["budget"]:
            m["bookings"] += 1
            m["revenue"] += fee
```

## WHEN TO USE IN PRODUCTION
Use it to size a niche-city before launching: how many leads per day justify the $100 Muse plan, when a second agent pays off, and how fill rate collapses if supply is thin. Do NOT use it to price a single client gig, nor as a substitute for real market tests — it is a planning tool, not a replacement for your first five paying customers.

## HOW IT HELPS STUDENTS
Students learn discrete-event simulation, Poisson arrivals and reproducible NumPy randomness — transferable to any capacity-planning problem, and a concrete way to reason about the margins the video hand-waves.

## STARTER CODE
`starter/main.py` builds the demand/supply processes, the `muse_agent` coroutine, a metrics collector and an argparse entry point, with `# TODO` markers for multi-worker, multi-city and agent-landline call scenarios.
