feat(agent): containerize agent and wire into compose stack

2026-08-23 17:24:06 -05:00
parent 01a9eef06c
commit 9adec1028c
6 changed files with 80 additions and 0 deletions
@@ -0,0 +1,40 @@
+# firefly-agent
+
+Worker container for the personal accounting agent. See the architecture spec:
+`docs/superpowers/specs/2026-08-23-accounting-agent-architecture-design.md`.
+
+## What it does (Phase 1)
+
+On startup: creates `agentdb` in the stack's Postgres if missing, applies SQL
+migrations from `src/agent/migrations/`, runs one heartbeat, then schedules the
+heartbeat every `HEARTBEAT_INTERVAL_MINUTES`. The heartbeat calls Firefly's
+`/api/v1/about` and records the outcome in `sync_runs`.
+
+## Development
+
+    python3 -m venv .venv && source .venv/bin/activate
+    pip install -e './agent[dev]'
+    cd agent && pytest          # needs Docker running (testcontainers)
+
+## Configuration
+
+All via environment variables (see `.env.example`, "Accounting Agent" section):
+`FIREFLY_API_URL`, `AGENT_FIREFLY_TOKEN` (required), `AGENT_DB_NAME`,
+`HEARTBEAT_INTERVAL_MINUTES`, plus the existing `DB_HOST`/`DB_PORT`/
+`POSTGRES_USER`/`POSTGRES_PASSWORD`.
+
+## Deploy & verify
+
+    # on the host, in the repo directory
+    git pull
+    docker compose build agent
+    docker compose up -d agent
+    docker compose exec agent python -m agent.verify
+
+Expected verify output: agentdb OK with migrations applied, recent heartbeat
+runs, Firefly version, and your asset accounts listed.
+
+Inspect heartbeats directly:
+
+    docker compose exec db psql -U firefly -d agentdb \
+      -c "SELECT connector, status, finished_at FROM sync_runs ORDER BY id DESC LIMIT 5;"