athena-oracle/docs/Deployment-Plan.md

Deployment Plan — Athena MVP

Prerequisites

• Docker installed on the target host
• Network access to the 6 source APIs/feeds (arxiv, github, huggingface, hackernews, reddit, rss_feeds)
• GITHUB_TOKEN available as an environment variable (optional, but raises the GitHub rate limit from 60/hr to 5000/hr)
• HUGGINGFACE_TOKEN available as an environment variable
• A local Ollama instance running llama3.2:1b, or an alternate reachable inference backend if swapping — per the model-agnostic summarize(text) -> (summary, model) contract
• Hermes cron infrastructure available and able to invoke oracle-pipeline.sh

Setup

1. Clone main (not a milestone branch) onto the target host
2. pip install -r requirements.txt if present; otherwise confirm stdlib + requests are available
3. Run schema.sql against a fresh oracle.db — this file is git-ignored and created locally, never committed
4. Export required environment variables (GITHUB_TOKEN, HUGGINGFACE_TOKEN) — never hardcode these
5. Build and run inside Docker with the 150MB memory cap and non-root user enforced, per the PRD platform requirements
6. Manual smoke test: run python3 pipeline.py once and confirm ingest → store → summarize → score completes without errors before handing off to cron

Cron / Scheduling

1. Confirm oracle-pipeline.sh is the entry point Hermes cron calls
2. Schedule for 13:00 UTC daily
3. Add a lock file or PID check so overlapping runs can't happen if a prior run is still in progress
4. Confirm the cron environment actually carries the exported tokens — cron environments are frequently minimal and won't inherit an interactive shell's exports

Hermes Integration

1. Confirm the wrapper script's exit codes are meaningful (0 = success, non-zero = failure) so Hermes can act on them
2. Define where Hermes should look for pipeline output/logs
3. Decide on a failure-notification path (Hermes alert, log flag, etc.) — not yet specified, needs a decision

Monitoring

1. Aggregate logs from each pipeline stage (ingest, store, summarize, score)
2. Track theme-scan new-arrival counts per cycle per theme — this is the core signal the falsification logic depends on, so it deserves visibility beyond raw logs
3. Add a heartbeat/dead-man's-switch alert if a scheduled run doesn't fire, rather than relying on someone noticing missing data days later
4. Watch memory usage against the 150MB cap under real production load, not just dev conditions

Rollback

1. Back up oracle.db before any schema change — it's git-ignored and not recoverable from the repo itself
2. If a bad deploy breaks the pipeline, revert to the last known-good commit on main and redeploy the Docker image
3. Check falsification state (new-arrivals counters) after any rollback — rolling back mid-window could distort the 7-day dead-thesis calculation if not handled carefully

---

Draft prepared by Claude from the README, whitepaper falsification logic, and MVP-PRD platform requirements on main. The Hermes failure-notification path is the one open decision blocking this from being final.