docs/DEPLOY.md

Zero-cost deployment

Run a public forecast demo with no paid server and no paid LLM — using GitHub Actions + GitHub Pages. Optional: Groq free tier for higher-quality cycles.

---

Architecture

GitHub Actions (daily, free tier)
  ├─ restore data/forecaster.db (cache)
  ├─ python run.py once --config config.ci.yaml [--mock | Groq]
  ├─ write site/index.html + feed.json
  └─ deploy-pages → GitHub Pages (free)

Local config.yaml keeps require_review: true — only config.ci.yaml auto-publishes.

Layer	Cost	Role
GitHub Actions	Free (monthly minutes)	Daily forecast cycle
GitHub Pages	Free	Public static report
Groq API	Free tier (optional secret)	LLM when GROQ_API_KEY is set
Mock LLM	$0	Fallback when no secret (--mock)
arXiv / RSS / BLS seed	$0	Ingest + Job Radar empirical layer

Not recommended on zero-cost deploy: ANTHROPIC_API_KEY, TAVILY_API_KEY, public REST API, 24/7 Streamlit on Render free tier (cold starts, ephemeral disk).

---

One-time setup

1. Enable GitHub Pages

1. Repo → Settings → Pages
2. Build and deployment → Source: GitHub Actions

2. (Optional) Groq free tier

1. Create key at console.groq.com
2. Repo → Settings → Secrets and variables → Actions
3. New secret: GROQ_API_KEY

Without this secret, the workflow uses --mock (deterministic stub, still publishes).

3. Trigger first deploy

• Actions → Daily forecast and GitHub Pages → Run workflow

Or wait for the daily cron (06:00 UTC).

Your site URL: https://<user>.github.io/<repo>/ (or custom domain).

---

Config profiles

File	require_review	Use
config.yaml	true (default)	Local dev, human approve via run.py approve
config.ci.yaml	false	CI only — writes directly to site/

Never flip require_review to false in config.yaml unless you fully trust the loop.

# Local dry-run of CI profile
python run.py once --config config.ci.yaml --mock
open site/index.html

---

Environment variables

Copy .env.example → .env for local use:

cp .env.example .env

Variable	Zero-cost deploy
GROQ_API_KEY	Optional; set as GitHub secret for CI
FORECASTER_MOCK_LLM=1	Local fallback without key
FORECASTER_CONFIG	e.g. config.ci.yaml
ANTHROPIC_API_KEY	Skip on public demo
TAVILY_API_KEY / FRED_API_KEY	Skip on public demo

---

SQLite persistence in CI

The workflow caches data/forecaster.db between runs so Brier scores and open predictions accumulate. Cache is best-effort; GitHub may evict it after ~7 days of inactivity.

---

Optional: Streamlit demo (Hugging Face Spaces)

For interactive Job Radar (not the daily loop):

1. Create a Hugging Face Space (Streamlit)
2. Point at this repo; set GROQ_API_KEY in Space secrets
3. Start command: streamlit run dashboard.py
4. Keep LLM KB expansion rare (rate-limit in UI or disable) to stay within free tier

---

License note (BUSL-1.1)

Free public demo + donation is fine. Commercial hosting of the REST/MCP API as a paid product requires a separate commercial license (see README).

---

Troubleshooting

Issue	Fix
Pages shows 404	Enable Pages source = GitHub Actions; run workflow once
Empty scoreboard	Normal on first run; cache builds over days
Workflow uses mock	Add GROQ_API_KEY secret or accept stub output
pending/ fills locally	Expected with require_review: true; run python run.py approve