# 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](https://bitcoinhotels.org)
(Bitcoin-native travel guides) and [hardcap.news](https://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)

```bash
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](deploy/systemd/README.md) 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](docs/DECISIONS.md) D5).

## License

MIT — see [LICENSE](LICENSE).