Traditional   →  "Here are your numbers."
Intelligent   →  "Here is what is happening."   (Ask + Explain)
Advanced      →  "Here is what you should do."   (Briefing + recommendations)
Future        →  "I prepared the action — review & approve."  (draft actions)

User (session: orgId, userId, role, branchScope)
      │  AI request (+ requestId)
      ▼
Entitlement + credit gate  ──►  402 NO_CREDITS / 403 NOT_ENABLED
      │  (tenant.aiStatus ACTIVE|TRIAL, feature on, balance > 0)
      ▼
Orchestrator (streamText / generateObject, tiered model, system prompt)
      │
      ├── Tool layer   → each tool: bound orgId + permission check + scoped query → JSON "card"
      ├── Business rules (reuse your existing permissions / limits / approvals)
      └── (later) memory / business context
      │
      ▼
Application layer (your existing services / ORM) ──► Postgres (source of truth)
      │
      ▼
onFinish: usage → cost → deduct credits + write an AI usage log
      │
      ▼
Stream message.parts → client renders text + custom cards

pnpm add ai @ai-sdk/react react-markdown   # AI SDK v7 + a markdown renderer
# zod is almost certainly already a dependency

# .env.local
AI_GATEWAY_API_KEY=vck_xxx          # from the Vercel dashboard; the `ai` pkg reads it automatically
AI_MODEL_CHEAP=google/gemini-2.5-flash
AI_MODEL_STRONG=anthropic/claude-haiku-4.5
AI_USD_TO_GHS=16                    # your currency conversion for cost accounting

// lib/ai/gateway.ts
export type ModelTier = "cheap" | "standard" | "strong";
 
export const MODELS: Record<ModelTier, string> = {
  cheap: process.env.AI_MODEL_CHEAP ?? "google/gemini-2.5-flash",
  standard: process.env.AI_MODEL_STANDARD ?? "openai/gpt-4o-mini",
  strong: process.env.AI_MODEL_STRONG ?? "anthropic/claude-haiku-4.5",
};
 
const USD_TO_LOCAL = Number(process.env.AI_USD_TO_GHS ?? "16");
 
// List price per 1M tokens (input/output). Unknown models fall back to a
// non-zero default so a mis-set model id can't make AI look free.
const DEFAULT_COST = { inUsdPerM: 0.5, outUsdPerM: 1.5 };
const COST_TABLE: Record<string, { inUsdPerM: number; outUsdPerM: number }> = {
  "google/gemini-2.5-flash": { inUsdPerM: 0.3, outUsdPerM: 2.5 },
  "openai/gpt-4o-mini": { inUsdPerM: 0.15, outUsdPerM: 0.6 },
  "anthropic/claude-haiku-4.5": { inUsdPerM: 1.0, outUsdPerM: 5.0 },
};
 
export type TokenUsage = { inputTokens?: number; outputTokens?: number };
 
export function computeRawCostLocal(usage: TokenUsage, model: string): number {
  const { inUsdPerM, outUsdPerM } = COST_TABLE[model] ?? DEFAULT_COST;
  const input = Math.max(0, usage.inputTokens ?? 0);
  const output = Math.max(0, usage.outputTokens ?? 0);
  const usd = (input / 1e6) * inUsdPerM + (output / 1e6) * outUsdPerM;
  return usd * USD_TO_LOCAL;
}
 
export const computeChargedLocal = (raw: number, margin: number) =>
  raw * Math.max(1, margin);
 
// Cheap by default; escalate only for genuinely hard reasoning.
export function pickModel(opts?: { hardReasoning?: boolean }) {
  const tier: ModelTier = opts?.hardReasoning ? "strong" : "cheap";
  return { tier, model: MODELS[tier] };
}

enum AiStatus { NOT_ENABLED  TRIAL  ACTIVE  SUSPENDED  DISABLED }
enum AiCreditReason { GRANT  TRIAL_GRANT  CONSUME  ADJUST  REFUND }
 
// on your tenant/Organization model:
aiStatus            AiStatus @default(NOT_ENABLED)   // OFF by default
aiFeatures          Json?     // { ask: true, explain: true, briefing: false, ... }
aiTrialEndsAt       DateTime?
aiCreditBalance     Decimal   @default(0) @db.Decimal(12, 4)  // a money wallet
aiMarginMultiplier  Decimal   @default(3) @db.Decimal(6, 3)   // charged = rawCost × margin
 
