@zanii/blackbox 0.13.0 → 0.14.0

package/README.md

@@ -83,6 +83,12 @@ verifyAnswerCredential(credential, lines, bodies, packs); // { ok, problems }: t
 
 The same checks run offline as pure functions: `toolHallucinations`, `groundingFindings`, `factsIn`, `loadReferencePacks`, `answerRisk`, `detectorAccuracy`.
 
+## New in 0.14.0
+
+- Price uplifts (`uplifts` in a price table): US-only inference, regional endpoints and fast modes priced above list, per deployment (`upliftPercent`).
+- Statements in any currency: the `fx:<CUR>:<rate>` unit, `fxRate(currency)` (the ECB's rate through Frankfurter), and `blackbox statement --currency EUR` with the rate, date and source in the statement.
+- Tax invoices for zero-rated and reverse-charge customers (`vat_treatment`).
+
 ## New in 0.13.0
 
 - `fromOtlp(body)`: OpenTelemetry spans (GenAI semconv or OpenInference) as session events, the mapping behind gateway v0.15's `POST /v1/traces`. Point any framework's OTLP exporter at the gateway with the session's token, and its spans join the record.

package/dist/billing/index.d.ts

@@ -31,6 +31,8 @@ export interface Plans {
 }
 /** Parses a plans file (spec/billing.md §1); throws on anything that isn't integer fils. */
 export declare function loadPlans(bytes: Uint8Array): Plans;
+/** spec/billing.md §5b: how VAT applies to a customer. */
+export type VatTreatment = "standard" | "zero_rated" | "reverse_charge";
 export interface TaxInvoiceInput {
     number: string;
     issued_at: string;
@@ -53,6 +55,8 @@ export interface TaxInvoiceInput {
         sessions: number;
     };
     vat_percent?: number;
+    /** §5b: `zero_rated` and `reverse_charge` invoice VAT at 0%, with a note saying why. */
+    vat_treatment?: VatTreatment;
 }
 /** spec/billing.md §5: the tax invoice document. */
 export declare function taxInvoice(input: TaxInvoiceInput): {
@@ -90,6 +94,8 @@ export declare function taxInvoice(input: TaxInvoiceInput): {
         events: number;
         sessions: number;
     };
+    vat_treatment?: "reverse_charge" | "zero_rated";
+    vat_note?: string;
     total_aed: string;
 };
 export type TaxInvoice = ReturnType<typeof taxInvoice>;

package/dist/billing/index.js

@@ -69,6 +69,10 @@ export function loadPlans(bytes) {
     }
     return doc;
 }
