@zanii/llm 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zanii
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,72 @@
+# @zanii/llm
+
+TypeScript and JavaScript client for [Zanii LLM](https://llm.zanii.agency): OpenAI-compatible
+inference where every call can produce a signed receipt on a public ledger.
+
+```bash
+npm install @zanii/llm            # add @zanii/core to verify proofs client-side
+```
+
+```js
+import { Zanii } from "@zanii/llm";
+
+const z = new Zanii();                                    // reads ZANII_LLM_API_KEY
+const answer = await z.chat("Summarise this claim in two sentences.", {
+  model: "glm-4.7-flash",
+});
+
+console.log(answer.text, answer.costAed, "AED");
+console.log((await z.verify(answer.receipt)).ok);
+```
+
+ESM with hand-written types beside it. No dependencies and no build step: a client library's
+dependency becomes a dependency in every application that installs it, and its build step becomes
+their build problem.
+
+## You may not need this
+
+The API speaks the OpenAI protocol, so the `openai` package works with one changed base URL and will
+keep working. This package adds what no OpenAI client knows about.
+
+| | |
+|---|---|
+| `answer.receipt`, `z.verify(...)` | the proof for a call, checked against the public ledger |
+| `InsufficientCredit` | a typed 402 carrying `topupUrl`, not an opaque error |
+| `z.usage()`, `z.balance()` | reconcile our invoice against your own records |
+| `maxSpendMicro` | a client-side ceiling; the request is never made |
+| `thinking: false` | skip the model's reasoning when the question does not need it |
+
+## Reasoning costs money
+
+These models reason before they answer. Reasoning tokens are billed like any other and come out of
+`maxTokens`. Measured on `glm-4.7-flash`, "name one thing Sharjah is known for" costs 412 output
+tokens and 4.4 seconds with reasoning on, and 22 tokens and 0.6 seconds with it off, for the same
+answer.
+
+```js
+await z.chat("Name one thing Sharjah is known for.", {
+  model: "glm-4.7-flash", thinking: false,
+});
+```
+
+If `answer.text` comes back empty, `answer.emptyBecause` says why and `answer.reasoningTokens` says
+where the budget went.
+
+## Streaming
+
+```js
+for await (const piece of z.stream("Write three lines about Dubai.", { model: "glm-4.7-flash" })) {
+  process.stdout.write(piece);
+}
+console.log(String(z.last));                              // the receipt, once the stream ends
+```
+
+## Parity
+
+The Python client [`zanii-llm-client`](https://pypi.org/project/zanii-llm-client/) mirrors this one
+method for method, in each language's idiom. A conformance suite runs the same cases through both
+and fails on a difference.
+
+---
+
+© Zanii, United Arab Emirates · [llm.zanii.agency](https://llm.zanii.agency) · info@zanii.agency

package/index.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Types for @zanii/llm, written by hand rather than generated.
+ *
+ * The package ships as plain ESM with these types beside it: no build step for us, and none forced
+ * on a consumer. TypeScript users get the same completion and checking they would from a compiled
+ * package; everyone else gets a file they can read.
+ */
+
+export declare const VERSION: string;
+
+export interface ZaniiOptions {
+  /** Defaults to ZANII_LLM_BASE_URL, then https://llm.zanii.agency/v1 */
+  baseUrl?: string;
+  /** Where receipts are verified. Defaults to https://ledger.zanii.agency */
+  ledgerUrl?: string;
+  timeoutMs?: number;
+  /** A client-side ceiling in micro-AED: a call past it throws before the request is made. */
+  maxSpendMicro?: number;
+  /** Ask for a receipt per call. Default true. */
+  receipts?: boolean;
+}
+
+export interface CallOptions {
+  model: string;
+  maxTokens?: number;
+  /**
+   * `false` turns the model's reasoning off. Reasoning tokens are billed like any other, and on a
+   * short question they dominate the bill: glm-4.7-flash answers "name one thing Sharjah is known
+   * for" in 412 output tokens with reasoning on and 22 with it off.
+   */
+  thinking?: boolean;
+  /** Your own id. The server meters it once, so a retry with the same id is free. */
+  requestId?: string;
+  [key: string]: unknown;
+}
+
+export declare class Receipt {
+  readonly hash: string;
+  readonly verifyUrl: string;
+  /** null until verify() has checked it against the ledger. */
+  ok: boolean | null;
+  index: number | null;
+  detail: { verifiedLocally?: boolean; note?: string };
+  readonly present: boolean;
+  toString(): string;
+}
+
+export interface Answer {
+  text: string;
+  receipt: Receipt;
+  costMicro: number;
+  /** The cost as dirhams and six decimal places, e.g. "0.000134". */
+  costAed: string;
+  balanceMicro: number;
+  requestId: string;
+  model: string;
+  usage: Record<string, unknown>;
+  finishReason: string;
+  /** Tokens spent thinking rather than answering. Billed: the GPU produced them. */
+  reasoningTokens: number;
+  raw: Record<string, unknown>;
+  /** Empty when `text` is present; otherwise why it is not, in words a caller can act on. */
+  emptyBecause: string;
+}
+
+export interface UsageTotals {
+  requests: number;
+  promptTokens: number;
+  completionTokens: number;
+  costMicro: number;
+  rows: Array<Record<string, unknown>>;
+}
+
+export declare class ZaniiError extends Error {
+  readonly status: number;
+  readonly code: string;
+  readonly detail: string;
+  readonly headers: Record<string, string>;
+}
+
+export declare class InsufficientCredit extends ZaniiError {
+  readonly topupUrl: string;
+  readonly balanceMicro: number;
+}
+
+export declare class RateLimited extends ZaniiError {
+  readonly retryAfterSeconds: number;
+}
+
+export declare class SpendLimitExceeded extends ZaniiError {}
+
+export declare class Zanii {
+  constructor(apiKey?: string, options?: ZaniiOptions);
+  readonly baseUrl: string;
+  readonly ledgerUrl: string;
+  spentMicro: number;
+  /** The receipt of the most recent stream, filled when the stream starts. */
+  last: Receipt | null;
+
+  chat(prompt: string | Array<Record<string, unknown>>, options: CallOptions): Promise<Answer>;
+  stream(prompt: string | Array<Record<string, unknown>>,
+         options: CallOptions): AsyncGenerator<string>;
+  models(): Promise<Array<Record<string, unknown>>>;
+  verify(receipt: Receipt | string, options?: { timeoutMs?: number }): Promise<Receipt>;
+  balance(): Promise<number>;
+  usage(since?: string): Promise<UsageTotals>;
+}
+
+export default Zanii;

package/index.js

@@ -0,0 +1,401 @@
+/**
+ * @zanii/llm — the thin layer over an OpenAI-compatible endpoint that an OpenAI client cannot give
+ * you.
+ *
+ *   import { Zanii } from "@zanii/llm";
+ *
+ *   const z = new Zanii();                                  // reads ZANII_LLM_API_KEY
+ *   const answer = await z.chat("Summarise this claim.", { model: "glm-4.7-flash" });
+ *   console.log(answer.text, String(answer.receipt));
+ *   console.log((await z.verify(answer.receipt)).ok);       // checked against the ledger, not us
+ *
+ * You do not need this package: the API speaks the OpenAI protocol, so the `openai` client works
+ * with one changed base URL, and anything here that broke that would be a bug. What it adds is the
+ * receipt and its verification, a typed InsufficientCredit carrying the top-up link, usage and
+ * balance for reconciliation, a client-side spend ceiling, and a key that is read from the
+ * environment and never sent over plain http.
+ *
+ * Shipped as plain ESM with hand-written types beside it. No dependencies, no build step: a client
+ * library's dependency becomes a dependency in every customer's application, and its build step
+ * becomes their build problem. Mirrors `zanii-llm` for Python, method for method, in each
+ * language's idiom — the conformance suite runs the same cases through both and fails on a
+ * difference.
+ */
+
+export const VERSION = "0.1.0";
+const DEFAULT_BASE = "https://llm.zanii.agency/v1";
+const DEFAULT_LEDGER = "https://ledger.zanii.agency";
+const USER_AGENT = `zanii-llm-js/${VERSION}`;
+
+/** Anything the API refused. `code` is the stable identifier; `message` is for a human. */
+export class ZaniiError extends Error {
+  constructor(status, code, message, headers = {}) {
+    super(`${code}: ${message}`);
+    this.name = "ZaniiError";
+    this.status = status;
+    this.code = code;
+    this.detail = message;
+    this.headers = headers;
+  }
+}
+
+/** 402. Carries where to top up, so a caller does not have to know the console's URL. */
+export class InsufficientCredit extends ZaniiError {
+  constructor(...args) {
+    super(...args);
+    this.name = "InsufficientCredit";
+  }
+
+  get topupUrl() {
+    return this.headers["x-zanii-topup-url"] || "https://llm.zanii.agency/app";
+  }
+
+  get balanceMicro() {
+    return Number(this.headers["x-zanii-balance-micro"] || 0);
+  }
+}
+
+export class RateLimited extends ZaniiError {
+  constructor(...args) {
+    super(...args);
+    this.name = "RateLimited";
+  }
+
+  get retryAfterSeconds() {
+    return Number(this.headers["retry-after"] || 1);
+  }
+}
+
+/** Raised before a call that could cost more than the caller allowed: the request is never made. */
+export class SpendLimitExceeded extends ZaniiError {
+  constructor(message) {
+    super(0, "spend_limit_exceeded", message);
+    this.name = "SpendLimitExceeded";
+  }
+}
+
+/** A call's proof. `ok` is only true once `verify()` has checked it against the ledger. */
+export class Receipt {
+  constructor(hash, verifyUrl = "") {
+    this.hash = hash;
+    this.verifyUrl = verifyUrl;
+    this.ok = null;
+    this.index = null;
+    this.detail = {};
+  }
+
+  toString() {
+    return this.hash;
+  }
+
+  get present() {
+    return Boolean(this.hash);
+  }
+}
+
+export class Zanii {
+  /**
+   * @param {string} [apiKey] defaults to ZANII_LLM_API_KEY, which is where a key belongs
+   * @param {{baseUrl?: string, ledgerUrl?: string, timeoutMs?: number, maxSpendMicro?: number,
+   *          receipts?: boolean}} [options]
+   */
+  constructor(apiKey, options = {}) {
+    const env = (typeof process !== "undefined" && process.env) || {};
+    this.apiKey = apiKey || env.ZANII_LLM_API_KEY || "";
+    if (!this.apiKey) throw new Error("no API key: pass one or set ZANII_LLM_API_KEY");
+
+    this.baseUrl = (options.baseUrl || env.ZANII_LLM_BASE_URL || DEFAULT_BASE).replace(/\/+$/, "");
+    if (this.baseUrl.startsWith("http://") && !isLocal(this.baseUrl)) {
+      // A key sent over plain http is a key in everyone's logs. Localhost is allowed for tests.
+      throw new Error("refusing to send an API key over http; use https");
+    }
+    this.ledgerUrl = (options.ledgerUrl || DEFAULT_LEDGER).replace(/\/+$/, "");
+    this.timeoutMs = options.timeoutMs ?? 120000;
+    this.receipts = options.receipts !== false;
+    this.maxSpendMicro = options.maxSpendMicro ?? null;
+    this.spentMicro = 0;
+    this.last = null;
+  }
+
+  // -- calling --------------------------------------------------------------
+
+  /**
+   * One completion.
+   *
+   * `thinking: false` turns the model's reasoning off, which is not a small saving on a short
+   * question: measured on glm-4.7-flash, "name one thing Sharjah is known for" costs 412 output
+   * tokens and 4.4 seconds with reasoning on, and 22 tokens and 0.6 seconds with it off, for the
+   * same answer. Reasoning tokens are billed like any other, because the GPU produced them.
+   */
+  async chat(prompt, { model, maxTokens, thinking, requestId, ...rest } = {}) {
+    const body = { model, messages: messagesFrom(prompt), ...thinkingOptions(thinking), ...rest };
+    if (maxTokens !== undefined) body.max_tokens = Number(maxTokens);
+    this.#checkBudget();
+    const { json, headers } = await this.#send("/chat/completions", body, requestId);
+    const answer = answerFrom(json, headers);
+    this.spentMicro += answer.costMicro;
+    return answer;
+  }
+
+  /**
+   * Yields text as it arrives. The receipt lands on `this.last` when the stream starts, because
+   * that is when the server sends its headers.
+   * @returns {AsyncGenerator<string>}
+   */
+  async *stream(prompt, { model, maxTokens, thinking, requestId, ...rest } = {}) {
+    const body = {
+      model, messages: messagesFrom(prompt), stream: true,
+      ...thinkingOptions(thinking), ...rest,
+    };
+    if (maxTokens !== undefined) body.max_tokens = Number(maxTokens);
+    this.#checkBudget();
+
+    const response = await this.#fetch("/chat/completions", {
+      method: "POST", headers: this.#headers(requestId), body: JSON.stringify(body),
+    });
+    if (!response.ok) throw await errorFrom(response);
+    this.last = new Receipt(response.headers.get("x-zanii-receipt-hash") || "",
+                            response.headers.get("x-zanii-verify-url") || "");
+
+    const decoder = new TextDecoder();
+    let buffer = "";
+    for await (const chunk of response.body) {
+      buffer += decoder.decode(chunk, { stream: true });
+      let cut;
+      while ((cut = buffer.indexOf("\n")) !== -1) {
+        const line = buffer.slice(0, cut).trim();
+        buffer = buffer.slice(cut + 1);
+        if (!line.startsWith("data:")) continue;
+        const payload = line.slice(5).trim();
+        if (!payload || payload === "[DONE]") continue;
+        let frame;
+        try {
+          frame = JSON.parse(payload);
+        } catch {
+          continue;                                  // a malformed frame must not end the stream
+        }
+        for (const choice of frame.choices || []) {
+          const piece = choice.delta && choice.delta.content;
+          if (piece) yield piece;
+        }
+      }
+    }
+  }
+
+  async models() {
+    const { json } = await this.#send("/models", null, undefined, "GET");
+    return json.data || [];
+  }
+
+  // -- proof ----------------------------------------------------------------
+
+  /**
+   * Fetch the Merkle proof from the ledger and check it. Does not call Zanii LLM at all.
+   *
+   * With `@zanii/core` installed the proof is verified cryptographically in the caller's own
+   * process. Without it, the proof is fetched and its shape checked, and `detail.verifiedLocally`
+   * says which of the two happened — a caller should never be misled about how much was proven.
+   */
+  async verify(receipt, { timeoutMs = 15000 } = {}) {
+    const hash = receipt instanceof Receipt ? receipt.hash : String(receipt || "");
+    if (!hash) throw new Error("no receipt hash to verify");
+    const out = new Receipt(hash, `${this.ledgerUrl}/verify/${hash}`);
+
+    let core = null;
+    try {
+      core = await import("@zanii/core");
+    } catch {
+      core = null;
+    }
+    const proof = await fetchJson(`${this.ledgerUrl}/v1/proof/${hash}`, timeoutMs);
+    out.index = proof.index ?? null;
+    if (core && typeof core.verifyInclusion === "function") {
+      out.ok = Boolean(core.verifyInclusion(proof.receipt, proof.index, proof.sth.size,
+                                            proof.proof, proof.sth.root));
+      out.detail = { verifiedLocally: true };
+    } else {
+      out.ok = Boolean(proof.proof !== undefined && proof.sth);
+      out.detail = { verifiedLocally: false,
+                     note: "install @zanii/core to verify the proof cryptographically" };
+    }
+    return out;
+  }
+
+  // -- money ----------------------------------------------------------------
+
+  /** Micro-AED left: a millionth of a dirham, because a call can cost less than a fils. */
+  async balance() {
+    const { json } = await this.#send("/balance", null, undefined, "GET");
+    return Number(json.balance_micro || 0);
+  }
+
+  /** What this account has spent, so you can reconcile our invoice against your own records. */
+  async usage(since = "") {
+    const path = "/usage" + (since ? `?since=${encodeURIComponent(since)}` : "");
+    const { json } = await this.#send(path, null, undefined, "GET");
+    const totals = json.totals || {};
+    return {
+      requests: Number(totals.requests || 0),
+      promptTokens: Number(totals.prompt_tokens || 0),
+      completionTokens: Number(totals.completion_tokens || 0),
+      costMicro: Number(totals.cost_micro || 0),
+      rows: json.recent || [],
+    };
+  }
+
+  // -- transport -------------------------------------------------------------
+
+  #checkBudget() {
+    if (this.maxSpendMicro === null) return;
+    if (this.spentMicro >= this.maxSpendMicro) {
+      throw new SpendLimitExceeded(
+        `this client has spent ${this.spentMicro} micro-AED of its ${this.maxSpendMicro} limit`);
+    }
+  }
+
+  #headers(requestId) {
+    const headers = {
+      "Authorization": `Bearer ${this.apiKey}`,
+      "Content-Type": "application/json",
+      "User-Agent": USER_AGENT,
+    };
+    // The server meters this id once, so a retry with the same one is free rather than charged.
+    if (requestId) headers["X-Request-Id"] = requestId;
+    if (this.receipts) headers["X-Zanii-Receipt"] = "on";
+    return headers;
+  }
+
+  async #fetch(path, init) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    try {
+      return await fetch(this.baseUrl + path, { ...init, signal: controller.signal });
+    } catch (cause) {
+      throw new ZaniiError(0, "unreachable", `could not reach ${this.baseUrl}: ${cause.message}`);
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  async #send(path, body, requestId, method = "POST") {
+    const response = await this.#fetch(path, {
+      method,
+      headers: this.#headers(requestId),
+      body: body === null ? undefined : JSON.stringify(body),
+    });
+    if (!response.ok) throw await errorFrom(response);
+    const text = await response.text();
+    return { json: text ? JSON.parse(text) : {}, headers: headersOf(response) };
+  }
+}
+
+// -- helpers ------------------------------------------------------------------
+
+function messagesFrom(prompt) {
+  return typeof prompt === "string" ? [{ role: "user", content: prompt }] : [...prompt];
+}
+
+/**
+ * How to ask a model to stop reasoning. Both spellings are sent because the servers behind this API
+ * accept different ones, and an ignored parameter costs nothing while a missing one costs the
+ * customer nineteen times the tokens.
+ */
+function thinkingOptions(thinking) {
+  if (thinking === undefined || thinking === null) return {};
+  if (thinking) return { chat_template_kwargs: { enable_thinking: true } };
+  return { chat_template_kwargs: { enable_thinking: false }, reasoning_effort: "none" };
+}
+
+function headersOf(response) {
+  const out = {};
+  response.headers.forEach((value, key) => {
+    out[key.toLowerCase()] = value;
+  });
+  return out;
+}
+
+function answerFrom(json, headers) {
+  const choice = (json.choices || [{}])[0] || {};
+  const message = choice.message || {};
+  const usage = json.usage || {};
+  const details = usage.completion_tokens_details || {};
+  const costMicro = Number(headers["x-zanii-cost-micro"] || 0);
+  const text = message.content || "";
+  const finishReason = choice.finish_reason || "";
+  const reasoningTokens = Number(details.reasoning_tokens || 0);
+  return {
+    text,
+    receipt: new Receipt(headers["x-zanii-receipt-hash"] || "",
+                         headers["x-zanii-verify-url"] || ""),
+    costMicro,
+    costAed: aed(costMicro),
+    balanceMicro: Number(headers["x-zanii-balance-micro"] || 0),
+    requestId: headers["x-request-id"] || "",
+    model: json.model || "",
+    usage,
+    finishReason,
+    reasoningTokens,
+    raw: json,
+    /**
+     * Why `text` is empty, in words a caller can act on. These models reason before answering and
+     * reasoning is charged against the same max_tokens budget, so a budget too small for both
+     * produces a perfectly successful call that returns nothing — the most confusing possible
+     * outcome.
+     */
+    emptyBecause: text ? "" : emptyBecause(finishReason, reasoningTokens),
+  };
+}
+
+function emptyBecause(finishReason, reasoningTokens) {
+  if (finishReason === "length" && reasoningTokens) {
+    return `the reply hit max_tokens after ${reasoningTokens} reasoning tokens, before any answer `
+      + "was written: raise max_tokens";
+  }
+  if (finishReason === "length") {
+    return "the reply hit max_tokens before any text was produced: raise max_tokens";
+  }
+  if (finishReason === "content_filter") return "the model stopped on a content filter";
+  return `the model returned no text (finish_reason=${finishReason || "unknown"})`;
+}
+
+function aed(micro) {
+  const whole = Math.trunc(micro / 1000000);
+  const frac = String(Math.abs(micro) % 1000000).padStart(6, "0");
+  return `${whole}.${frac}`;
+}
+
+async function errorFrom(response) {
+  const raw = await response.text();
+  let error = {};
+  try {
+    error = (JSON.parse(raw) || {}).error || {};
+  } catch {
+    error = {};
+  }
+  const code = String(error.code || `http_${response.status}`);
+  const message = String(error.message || raw.slice(0, 200) || "request failed");
+  const headers = headersOf(response);
+  if (response.status === 402) return new InsufficientCredit(402, code, message, headers);
+  if (response.status === 429) return new RateLimited(429, code, message, headers);
+  return new ZaniiError(response.status, code, message, headers);
+}
+
+async function fetchJson(url, timeoutMs) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const response = await fetch(url, {
+      headers: { "User-Agent": USER_AGENT }, signal: controller.signal,
+    });
+    if (!response.ok) throw new ZaniiError(response.status, "proof_unavailable", await response.text());
+    return await response.json();
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function isLocal(url) {
+  return url.includes("://127.0.0.1") || url.includes("://localhost") || url.includes("://[::1]");
+}
+
+export default Zanii;

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@zanii/llm",
+  "version": "0.1.0",
+  "description": "Client for the Zanii LLM API: OpenAI-compatible inference with a verifiable receipt for every call",
+  "type": "module",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js"
+    }
+  },
+  "files": ["index.js", "index.d.ts", "README.md", "LICENSE"],
+  "engines": { "node": ">=18" },
+  "dependencies": {},
+  "peerDependencies": {
+    "@zanii/core": ">=0.24.0"
+  },
+  "peerDependenciesMeta": {
+    "@zanii/core": { "optional": true }
+  },
+    "keywords": ["llm", "openai", "inference", "receipts", "audit", "uae", "zanii"],
+  "author": "Zanii <info@zanii.agency>",
+  "license": "MIT",
+  "homepage": "https://llm.zanii.agency",
+  "repository": { "type": "git", "url": "git+https://github.com/vigilancetrent/zanii-llm.git", "directory": "sdk/js" },
+  "bugs": { "url": "https://llm.zanii.agency/contact" }
+}