Cayce Ops

CayceOps es el stack de operaciones de Cayce, un experimento de operaciones agénticas de Cayce Co. Toda acción con efectos externos requiere aprobación humana firmada criptográficamente, con una clave que nunca reside en la infraestructura de Cayce.

Cayce operates bitcoinhotels.org (Bitcoin-native travel guides) and hardcap.news (Bitcoin security intelligence).

Five decoupled components share one Postgres database. Each is a CLI command, driven by cron/systemd timers. Nothing runs without an audit trail.

Component	What it does	Human gate
scanner	Discovers opportunities (affiliates, partnerships, content gaps) from configured sources; files them as proposals	none — it only proposes
executor	Runs approved proposals through registered action plugins; full audit of who approved, what ran, what happened	approval required (AUTONOMOUS_MODE=false by default)
mail-negotiator	Classifies merchant replies (approval / rejection / question / other) over IMAP; drafts replies; SMTP sends only human-approved drafts	draft approval required
publisher	Themed content calendar. Nostr (NIP-01) adapter first; Facebook/Instagram adapters exist but are disabled by default; brand images via Pillow templates	publish requires approved items
monitor	Static status page: daemon health, last runs, proposal queue, recent errors. No sensitive data	none — read-only

State machines:

proposal: proposed -> approved -> running -> done | failed
mail:     inbound classified; draft: none -> drafted -> approved -> sent
content:  draft -> approved -> published

Quickstart (local)

uv sync --frozen            # installs Python 3.12 + locked deps
cp .env.example .env        # fill in; values are placeholders
docker compose up -d db     # Postgres 16
uv run alembic upgrade head
uv run cayceops scanner run
uv run pytest

docker compose up (everything) runs all five daemons in loops; on a VPS use deploy/systemd instead.

Layout

cayceops/            the package
  config.py          env-var config (CAYCE_OPS_*), no config files
  db.py              engine/session/upgrade helpers
  models.py          ORM schema + state machines + audit helper
  llm.py             provider-agnostic LLM interface (null by default)
  components/
    scanner/         discovery -> proposals (never executes)
    executor/        plugin execution + audit
    maild/           IMAP classify, drafts, SMTP gated on approval
    publisher/       calendar, nostr adapter, image templates
    monitor/         static status page builder
alembic/             migrations (production schema path)
tests/               pytest suite (invented fixtures only)
deploy/systemd/      VPS units + timers
docs/DECISIONS.md    architectural decisions and their costs

Security posture

• Config exclusively via env vars; .env is gitignored, .env.example holds placeholders.
• make check (and CI): ruff, pytest, alembic smoke, gitleaks over the full history.
• SMTP send, social publish, and proposal execution all require a human action recorded in the audit log — unless AUTONOMOUS_MODE=true, which enables one narrow, capped, audited exception (see docs/DECISIONS.md D5).

License

MIT — see LICENSE.