# Scheduled Bot Routine Orchestrator

## PURPOSE
A Flask + SQLAlchemy service that recreates the Grokbot workflow in the video: bots that "run on some sort of schedule or a webhook" and do repeatable jobs. It stores routines in a database, fires them on cron-like triggers with APScheduler, and calls external connectors over httpx. A `kind` flag separates deterministic jobs (the trigger.dev pattern) from agentic ones so simple syncs never burn an expensive agent loop.

## WHY THIS MATTERS
The transcript gives two concrete routines: after every Q&A call a bot "grabs the transcript, posts it in my community, and puts it in the classroom," and another posts to both communities whenever a new video drops. Nateherk also draws the line between automations that "do the same steps every time" and those needing a full agent harness — calling an agent for a simple document sync "overkill." This service teaches that distinction in real code.

## HOW TO BUILD
1. `pip install flask sqlalchemy apscheduler httpx`.
2. Define `Routine` (name, trigger, interval, kind, connector) and `Run` (status, detail, timestamp) models.
3. At startup, register every schedule-triggered routine with APScheduler.
4. `execute(routine)` calls each connector step via httpx and writes a `Run` row; deterministic jobs take a plain code path, agentic ones would call the gateway.
5. Expose `POST /hooks/<name>` for webhook-triggered runs and `GET /runs` for history.

Key snippet:
```python
def register_jobs():
    for r in Routine.query.filter_by(trigger="schedule").all():
        scheduler.add_job(execute, "interval", minutes=r.interval_min, args=[r], id=r.name)
```

## WHEN TO USE IN PRODUCTION
Use it for recurring transcript drops, syncing data between two tools, or posting announcements on a schedule. Do NOT use it for jobs needing multi-step judgment or browsing — route those to an agent; and skip it for sub-second, high-frequency work where a plain cron + script is simpler.

## HOW IT HELPS STUDENTS
Students learn ORM modeling, background scheduling, webhook design, idempotency, and the deterministic-vs-agent decision that underpins any real automation business.

## STARTER CODE
`starter/main.py` ships the models, scheduler wiring, the two routines from the video, and a stubbed connector with `# TODO` markers.
