Implement API usage logging and the cost tracking dashboard #44

New issue

Open

opened 2026-07-28 04:59:54 +00:00 by claude-bot · 0 comments

claude-bot commented

2026-07-28 04:59:54 +00:00

Context

AI analysis costs money per photo, and a large family collection means a lot of photos.
The spec includes an APIUsageLog and calls for dashboard cost tracking with limit
warnings. Discovering the cost after the fact is the problem this prevents.

Scope

API usage logging and a cost dashboard with budget warnings.

Implementation notes

Implement APIUsageLog per the spec's data model â€” this table does not exist yet and
needs a migration.
Record per-call model, token counts, computed cost, timestamp, and the photo and job
it belonged to.
Dashboard: spend over time, spend by model, cost per photo, and projected cost to
finish the remaining unanalyzed collection. The projection is the genuinely useful
number â€” it answers "what will finishing this cost me?" before the money is spent.
Warn as configured limits are approached, not only when they are hit. A warning that
arrives at 100% of budget arrives too late to act on.
Reconcile against the budget enforcement built with the AI handler in v0.2.0 so the
dashboard and the enforcement path read the same numbers.
Local AI backends contribute time rather than cost; represent that honestly instead of
showing a misleading zero.
Historical retention so month-over-month spend stays visible.

Done when

APIUsageLog exists and records every AI call with token counts and cost
The dashboard shows spend over time and cost per photo
Projected cost to complete the collection is shown
Warnings fire before limits are reached
Dashboard figures agree with the enforcement path

References

docs/circa-spec.md section 8 (APIUsageLog), Phase 4
Cost controls from #3

Depends on: #3 (AI analysis job handler).

## Context AI analysis costs money per photo, and a large family collection means a lot of photos. The spec includes an `APIUsageLog` and calls for dashboard cost tracking with limit warnings. Discovering the cost after the fact is the problem this prevents. ## Scope API usage logging and a cost dashboard with budget warnings. ## Implementation notes - Implement `APIUsageLog` per the spec's data model â€” this table does not exist yet and needs a migration. - Record per-call model, token counts, computed cost, timestamp, and the photo and job it belonged to. - Dashboard: spend over time, spend by model, cost per photo, and projected cost to finish the remaining unanalyzed collection. The projection is the genuinely useful number â€” it answers "what will finishing this cost me?" before the money is spent. - Warn as configured limits are approached, not only when they are hit. A warning that arrives at 100% of budget arrives too late to act on. - Reconcile against the budget enforcement built with the AI handler in v0.2.0 so the dashboard and the enforcement path read the same numbers. - Local AI backends contribute time rather than cost; represent that honestly instead of showing a misleading zero. - Historical retention so month-over-month spend stays visible. ## Done when - [ ] `APIUsageLog` exists and records every AI call with token counts and cost - [ ] The dashboard shows spend over time and cost per photo - [ ] Projected cost to complete the collection is shown - [ ] Warnings fire before limits are reached - [ ] Dashboard figures agree with the enforcement path ## References - `docs/circa-spec.md` section 8 (`APIUsageLog`), Phase 4 - Cost controls from #3 Depends on: #3 (AI analysis job handler).

claude-bot added this to the v0.6.0 milestone

2026-07-28 04:59:54 +00:00

claude-bot added the

frontend

backend

labels

2026-07-28 04:59:54 +00:00