app/docs/superpowers/specs/2026-06-08-ai-assistant-phase1-design.md

Design — AI assistant, Phase 1 (chat + invoice import + budget cap)

Date: 2026-06-08 Status: Approved (brainstorming) — ready for implementation plan Phase 1 of 2. Phase 2 (the AI querying system data via read-tools) is a separate later cycle — see "Deferred: Phase 2" at the end.

---

Goal

Add the app's first AI capability: an admin-only chat assistant embedded on the dashboard where you can talk to Claude and, crucially, attach received-invoice PDFs that the AI reads and imports into Přijaté faktury (extract → you confirm → save). All AI usage is bounded by an admin-editable monthly budget (default $50) that hard-stops calls when exhausted.

Decisions (locked in brainstorming)

• Scope (Phase 1): chat + invoice import + budget cap. No system-data access (the AI cannot query your invoices/projects/attendance — that's Phase 2).
• Placement: a DashAssistant widget on the dashboard, at the top under the welcome text — not a separate page, not a floating bubble.
• Access: admins only, via a new ai.use permission.
• Model: Claude Sonnet 4.6 (strong vision, low cost).
• Save flow: extract → you confirm/edit → save (never silent auto-save).
• Budget: $50/month, resets each calendar month, admin-editable in Settings; AI calls are blocked once the month's spend reaches the budget.
• Chat: non-streaming (request → full reply) and in-browser history only (not persisted server-side) for v1 — both are easy later upgrades.

Non-goals / out of scope (Phase 1)

• No system-data query tools / function-calling (Phase 2).
• No server-side conversation persistence, no streaming.
• No new invoice storage path — reuses POST /received-invoices verbatim.

---

Architecture

Greenfield AI integration; the rest of the app is unaffected and works unchanged if ANTHROPIC_API_KEY is absent (the assistant widget simply doesn't render and the AI routes return a clear "not configured" error).

• Dependency: @anthropic-ai/sdk.
• Env: ANTHROPIC_API_KEY (required for the feature). Optional AI_MONTHLY_BUDGET_USD default seed (the live value lives in the DB, below).
• src/services/ai.service.ts — wraps the SDK, owns the model choice + system prompt + cost accounting. Two operations:
  • chat(messages) → client.messages.create({ model: "claude-sonnet-4-6", … }), non-streaming, returns { reply: string, usage }.
  • extractInvoice(pdfBuffer, fileName) → client.messages.create with the PDF as a document content block + output_config.format JSON-schema for the received-invoice fields, returns { fields, usage }.
  • Both call the spend tracker to record usage and are gated by the budget guard (below) BEFORE the API call.
  • Isolated so tests can stub the Anthropic call (no real API in CI).

Spend cap (the $50/month budget)

• New table ai_usage (migration): id, user_id?, kind ("chat" | "extract"), model, input_tokens, output_tokens, cost_usd @db.Decimal(10,6), created_at @db.Timestamp(0), with an index on created_at.
• Cost map (in ai.service.ts): model → { inputPerToken, outputPerToken }. Sonnet 4.6 = $3 / $15 per 1M → 0.000003 / 0.000015 per token. cost_usd = in*inP + out*outP.
• Budget value: a new ai_monthly_budget_usd Decimal @default(50) column on company_settings (the existing app-config singleton). Admin-editable in Settings.
• Budget guard assertBudgetAvailable(): sum cost_usd for rows where created_at >= startOfMonth(now); if >= ai_monthly_budget_usd, return { error: "Měsíční rozpočet AI byl vyčerpán", status: 402 }. Called at the top of every AI route BEFORE the Claude call.
• Usage read: GET /api/admin/ai/usage → { month_spend_usd, budget_usd, remaining_usd } for the chat's budget indicator and the Settings page.

Backend routes — src/routes/admin/ai.ts

All guarded by requirePermission("ai.use").

• POST /api/admin/ai/chat — body { messages: {role, content}[] }. Budget guard → ai.service.chat → log usage → success(reply: string, remaining_usd).
• POST /api/admin/ai/extract-invoices — multipart PDF files (≤ MAX_UPLOAD_SIZE, PDF/image only). Budget guard → extractInvoice per file → returns the extracted fields per file (NOT saved) + usage. The files are not persisted here.
• GET /api/admin/ai/usage — current-month spend + budget + remaining.

If ANTHROPIC_API_KEY is unset, the POST routes return { error: "AI není nakonfigurováno", status: 503 }.

Invoice import flow (extract → confirm → save)

1. Admin attaches one or more invoice PDFs in the dashboard chat (optionally with a text note).
2. Frontend posts the files to POST /ai/extract-invoices; the AI returns the extracted fields for each.
3. The chat renders an editable review card per invoice (dodavatel, číslo faktury, částka, měna, sazba DPH, datum vystavení/splatnosti, poznámka), pre-filled with the AI's values, plus a duplicate hint if invoice_number + supplier_name already exists.
4. Admin glances/edits → "Uložit" (per card) or "Uložit vše".
5. The frontend submits the original File + the confirmed metadata to the existing POST /api/admin/received-invoices (multipart) — same NAS storage, same server-side VAT recompute, same audit. The AI never writes invoices directly. (The PDF is uploaded twice — once to extract, once to save — which is fine for invoice-sized files and avoids any server-side temp-file handling.)

Frontend

• src/admin/components/dashboard/DashAssistant.tsx — the chat widget: message list, input box, attach-file button, and a small budget indicator ("Rozpočet: $X.XX / $50"). Non-streaming; conversation in component state only. Renders the invoice review cards inline (reusing the received-invoice field inputs / kit components).
• src/admin/pages/Dashboard.tsx — render <DashAssistant /> at the top, directly under the welcome text, only when the user is admin / has ai.use (and only when AI is configured — a GET /ai/usage 503 hides it gracefully).
• src/admin/lib/queries/ai.ts — React Query options/mutations for chat, extract, and usage. On a successful invoice save, invalidate ["received-invoices"].
• Settings — an admin field to set the monthly budget (writes company_settings.ai_monthly_budget_usd).

Permissions & migration

One Prisma migration:

• Create ai_usage table.
• Add ai_monthly_budget_usd to company_settings (default 50).
• Insert the ai.use permission and grant it to the admin role (explicit INSERTs in migration.sql, per the project's migration policy).

(The admin role bypasses permission checks via roleName === "admin", but the explicit ai.use permission lets the access be widened later without code changes and documents intent.)

Security / privacy

• Phase 1 has no tools, so the AI cannot take actions on your data — its only effect is the human-confirmed invoice save. A malicious/auto-generated invoice PDF therefore can't trigger anything (the injection-to-action surface arrives in Phase 2 and is designed there).
• Attached PDFs are sent to the Anthropic API to be read. The API key lives in .env (server-side only), never exposed to the browser.
• Standard sanitization already applies on the received-invoice render/PDF paths; AI-extracted text flows through the same validated received_invoices create.

Testing

Server-side, real test DB, Anthropic call stubbed (no real API in CI):

• Spend tracker: cost_usd computed correctly from tokens for Sonnet 4.6; monthly sum only counts the current month.
• Budget guard: under budget → allowed; at/over budget → 402 with the Czech message; the guard reads the DB budget value.
• Permissions: all /ai/* routes return 403 without ai.use.
• Not-configured: with no ANTHROPIC_API_KEY, POST routes return 503.
• extract field-mapping: given a stubbed AI response, the route returns the expected received_invoices field shape (and computes nothing that the existing create doesn't already).

Frontend has no component-test harness → gated by tsc -b + build + a manual check (the dashboard widget renders for admins, hidden otherwise).

Gates: npx tsc -b --noEmit, npm run build, npx vitest run.

Rollout

Ships as v2.1.0 (notable new capability) via the standard process. Requires a migration, so the dev server must be stopped for prisma migrate dev (ask first), and the release runs prisma migrate deploy on prod. ANTHROPIC_API_KEY must be set in the production .env before the feature works.

---

Deferred: Phase 2 (system-data access) — captured

A later, separate spec + cycle. The AI gains read-only tools (function calling) to answer questions about your data — e.g. "co je po splatnosti?", "kolik jsme fakturovali v květnu?". Key design work for Phase 2:

• A curated set of read tools (search invoices, overdue list, project lookup, attendance summary, …), each scoped to the calling user's permissions so the AI never returns data the user can't see.
• The agentic tool-loop (Claude requests a tool → app executes against Prisma → returns results → Claude continues), with a per-conversation tool-call cap to bound cost (within the same monthly budget).
• Prompt-injection hardening: because the AI will both read untrusted invoice content and hold tools, tools stay read-only, results are treated as data, and any state-changing action remains human-confirmed.