@circuit-llm/inference 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Circuit LLM
+
+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,28 @@
+# @circuit-llm/inference
+
+> OpenAI-compatible client for Circuit's decentralized 72B, served across a mesh of independent GPUs and **paid per request in CIRC** over x402.
+
+Part of the **[Circuit SDK](https://github.com/Circuit-LLM/circuit-sdk)**. [Getting started →](https://github.com/Circuit-LLM/circuit-sdk/blob/main/docs/getting-started.md)
+
+## Install
+
+```bash
+npm install @circuit-llm/inference @circuit-llm/wallet
+```
+
+## Usage
+
+```ts
+import { makeWallet } from '@circuit-llm/wallet';
+import { Inference } from '@circuit-llm/inference';
+
+const ai = new Inference({ wallet: makeWallet() });   // wallet from CIRCUIT_WALLET
+const res = await ai.chat({ messages: [{ role: 'user', content: 'what is a falling knife?' }] });
+console.log(res.content);
+```
+
+- `chat(params)` — completion, paid automatically per call.
+- `chatVerified(params, { acceptedKeys })` — returns a **signed inference receipt** for [Verified Intents](https://github.com/Circuit-LLM/circuit-sdk/blob/main/docs/verified-intents.md).
+- `listModels()`, `signingKey()`.
+
+Cap spend per call: `new Inference({ wallet, maxSpendRaw: 500_000_000n })`.

package/dist/index.d.ts

@@ -0,0 +1,78 @@
+import { ChatMessage, CircuitConfig } from '@circuit-llm/core';
+import { PaymentQuote, X402Client, PaymentWallet } from '@circuit-llm/x402';
+import { InferenceReceipt } from '@circuit-llm/attest';
+
+interface InferenceOptions {
+    /** A pre-built payment client. If omitted, one is built from `wallet`. */
+    x402?: X402Client;
+    /** Wallet to pay with (used only when `x402` is not provided). */
+    wallet?: PaymentWallet;
+    /** Per-call CIRC spend cap (raw base units), passed to the built X402Client. */
+    maxSpendRaw?: bigint;
+    /** Approval/notification hook for payments. */
+    onPay?: (quote: PaymentQuote) => void | Promise<void>;
+    config?: CircuitConfig;
+    /** Override the inference base URL (else config.endpoints.inference). */
+    baseUrl?: string;
+    /** Default model id (else config.model, e.g. 'circuit'). */
+    model?: string;
+    /** X-Internal-Key bypass for trusted/co-located callers (skips payment). */
+    internalKey?: string;
+    fetchImpl?: typeof fetch;
+}
+interface ChatParams {
+    messages: ChatMessage[];
+    model?: string;
+    maxTokens?: number;
+    temperature?: number;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}
+interface Usage {
+    completion_tokens?: number;
+    prompt_tokens?: number;
+    total_tokens?: number;
+}
+interface ChatResult {
+    content: string;
+    usage: Usage | null;
+    paymentTx: string | null;
+    quote: PaymentQuote | null;
+    raw: unknown;
+}
+type ChatStreamResult = Omit<ChatResult, 'raw'>;
+declare class Inference {
+    private readonly x402;
+    private readonly fetchImpl;
+    private readonly base;
+    private readonly model;
+    private readonly internalKey?;
+    constructor(opts?: InferenceOptions);
+    private headers;
+    private body;
+    /** List available model ids (free). */
+    listModels(): Promise<string[]>;
+    /** Non-streaming completion. Pays CIRC if the gateway answers 402. */
+    chat(params: ChatParams): Promise<ChatResult>;
+    /** Non-streaming completion with a signed InferenceReceipt (`?signed=1`): proves the
+     *  mesh produced this output for this input. The agent forwards `receipt` as evidence so
+     *  the off-box signer trusts the AI's call (a short answer like "BUY" becomes `verdict`).
+     *  Pass `acceptedKeys` to verify the receipt here too (throws on a bad receipt). */
+    chatVerified(params: ChatParams, opts?: {
+        acceptedKeys?: Record<string, 'data' | 'inference'>;
+        maxAgeMs?: number;
+    }): Promise<ChatResult & {
+        receipt: InferenceReceipt;
+    }>;
+    /** The inference signing public key (raw hex) to pin in `acceptedKeys`. */
+    signingKey(): Promise<{
+        key: string;
+        alg: string;
+        kind: string;
+    }>;
+    /** Streaming completion. Yields token deltas as they arrive; the generator's
+     *  return value is the full { content, usage, paymentTx, quote }. */
+    chatStream(params: ChatParams): AsyncGenerator<string, ChatStreamResult, void>;
+}
+
+export { type ChatParams, type ChatResult, type ChatStreamResult, Inference, type InferenceOptions, type Usage };

package/dist/index.js

@@ -0,0 +1,150 @@
+// src/inference.ts
+import { DEFAULT_CONFIG } from "@circuit-llm/core";
+import {
+  X402Client
+} from "@circuit-llm/x402";
+import { verifyEvidence } from "@circuit-llm/attest";
+var Inference = class {
+  x402;
+  fetchImpl;
+  base;
+  model;
+  internalKey;
+  constructor(opts = {}) {
+    this.fetchImpl = opts.fetchImpl ?? fetch;
+    this.x402 = opts.x402 ?? new X402Client({
+      wallet: opts.wallet,
+      maxSpendRaw: opts.maxSpendRaw,
+      onPay: opts.onPay,
+      fetchImpl: this.fetchImpl
+    });
+    const cfg = opts.config ?? DEFAULT_CONFIG;
+    this.base = (opts.baseUrl ?? cfg.endpoints.inference).replace(/\/$/, "");
+    this.model = opts.model ?? cfg.model;
+    this.internalKey = opts.internalKey;
+  }
+  headers() {
+    const h = { "Content-Type": "application/json" };
+    if (this.internalKey) h["X-Internal-Key"] = this.internalKey;
+    return h;
+  }
+  body(params, stream) {
+    return JSON.stringify({
+      model: params.model ?? this.model,
+      messages: params.messages,
+      max_tokens: params.maxTokens ?? 512,
+      temperature: params.temperature ?? 0.5,
+      stream
+    });
+  }
+  /** List available model ids (free). */
+  async listModels() {
+    const { data } = await this.x402.json(`${this.base}/models`, {
+      headers: this.headers()
+    });
+    return (data?.data ?? []).map((m) => m.id);
+  }
+  /** Non-streaming completion. Pays CIRC if the gateway answers 402. */
+  async chat(params) {
+    const { data, paymentTx, quote } = await this.x402.json(`${this.base}/chat/completions`, {
+      method: "POST",
+      headers: this.headers(),
+      body: this.body(params, false),
+      signal: params.signal ?? AbortSignal.timeout(params.timeoutMs ?? 12e4)
+    });
+    return {
+      content: data?.choices?.[0]?.message?.content?.trim() ?? "",
+      usage: data?.usage ?? null,
+      paymentTx,
+      quote,
+      raw: data
+    };
+  }
+  // ── verified intents (docs/verified-intents.md) ────────────────────────────
+  /** Non-streaming completion with a signed InferenceReceipt (`?signed=1`): proves the
+   *  mesh produced this output for this input. The agent forwards `receipt` as evidence so
+   *  the off-box signer trusts the AI's call (a short answer like "BUY" becomes `verdict`).
+   *  Pass `acceptedKeys` to verify the receipt here too (throws on a bad receipt). */
+  async chatVerified(params, opts = {}) {
+    const { data, paymentTx, quote } = await this.x402.json(`${this.base}/chat/completions?signed=1`, {
+      method: "POST",
+      headers: this.headers(),
+      body: this.body(params, false),
+      signal: params.signal ?? AbortSignal.timeout(params.timeoutMs ?? 12e4)
+    });
+    const receipt = data?.attestation;
+    if (!receipt || receipt.kind !== "inference-receipt") throw new Error("gateway did not return an InferenceReceipt \u2014 is receipt signing enabled?");
+    if (opts.acceptedKeys) {
+      const r = verifyEvidence(receipt, { acceptedKeys: opts.acceptedKeys, maxAgeMs: opts.maxAgeMs });
+      if (!r.ok) throw new Error(`inference-receipt failed verification: ${r.code}`);
+    }
+    return {
+      content: data?.choices?.[0]?.message?.content?.trim() ?? "",
+      usage: data?.usage ?? null,
+      paymentTx,
+      quote,
+      raw: data,
+      receipt
+    };
+  }
+  /** The inference signing public key (raw hex) to pin in `acceptedKeys`. */
+  async signingKey() {
+    const root = this.base.replace(/\/v1$/, "");
+    const { data } = await this.x402.json(
+      `${root}/.well-known/circuit-inference-key`,
+      { headers: this.headers() }
+    );
+    return data;
+  }
+  /** Streaming completion. Yields token deltas as they arrive; the generator's
+   *  return value is the full { content, usage, paymentTx, quote }. */
+  async *chatStream(params) {
+    const url = `${this.base}/chat/completions`;
+    const body = this.body(params, true);
+    const { resp, paymentTx, quote } = await this.x402.request(
+      (extra) => this.fetchImpl(url, {
+        method: "POST",
+        headers: { ...this.headers(), ...extra },
+        body,
+        signal: params.signal ?? AbortSignal.timeout(params.timeoutMs ?? 12e4)
+      })
+    );
+    if (!resp.ok) {
+      const e = await resp.json().catch(() => ({}));
+      throw new Error(`Inference ${resp.status}: ${e.error ?? e.message ?? ""}`);
+    }
+    if (!resp.body) throw new Error("Inference response had no body to stream");
+    let content = "";
+    let usage = null;
+    const reader = resp.body.getReader();
+    const decoder = new TextDecoder();
+    let buf = "";
+    for (; ; ) {
+      const { value, done } = await reader.read();
+      if (done) break;
+      buf += decoder.decode(value, { stream: true });
+      const lines = buf.split("\n");
+      buf = lines.pop() ?? "";
+      for (const line of lines) {
+        const t = line.trim();
+        if (!t.startsWith("data:")) continue;
+        const payload = t.slice(5).trim();
+        if (payload === "[DONE]") continue;
+        try {
+          const json = JSON.parse(payload);
+          const delta = json.choices?.[0]?.delta?.content;
+          if (delta) {
+            content += delta;
+            yield delta;
+          }
+          if (json.usage) usage = json.usage;
+        } catch {
+        }
+      }
+    }
+    return { content, usage, paymentTx, quote };
+  }
+};
+export {
+  Inference
+};

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@circuit-llm/inference",
+  "version": "0.2.1",
+  "description": "Circuit SDK inference — OpenAI-compatible client for the decentralized DLLM mesh, paid per call in CIRC (x402).",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "development": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "test": "node --experimental-strip-types --conditions=development --test test/*.test.ts",
+    "typecheck": "tsc -p tsconfig.json",
+    "build": "tsup src/index.ts --format esm --dts --clean --out-dir dist",
+    "prepack": "tsup src/index.ts --format esm --dts --clean --out-dir dist"
+  },
+  "dependencies": {
+    "@circuit-llm/attest": "0.2.1",
+    "@circuit-llm/core": "0.2.1",
+    "@circuit-llm/x402": "0.2.1"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Circuit-LLM/circuit-sdk.git",
+    "directory": "packages/inference"
+  },
+  "homepage": "https://github.com/Circuit-LLM/circuit-sdk/tree/main/packages/inference#readme",
+  "bugs": {
+    "url": "https://github.com/Circuit-LLM/circuit-sdk/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}