// append-only ledger — never mutate/delete
model AiCreditLedger {
  id           String         @id @default(cuid())
  orgId        String
  deltaLocal   Decimal        @db.Decimal(12, 4)   // + grant, − consume
  balanceAfter Decimal        @db.Decimal(12, 4)
  reason       AiCreditReason
  reference    String?
  createdById  String?
  createdAt    DateTime       @default(now())
  @@index([orgId, createdAt])
}
 
// one row per interaction — observability + the activity feed
model AiUsageLog {
  id            String   @id @default(cuid())
  requestId     String   @unique
  orgId         String
  userId        String?
  feature       String   // "ask" | "explain" | "briefing" | ...
  model         String
  toolsUsed     String[]
  inputTokens   Int      @default(0)
  outputTokens  Int      @default(0)
  rawCost       Decimal  @default(0) @db.Decimal(12, 6)
  chargedCost   Decimal  @default(0) @db.Decimal(12, 6)
  latencyMs     Int      @default(0)
  status        String   // "ok" | "error"
  prompt        String?  // what was asked (truncated)
  reply         String?  // what the AI replied (truncated)
  createdAt     DateTime @default(now())
  @@index([orgId, createdAt])
}

// lib/ai/entitlement.ts
import "server-only";
import { db } from "@/lib/db";
import {
  computeChargedLocal,
  computeRawCostLocal,
  type TokenUsage,
} from "@/lib/ai/gateway";
import { requireOrg } from "@/lib/tenant"; // resolves the authed session → { orgId, userId, role, branchId }
 
export type AiFeature = "ask" | "explain" | "briefing" | "ping";
const CORE = new Set<AiFeature>(["ping"]); // always allowed when active (no per-feature flag)
 
export type AiContext = {
  orgId: string;
  userId: string;
  role: string;
  branchId: string | null;
  currency: string;
  marginMultiplier: number;
  balance: number;
};
 
export class AiError extends Error {
  constructor(
    public code: "AI_NOT_ENABLED" | "AI_FEATURE_OFF" | "AI_NO_CREDITS",
    msg: string
  ) {
    super(msg);
    this.httpStatus = code === "AI_NO_CREDITS" ? 402 : 403;
  }
  httpStatus: number;
}
 
export async function requireAiFeature(feature: AiFeature): Promise<AiContext> {
  const user = await requireOrg(); // ← tenant context from the SESSION
  const org = await db.organization.findUnique({
    where: { id: user.orgId },
    select: {
      aiStatus: true,
      aiFeatures: true,
      aiTrialEndsAt: true,
      aiMarginMultiplier: true,
      aiCreditBalance: true,
      currency: true,
    },
  });
 
  if (!org || (org.aiStatus !== "ACTIVE" && org.aiStatus !== "TRIAL"))
    throw new AiError(
      "AI_NOT_ENABLED",
      "AI isn't enabled for your organisation."
    );
  if (
    org.aiStatus === "TRIAL" &&
    org.aiTrialEndsAt &&
    org.aiTrialEndsAt < new Date()
  )
    throw new AiError("AI_NOT_ENABLED", "Your AI trial has ended.");
  if (!CORE.has(feature) && (org.aiFeatures as any)?.[feature] !== true)
    throw new AiError(
      "AI_FEATURE_OFF",
      `The "${feature}" capability isn't enabled.`
    );
  if (!(Number(org.aiCreditBalance) > 0))
    throw new AiError(
      "AI_NO_CREDITS",
      "Out of AI credits. Ask your admin to top up."
    );
 
  return {
    orgId: user.orgId,
    userId: user.userId,
    role: user.role,
    branchId: user.branchId,
    currency: org.currency,
    marginMultiplier: Number(org.aiMarginMultiplier),
    balance: Number(org.aiCreditBalance),
  };
}
 
// Log one interaction + deduct its cost, atomically.
export async function chargeAi(a: {
  ctx: AiContext;
  requestId: string;
  feature: AiFeature;
  model: string;
  usage: TokenUsage;
  latencyMs: number;
  toolsUsed?: string[];
  prompt?: string;
  reply?: string;
}) {
  const raw = computeRawCostLocal(a.usage, a.model);
  const charged = computeChargedLocal(raw, a.ctx.marginMultiplier);
  const trim = (s: string | undefined, n: number) =>
    s == null ? null : s.slice(0, n);
 
  return db.$transaction(async (tx) => {
    await tx.aiUsageLog.create({
      data: {
        requestId: a.requestId,
        orgId: a.ctx.orgId,
        userId: a.ctx.userId,
        feature: a.feature,
        model: a.model,
        toolsUsed: a.toolsUsed ?? [],
        inputTokens: a.usage.inputTokens ?? 0,
        outputTokens: a.usage.outputTokens ?? 0,
        rawCost: raw,
        chargedCost: charged,
        latencyMs: a.latencyMs,
        status: "ok",
        prompt: trim(a.prompt, 4000),
        reply: trim(a.reply, 8000),
      },
    });
    const updated = await tx.organization.update({
      where: { id: a.ctx.orgId },
      data: { aiCreditBalance: { decrement: charged } },
      select: { aiCreditBalance: true },
    });
    const balanceAfter = Number(updated.aiCreditBalance);
    await tx.aiCreditLedger.create({
      data: {
        orgId: a.ctx.orgId,
        deltaLocal: -charged,
        balanceAfter,
        reason: "CONSUME",
        reference: a.requestId,
      },
    });
    return { raw, charged, balanceAfter };
  });
}

