AI Assistant

Overview

The AI Assistant acts as an in-product operator workspace for the shopkeeper. It can answer business questions, stream summaries back into the dashboard, prepare reviewable AI action cards, and turn uploaded files into structured review drafts.

Why it exists

Shopkeepers should not have to jump across multiple pages just to answer questions like "What were my sales this week?" or "Who still owes me money?". The assistant compresses those steps into a single conversational surface while still keeping write actions explicit and reviewable.

User flow

  1. User clicks the AI Chat bubble located globally in the bottom right corner of the dashboard.
  2. The assistant panel warms bootstrap state, including entitlements, AI control, prompt inputs, and recent history.
  3. The user asks a question such as Show me how much receivable I have.
  4. The server records a routing label from classifyFastPath() (for telemetry only) and always streams through the tool-assisted path: the model may call read tools and emit *_suggestion cards; greetings and small talk use the same path with tools available but usually unused.
  5. The response is streamed back to the panel as NDJSON events, and pending action cards are refreshed if a mutation suggestion was created.

UI walkthrough

![AI Chat Sidebar](../../assets/images/ai/chat.png) ![AI OCR Import Status](../../assets/images/ai/ocr-status.png)

Backend logic

Bambu uses the Vercel AI SDK with a stricter routing and tool runtime layer.

  1. The panel sends requests to app/api/ai/route.ts.
  2. Messages are sanitized and checked against quota and policy.
  3. classifyFastPath() labels the request (mutation vs business-data vs small talk) for logs; execution is always tool-assisted.
  4. Tool-assisted requests use the tool registry in lib/ai/tools/registry.ts.
  5. Read tools execute immediately; mutation tools create pending confirmation cards instead of writing directly.
  6. Final responses are validated, sanitized, logged, and saved to conversation history.

Database tables involved

Global AI support tables include:

  • AiSession: session identity and metadata
  • AiTurn: request/response turn records
  • AiPendingAction: approval cards waiting for user decision
  • AiExecutionLedger: idempotent confirmation/revert execution records
  • AiToolCallLedger: tool call result ledger
  • AI usage and request log tables used for quota tracking and audit reporting

API endpoints

  • POST /api/ai - Main streaming assistant route
  • GET /api/ai/bootstrap - Warm assistant runtime state
  • GET /api/ai/usage - AI usage and quota summary
  • GET /api/ai/actions/pending - Pending action cards
  • POST /api/ai/actions/confirm - Approve or reject AI suggestions
  • POST /api/ai/actions/revert - Revert eligible executed AI actions
  • POST /api/ai/attachments - Upload assistant attachments
  • POST /api/ai/attachment-turn - Build an attachment review turn

Permissions / roles

  • owner and manager can use confirmation-based mutation tools such as product and supplier creation suggestions.
  • Tenant entitlements control whether auto and agent modes are available.
  • Audit visibility is restricted to owner and manager.

Edge cases

  • Mutations are never executed directly from model reasoning. They must become confirmation cards first.
  • If a provider endpoint does not support tool use, the route falls back to text-only tool-assisted prompting.
  • The panel shows a safe fallback message if the stream ends without assistant text.

Validation rules

  • Input payloads, tools, and action cards are validated with Zod.
  • Tool execution is wrapped with policy checks, rate limits, and 5 second timeouts.
  • Responses are sanitized before display and storage.

Error handling

  • Quota, policy, and provider failures are converted into user-facing safe messages.
  • Confirmation and revert routes are idempotent and version-checked to prevent stale or duplicate execution.

Screenshots placeholders

![Confirmation Card Output](../../assets/images/ai/confirmation-card.png)

Troubleshooting

  • If auto or agent mode is unavailable, check the tenant entitlements for advanced assistant access.
  • If a card cannot be confirmed or reverted, check for stale expectedVersion values or policy changes since the card was created.

Related features