41 lines
1.4 KiB
Markdown
41 lines
1.4 KiB
Markdown
# 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;"
|