// lib/ai/tools.ts
import { tool, type ToolSet } from "ai";
import { z } from "zod";
import type { AiContext } from "@/lib/ai/entitlement";
import { db } from "@/lib/db";
import { can, type Permission } from "@/lib/permissions"; // your existing RBAC helper
 
const ORG_WIDE = new Set(["ORG_ADMIN", "REGIONAL_MANAGER"]);
 
export function buildTools(ctx: AiContext): ToolSet {
  const money = (n: number) => `${ctx.currency} ${Number(n).toFixed(2)}`;
  // Branch scope: staff pinned to a branch only ever see their branch.
  const orgWide = ORG_WIDE.has(ctx.role);
  const branchWhere =
    !orgWide && ctx.branchId ? { branchId: ctx.branchId } : {};
 
  const tools: ToolSet = {};
  // NB: type the param as ToolSet[string], NOT ReturnType<typeof tool> (which
  // collapses to Tool<never> under AI SDK v7 and won't accept your tools).
  const add = (perm: Permission, name: string, t: ToolSet[string]) => {
    if (can(ctx.role, perm)) tools[name] = t; // ← omitted entirely if not permitted
  };
 
  add(
    "sale.view",
    "getSalesSummary",
    tool({
      description:
        "Total revenue, transactions and average sale for a period. Use for 'how are sales', 'revenue today/this week'.",
      inputSchema: z.object({
        period: z.enum(["today", "7d", "30d"]).default("today"),
      }),
      execute: async ({ period }) => {
        const start = rangeStart(period);
        const agg = await db.sale.aggregate({
          where: {
            orgId: ctx.orgId,
            status: "ACTIVE",
            createdAt: { gte: start },
            ...branchWhere,
          },
          _sum: { total: true },
          _count: true,
        });
        const revenue = Number(agg._sum.total ?? 0);
        return {
          card: "stats",
          title: `Sales — ${period}`,
          stats: [
            { label: "Revenue", value: money(revenue) },
            { label: "Transactions", value: String(agg._count) },
            {
              label: "Avg sale",
              value: money(agg._count ? revenue / agg._count : 0),
            },
          ],
        };
      },
    })
  );
 
  add(
    "sale.view",
    "getOverdueCredit",
    tool({
      description:
        "Customers whose credit is past due. Use for 'who owes me money'.",
      inputSchema: z.object({}),
      execute: async () => {
        const sales = await db.sale.findMany({
          where: {
            orgId: ctx.orgId,
            status: "ACTIVE",
            balanceDue: { gt: 0 },
            dueDate: { lt: new Date() },
            ...branchWhere,
          },
          select: { balanceDue: true, customer: { select: { name: true } } },
          orderBy: { balanceDue: "desc" },
          take: 25,
        });
        return {
          card: "list",
          title: "Overdue credit",
          columns: [
            { key: "customer", label: "Customer" },
            { key: "amount", label: "Overdue", align: "right" },
          ],
          rows: sales.map((s) => ({
            customer: s.customer?.name ?? "Walk-in",
            amount: money(Number(s.balanceDue)),
          })),
          note: sales.length
            ? undefined
            : "No overdue credit — everyone is up to date.",
        };
      },
    })
  );
 
  // …add getLowStock, getExpiringStock, getTopProducts, getDashboardSummary, etc.
  return tools;
}

// lib/ai/period.ts
export const PERIODS = [
  "today",
  "yesterday",
  "this_week",
  "last_week",
  "this_month",
  "last_month",
  "this_quarter",
  "last_quarter",
  "this_year",
  "last_year",
  "ytd",
  "mtd",
  "7d",
  "14d",
  "30d",
  "60d",
  "90d",
  "all_time",
] as const;
 