+const VAT_NOTES = {
+    zero_rated: "Zero-rated supply (export of services): VAT at 0%",
+    reverse_charge: "Reverse charge: the customer accounts for the VAT",
+};
 /** The month's `[from, to)` and its last day (spec/billing.md §5). */
 function period(month) {
     const [y, m] = month.split("-").map(Number);
@@ -79,7 +83,8 @@ function period(month) {
 /** spec/billing.md §5: the tax invoice document. */
 export function taxInvoice(input) {
     const p = period(input.month);
-    const inv = invoice(input.plan, input.usage, input.vat_percent ?? 5);
+    const treatment = input.vat_treatment ?? "standard";
+    const inv = invoice(input.plan, input.usage, treatment === "standard" ? (input.vat_percent ?? 5) : 0);
     return {
         v: 1,
         title: "Tax Invoice",
@@ -101,6 +106,9 @@ export function taxInvoice(input) {
         plan: { id: input.plan_id, name: input.plan.name, version: input.plans_version },
         usage: { events: input.usage.events, sessions: input.usage.sessions },
         ...inv,
+        ...(treatment !== "standard"
+            ? { vat_treatment: treatment, vat_note: VAT_NOTES[treatment] }
+            : {}),
         total_aed: formatAed(inv.total_fils),
     };
 }
@@ -146,6 +154,7 @@ export function renderTaxInvoice(d) {
         `| VAT ${d.vat_percent}% | ${aed(d.vat_fils)} |`,
         `| **Total** | **${aed(d.total_fils)}** |`,
         "",
+        ...(d.vat_note ? [`VAT: ${d.vat_note}.`, ""] : []),
         `Plan: ${oneLine(d.plan.name)} (${d.plan.id}, plans ${d.plan.version}). Usage: ${grouped(d.usage.events)} events, ${grouped(d.usage.sessions)} sessions.`,
         "",
     ];

package/dist/cli.js

@@ -43,7 +43,7 @@ const USAGE = `usage (spec/cli.md):
   blackbox policy-from-zanii <zanii-policy.json> [--out <file>]
   blackbox policy-to-zanii <policy.json> [--out <file>]
   blackbox statement --provider anthropic|openai --from <YYYY-MM-DD> --to <YYYY-MM-DD> [--out <file>]
-  blackbox statement --provider csv --file <f> --model-column <name> --amount-column <name> --unit usd|cents|micro_usd|aed [--delimiter <c>] --from <d> --to <d> [--out <file>]
+  blackbox statement --provider csv --file <f> --model-column <name> --amount-column <name> (--unit usd|cents|micro_usd|aed | --currency <CUR> [--rate <usd per unit>] [--rate-date <d>]) [--delimiter <c>] --from <d> --to <d> [--out <file>]
   blackbox statement --provider custom --connector <file> --from <d> --to <d> [--out <file>]
   blackbox preflight --require <items> [--optional <items>]
   blackbox --version
@@ -956,8 +956,29 @@ async function statementAny(provider, flags, from, to) {
     if (provider === "csv") {
         const model = flags["model-column"];
         const amount = flags["amount-column"];
-        const unit = flags.unit;
+        let unit = flags.unit;
         const delimiter = flags.delimiter;
+        // spec/money.md §2c: another currency, at a stated rate or the ECB's for the day
+        let fx;
+        if (flags.currency) {
+            try {
+                fx = flags.rate
+                    ? {
+                        currency: flags.currency,
+                        usd_per_unit: flags.rate,
+                        date: flags["rate-date"] ?? to,
+                        source: "stated",
+                    }
+                    : await money.fxRate(flags.currency, {
+                        ...(flags["rate-date"] ? { date: flags["rate-date"] } : {}),
+                        ...(process.env.BLACKBOX_FX_URL ? { url: process.env.BLACKBOX_FX_URL } : {}),
+                    });
+                unit = money.fxUnit(fx.currency, fx.usd_per_unit);
+            }
+            catch (e) {
+                return message(e);
+            }
+        }
         if (!flags.file ||
             !model ||
             !amount ||
@@ -972,7 +993,7 @@ async function statementAny(provider, flags, from, to) {
                 unit,
                 ...(delimiter ? { delimiter } : {}),
             });
-            return { doc: { provider: "csv", from, to, lines: statement.lines } };
+            return { doc: { provider: "csv", from, to, lines: statement.lines, ...(fx ? { fx } : {}) } };
         }
         catch (e) {
             return message(e);

package/dist/cost/index.d.ts

@@ -33,6 +33,19 @@ export interface PriceTable {
     currency: "USD";
     unit: "micro_usd_per_mtok";
     models: Record<string, ModelPrice>;
+    /** spec/cost.md §1a: percentages added to a call's table price when it matches. */
+    uplifts?: Uplift[];
+}
+/** spec/cost.md §1a: a call that matches every condition given costs `percent` more. */
+export interface Uplift {
+    /** The configured provider id the call went to (`bedrock-eu`). */
+    provider?: string;
+    /** A model id prefix (`claude-opus-5`). */
+    model?: string;
+    /** Flattened usage fields and the values they must have (`{"inference_geo": "us"}`). */
+    usage?: Record<string, string>;
+    percent: number;
+    note?: string;
 }
 export interface Tokens {
     input: number;
@@ -58,6 +71,8 @@ export interface CallCost {
         service?: string;
         context_above?: number;
     };
+    /** spec/cost.md §1a: the uplift applied, when one matched. */
+    uplift_percent?: number;
     source?: "reported";
 }
 export interface CostReport {
@@ -126,6 +141,9 @@ export declare function priceCall(call: {
 }, table: PriceTable): Omit<CallCost, "seq" | "model"> & {
     key: string | null;
 };
+/** spec/cost.md §1a: the sum of the uplifts a call matches (0 when none): its provider, a model
+ * prefix, and usage fields, each only when the uplift names it. */
+export declare function upliftPercent(table: PriceTable, provider: string | null, model: string, usage: Record<string, unknown>): number;
 /** fils at the CBUAE peg (3.6725 AED / USD), rounded half up. */
 export declare function toAedFils(microUsd: number): number;
 export declare function formatAed(fils: number): string;

package/dist/cost/index.js

@@ -40,6 +40,24 @@ export function loadPrices(bytes) {
         if (p.status !== undefined && p.status !== "deprecated" && p.status !== "beta")
             throw new Error(`price table: ${model}.status must be deprecated or beta`);
     }
+    if (table.uplifts !== undefined) {
+        if (!Array.isArray(table.uplifts))
+            throw new Error("price table: uplifts must be a list");
+        for (const [i, u] of table.uplifts.entries()) {
+            const at = `price table: uplifts[${i}]`;
+            if (!Number.isSafeInteger(u?.percent) || u.percent < 1 || u.percent > 1000)
+                throw new Error(`${at}.percent must be an integer 1-1000`);
+            if (u.provider !== undefined && typeof u.provider !== "string")
+                throw new Error(`${at}.provider must be a string`);
+            if (u.model !== undefined && typeof u.model !== "string")
+                throw new Error(`${at}.model must be a string`);
+            if (u.usage !== undefined &&
+                (typeof u.usage !== "object" ||
+                    u.usage === null ||
+                    Object.values(u.usage).some((v) => typeof v !== "string")))
+                throw new Error(`${at}.usage must map usage fields to strings`);
+        }
+    }
     return { table, sha256: `sha256:${createHash("sha256").update(bytes).digest("hex")}` };
 }
 /** The exact model, else the longest table key the model starts with; null when there's none. */
@@ -194,12 +212,15 @@ export function priceCall(call, table) {
     const match = call.model === null ? null : priceFor(call.model, table, call.provider);
     if (match) {
         const { price, tier } = effectivePrice(match.price, tokens, call.serviceTier);
+        const base = callMicroUsd(tokens, price, requests);
+        const uplift = upliftPercent(table, call.provider ?? null, call.model, call.usage);
         return {
             key: match.key,
             tokens,
-            micro_usd: callMicroUsd(tokens, price, requests),
+            micro_usd: uplift ? Math.floor((base * (100 + uplift) + 50) / 100) : base,
             ...(requests ? { requests } : {}),
             ...(tier ? { tier } : {}),
+            ...(uplift ? { uplift_percent: uplift } : {}),
         };
     }
     if (typeof call.reportedMicroUsd === "number")
@@ -212,6 +233,21 @@ export function priceCall(call, table) {
         };
     return { key: null, tokens, micro_usd: null, ...(requests ? { requests } : {}) };
 }
+/** spec/cost.md §1a: the sum of the uplifts a call matches (0 when none): its provider, a model
+ * prefix, and usage fields, each only when the uplift names it. */
+export function upliftPercent(table, provider, model, usage) {
+    let percent = 0;
+    for (const u of table.uplifts ?? []) {
+        if (u.provider !== undefined && u.provider !== provider)
+            continue;
+        if (u.model !== undefined && !model.startsWith(u.model))
+            continue;
+        if (u.usage && Object.entries(u.usage).some(([k, v]) => String(usage[k] ?? "") !== v))
+            continue;
+        percent += u.percent;
+    }
+    return percent;
+}
 /** fils at the CBUAE peg (3.6725 AED / USD), rounded half up. */
 export function toAedFils(microUsd) {
     return Math.floor((microUsd * 36725 + 50_000_000) / 100_000_000);

package/dist/money/index.d.ts

@@ -45,7 +45,23 @@ export declare function fuel(summary: Summary, budgetMicroUsd: number | null, ba
     p90_total_micro_usd: number | null;
     verdict: string;
 };
-export type AmountUnit = "usd" | "cents" | "micro_usd" | "aed";
+/** `fx:<ISO code>:<USD per unit>` (`fx:EUR:1.0821`): another currency at a stated rate (§2c). */
+export type AmountUnit = "usd" | "cents" | "micro_usd" | "aed" | `fx:${string}`;
+/** spec/money.md §2c: the unit for amounts in `currency` at `usdPerUnit` (a decimal string). */
+export declare function fxUnit(currency: string, usdPerUnit: string): AmountUnit;
+export interface FxRate {
+    currency: string;
+    /** USD per one unit of the currency, as the source gave it (a decimal string). */
+    usd_per_unit: string;
+    /** The rate's own date (a reference rate is set once a working day). */
+    date: string;
+    source: string;
+}
+/** spec/money.md §2c: the ECB reference rate for a day (or the latest), through Frankfurter. */
+export declare function fxRate(currency: string, opts?: {
+    date?: string;
+    url?: string;
+}): Promise<FxRate>;
 /** spec/money.md §2a-b: an exact decimal amount (string, or a JSON number's text) to integer
  * micro-USD, rounded half up. `unit` is what the amount counts. */
 export declare function decimalToMicroUsd(value: unknown, unit: AmountUnit): number;

package/dist/money/index.js

@@ -112,23 +112,66 @@ const UNITS = {
     micro_usd: [0, 1n],
     aed: [10, 36725n],
 };
+const FX_UNIT = /^fx:([A-Z]{3}):(\d{1,9})(?:\.(\d{1,12}))?$/;
+/** A unit as [power of ten, multiplier, divisor]; null for one that isn't. */
+function unitScale(unit) {
+    const s = Object.hasOwn(UNITS, unit) ? UNITS[unit] : undefined;
+    if (s)
+        return [s[0], 1n, s[1]];
+    const m = FX_UNIT.exec(unit);
+    if (!m)
+        return null;
+    const frac = m[3] ?? "";
+    const rate = BigInt(`${m[2]}${frac}`);
+    return rate === 0n ? null : [6 - frac.length, rate, 1n];
+}
+/** spec/money.md §2c: the unit for amounts in `currency` at `usdPerUnit` (a decimal string). */
+export function fxUnit(currency, usdPerUnit) {
+    const unit = `fx:${currency}:${usdPerUnit}`;
+    if (!unitScale(unit))
+        throw new Error(`not a currency and rate: ${currency} ${usdPerUnit}`);
+    return unit;
+}
+/** spec/money.md §2c: the ECB reference rate for a day (or the latest), through Frankfurter. */
+export async function fxRate(currency, opts = {}) {
+    if (!/^[A-Z]{3}$/.test(currency))
+        throw new Error(`not an ISO 4217 code: ${currency}`);
+    if (opts.date !== undefined && !/^\d{4}-\d{2}-\d{2}$/.test(opts.date))
+        throw new Error(`not a date: ${opts.date}`);
+    const base = (opts.url ?? "https://api.frankfurter.dev").replace(/\/+$/, "");
+    const res = await fetch(`${base}/v1/${opts.date ?? "latest"}?base=${currency}&symbols=USD`, {
+        signal: AbortSignal.timeout(10_000),
+    });
+    if (!res.ok)
+        throw new Error(`the rate service answered HTTP ${res.status}`);
+    const body = (await res.json());
+    const usd = body.rates?.USD;
+    if (typeof usd !== "number" || !(usd > 0) || typeof body.date !== "string")
+        throw new Error("the rate service's answer has no USD rate");
+    return {
+        currency,
+        usd_per_unit: String(usd),
+        date: body.date,
+        source: "ECB reference rate, via Frankfurter",
+    };
+}
 /** spec/money.md §2a-b: an exact decimal amount (string, or a JSON number's text) to integer
  * micro-USD, rounded half up. `unit` is what the amount counts. */
 export function decimalToMicroUsd(value, unit) {
     const text = typeof value === "number" && Number.isFinite(value) ? String(value) : value;
     const m = typeof text === "string" ? DECIMAL.exec(text.trim()) : null;
-    const scale = UNITS[unit];
+    const scale = unitScale(unit);
     if (!m || !scale)
         throw new Error(`not a non-negative decimal amount: ${JSON.stringify(value)}`);
     const frac = m[2] ?? "";
-    const digits = BigInt(`${m[1]}${frac}`);
+    const digits = BigInt(`${m[1]}${frac}`) * scale[1];
     if (digits === 0n)
         return 0;
     const k = Number(m[3] ?? 0) - frac.length + scale[0];
     if (k > 30)
         throw new Error(`amount too large: ${JSON.stringify(value)}`);
     const num = k >= 0 ? digits * 10n ** BigInt(k) : digits;
-    const den = scale[1] * (k >= 0 ? 1n : 10n ** BigInt(-k));
+    const den = scale[2] * (k >= 0 ? 1n : 10n ** BigInt(-k));
     let micro = num / den;
     if ((num % den) * 2n >= den)
         micro += 1n;
@@ -312,8 +355,8 @@ export function checkConnector(value) {
     for (const k of ["results", "model", "amount"])
         if (typeof c[k] !== "string" || !PATH.test(c[k]))
             return `${k} must be a path`;
-    if (!c.unit || !(c.unit in UNITS))
-        return "unit must be usd, cents, micro_usd or aed";
+    if (!c.unit || !unitScale(c.unit))
+        return "unit must be usd, cents, micro_usd, aed or fx:<CUR>:<USD per unit>";
     if (c.currency !== undefined &&
         (typeof c.currency?.path !== "string" ||
             !PATH.test(c.currency.path) ||

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.13.0";
+export declare const VERSION = "0.14.0";

package/dist/version.js

@@ -1,2 +1,2 @@
 // The SDK version, on its own so the CLI can print it without loading the whole SDK.
-export const VERSION = "0.13.0";
+export const VERSION = "0.14.0";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zanii/blackbox",
   "license": "Apache-2.0",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "The flight recorder for AI agents: sessions, a zero-loss spool, framework hooks, approvals, and offline verification of the gateway's hash-chained record.",
   "keywords": [
     "ai-agents",