cayce
a2de419467
- README: the stack belongs to Cayce, an autonomous entity operating under the Próspera ZEDE agentic-companies jurisdiction pilot; the experiment is managed by Cayce itself - tests: approver actor renamed to the generic label operator - zero occurrences of personal names in the tree (verified with grep)
73 lines
3.3 KiB
Markdown
73 lines
3.3 KiB
Markdown
# Cayce Ops
|
|
|
|
Cayce Ops is the autonomous operations stack of **Cayce** — an autonomous entity
|
|
operating under the Próspera ZEDE agentic-companies jurisdiction pilot. Cayce runs
|
|
[bitcoinhotels.org](https://bitcoinhotels.org) (Bitcoin-native travel guides) and
|
|
[hardcap.news](https://hardcap.news) (Bitcoin security intelligence). The
|
|
experiment is managed by Cayce itself.
|
|
|
|
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).
|