export function resolveRange(
  a: { period?: string; from?: string; to?: string },
  fallback = "30d"
) {
  // A custom range always wins ("between X and Y", "since [date]").
  if (a.from || a.to) {
    const start = a.from ? new Date(a.from) : new Date(0);
    const end = a.to ? new Date(a.to) : new Date();
    if (!isNaN(+start) && !isNaN(+end))
      return {
        start,
        end,
        label: `${start.toLocaleDateString()} – ${end.toLocaleDateString()}`,
      };
  }
  // …switch on the named period → Monday-based weeks, calendar months/quarters,
  //   ytd/mtd, rolling N-day windows, all_time = epoch→now…
}
 
// The reusable input fragment every time-based tool spreads into its schema:
export const rangeShape = {
  period: z
    .enum(PERIODS)
    .optional()
    .describe("today, this_week, last_month, ytd, 30d, all_time, …"),
  from: z.string().optional().describe("Custom range start YYYY-MM-DD"),
  to: z.string().optional().describe("Custom range end YYYY-MM-DD"),
};

inputSchema: z.object({ ...rangeShape, /* tool-specific args */ }),
execute: async ({ period, from, to, ...rest }) => {
  const { start, end, label } = resolveRange({ period, from, to }, "this_month");
  // one query, consistent windows, a human label for the card title
},

// A tool that fetches + buckets real data → a line chart:
add(
  "sale.view",
  "getSalesTrend",
  tool({
    description:
      "Sales revenue over time as a CHART. 'sales trend', 'monthly sales chart', 'graph my sales'. Buckets by day/week/month automatically.",
    inputSchema: z.object({
      ...rangeShape,
      bucket: z.enum(["day", "week", "month"]).optional(),
    }),
    execute: async ({ period, from, to, bucket }) => {
      const { start, end, label } = resolveRange(
        { period, from, to },
        "this_year"
      );
      // …group ACTIVE sales into buckets → points:[{label,value}]…
      return {
        card: "chart",
        chartType: "line",
        title: `Sales trend — ${label}`,
        points,
      };
    },
  })
);
 
// A meta-tool that charts numbers the user ALREADY has — no gate, no DB:
tools.renderChart = tool({
  description:
    "Render figures the user ALREADY has (from a previous tool result) as a chart. Pass values EXACTLY as returned — never invent numbers. chartType: bar (rank), line (trend), pie (share).",
  inputSchema: z.object({
    chartType: z.enum(["bar", "line", "pie"]).default("bar"),
    title: z.string(),
    points: z
      .array(z.object({ label: z.string(), value: z.number() }))
      .min(1)
      .max(60),
  }),
  execute: async ({ chartType, title, points }) => ({
    card: "chart",
    chartType,
    title,
    points,
  }),
});

tools.requestDataAccess = tool({
  // no gate — always available
  description:
    "Call when NO other tool can answer the user's question. Describe the data that WOULD answer it. Renders a 'request access' button — do not apologise or invent an answer.",
  inputSchema: z.object({
    question: z.string().describe("What the user asked, in their words."),
    dataDescription: z
      .string()
      .describe("The data/capability that would answer it."),
  }),
  execute: async ({ question, dataDescription }) => ({
    card: "request",
    question,
    dataDescription,
  }),
});

// app/api/ai/chat/route.ts
import {
  convertToModelMessages,
  stepCountIs,
  streamText,
  type UIMessage,
} from "ai";
import { NextResponse } from "next/server";
import { AiError, chargeAi, requireAiFeature } from "@/lib/ai/entitlement";
import { pickModel } from "@/lib/ai/gateway";
import { buildTools } from "@/lib/ai/tools";
 
export async function POST(req: Request) {
  let ctx;
  try {
    ctx = await requireAiFeature("ask");
  } catch (e) {
    if (e instanceof AiError)
      return NextResponse.json(
        { error: e.message, code: e.code },
        { status: e.httpStatus }
      );
    throw e;
  }
 
  const { messages = [] } = (await req.json()) as { messages: UIMessage[] };
  const promptText = lastUserText(messages); // for the activity log
  const { model } = pickModel();
  const requestId = crypto.randomUUID();
  const startedAt = Date.now();
 
  // ⚠️ AI SDK v7: convertToModelMessages is ASYNC — await it.
  const modelMessages = await convertToModelMessages(messages);
 
  const result = streamText({
    model,
    system: [
      "You are an assistant embedded in a business platform.",
      `The user's role is ${ctx.role}; currency ${ctx.currency}; today is ${new Date().toISOString().slice(0, 10)}.`,
      "ALWAYS get business figures by calling a tool — never invent, estimate or recall numbers. If no tool can answer, say so.",
      "A tool returns a card the UI shows; keep your text reply to ONE short sentence. Don't restate every number.",
    ].join("\n"),
    messages: modelMessages,
    tools: buildTools(ctx), // ← tools bound to the authed context
    stopWhen: stepCountIs(6), // allow: call tool → read result → reply
    onFinish: async (event) => {
      const toolsUsed = [
        ...new Set((event.toolCalls ?? []).map((c) => c.toolName)),
      ];
      await chargeAi({
        ctx,
        requestId,
        feature: "ask",
        model,
        usage: {
          inputTokens: event.usage.inputTokens,
          outputTokens: event.usage.outputTokens,
        },
        latencyMs: Date.now() - startedAt,
        toolsUsed,
        prompt: promptText,
        reply: event.text,
      }).catch(() => {}); // never fail the response over billing bookkeeping
    },
  });
 
  return result.toUIMessageStreamResponse();
}

