@zaip-ai/cli 1.0.7 → 1.0.8

package/templates/.agents/dashboard/apps/frontend/src/CostCalculationGuidePage.tsx

@@ -0,0 +1,641 @@
+import { useMemo, useState } from "react";
+import type { FxRate, PricingCatalog, PricingModel } from "./dashboard-api.js";
+import type { DashboardLocale } from "./dashboard-localization.js";
+
+type Currency = "USD" | "BRL";
+type Tier = "standard" | "priority";
+
+interface TokenUsage {
+  input: number;
+  cache: number;
+  output: number;
+  reasoning: number;
+}
+
+interface CostRates {
+  input: number;
+  cache: number | null;
+  output: number;
+}
+
+export interface Example {
+  usage: TokenUsage;
+  rates: CostRates;
+  inputMultiplier: number;
+  outputMultiplier: number;
+  inputUsd: number;
+  cacheUsd: number;
+  outputUsd: number;
+  reasoningUsd: 0;
+  totalUsd: number;
+  totalBrl: number | null;
+}
+
+export const exampleUsage: TokenUsage = {
+  input: 100_000,
+  cache: 40_000,
+  output: 20_000,
+  reasoning: 8_000,
+};
+
+const roundCurrency = (value: number) => Math.round(value * 1_000_000) / 1_000_000;
+
+function calculateExample(
+  usage: TokenUsage,
+  rates: CostRates,
+  inputMultiplier: number,
+  outputMultiplier: number,
+  fxRate: number | null,
+): Example {
+  const uncachedInput = Math.max(usage.input - usage.cache, 0);
+  const inputUsd = roundCurrency((uncachedInput / 1_000_000) * rates.input * inputMultiplier);
+  const cacheUsd = roundCurrency((usage.cache / 1_000_000) * (rates.cache ?? 0) * inputMultiplier);
+  const outputUsd = roundCurrency((usage.output / 1_000_000) * rates.output * outputMultiplier);
+  const totalUsd = roundCurrency(inputUsd + cacheUsd + outputUsd);
+
+  return {
+    usage,
+    rates,
+    inputMultiplier,
+    outputMultiplier,
+    inputUsd,
+    cacheUsd,
+    outputUsd,
+    reasoningUsd: 0,
+    totalUsd,
+    totalBrl: fxRate === null ? null : roundCurrency(totalUsd * fxRate),
+  };
+}
+
+function ratesForTier(model: PricingModel, tier: Tier): CostRates | null {
+  if (tier === "standard") {
+    return {
+      input: model.input_per_million_usd,
+      cache: model.cached_input_per_million_usd,
+      output: model.output_per_million_usd,
+    };
+  }
+
+  const input = model.priority_input_per_million_usd;
+  const output = model.priority_output_per_million_usd;
+  if (input === null || input === undefined || output === null || output === undefined) {
+    return null;
+  }
+
+  return {
+    input,
+    cache: model.priority_cached_input_per_million_usd ?? null,
+    output,
+  };
+}
+
+export function calculateGuideCost(
+  model: PricingModel,
+  tier: Tier,
+  fxRate: number | null,
+): Example | null {
+  const rates = ratesForTier(model, tier);
+  return rates === null ? null : calculateExample(exampleUsage, rates, 1, 1, fxRate);
+}
+
+export function calculateLongContextGuideCost(
+  model: PricingModel,
+  fxRate: number | null,
+): Example | null {
+  if (model.long_context_threshold_tokens === null) return null;
+
+  const usage: TokenUsage = {
+    input: model.long_context_threshold_tokens + 50_000,
+    cache: exampleUsage.cache,
+    output: exampleUsage.output,
+    reasoning: exampleUsage.reasoning,
+  };
+  return calculateExample(
+    usage,
+    ratesForTier(model, "standard")!,
+    model.long_context_input_multiplier,
+    model.long_context_output_multiplier,
+    fxRate,
+  );
+}
+
+const copy = {
+  "pt-BR": {
+    eyebrow: "CONFIGURAÇÕES · TRANSPARÊNCIA",
+    title: "Como o custo é calculado",
+    intro:
+      "Do menor grão — uma chamada LLM — até o total: veja quais tokens entram na conta e como modelo, esforço, contexto e velocidade mudam o resultado.",
+    back: "Voltar ao dashboard",
+    model: "Modelo usado nos exemplos",
+    currency: "Moeda",
+    unavailable: "Indisponível",
+    millionRate: "por 1 milhão de tokens",
+    rateTitle: "1. Comece pelas tarifas do modelo",
+    rateIntro:
+      "O modelo escolhe a tabela de preços. Priority/Fast usa outra tabela quando o catálogo publica essas tarifas.",
+    standard: "Standard",
+    priority: "Priority / Fast",
+    input: "Input",
+    cache: "Cache",
+    output: "Output",
+    reasoning: "Reasoning",
+    ratio: "Priority ÷ Standard",
+    included: "Incluído no output (+0)",
+    noPublishedRate: "Sem tarifa publicada (custo adicional 0)",
+    conceptsTitle: "2. Entenda cada parte da chamada",
+    concepts: [
+      [
+        "Chamada LLM",
+        "É o menor grão do cálculo: uma requisição ao provedor, com um modelo e um tier de serviço.",
+      ],
+      [
+        "Input tokens",
+        "Tudo que entra no modelo: instruções, histórico, contexto, ferramentas e a mensagem atual.",
+      ],
+      [
+        "Cache tokens",
+        "São parte do input, não tokens extras. Primeiro subtraímos o cache do input e depois aplicamos sua tarifa própria.",
+      ],
+      [
+        "Output tokens",
+        "É o total produzido pelo modelo. O custo usa o output total informado pela telemetria.",
+      ],
+      [
+        "Reasoning tokens",
+        "São parte do output. O cálculo atual cobra o output uma vez e mantém reasoningUsd = 0, evitando cobrança dupla.",
+      ],
+      [
+        "Modelo e esforço",
+        "O modelo muda as tarifas. O esforço não tem multiplicador próprio, mas pode gerar mais reasoning, output ou ciclos e aumentar o custo indiretamente.",
+      ],
+      [
+        "Multiplicador de contexto",
+        "Acima do limite do modelo, o multiplicador de input vale também para cache; o multiplicador de output vale para todo o output.",
+      ],
+      [
+        "Multiplicador de velocidade",
+        "É a razão derivada entre o total Priority/Fast e o Standard. Serve para comparar; nunca é multiplicado de novo no total.",
+      ],
+    ],
+    exampleTitle: "3. Exemplo simples, parcela por parcela",
+    exampleIntro:
+      "Uma chamada com 100 mil tokens de input, dos quais 40 mil vieram do cache, e 20 mil tokens de output, dos quais 8 mil são reasoning.",
+    billableInput: "Input faturável",
+    operation: "Operação",
+    cost: "Custo",
+    total: "Total da chamada",
+    speedMultiplier: "Multiplicador de velocidade derivado",
+    longTitle: "4. Exemplo com contexto longo",
+    longIntro:
+      "Para realmente ultrapassar o limite, o exemplo usa o threshold do modelo + 50 mil tokens de input. A conta abaixo continua no tier Standard.",
+    threshold: "Limite do modelo",
+    longInput: "Input do exemplo longo",
+    priorityLong: "Priority/Fast + contexto longo",
+    priorityLongNote:
+      "Indisponível: sem uma combinação publicada no catálogo, o dashboard não inventa uma tarifa.",
+    finalNote:
+      "Regra prática: escolha o modelo e o tier, separe input de cache, cobre o output total uma única vez e só então aplique câmbio. Mais esforço só aumenta o custo quando aumenta o uso registrado.",
+  },
+  "en-US": {
+    eyebrow: "SETTINGS · TRANSPARENCY",
+    title: "How cost is calculated",
+    intro:
+      "From the smallest grain — one LLM call — to the total: see which tokens enter the calculation and how model, effort, context, and speed affect it.",
+    back: "Back to dashboard",
+    model: "Model used in the examples",
+    currency: "Currency",
+    unavailable: "Unavailable",
+    millionRate: "per 1 million tokens",
+    rateTitle: "1. Start with the model rates",
+    rateIntro:
+      "The model selects the price table. Priority/Fast uses a different table when the catalog publishes those rates.",
+    standard: "Standard",
+    priority: "Priority / Fast",
+    input: "Input",
+    cache: "Cache",
+    output: "Output",
+    reasoning: "Reasoning",
+    ratio: "Priority ÷ Standard",
+    included: "Included in output (+0)",
+    noPublishedRate: "No published rate (additional cost 0)",
+    conceptsTitle: "2. Understand each part of the call",
+    concepts: [
+      [
+        "LLM call",
+        "The smallest calculation grain: one provider request with one model and one service tier.",
+      ],
+      [
+        "Input tokens",
+        "Everything sent to the model: instructions, history, context, tools, and the current message.",
+      ],
+      [
+        "Cache tokens",
+        "They are part of input, not extra tokens. Cache is subtracted from input first, then its own rate is applied.",
+      ],
+      [
+        "Output tokens",
+        "Everything produced by the model. Cost uses the total output reported by telemetry.",
+      ],
+      [
+        "Reasoning tokens",
+        "They are part of output. Current math charges output once and keeps reasoningUsd = 0, preventing double billing.",
+      ],
+      [
+        "Model and effort",
+        "The model changes rates. Effort has no direct multiplier, but it can produce more reasoning, output, or cycles and indirectly raise cost.",
+      ],
+      [
+        "Context multiplier",
+        "Above the model threshold, the input multiplier also applies to cache; the output multiplier applies to all output.",
+      ],
+      [
+        "Speed multiplier",
+        "It is the derived ratio between Priority/Fast and Standard totals. It is only a comparison and is never multiplied into the total again.",
+      ],
+    ],
+    exampleTitle: "3. A simple example, component by component",
+    exampleIntro:
+      "One call with 100 thousand input tokens, including 40 thousand cache tokens, and 20 thousand output tokens, including 8 thousand reasoning tokens.",
+    billableInput: "Billable input",
+    operation: "Operation",
+    cost: "Cost",
+    total: "Call total",
+    speedMultiplier: "Derived speed multiplier",
+    longTitle: "4. Long-context example",
+    longIntro:
+      "To actually exceed the limit, this example uses the model threshold + 50 thousand input tokens. The calculation remains on Standard tier.",
+    threshold: "Model threshold",
+    longInput: "Long-example input",
+    priorityLong: "Priority/Fast + long context",
+    priorityLongNote:
+      "Unavailable: without a published combination in the catalog, the dashboard does not invent a rate.",
+    finalNote:
+      "Rule of thumb: choose model and tier, separate input from cache, charge total output once, then apply FX. Higher effort only raises cost when it raises recorded usage.",
+  },
+} as const;
+
+function formatMoney(
+  usdValue: number,
+  currency: Currency,
+  fxRate: number | null,
+  unavailable: string,
+): string {
+  if (currency === "BRL" && fxRate === null) return unavailable;
+  const value = currency === "BRL" ? usdValue * fxRate! : usdValue;
+  return new Intl.NumberFormat(currency === "BRL" ? "pt-BR" : "en-US", {
+    style: "currency",
+    currency,
+    minimumFractionDigits: 2,
+    maximumFractionDigits: 6,
+  }).format(value);
+}
+
+function formatRate(
+  rate: number | null | undefined,
+  currency: Currency,
+  fxRate: number | null,
+  unavailable: string,
+  noPublishedRate: string,
+): string {
+  if (rate === null || rate === undefined) return noPublishedRate;
+  return formatMoney(rate, currency, fxRate, unavailable);
+}
+
+function formatTokens(value: number, locale: DashboardLocale): string {
+  return new Intl.NumberFormat(locale).format(value);
+}
+
+function CostLines({
+  example,
+  currency,
+  fxRate,
+  locale,
+  labels,
+}: {
+  example: Example;
+  currency: Currency;
+  fxRate: number | null;
+  locale: DashboardLocale;
+  labels: (typeof copy)[DashboardLocale];
+}) {
+  const unavailable = labels.unavailable;
+  const uncachedInput = Math.max(example.usage.input - example.usage.cache, 0);
+  const inputMultiplier = example.inputMultiplier === 1 ? "" : ` × ${example.inputMultiplier}`;
+  const outputMultiplier = example.outputMultiplier === 1 ? "" : ` × ${example.outputMultiplier}`;
+  const cacheRate = example.rates.cache ?? 0;
+  const lines = [
+    {
+      label: labels.billableInput,
+      operation: `${formatTokens(example.usage.input, locale)} − ${formatTokens(example.usage.cache, locale)} = ${formatTokens(uncachedInput, locale)} tokens`,
+      cost: null,
+    },
+    {
+      label: labels.input,
+      operation: `${formatTokens(uncachedInput, locale)} ÷ 1M × ${formatRate(example.rates.input, currency, fxRate, unavailable, labels.noPublishedRate)}${inputMultiplier}`,
+      cost: example.inputUsd,
+    },
+    {
+      label: labels.cache,
+      operation: `${formatTokens(example.usage.cache, locale)} ÷ 1M × ${formatRate(cacheRate, currency, fxRate, unavailable, labels.noPublishedRate)}${inputMultiplier}`,
+      cost: example.cacheUsd,
+    },
+    {
+      label: labels.output,
+      operation: `${formatTokens(example.usage.output, locale)} ÷ 1M × ${formatRate(example.rates.output, currency, fxRate, unavailable, labels.noPublishedRate)}${outputMultiplier}`,
+      cost: example.outputUsd,
+    },
+    {
+      label: labels.reasoning,
+      operation: `${formatTokens(example.usage.reasoning, locale)} tokens ⊂ ${labels.output} → +0`,
+      cost: example.reasoningUsd,
+    },
+  ];
+
+  return (
+    <div className="cost-guide-calculation">
+      <div className="cost-guide-calculation-head" aria-hidden="true">
+        <span></span>
+        <span>{labels.operation}</span>
+        <span>{labels.cost}</span>
+      </div>
+      {lines.map((line) => (
+        <div className="cost-guide-calculation-line" key={line.label}>
+          <strong>{line.label}</strong>
+          <code>{line.operation}</code>
+          <span>
+            {line.cost === null ? "—" : formatMoney(line.cost, currency, fxRate, unavailable)}
+          </span>
+        </div>
+      ))}
+      <div className="cost-guide-calculation-total">
+        <strong>{labels.total}</strong>
+        <span>{formatMoney(example.totalUsd, currency, fxRate, unavailable)}</span>
+      </div>
+    </div>
+  );
+}
+
+export function CostCalculationGuidePage({
+  catalog,
+  fxRate,
+  locale,
+  onClose,
+}: {
+  catalog: PricingCatalog;
+  fxRate: FxRate | null;
+  locale: DashboardLocale;
+  onClose: () => void;
+}) {
+  const labels = copy[locale];
+  const [modelId, setModelId] = useState(catalog.models[0]?.id ?? "");
+  const [currency, setCurrency] = useState<Currency>("USD");
+  const model = useMemo(
+    () => catalog.models.find((item) => item.id === modelId) ?? catalog.models[0] ?? null,
+    [catalog.models, modelId],
+  );
+
+  if (model === null) {
+    return (
+      <main className="cost-guide">
+        <button onClick={onClose} type="button">
+          ← {labels.back}
+        </button>
+        <h1>{labels.title}</h1>
+        <p>{labels.unavailable}</p>
+      </main>
+    );
+  }
+
+  const fx = fxRate?.rate ?? null;
+  const standard = calculateGuideCost(model, "standard", fx)!;
+  const priority = calculateGuideCost(model, "priority", fx);
+  const longContext = calculateLongContextGuideCost(model, fx);
+  const speedMultiplier =
+    priority !== null && standard.totalUsd > 0 ? priority.totalUsd / standard.totalUsd : null;
+  const rateRows: Array<{
+    label: string;
+    standard: number | null;
+    priority: number | null | undefined;
+  }> = [
+    {
+      label: labels.input,
+      standard: model.input_per_million_usd,
+      priority: model.priority_input_per_million_usd,
+    },
+    {
+      label: labels.cache,
+      standard: model.cached_input_per_million_usd,
+      priority: model.priority_cached_input_per_million_usd,
+    },
+    {
+      label: labels.output,
+      standard: model.output_per_million_usd,
+      priority: model.priority_output_per_million_usd,
+    },
+  ];
+
+  return (
+    <main className="cost-guide">
+      <header>
+        <div>
+          <small>{labels.eyebrow}</small>
+          <h1>{labels.title}</h1>
+          <p>{labels.intro}</p>
+        </div>
+        <button onClick={onClose} type="button">
+          ← {labels.back}
+        </button>
+      </header>
+
+      <section className="cost-guide-controls" aria-label={labels.model}>
+        <label>
+          {labels.model}
+          <select value={model.id} onChange={(event) => setModelId(event.target.value)}>
+            {catalog.models.map((item) => (
+              <option key={item.id} value={item.id}>
+                {item.id}
+              </option>
+            ))}
+          </select>
+        </label>
+        <label>
+          {labels.currency}
+          <select
+            value={currency}
+            onChange={(event) => setCurrency(event.target.value as Currency)}
+          >
+            <option value="USD">USD</option>
+            <option value="BRL">
+              BRL {fx === null ? `(${labels.unavailable})` : `(1 USD = ${fx.toFixed(4)} BRL)`}
+            </option>
+          </select>
+        </label>
+      </section>
+
+      <section className="cost-guide-section">
+        <div className="cost-guide-section-heading">
+          <h2>{labels.rateTitle}</h2>
+          <p>{labels.rateIntro}</p>
+        </div>
+        <div className="cost-guide-table-wrap">
+          <table>
+            <caption>
+              {model.id} · {labels.millionRate}
+            </caption>
+            <thead>
+              <tr>
+                <th scope="col"></th>
+                <th scope="col">{labels.standard}</th>
+                <th scope="col">{labels.priority}</th>
+                <th scope="col">{labels.ratio}</th>
+              </tr>
+            </thead>
+            <tbody>
+              {rateRows.map((row) => (
+                <tr key={row.label}>
+                  <th scope="row">{row.label}</th>
+                  <td>
+                    {formatRate(
+                      row.standard,
+                      currency,
+                      fx,
+                      labels.unavailable,
+                      labels.noPublishedRate,
+                    )}
+                  </td>
+                  <td>
+                    {formatRate(
+                      row.priority,
+                      currency,
+                      fx,
+                      labels.unavailable,
+                      labels.noPublishedRate,
+                    )}
+                  </td>
+                  <td>
+                    {row.standard !== null &&
+                    row.standard > 0 &&
+                    row.priority !== null &&
+                    row.priority !== undefined
+                      ? `${(row.priority / row.standard).toFixed(2)}×`
+                      : labels.unavailable}
+                  </td>
+                </tr>
+              ))}
+              <tr>
+                <th scope="row">{labels.reasoning}</th>
+                <td colSpan={3}>{labels.included}</td>
+              </tr>
+            </tbody>
+          </table>
+        </div>
+      </section>
+
+      <section className="cost-guide-section">
+        <div className="cost-guide-section-heading">
+          <h2>{labels.conceptsTitle}</h2>
+        </div>
+        <div className="cost-guide-blocks">
+          {labels.concepts.map(([title, body]) => (
+            <article key={title}>
+              <strong>{title}</strong>
+              <p>{body}</p>
+            </article>
+          ))}
+        </div>
+      </section>
+
+      <section className="cost-guide-section">
+        <div className="cost-guide-section-heading">
+          <h2>{labels.exampleTitle}</h2>
+          <p>{labels.exampleIntro}</p>
+        </div>
+        <div className="cost-guide-example-grid">
+          <article className="cost-guide-example-card">
+            <h3>{labels.standard}</h3>
+            <CostLines
+              example={standard}
+              currency={currency}
+              fxRate={fx}
+              locale={locale}
+              labels={labels}
+            />
+          </article>
+          <article className="cost-guide-example-card">
+            <h3>{labels.priority}</h3>
+            {priority === null ? (
+              <p className="cost-guide-unavailable">{labels.unavailable}</p>
+            ) : (
+              <CostLines
+                example={priority}
+                currency={currency}
+                fxRate={fx}
+                locale={locale}
+                labels={labels}
+              />
+            )}
+          </article>
+        </div>
+        <div className="cost-guide-speed">
+          <span>{labels.speedMultiplier}</span>
+          <strong>
+            {speedMultiplier === null ? labels.unavailable : `${speedMultiplier.toFixed(2)}×`}
+          </strong>
+          <code>
+            {labels.priority} {labels.total} ÷ {labels.standard} {labels.total}
+          </code>
+        </div>
+      </section>
+
+      <section className="cost-guide-section">
+        <div className="cost-guide-section-heading">
+          <h2>{labels.longTitle}</h2>
+          <p>{labels.longIntro}</p>
+        </div>
+        <div className="cost-guide-context-summary">
+          <span>
+            {labels.threshold}:{" "}
+            <strong>
+              {model.long_context_threshold_tokens === null
+                ? labels.unavailable
+                : formatTokens(model.long_context_threshold_tokens, locale)}
+            </strong>
+          </span>
+          <span>
+            {labels.longInput}:{" "}
+            <strong>
+              {longContext === null
+                ? labels.unavailable
+                : formatTokens(longContext.usage.input, locale)}
+            </strong>
+          </span>
+          <span>
+            Input/cache: <strong>{model.long_context_input_multiplier}×</strong>
+          </span>
+          <span>
+            Output: <strong>{model.long_context_output_multiplier}×</strong>
+          </span>
+        </div>
+        {longContext === null ? (
+          <p className="cost-guide-unavailable">{labels.unavailable}</p>
+        ) : (
+          <CostLines
+            example={longContext}
+            currency={currency}
+            fxRate={fx}
+            locale={locale}
+            labels={labels}
+          />
+        )}
+        <div className="cost-guide-unavailable-combination">
+          <strong>
+            {labels.priorityLong}: {labels.unavailable}
+          </strong>
+          <p>{labels.priorityLongNote}</p>
+        </div>
+      </section>
+
+      <aside className="cost-guide-final-note">{labels.finalNote}</aside>
+    </main>
+  );
+}