# 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;"