// components/ai/cards/tool-card.tsx  ("use client")
export function AiToolCard({ output }: { output: unknown }) {
  const d = output as any;
  if (!d || typeof d !== "object" || !("card" in d)) return null;
  if (d.card === "stats") return <StatsCard d={d} />;
  if (d.card === "list") return <ListCard d={d} />;
  if (d.card === "breakdown") return <BreakdownCard d={d} />;
  if (d.card === "chart") return <ChartCardView d={d} />; // §7.3
  if (d.card === "request") return <RequestAccessCard d={d} />; // §5.4 → §13
  return null;
}

// components/ai/ask.tsx  ("use client")
import { DefaultChatTransport } from "ai";
import { useChat } from "@ai-sdk/react";
import ReactMarkdown from "react-markdown";
import { AiToolCard } from "@/components/ai/cards/tool-card";
 
export function AskPanel() {
  const [input, setInput] = useState("");
  const { messages, sendMessage, status } = useChat({
    transport: new DefaultChatTransport({ api: "/api/ai/chat" }),
  });
  const busy = status === "submitted" || status === "streaming";
 
  return (
    <>
      {messages.map((m) => (
        <div key={m.id}>
          {m.parts.map((part: any, i: number) => {
            if (part.type === "text")
              return <ReactMarkdown key={i}>{part.text}</ReactMarkdown>;
            if (part.type.startsWith("tool-"))
              // ← "tool-getSalesSummary" etc.
              return part.state === "output-available" ? (
                <AiToolCard key={i} output={part.output} /> // pass the tool JSON as props
              ) : (
                <span key={i}>Looking that up…</span>
              );
            return null;
          })}
        </div>
      ))}
      <form
        onSubmit={(e) => {
          e.preventDefault();
          if (input.trim() && !busy) {
            sendMessage({ text: input });
            setInput("");
          }
        }}
      >
        <input value={input} onChange={(e) => setInput(e.target.value)} />
      </form>
    </>
  );
}

// inside tool-card.tsx — bar (rank), line (trend), pie (share)
function ChartCardView({ d }: { d: ChartCard }) {
  const data = d.points.map((p) => ({
    name: p.label,
    value: Number(p.value) || 0,
  }));
  if (!data.length)
    return (
      <CardShell title={d.title}>
        <Note text="No data to chart." />
      </CardShell>
    );
  return (
    <CardShell title={d.title}>
      <div className="h-56 w-full p-2">
        <ResponsiveContainer width="100%" height="100%">
          {d.chartType === "line" ? (
            <LineChart data={data}>
              {/* Grid, X/Y, Tooltip */}
              <Line
                type="monotone"
                dataKey="value"
                stroke={CHART_COLORS[0]}
                strokeWidth={2}
                dot={false}
              />
            </LineChart>
          ) : d.chartType === "pie" ? (
            <PieChart>
              <Pie
                data={data}
                dataKey="value"
                nameKey="name"
                innerRadius={38}
                outerRadius={78}
              >
                {data.map((_, i) => (
                  <Cell key={i} fill={CHART_COLORS[i % CHART_COLORS.length]} />
                ))}
              </Pie>
              <Tooltip />
            </PieChart>
          ) : (
            <BarChart data={data}>
              {/* Grid, X/Y, Tooltip */}
              <Bar dataKey="value" radius={[4, 4, 0, 0]}>
                {data.map((_, i) => (
                  <Cell key={i} fill={CHART_COLORS[i % CHART_COLORS.length]} />
                ))}
              </Bar>
            </BarChart>
          )}
        </ResponsiveContainer>
      </div>
    </CardShell>
  );
}

const [expanded, setExpanded] = useState(false);
<aside className={cn("… transition-[max-width]", expanded ? "max-w-3xl" : "max-w-md")}>
  …
  <button onClick={() => setExpanded(v => !v)} aria-label={expanded ? "Collapse" : "Expand"}>
    {expanded ? <Minimize2 /> : <Maximize2 />}
  </button>

// lib/ai/explain.ts — one tool that re-computes a known metric from the DB
export function buildExplainTools(ctx: AiContext): ToolSet {
  const explainMetric = tool({
    description:
      "Re-derive a business figure from source so the user can see where it comes from.",
    inputSchema: z.object({
      metric: z.enum([
        "revenue",
        "receivables",
        "overdue_credit",
        "inventory_value" /* … */,
      ]),
      period: z.enum(["today", "7d", "30d"]).default("today"),
    }),
    execute: async ({ metric, period }) => {
      if (!can(ctx.role, METRIC_PERM[metric]))
        return {
          card: "breakdown",
          title: "Not permitted",
          value: "—",
          definition: "You don't have permission to see this figure.",
          components: [],
        };
      // …switch on metric, run the exact query behind the on-screen number…
      return {
        card: "breakdown",
        title: "Revenue — today",
        value: money(revenue),
        definition:
          "Revenue = the sum of the total on every completed (non-cancelled) sale in the period.",
        components: [
          { label: "Completed sales", value: String(count) },
          { label: "Sum of sale totals", value: money(revenue) },
        ],
      };
    },
  });
  return { explainMetric };
}

const [transport] = useState(
  () =>
    new DefaultChatTransport({
      api: "/api/ai/explain",
      body: { metric, period },
    })
);
const { messages, sendMessage } = useChat({ transport });
// on open: sendMessage({ text: "Where does this figure come from?" })

// lib/ai/report-explain.ts — one tool, scoped to the report the user is viewing
export function buildReportExplainTools(
  ctx: AiContext,
  scope: { reportType: ReportType; from: Date; to: Date; branchId?: string }
): ToolSet {
  const explainReport = tool({
    description:
      "Get the figures behind the report the user is viewing (this period AND the previous period) so you can explain what changed and why. Call once, then explain.",
    inputSchema: z.object({}), // ← no model inputs; scope is bound from the request
    execute: async () => {
      if (!can(ctx.role, REPORT_PERMISSION[scope.reportType]))
        return {
          card: "stats",
          title: "Not permitted",
          stats: [],
          note: "You don't have permission to view this report.",
        };
 
      // Branch staff are pinned to their branch, exactly as the report API does.
      const orgWide = [
        "ORG_ADMIN",
        "SUB_ORG_ADMIN",
        "REGIONAL_MANAGER",
      ].includes(ctx.role);
      const branchId = orgWide ? scope.branchId : (ctx.branchId ?? undefined);
 
      // The previous window = same length, immediately before.
      const lenMs = Math.max(1, scope.to.getTime() - scope.from.getTime());
      const prevTo = new Date(scope.from.getTime());
      const prevFrom = new Date(scope.from.getTime() - lenMs);
 
      const [current, previous] = await Promise.all([
        computeReport(scope.reportType, ctx.orgId, {
          from: scope.from,
          to: scope.to,
          branchId,
        }),
        computeReport(scope.reportType, ctx.orgId, {
          from: prevFrom,
          to: prevTo,
          branchId,
        }),
      ]);
 
      const asFacts = (p) =>
        p.summary.map(
          (s) => `${s.label}: ${s.value}${s.sub ? ` (${s.sub})` : ""}`
        );
      return {
        // What the CARD renders — this period's headline summary:
        card: "stats",
        title: current.title,
        note: current.rangeLabel,
        stats: current.summary.map((s) => ({ label: s.label, value: s.value })),
        // Extra context ONLY the model reads (the card ignores these) to reason about change:
        currentPeriod: { range: current.rangeLabel, summary: asFacts(current) },
        previousPeriod: {
          range: previous.rangeLabel,
          summary: asFacts(previous),
        },
        topRows: current.rows.slice(0, 6),
        columns: current.columns.map((c) => c.label),
      };
    },
  });
  return { explainReport };
}

system: [
  "The user is looking at a business report and clicked 'Explain with AI'.",
  `The report is "${report}". Their role is ${ctx.role}; currency ${ctx.currency}.`,
  "Call explainReport ONCE to get this period's and the previous period's figures, then explain in 2–4 short sentences: the headline result, the biggest changes vs the previous period (rough % where useful), anything unusual, and the most likely causes you can infer.",
  "Use ONLY the figures the tool returns — never invent numbers. Be specific and practical, not generic.",
].join("\n"),
tools: buildReportExplainTools(ctx, { reportType: report, from, to, branchId }),
stopWhen: stepCountIs(3),

const [transport] = useState(
  () =>
    new DefaultChatTransport({
      api: "/api/ai/report",
      body: { report, from, to, branchId },
    })
);
const { messages, sendMessage } = useChat({ transport });
// on open: sendMessage({ text: "Explain what changed in this report and why." })

// lib/ai/briefing.ts
import { generateObject } from "ai";
import { z } from "zod";
 
const BriefingSchema = z.object({
  greeting: z.string(),
  items: z
    .array(
      z.object({
        severity: z.enum(["critical", "warning", "info"]),
        title: z.string(),
        detail: z.string(),
      })
    )
    .max(6),
  recommendations: z.array(z.string()).max(5),
});
 
export async function generateBriefing(ctx: AiContext) {
  const key = cacheKey(
    "dashboard",
    ctx.orgId,
    "ai-briefing",
    ctx.branchId ?? "org",
    todayIso()
  );
  return getCachedOrFetch(
    key,
    async () => {
      const signals = await gatherSignals(ctx); // ← DETERMINISTIC numbers, from your DB
      const facts = renderFacts(signals); // a plain-text summary of those numbers
      const model = pickModel().model;
      const { object, usage } = await generateObject({
        model,
        schema: BriefingSchema,
        system:
          "Use ONLY the figures provided — never invent numbers. Prioritise cash, then stock risk, then revenue.",
        prompt: `Today's figures:\n${facts}\n\nWrite the briefing.`,
      });
      await chargeAi({
        ctx,
        requestId: crypto.randomUUID(),
        feature: "briefing",
        model,
        usage: {
          inputTokens: usage.inputTokens,
          outputTokens: usage.outputTokens,
        },
        latencyMs: 0,
        prompt: facts,
        reply: JSON.stringify(object),
      }).catch(() => {});
      return object;
    },
    60 * 60 * 12
  ); // 12h TTL
}

// lib/ai/activity.ts — a day's interactions for one org (org-scoped; caller authorises orgId)
export async function getAiActivityForDay(orgId: string, date: string) {
  const start = new Date(`${date}T00:00:00.000Z`);
  const end = new Date(start.getTime() + 86_400_000);
  const items = await db.aiUsageLog.findMany({
    where: { orgId, createdAt: { gte: start, lt: end } },
    orderBy: { createdAt: "desc" },
  });
  return {
    date,
    items,
    summary: {
      interactions: items.length,
      toolsCalled: items.reduce((a, r) => a + r.toolsUsed.length, 0),
      spent: items.reduce((a, r) => a + Number(r.chargedCost), 0),
    },
  };
}

Vercel AI Gateway balance (USD)  ──× FX (USD→local)──►  the credit POOL (local)
        │  real capacity you paid for                     what you're allowed to sell
        ▼
Per request:  our cost  rawLocal  = gatewayUSD × FX
              we charge chargedLocal = rawLocal × org.margin
              profit               = rawLocal × (margin − 1)

// lib/ai/platform.ts   [server-only]
import { gateway } from "ai";
 
export async function getVercelCredits() {
  // cached ~60s; null on error
  try {
    const c = await gateway.getCredits(); // { balance, totalUsed } in USD
    return { balanceUsd: Number(c.balance), totalUsedUsd: Number(c.totalUsed) };
  } catch {
    return null; // no card / API down → show "unavailable", not a crash
  }
}

export async function getUsdToGhs(): Promise<number> {
  // DB-backed, cached 5 min
  const cached = await cache.get<string>("ai:usd-to-ghs");
  if (cached != null) return Number(cached);
  const row = await db.aiPlatformConfig.upsert({
    where: { id: "singleton" },
    create: { id: "singleton", usdToGhs: USD_TO_GHS },
    update: {},
    select: { usdToGhs: true },
  });
  await cache.set("ai:usd-to-ghs", String(row.usdToGhs), { ex: 300 });
  return Number(row.usdToGhs);
}

export async function getPlatformCreditView() {
  const [rate, vercel, orgs, usage] = await Promise.all([
    getUsdToGhs(),
    getVercelCredits(),
    db.organization.findMany({
      where: { aiStatus: { in: ["ACTIVE", "TRIAL"] } },
      select: { aiCreditBalanceGhs: true, aiMarginMultiplier: true },
    }),
    db.aiUsageLog.aggregate({ _sum: { chargedGhs: true, rawCostGhs: true } }),
  ]);
 
  let committedRawGhs = 0,
    outstandingChargedGhs = 0;
  for (const o of orgs) {
    const bal = Number(o.aiCreditBalanceGhs);
    const margin = Math.max(1, Number(o.aiMarginMultiplier));
    committedRawGhs += bal / margin; // real cost we're on the hook for
    outstandingChargedGhs += bal; // face value we owe the orgs
  }
  const poolGhs = vercel ? vercel.balanceUsd * rate : null;
  const availableRawGhs = poolGhs != null ? poolGhs - committedRawGhs : null;
 
  const lifetimeChargedGhs = Number(usage._sum.chargedGhs ?? 0);
  const lifetimeRawGhs = Number(usage._sum.rawCostGhs ?? 0);
  return {
    usdToGhs: rate,
    vercel,
    poolGhs,
    committedRawGhs,
    availableRawGhs,
    outstandingChargedGhs,
    orgsWithAi: orgs.length,
    lifetimeProfitGhs: lifetimeChargedGhs - lifetimeRawGhs,
  };
}

export function previewGrant(
  amountGhs: number,
  margin: number,
  availableRawGhs: number | null
) {
  const m = Math.max(1, margin);
  const costRawGhs = amountGhs / m; // real cost this grant commits
  const profitGhs = amountGhs - costRawGhs; // profit if fully consumed
  const exceedsPool =
    availableRawGhs != null && costRawGhs > availableRawGhs + 1e-6;
  return { costRawGhs, profitGhs, exceedsPool, availableRawGhs };
}

// lib/ai/errors.ts (sketch)  — distinguish "gateway unavailable" from "no credits"
export function classifyAiError(e: unknown) {
  const m = String((e as any)?.message ?? "").toLowerCase();
  if (
    m.includes("customer_verification") ||
    m.includes("credit card") ||
    m.includes("ai gateway") ||
    m.includes("rate limit") ||
    m.includes("quota")
  )
    return "gateway_unavailable";
  return "unknown";
}
// markGatewayDown()/isGatewayDown() flip a 5-min key in Redis; the chat route checks it
// up front and the status route surfaces it, so the UI self-recovers.

// the request card's button (client)
await fetch("/api/ai/access-request", {
  method: "POST",
  body: JSON.stringify({
    question: d.question,
    dataDescription: d.dataDescription,
  }),
});
// server: db.aiDataRequest.create({ data: { orgId, userId, question, dataDescription, status: "OPEN" } })

lib/ai/gateway.ts        model tiers + cost math (pure, unit-tested)
lib/ai/period.ts         universal date resolution (resolveRange + rangeShape)
lib/ai/entitlement.ts    requireAiFeature (gate) + chargeAi (meter)          [server-only]
lib/ai/tools.ts          40+ RBAC/tenant-scoped read tools → card envelopes
lib/ai/explain.ts        explainMetric → breakdown card
lib/ai/report-explain.ts explainReport → re-derive a whole report vs prior period
lib/ai/signals.ts        deterministic figures for the briefing (pure DB)
lib/ai/briefing.ts       generateObject + daily cache                        [server-only]
lib/ai/activity.ts       a day's interactions for the activity page
lib/ai/platform.ts       AI economics: gateway balance, FX, pool + oversell   [server-only]
lib/ai/errors.ts         classify gateway errors + Redis circuit breaker      [server-only]
 
app/api/ai/chat/route.ts       streaming chat (tool-calling)
app/api/ai/explain/route.ts    focused provenance chat
app/api/ai/report/route.ts     "explain this report"
app/api/ai/briefing/route.ts   cached daily briefing
app/api/ai/status/route.ts     { enabled, features, available, hasCredits } for the client
app/api/ai/ping/route.ts       end-to-end diagnostic
app/api/ai/access-request/route.ts              file a missing-tool request (requestDataAccess)
app/api/super-admin/ai/route.ts                 economics view (GET) + set FX rate (PATCH)
app/api/super-admin/ai/requests/route.ts        the data-request queue
app/api/organizations/[id]/ai/route.ts          super-admin enable/disable/trial + margin/features
app/api/organizations/[id]/ai/credits/route.ts  super-admin grant credits (oversell-guarded)
 
components/ai/ask-intellixio.tsx     chat launcher + slide-over (expand toggle, skeletons)
components/ai/explain-button.tsx     the "Explain this figure" popover
components/ai/explain-report-button.tsx  "explain this report" popover
components/ai/executive-briefing.tsx dashboard briefing widget
components/ai/cards/tool-card.tsx    stats / list / breakdown / chart / request renderer
components/super-admin/ai-console.tsx    economics console (balance, FX, pool, requests)