Mirror chat/completions from Python SDK; drop ML inference#5

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
adambalogh merged 4 commits into from
May 5, 2026
Merged

Mirror chat/completions from Python SDK; drop ML inference #5

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
188baa6
Mirror chat/completions from Python SDK; drop ML inference
claude May 5, 2026
0b3aa8d
Add llm_chat and llm_chat_stream examples
claude May 5, 2026
4482c63
Use official x402-fetch package; settle in OPG on Base
claude May 5, 2026
e8b86ed
Add ESLint flat config, smoke tests, and CI workflow
claude May 5, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 30 additions & 0 deletions .github/workflows/ci.yml
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
name: CI

on:
push:
branches: [main]
pull_request:
branches: [main]

jobs:
ci:
runs-on: ubuntu-latest
strategy:
matrix:
node-version: [18.x, 20.x]
steps:
- uses: actions/checkout@v4

- name: Use Node.js ${{ matrix.node-version }}
uses: actions/setup-node@v4
with:
node-version: ${{ matrix.node-version }}
cache: npm

- run: npm ci

- run: npm run lint

- run: npm test

- run: npm run build
136 changes: 102 additions & 34 deletions README.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -1,55 +1,123 @@
# OpenGradient TypeScript SDK

A TypeScript/JavaScript SDK for performing on-chain inference using the OpenGradient network. Run machine learning models and LLMs directly on the blockchain with robust transaction handling and retry mechanisms.
A TypeScript/JavaScript SDK for performing LLM chat and completion via OpenGradient's TEE (Trusted Execution Environment) with [x402](https://x402.org) payment protocol support.

## Installation

```bash
npm install opengradient-sdk
```

## Requirements

- Node.js 18+ (for global `fetch`)
- A funded EVM wallet on Base (settlement happens in OPG on the Base network via [x402](https://x402.org))

## Quick Start

```typescript
import { Client, InferenceMode, LLMInferenceMode } from 'opengradient-sdk';
import { Client, TEE_LLM } from "opengradient-sdk";

// Initialize the client
const client = new Client({
privateKey: 'your-private-key'
privateKey: process.env.PRIVATE_KEY!, // EVM private key (with or without 0x prefix)
});

// Non-streaming chat
const result = await client.llm.chat({
model: TEE_LLM.CLAUDE_3_5_HAIKU,
messages: [{ role: "user", content: "Hello!" }],
maxTokens: 100,
});
console.log(result.chatOutput?.content);
console.log("payment hash:", result.paymentHash);
```

### Streaming chat

```typescript
import { Client, TEE_LLM } from "opengradient-sdk";

const client = new Client({ privateKey: process.env.PRIVATE_KEY! });

const stream = client.llm.chat({
model: TEE_LLM.CLAUDE_3_5_HAIKU,
messages: [{ role: "user", content: "Stream me a haiku." }],
stream: true,
});

for await (const chunk of stream) {
process.stdout.write(chunk.choices[0]?.delta.content ?? "");
}
```

### Tool / function calling

```typescript
const result = await client.llm.chat({
model: TEE_LLM.GPT_4O,
messages: [{ role: "user", content: "What's the weather in Paris?" }],
tools: [
{
type: "function",
function: {
name: "get_weather",
description: "Get current weather for a city",
parameters: {
type: "object",
properties: { city: { type: "string" } },
required: ["city"],
},
},
},
],
});
console.log(result.chatOutput?.tool_calls);
```

### Completion

```typescript
const result = await client.llm.completion({
model: TEE_LLM.CLAUDE_3_5_HAIKU,
prompt: "The capital of France is",
maxTokens: 20,
});
console.log(result.completionOutput);
```

## x402 Settlement Modes

```typescript
import { X402SettlementMode } from "opengradient-sdk";

await client.llm.chat({
model: TEE_LLM.GPT_4O,
messages: [{ role: "user", content: "Hi" }],
x402SettlementMode: X402SettlementMode.SETTLE_BATCH, // default
});
```

- `SETTLE` — records input/output hashes only (most privacy-preserving).
- `SETTLE_METADATA` — records full model info, complete input/output, and metadata.
- `SETTLE_BATCH` — aggregates multiple inferences into a single on-chain settlement (most cost-efficient, default).

// Run LLM chat inference
const [txHash, finishReason, response] = await client.llmChat(
'Qwen/Qwen2.5-72B-Instruct',
LLMInferenceMode.VANILLA,
[{ role: 'user', content: 'Hello!' }],
100 // max tokens
);

// Run general model inference
const modelInput = {
num_input1: [1.0, 2.0, 3.0],
num_input2: 10,
str_input1: ["hello", "ONNXY"],
str_input2: " world"
};

const [txHash, output] = await client.infer(
"QmbUqS93oc4JTLMHwpVxsE39mhNxy6hpf6Py3r9oANr8aZ",
InferenceMode.VANILLA,
modelInput
);
## Development

```bash
npm install # install deps
npm run lint # ESLint over src/
npm test # Jest unit tests
npm run build # tsc → dist/
npm run format # prettier --write
```

## Features
CI runs `lint`, `test`, and `build` on Node 18 and 20 — see `.github/workflows/ci.yml`.

- On-chain ML model inference
- LLM completion and chat interfaces
- Support for vanilla, ZKML and TEE (Trusted Execution Environment) inference modes
- Automatic transaction retry with configurable parameters
- Built-in gas estimation and management
- Tool calling support for LLM chat
## Available models

## Contributing
See `TEE_LLM` for the supported models, including:

We welcome contributions! Please check our contribution guidelines for more details.
- `TEE_LLM.GPT_4O`, `TEE_LLM.GPT_4_1_2025_04_14`, `TEE_LLM.O4_MINI`
- `TEE_LLM.CLAUDE_3_5_HAIKU`, `TEE_LLM.CLAUDE_3_7_SONNET`, `TEE_LLM.CLAUDE_4_0_SONNET`
- `TEE_LLM.GEMINI_2_0_FLASH`, `TEE_LLM.GEMINI_2_5_FLASH`, `TEE_LLM.GEMINI_2_5_FLASH_LITE`, `TEE_LLM.GEMINI_2_5_PRO`
- `TEE_LLM.GROK_2_1212`, `TEE_LLM.GROK_2_VISION_LATEST`, `TEE_LLM.GROK_3_BETA`, `TEE_LLM.GROK_3_MINI_BETA`, `TEE_LLM.GROK_4_1_FAST`, `TEE_LLM.GROK_4_1_FAST_NON_REASONING`
29 changes: 29 additions & 0 deletions eslint.config.js
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
const tseslint = require("@typescript-eslint/eslint-plugin");
const tsparser = require("@typescript-eslint/parser");

module.exports = [
{
ignores: ["dist/**", "node_modules/**", "examples/**"],
},
{
files: ["src/**/*.ts"],
languageOptions: {
parser: tsparser,
parserOptions: {
ecmaVersion: 2020,
sourceType: "module",
},
},
plugins: {
"@typescript-eslint": tseslint,
},
rules: {
...tseslint.configs.recommended.rules,
"@typescript-eslint/no-unused-vars": [
"error",
{ argsIgnorePattern: "^_", varsIgnorePattern: "^_" },
],
"@typescript-eslint/no-explicit-any": "off",
},
},
];
35 changes: 35 additions & 0 deletions examples/llm_chat.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
// Run a non-streaming chat completion against a TEE-hosted LLM through
// OpenGradient with x402 payments.
//
// Run with: OG_PRIVATE_KEY=0x... npx ts-node examples/llm_chat.ts

import { Client, TEE_LLM, X402SettlementMode } from "../src";

async function main() {
const privateKey = process.env.OG_PRIVATE_KEY;
if (!privateKey) {
throw new Error("OG_PRIVATE_KEY environment variable is not set");
}

const client = new Client({ privateKey });

const messages = [
{ role: "user", content: "What is Python?" },
{ role: "assistant", content: "Python is a high-level programming language." },
{ role: "user", content: "What makes it good for beginners?" },
];

const result = await client.llm.chat({
model: TEE_LLM.GPT_4_1_2025_04_14,
messages,
x402SettlementMode: X402SettlementMode.SETTLE_METADATA,
});

console.log(`Response: ${result.chatOutput?.content}`);
console.log(`Payment hash: ${result.paymentHash}`);
}

main().catch((err) => {
console.error(err);
process.exit(1);
});
38 changes: 38 additions & 0 deletions examples/llm_chat_stream.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
// Stream a chat completion from a TEE-hosted LLM through OpenGradient
// with x402 payments.
//
// Run with: OG_PRIVATE_KEY=0x... npx ts-node examples/llm_chat_stream.ts

import { Client, TEE_LLM, X402SettlementMode } from "../src";

async function main() {
const privateKey = process.env.OG_PRIVATE_KEY;
if (!privateKey) {
throw new Error("OG_PRIVATE_KEY environment variable is not set");
}

const client = new Client({ privateKey });

const messages = [
{ role: "user", content: "Describe to me the 7 network layers?" },
];

const stream = client.llm.chat({
model: TEE_LLM.GPT_4_1_2025_04_14,
messages,
x402SettlementMode: X402SettlementMode.SETTLE_METADATA,
stream: true,
maxTokens: 1000,
});

for await (const chunk of stream) {
const content = chunk.choices[0]?.delta.content;
if (content) process.stdout.write(content);
}
process.stdout.write("\n");
}

main().catch((err) => {
console.error(err);
process.exit(1);
});
Loading
Loading
, 'i'); if (__m === '*' || __re.test(location.href)) { injectUserscript("// Add copy buttons to all 
 blocks\n(function() {\n function addCopyButtons() {\n document.querySelectorAll('pre code').forEach(function(codeBlock) {\n if (codeBlock.parentElement.hasAttribute('data-copy-added')) return;\n codeBlock.parentElement.setAttribute('data-copy-added', 'true');\n \n var btn = document.createElement('button');\n btn.textContent = 'Copy';\n btn.style.cssText = 'position:absolute;top:4px;right:4px;padding:2px 8px;font-size:11px;background:#4ecdc4;border:none;border-radius:4px;color:#1a1a2e;cursor:pointer;opacity:0.7;transition:opacity 0.2s;';\n btn.onmouseover = function() { this.style.opacity = '1'; };\n btn.onmouseout = function() { this.style.opacity = '0.7'; };\n btn.onclick = function() {\n navigator.clipboard.writeText(codeBlock.textContent).then(function() {\n btn.textContent = 'Copied!';\n setTimeout(function() { btn.textContent = 'Copy'; }, 1500);\n });\n };\n codeBlock.parentElement.style.position = 'relative';\n codeBlock.parentElement.appendChild(btn);\n });\n }\n \n addCopyButtons();\n \n // Re-run on dynamic content\n var observer = new MutationObserver(addCopyButtons);\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Add Copy Buttons to Code Blocks");
}
} catch(__e) { console.warn('[Userscript:Add Copy Buttons to Code Blocks]', __e); }
})();
(function(){
try {
var __m = "github.com";
var __re = new RegExp('^' + "github\\.com" + '

Skip to content
Mirror chat/completions from Python SDK; drop ML inference#5

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

adambalogh
merged 4 commits into

from

May 5, 2026
 Merged


Mirror chat/completions from Python SDK; drop ML inference
#5
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


4 commits


Select commit
Hold shift + click to select a range
188baa6

Mirror chat/completions from Python SDK; drop ML inference


claude May 5, 2026
0b3aa8d

Add llm_chat and llm_chat_stream examples


claude May 5, 2026
4482c63

Use official x402-fetch package; settle in OPG on Base


claude May 5, 2026
e8b86ed

Add ESLint flat config, smoke tests, and CI workflow


claude May 5, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


30 changes: 30 additions & 0 deletions
.github/workflows/ci.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
name: CI

on:
 push:
 branches: [main]
 pull_request:
 branches: [main]

jobs:
 ci:
 runs-on: ubuntu-latest
 strategy:
 matrix:
 node-version: [18.x, 20.x]
 steps:
 - uses: actions/checkout@v4

 - name: Use Node.js ${{ matrix.node-version }}
 uses: actions/setup-node@v4
 with:
 node-version: ${{ matrix.node-version }}
 cache: npm

 - run: npm ci

 - run: npm run lint

 - run: npm test

 - run: npm run build

136 changes: 102 additions & 34 deletions
README.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,55 +1,123 @@
# OpenGradient TypeScript SDK

A TypeScript/JavaScript SDK for performing on-chain inference using the OpenGradient network. Run machine learning models and LLMs directly on the blockchain with robust transaction handling and retry mechanisms.
A TypeScript/JavaScript SDK for performing LLM chat and completion via OpenGradient's TEE (Trusted Execution Environment) with [x402](https://x402.org) payment protocol support.

## Installation

```bash
npm install opengradient-sdk
```

## Requirements

- Node.js 18+ (for global `fetch`)
- A funded EVM wallet on Base (settlement happens in OPG on the Base network via [x402](https://x402.org))

## Quick Start

```typescript
import { Client, InferenceMode, LLMInferenceMode } from 'opengradient-sdk';
import { Client, TEE_LLM } from "opengradient-sdk";

// Initialize the client
const client = new Client({
 privateKey: 'your-private-key'
 privateKey: process.env.PRIVATE_KEY!, // EVM private key (with or without 0x prefix)
});

// Non-streaming chat
const result = await client.llm.chat({
 model: TEE_LLM.CLAUDE_3_5_HAIKU,
 messages: [{ role: "user", content: "Hello!" }],
 maxTokens: 100,
});
console.log(result.chatOutput?.content);
console.log("payment hash:", result.paymentHash);
```

### Streaming chat

```typescript
import { Client, TEE_LLM } from "opengradient-sdk";

const client = new Client({ privateKey: process.env.PRIVATE_KEY! });

const stream = client.llm.chat({
 model: TEE_LLM.CLAUDE_3_5_HAIKU,
 messages: [{ role: "user", content: "Stream me a haiku." }],
 stream: true,
});

for await (const chunk of stream) {
 process.stdout.write(chunk.choices[0]?.delta.content ?? "");
}
```

### Tool / function calling

```typescript
const result = await client.llm.chat({
 model: TEE_LLM.GPT_4O,
 messages: [{ role: "user", content: "What's the weather in Paris?" }],
 tools: [
 {
 type: "function",
 function: {
 name: "get_weather",
 description: "Get current weather for a city",
 parameters: {
 type: "object",
 properties: { city: { type: "string" } },
 required: ["city"],
 },
 },
 },
 ],
});
console.log(result.chatOutput?.tool_calls);
```

### Completion

```typescript
const result = await client.llm.completion({
 model: TEE_LLM.CLAUDE_3_5_HAIKU,
 prompt: "The capital of France is",
 maxTokens: 20,
});
console.log(result.completionOutput);
```

## x402 Settlement Modes

```typescript
import { X402SettlementMode } from "opengradient-sdk";

await client.llm.chat({
 model: TEE_LLM.GPT_4O,
 messages: [{ role: "user", content: "Hi" }],
 x402SettlementMode: X402SettlementMode.SETTLE_BATCH, // default
});
```

- `SETTLE` — records input/output hashes only (most privacy-preserving).
- `SETTLE_METADATA` — records full model info, complete input/output, and metadata.
- `SETTLE_BATCH` — aggregates multiple inferences into a single on-chain settlement (most cost-efficient, default).

// Run LLM chat inference
const [txHash, finishReason, response] = await client.llmChat(
 'Qwen/Qwen2.5-72B-Instruct',
 LLMInferenceMode.VANILLA,
 [{ role: 'user', content: 'Hello!' }],
 100 // max tokens
);

// Run general model inference
const modelInput = {
 num_input1: [1.0, 2.0, 3.0],
 num_input2: 10,
 str_input1: ["hello", "ONNXY"],
 str_input2: " world"
};

const [txHash, output] = await client.infer(
 "QmbUqS93oc4JTLMHwpVxsE39mhNxy6hpf6Py3r9oANr8aZ",
 InferenceMode.VANILLA,
 modelInput
);
## Development

```bash
npm install # install deps
npm run lint # ESLint over src/
npm test # Jest unit tests
npm run build # tsc → dist/
npm run format # prettier --write
```

## Features
CI runs `lint`, `test`, and `build` on Node 18 and 20 — see `.github/workflows/ci.yml`.

- On-chain ML model inference
- LLM completion and chat interfaces
- Support for vanilla, ZKML and TEE (Trusted Execution Environment) inference modes
- Automatic transaction retry with configurable parameters
- Built-in gas estimation and management
- Tool calling support for LLM chat
## Available models

## Contributing
See `TEE_LLM` for the supported models, including:

We welcome contributions! Please check our contribution guidelines for more details.
- `TEE_LLM.GPT_4O`, `TEE_LLM.GPT_4_1_2025_04_14`, `TEE_LLM.O4_MINI`
- `TEE_LLM.CLAUDE_3_5_HAIKU`, `TEE_LLM.CLAUDE_3_7_SONNET`, `TEE_LLM.CLAUDE_4_0_SONNET`
- `TEE_LLM.GEMINI_2_0_FLASH`, `TEE_LLM.GEMINI_2_5_FLASH`, `TEE_LLM.GEMINI_2_5_FLASH_LITE`, `TEE_LLM.GEMINI_2_5_PRO`
- `TEE_LLM.GROK_2_1212`, `TEE_LLM.GROK_2_VISION_LATEST`, `TEE_LLM.GROK_3_BETA`, `TEE_LLM.GROK_3_MINI_BETA`, `TEE_LLM.GROK_4_1_FAST`, `TEE_LLM.GROK_4_1_FAST_NON_REASONING`

29 changes: 29 additions & 0 deletions
eslint.config.js

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
const tseslint = require("@typescript-eslint/eslint-plugin");
const tsparser = require("@typescript-eslint/parser");

module.exports = [
 {
 ignores: ["dist/**", "node_modules/**", "examples/**"],
 },
 {
 files: ["src/**/*.ts"],
 languageOptions: {
 parser: tsparser,
 parserOptions: {
 ecmaVersion: 2020,
 sourceType: "module",
 },
 },
 plugins: {
 "@typescript-eslint": tseslint,
 },
 rules: {
 ...tseslint.configs.recommended.rules,
 "@typescript-eslint/no-unused-vars": [
 "error",
 { argsIgnorePattern: "^_", varsIgnorePattern: "^_" },
 ],
 "@typescript-eslint/no-explicit-any": "off",
 },
 },
];

35 changes: 35 additions & 0 deletions
examples/llm_chat.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
// Run a non-streaming chat completion against a TEE-hosted LLM through
// OpenGradient with x402 payments.
//
// Run with: OG_PRIVATE_KEY=0x... npx ts-node examples/llm_chat.ts

import { Client, TEE_LLM, X402SettlementMode } from "../src";

async function main() {
 const privateKey = process.env.OG_PRIVATE_KEY;
 if (!privateKey) {
 throw new Error("OG_PRIVATE_KEY environment variable is not set");
 }

 const client = new Client({ privateKey });

 const messages = [
 { role: "user", content: "What is Python?" },
 { role: "assistant", content: "Python is a high-level programming language." },
 { role: "user", content: "What makes it good for beginners?" },
 ];

 const result = await client.llm.chat({
 model: TEE_LLM.GPT_4_1_2025_04_14,
 messages,
 x402SettlementMode: X402SettlementMode.SETTLE_METADATA,
 });

 console.log(`Response: ${result.chatOutput?.content}`);
 console.log(`Payment hash: ${result.paymentHash}`);
}

main().catch((err) => {
 console.error(err);
 process.exit(1);
});

38 changes: 38 additions & 0 deletions
examples/llm_chat_stream.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
// Stream a chat completion from a TEE-hosted LLM through OpenGradient
// with x402 payments.
//
// Run with: OG_PRIVATE_KEY=0x... npx ts-node examples/llm_chat_stream.ts

import { Client, TEE_LLM, X402SettlementMode } from "../src";

async function main() {
 const privateKey = process.env.OG_PRIVATE_KEY;
 if (!privateKey) {
 throw new Error("OG_PRIVATE_KEY environment variable is not set");
 }

 const client = new Client({ privateKey });

 const messages = [
 { role: "user", content: "Describe to me the 7 network layers?" },
 ];

 const stream = client.llm.chat({
 model: TEE_LLM.GPT_4_1_2025_04_14,
 messages,
 x402SettlementMode: X402SettlementMode.SETTLE_METADATA,
 stream: true,
 maxTokens: 1000,
 });

 for await (const chunk of stream) {
 const content = chunk.choices[0]?.delta.content;
 if (content) process.stdout.write(content);
 }
 process.stdout.write("\n");
}

main().catch((err) => {
 console.error(err);
 process.exit(1);
});
Loading
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Force GitHub README to respect dark mode\n(function() {\n var style = document.createElement('style');\n style.textContent = '\n .markdown-body {\n color-scheme: dark light;\n }\n .markdown-body pre { background: #161b22 !important; }\n .markdown-body code { background: rgba(110, 118, 129, 0.4) !important; }\n .markdown-body table th, .markdown-body table td { border-color: #30363d !important; }\n .markdown-body img { background: #0d1117; }\n .markdown-body blockquote { border-left-color: #8b949e; }\n .markdown-body hr { border-color: #30363d; }\n ';\n document.head.appendChild(style);\n})();", "GitHub Dark Mode README Fix");
}
} catch(__e) { console.warn('[Userscript:GitHub Dark Mode README Fix]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
Mirror chat/completions from Python SDK; drop ML inference#5

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

adambalogh
merged 4 commits into

from

May 5, 2026
 Merged


Mirror chat/completions from Python SDK; drop ML inference
#5
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


4 commits


Select commit
Hold shift + click to select a range
188baa6

Mirror chat/completions from Python SDK; drop ML inference


claude May 5, 2026
0b3aa8d

Add llm_chat and llm_chat_stream examples


claude May 5, 2026
4482c63

Use official x402-fetch package; settle in OPG on Base


claude May 5, 2026
e8b86ed

Add ESLint flat config, smoke tests, and CI workflow


claude May 5, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


30 changes: 30 additions & 0 deletions
.github/workflows/ci.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
name: CI

on:
 push:
 branches: [main]
 pull_request:
 branches: [main]

jobs:
 ci:
 runs-on: ubuntu-latest
 strategy:
 matrix:
 node-version: [18.x, 20.x]
 steps:
 - uses: actions/checkout@v4

 - name: Use Node.js ${{ matrix.node-version }}
 uses: actions/setup-node@v4
 with:
 node-version: ${{ matrix.node-version }}
 cache: npm

 - run: npm ci

 - run: npm run lint

 - run: npm test

 - run: npm run build

136 changes: 102 additions & 34 deletions
README.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,55 +1,123 @@
# OpenGradient TypeScript SDK

A TypeScript/JavaScript SDK for performing on-chain inference using the OpenGradient network. Run machine learning models and LLMs directly on the blockchain with robust transaction handling and retry mechanisms.
A TypeScript/JavaScript SDK for performing LLM chat and completion via OpenGradient's TEE (Trusted Execution Environment) with [x402](https://x402.org) payment protocol support.

## Installation

```bash
npm install opengradient-sdk
```

## Requirements

- Node.js 18+ (for global `fetch`)
- A funded EVM wallet on Base (settlement happens in OPG on the Base network via [x402](https://x402.org))

## Quick Start

```typescript
import { Client, InferenceMode, LLMInferenceMode } from 'opengradient-sdk';
import { Client, TEE_LLM } from "opengradient-sdk";

// Initialize the client
const client = new Client({
 privateKey: 'your-private-key'
 privateKey: process.env.PRIVATE_KEY!, // EVM private key (with or without 0x prefix)
});

// Non-streaming chat
const result = await client.llm.chat({
 model: TEE_LLM.CLAUDE_3_5_HAIKU,
 messages: [{ role: "user", content: "Hello!" }],
 maxTokens: 100,
});
console.log(result.chatOutput?.content);
console.log("payment hash:", result.paymentHash);
```

### Streaming chat

```typescript
import { Client, TEE_LLM } from "opengradient-sdk";

const client = new Client({ privateKey: process.env.PRIVATE_KEY! });

const stream = client.llm.chat({
 model: TEE_LLM.CLAUDE_3_5_HAIKU,
 messages: [{ role: "user", content: "Stream me a haiku." }],
 stream: true,
});

for await (const chunk of stream) {
 process.stdout.write(chunk.choices[0]?.delta.content ?? "");
}
```

### Tool / function calling

```typescript
const result = await client.llm.chat({
 model: TEE_LLM.GPT_4O,
 messages: [{ role: "user", content: "What's the weather in Paris?" }],
 tools: [
 {
 type: "function",
 function: {
 name: "get_weather",
 description: "Get current weather for a city",
 parameters: {
 type: "object",
 properties: { city: { type: "string" } },
 required: ["city"],
 },
 },
 },
 ],
});
console.log(result.chatOutput?.tool_calls);
```

### Completion

```typescript
const result = await client.llm.completion({
 model: TEE_LLM.CLAUDE_3_5_HAIKU,
 prompt: "The capital of France is",
 maxTokens: 20,
});
console.log(result.completionOutput);
```

## x402 Settlement Modes

```typescript
import { X402SettlementMode } from "opengradient-sdk";

await client.llm.chat({
 model: TEE_LLM.GPT_4O,
 messages: [{ role: "user", content: "Hi" }],
 x402SettlementMode: X402SettlementMode.SETTLE_BATCH, // default
});
```

- `SETTLE` — records input/output hashes only (most privacy-preserving).
- `SETTLE_METADATA` — records full model info, complete input/output, and metadata.
- `SETTLE_BATCH` — aggregates multiple inferences into a single on-chain settlement (most cost-efficient, default).

// Run LLM chat inference
const [txHash, finishReason, response] = await client.llmChat(
 'Qwen/Qwen2.5-72B-Instruct',
 LLMInferenceMode.VANILLA,
 [{ role: 'user', content: 'Hello!' }],
 100 // max tokens
);

// Run general model inference
const modelInput = {
 num_input1: [1.0, 2.0, 3.0],
 num_input2: 10,
 str_input1: ["hello", "ONNXY"],
 str_input2: " world"
};

const [txHash, output] = await client.infer(
 "QmbUqS93oc4JTLMHwpVxsE39mhNxy6hpf6Py3r9oANr8aZ",
 InferenceMode.VANILLA,
 modelInput
);
## Development

```bash
npm install # install deps
npm run lint # ESLint over src/
npm test # Jest unit tests
npm run build # tsc → dist/
npm run format # prettier --write
```

## Features
CI runs `lint`, `test`, and `build` on Node 18 and 20 — see `.github/workflows/ci.yml`.

- On-chain ML model inference
- LLM completion and chat interfaces
- Support for vanilla, ZKML and TEE (Trusted Execution Environment) inference modes
- Automatic transaction retry with configurable parameters
- Built-in gas estimation and management
- Tool calling support for LLM chat
## Available models

## Contributing
See `TEE_LLM` for the supported models, including:

We welcome contributions! Please check our contribution guidelines for more details.
- `TEE_LLM.GPT_4O`, `TEE_LLM.GPT_4_1_2025_04_14`, `TEE_LLM.O4_MINI`
- `TEE_LLM.CLAUDE_3_5_HAIKU`, `TEE_LLM.CLAUDE_3_7_SONNET`, `TEE_LLM.CLAUDE_4_0_SONNET`
- `TEE_LLM.GEMINI_2_0_FLASH`, `TEE_LLM.GEMINI_2_5_FLASH`, `TEE_LLM.GEMINI_2_5_FLASH_LITE`, `TEE_LLM.GEMINI_2_5_PRO`
- `TEE_LLM.GROK_2_1212`, `TEE_LLM.GROK_2_VISION_LATEST`, `TEE_LLM.GROK_3_BETA`, `TEE_LLM.GROK_3_MINI_BETA`, `TEE_LLM.GROK_4_1_FAST`, `TEE_LLM.GROK_4_1_FAST_NON_REASONING`

29 changes: 29 additions & 0 deletions
eslint.config.js

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
const tseslint = require("@typescript-eslint/eslint-plugin");
const tsparser = require("@typescript-eslint/parser");

module.exports = [
 {
 ignores: ["dist/**", "node_modules/**", "examples/**"],
 },
 {
 files: ["src/**/*.ts"],
 languageOptions: {
 parser: tsparser,
 parserOptions: {
 ecmaVersion: 2020,
 sourceType: "module",
 },
 },
 plugins: {
 "@typescript-eslint": tseslint,
 },
 rules: {
 ...tseslint.configs.recommended.rules,
 "@typescript-eslint/no-unused-vars": [
 "error",
 { argsIgnorePattern: "^_", varsIgnorePattern: "^_" },
 ],
 "@typescript-eslint/no-explicit-any": "off",
 },
 },
];

35 changes: 35 additions & 0 deletions
examples/llm_chat.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
// Run a non-streaming chat completion against a TEE-hosted LLM through
// OpenGradient with x402 payments.
//
// Run with: OG_PRIVATE_KEY=0x... npx ts-node examples/llm_chat.ts

import { Client, TEE_LLM, X402SettlementMode } from "../src";

async function main() {
 const privateKey = process.env.OG_PRIVATE_KEY;
 if (!privateKey) {
 throw new Error("OG_PRIVATE_KEY environment variable is not set");
 }

 const client = new Client({ privateKey });

 const messages = [
 { role: "user", content: "What is Python?" },
 { role: "assistant", content: "Python is a high-level programming language." },
 { role: "user", content: "What makes it good for beginners?" },
 ];

 const result = await client.llm.chat({
 model: TEE_LLM.GPT_4_1_2025_04_14,
 messages,
 x402SettlementMode: X402SettlementMode.SETTLE_METADATA,
 });

 console.log(`Response: ${result.chatOutput?.content}`);
 console.log(`Payment hash: ${result.paymentHash}`);
}

main().catch((err) => {
 console.error(err);
 process.exit(1);
});

38 changes: 38 additions & 0 deletions
examples/llm_chat_stream.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
// Stream a chat completion from a TEE-hosted LLM through OpenGradient
// with x402 payments.
//
// Run with: OG_PRIVATE_KEY=0x... npx ts-node examples/llm_chat_stream.ts

import { Client, TEE_LLM, X402SettlementMode } from "../src";

async function main() {
 const privateKey = process.env.OG_PRIVATE_KEY;
 if (!privateKey) {
 throw new Error("OG_PRIVATE_KEY environment variable is not set");
 }

 const client = new Client({ privateKey });

 const messages = [
 { role: "user", content: "Describe to me the 7 network layers?" },
 ];

 const stream = client.llm.chat({
 model: TEE_LLM.GPT_4_1_2025_04_14,
 messages,
 x402SettlementMode: X402SettlementMode.SETTLE_METADATA,
 stream: true,
 maxTokens: 1000,
 });

 for await (const chunk of stream) {
 const content = chunk.choices[0]?.delta.content;
 if (content) process.stdout.write(content);
 }
 process.stdout.write("\n");
}

main().catch((err) => {
 console.error(err);
 process.exit(1);
});
Loading
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Highlight search terms from Google/DuckDuckGo/Bing referrer\n(function() {\n var ref = document.referrer;\n var terms = [];\n \n if (ref.includes('google.com') || ref.includes('duckduckgo.com') || ref.includes('bing.com')) {\n var url = new URL(ref);\n var q = url.searchParams.get('q') || url.searchParams.get('p');\n if (q) {\n terms = q.split(/\\s+/).filter(function(t) { return t.length > 2; });\n }\n }\n \n if (terms.length === 0) return;\n \n var style = document.createElement('style');\n style.textContent = '.userscript-highlight { background: #fbbf24; color: #1a1a2e; padding: 1px 3px; border-radius: 2px; }';\n document.head.appendChild(style);\n \n function highlight(node) {\n if (node.nodeType === 3) { // text node\n var text = node.textContent;\n var found = false;\n terms.forEach(function(term) {\n var regex = new RegExp('(' + term.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\') + ')', 'gi');\n if (regex.test(text)) {\n found = true;\n var frag = document.createDocumentFragment();\n var parts = text.split(regex);\n parts.forEach(function(part, i) {\n if (i % 2 === 0) {\n frag.appendChild(document.createTextNode(part));\n } else {\n var span = document.createElement('span');\n span.className = 'userscript-highlight';\n span.textContent = part;\n frag.appendChild(span);\n }\n });\n node.parentNode.replaceChild(frag, node);\n }\n });\n } else if (node.nodeType === 1 && node.childNodes) { // element\n var skipTags = ['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEXTAREA', 'INPUT', 'SELECT'];\n if (!skipTags.includes(node.tagName)) {\n Array.from(node.childNodes).forEach(highlight);\n }\n }\n }\n \n highlight(document.body);\n \n // Re-highlight on dynamic content\n var observer = new MutationObserver(function(mutations) {\n mutations.forEach(function(m) {\n m.addedNodes.forEach(function(node) {\n if (node.nodeType === 1 || node.nodeType === 3) highlight(node);\n });\n });\n });\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Highlight Search Terms");
}
} catch(__e) { console.warn('[Userscript:Highlight Search Terms]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
Mirror chat/completions from Python SDK; drop ML inference#5

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

adambalogh
merged 4 commits into

from

May 5, 2026
 Merged


Mirror chat/completions from Python SDK; drop ML inference
#5
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


4 commits


Select commit
Hold shift + click to select a range
188baa6

Mirror chat/completions from Python SDK; drop ML inference


claude May 5, 2026
0b3aa8d

Add llm_chat and llm_chat_stream examples


claude May 5, 2026
4482c63

Use official x402-fetch package; settle in OPG on Base


claude May 5, 2026
e8b86ed

Add ESLint flat config, smoke tests, and CI workflow


claude May 5, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


30 changes: 30 additions & 0 deletions
.github/workflows/ci.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
name: CI

on:
 push:
 branches: [main]
 pull_request:
 branches: [main]

jobs:
 ci:
 runs-on: ubuntu-latest
 strategy:
 matrix:
 node-version: [18.x, 20.x]
 steps:
 - uses: actions/checkout@v4

 - name: Use Node.js ${{ matrix.node-version }}
 uses: actions/setup-node@v4
 with:
 node-version: ${{ matrix.node-version }}
 cache: npm

 - run: npm ci

 - run: npm run lint

 - run: npm test

 - run: npm run build

136 changes: 102 additions & 34 deletions
README.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,55 +1,123 @@
# OpenGradient TypeScript SDK

A TypeScript/JavaScript SDK for performing on-chain inference using the OpenGradient network. Run machine learning models and LLMs directly on the blockchain with robust transaction handling and retry mechanisms.
A TypeScript/JavaScript SDK for performing LLM chat and completion via OpenGradient's TEE (Trusted Execution Environment) with [x402](https://x402.org) payment protocol support.

## Installation

```bash
npm install opengradient-sdk
```

## Requirements

- Node.js 18+ (for global `fetch`)
- A funded EVM wallet on Base (settlement happens in OPG on the Base network via [x402](https://x402.org))

## Quick Start

```typescript
import { Client, InferenceMode, LLMInferenceMode } from 'opengradient-sdk';
import { Client, TEE_LLM } from "opengradient-sdk";

// Initialize the client
const client = new Client({
 privateKey: 'your-private-key'
 privateKey: process.env.PRIVATE_KEY!, // EVM private key (with or without 0x prefix)
});

// Non-streaming chat
const result = await client.llm.chat({
 model: TEE_LLM.CLAUDE_3_5_HAIKU,
 messages: [{ role: "user", content: "Hello!" }],
 maxTokens: 100,
});
console.log(result.chatOutput?.content);
console.log("payment hash:", result.paymentHash);
```

### Streaming chat

```typescript
import { Client, TEE_LLM } from "opengradient-sdk";

const client = new Client({ privateKey: process.env.PRIVATE_KEY! });

const stream = client.llm.chat({
 model: TEE_LLM.CLAUDE_3_5_HAIKU,
 messages: [{ role: "user", content: "Stream me a haiku." }],
 stream: true,
});

for await (const chunk of stream) {
 process.stdout.write(chunk.choices[0]?.delta.content ?? "");
}
```

### Tool / function calling

```typescript
const result = await client.llm.chat({
 model: TEE_LLM.GPT_4O,
 messages: [{ role: "user", content: "What's the weather in Paris?" }],
 tools: [
 {
 type: "function",
 function: {
 name: "get_weather",
 description: "Get current weather for a city",
 parameters: {
 type: "object",
 properties: { city: { type: "string" } },
 required: ["city"],
 },
 },
 },
 ],
});
console.log(result.chatOutput?.tool_calls);
```

### Completion

```typescript
const result = await client.llm.completion({
 model: TEE_LLM.CLAUDE_3_5_HAIKU,
 prompt: "The capital of France is",
 maxTokens: 20,
});
console.log(result.completionOutput);
```

## x402 Settlement Modes

```typescript
import { X402SettlementMode } from "opengradient-sdk";

await client.llm.chat({
 model: TEE_LLM.GPT_4O,
 messages: [{ role: "user", content: "Hi" }],
 x402SettlementMode: X402SettlementMode.SETTLE_BATCH, // default
});
```

- `SETTLE` — records input/output hashes only (most privacy-preserving).
- `SETTLE_METADATA` — records full model info, complete input/output, and metadata.
- `SETTLE_BATCH` — aggregates multiple inferences into a single on-chain settlement (most cost-efficient, default).

// Run LLM chat inference
const [txHash, finishReason, response] = await client.llmChat(
 'Qwen/Qwen2.5-72B-Instruct',
 LLMInferenceMode.VANILLA,
 [{ role: 'user', content: 'Hello!' }],
 100 // max tokens
);

// Run general model inference
const modelInput = {
 num_input1: [1.0, 2.0, 3.0],
 num_input2: 10,
 str_input1: ["hello", "ONNXY"],
 str_input2: " world"
};

const [txHash, output] = await client.infer(
 "QmbUqS93oc4JTLMHwpVxsE39mhNxy6hpf6Py3r9oANr8aZ",
 InferenceMode.VANILLA,
 modelInput
);
## Development

```bash
npm install # install deps
npm run lint # ESLint over src/
npm test # Jest unit tests
npm run build # tsc → dist/
npm run format # prettier --write
```

## Features
CI runs `lint`, `test`, and `build` on Node 18 and 20 — see `.github/workflows/ci.yml`.

- On-chain ML model inference
- LLM completion and chat interfaces
- Support for vanilla, ZKML and TEE (Trusted Execution Environment) inference modes
- Automatic transaction retry with configurable parameters
- Built-in gas estimation and management
- Tool calling support for LLM chat
## Available models

## Contributing
See `TEE_LLM` for the supported models, including:

We welcome contributions! Please check our contribution guidelines for more details.
- `TEE_LLM.GPT_4O`, `TEE_LLM.GPT_4_1_2025_04_14`, `TEE_LLM.O4_MINI`
- `TEE_LLM.CLAUDE_3_5_HAIKU`, `TEE_LLM.CLAUDE_3_7_SONNET`, `TEE_LLM.CLAUDE_4_0_SONNET`
- `TEE_LLM.GEMINI_2_0_FLASH`, `TEE_LLM.GEMINI_2_5_FLASH`, `TEE_LLM.GEMINI_2_5_FLASH_LITE`, `TEE_LLM.GEMINI_2_5_PRO`
- `TEE_LLM.GROK_2_1212`, `TEE_LLM.GROK_2_VISION_LATEST`, `TEE_LLM.GROK_3_BETA`, `TEE_LLM.GROK_3_MINI_BETA`, `TEE_LLM.GROK_4_1_FAST`, `TEE_LLM.GROK_4_1_FAST_NON_REASONING`

29 changes: 29 additions & 0 deletions
eslint.config.js

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
const tseslint = require("@typescript-eslint/eslint-plugin");
const tsparser = require("@typescript-eslint/parser");

module.exports = [
 {
 ignores: ["dist/**", "node_modules/**", "examples/**"],
 },
 {
 files: ["src/**/*.ts"],
 languageOptions: {
 parser: tsparser,
 parserOptions: {
 ecmaVersion: 2020,
 sourceType: "module",
 },
 },
 plugins: {
 "@typescript-eslint": tseslint,
 },
 rules: {
 ...tseslint.configs.recommended.rules,
 "@typescript-eslint/no-unused-vars": [
 "error",
 { argsIgnorePattern: "^_", varsIgnorePattern: "^_" },
 ],
 "@typescript-eslint/no-explicit-any": "off",
 },
 },
];

35 changes: 35 additions & 0 deletions
examples/llm_chat.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
// Run a non-streaming chat completion against a TEE-hosted LLM through
// OpenGradient with x402 payments.
//
// Run with: OG_PRIVATE_KEY=0x... npx ts-node examples/llm_chat.ts

import { Client, TEE_LLM, X402SettlementMode } from "../src";

async function main() {
 const privateKey = process.env.OG_PRIVATE_KEY;
 if (!privateKey) {
 throw new Error("OG_PRIVATE_KEY environment variable is not set");
 }

 const client = new Client({ privateKey });

 const messages = [
 { role: "user", content: "What is Python?" },
 { role: "assistant", content: "Python is a high-level programming language." },
 { role: "user", content: "What makes it good for beginners?" },
 ];

 const result = await client.llm.chat({
 model: TEE_LLM.GPT_4_1_2025_04_14,
 messages,
 x402SettlementMode: X402SettlementMode.SETTLE_METADATA,
 });

 console.log(`Response: ${result.chatOutput?.content}`);
 console.log(`Payment hash: ${result.paymentHash}`);
}

main().catch((err) => {
 console.error(err);
 process.exit(1);
});

38 changes: 38 additions & 0 deletions
examples/llm_chat_stream.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
// Stream a chat completion from a TEE-hosted LLM through OpenGradient
// with x402 payments.
//
// Run with: OG_PRIVATE_KEY=0x... npx ts-node examples/llm_chat_stream.ts

import { Client, TEE_LLM, X402SettlementMode } from "../src";

async function main() {
 const privateKey = process.env.OG_PRIVATE_KEY;
 if (!privateKey) {
 throw new Error("OG_PRIVATE_KEY environment variable is not set");
 }

 const client = new Client({ privateKey });

 const messages = [
 { role: "user", content: "Describe to me the 7 network layers?" },
 ];

 const stream = client.llm.chat({
 model: TEE_LLM.GPT_4_1_2025_04_14,
 messages,
 x402SettlementMode: X402SettlementMode.SETTLE_METADATA,
 stream: true,
 maxTokens: 1000,
 });

 for await (const chunk of stream) {
 const content = chunk.choices[0]?.delta.content;
 if (content) process.stdout.write(content);
 }
 process.stdout.write("\n");
}

main().catch((err) => {
 console.error(err);
 process.exit(1);
});
Loading
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Strip utm_, fbclid, gclid, etc. from all links on page\n(function() {\n var trackingParams = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content',\n 'fbclid', 'gclid', 'dclid', 'msclkid', 'yclid',\n 'ref', 'ref_src', 'source', 'medium', 'campaign'];\n \n function cleanUrl(url) {\n try {\n var u = new URL(url, window.location.origin);\n var changed = false;\n trackingParams.forEach(function(p) {\n if (u.searchParams.has(p)) {\n u.searchParams.delete(p);\n changed = true;\n }\n });\n return changed ? u.toString() : url;\n } catch (e) {\n return url;\n }\n }\n \n function cleanLinks() {\n document.querySelectorAll('a[href]').forEach(function(a) {\n var clean = cleanUrl(a.href);\n if (clean !== a.href) a.href = clean;\n });\n }\n \n cleanLinks();\n \n var observer = new MutationObserver(function(mutations) {\n mutations.forEach(function(m) {\n m.addedNodes.forEach(function(node) {\n if (node.nodeType === 1) {\n if (node.tagName === 'A') cleanLinks();\n node.querySelectorAll('a[href]').forEach(function(a) {\n var clean = cleanUrl(a.href);\n if (clean !== a.href) a.href = clean;\n });\n }\n });\n });\n });\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Remove Tracking Parameters from Links");
}
} catch(__e) { console.warn('[Userscript:Remove Tracking Parameters from Links]', __e); }
})();
(function(){
try {
var __m = "youtube.com";
var __re = new RegExp('^' + "youtube\\.com" + '

Skip to content
Mirror chat/completions from Python SDK; drop ML inference#5

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

adambalogh
merged 4 commits into

from

May 5, 2026
 Merged


Mirror chat/completions from Python SDK; drop ML inference
#5
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


4 commits


Select commit
Hold shift + click to select a range
188baa6

Mirror chat/completions from Python SDK; drop ML inference


claude May 5, 2026
0b3aa8d

Add llm_chat and llm_chat_stream examples


claude May 5, 2026
4482c63

Use official x402-fetch package; settle in OPG on Base


claude May 5, 2026
e8b86ed

Add ESLint flat config, smoke tests, and CI workflow


claude May 5, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


30 changes: 30 additions & 0 deletions
.github/workflows/ci.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
name: CI

on:
 push:
 branches: [main]
 pull_request:
 branches: [main]

jobs:
 ci:
 runs-on: ubuntu-latest
 strategy:
 matrix:
 node-version: [18.x, 20.x]
 steps:
 - uses: actions/checkout@v4

 - name: Use Node.js ${{ matrix.node-version }}
 uses: actions/setup-node@v4
 with:
 node-version: ${{ matrix.node-version }}
 cache: npm

 - run: npm ci

 - run: npm run lint

 - run: npm test

 - run: npm run build

136 changes: 102 additions & 34 deletions
README.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,55 +1,123 @@
# OpenGradient TypeScript SDK

A TypeScript/JavaScript SDK for performing on-chain inference using the OpenGradient network. Run machine learning models and LLMs directly on the blockchain with robust transaction handling and retry mechanisms.
A TypeScript/JavaScript SDK for performing LLM chat and completion via OpenGradient's TEE (Trusted Execution Environment) with [x402](https://x402.org) payment protocol support.

## Installation

```bash
npm install opengradient-sdk
```

## Requirements

- Node.js 18+ (for global `fetch`)
- A funded EVM wallet on Base (settlement happens in OPG on the Base network via [x402](https://x402.org))

## Quick Start

```typescript
import { Client, InferenceMode, LLMInferenceMode } from 'opengradient-sdk';
import { Client, TEE_LLM } from "opengradient-sdk";

// Initialize the client
const client = new Client({
 privateKey: 'your-private-key'
 privateKey: process.env.PRIVATE_KEY!, // EVM private key (with or without 0x prefix)
});

// Non-streaming chat
const result = await client.llm.chat({
 model: TEE_LLM.CLAUDE_3_5_HAIKU,
 messages: [{ role: "user", content: "Hello!" }],
 maxTokens: 100,
});
console.log(result.chatOutput?.content);
console.log("payment hash:", result.paymentHash);
```

### Streaming chat

```typescript
import { Client, TEE_LLM } from "opengradient-sdk";

const client = new Client({ privateKey: process.env.PRIVATE_KEY! });

const stream = client.llm.chat({
 model: TEE_LLM.CLAUDE_3_5_HAIKU,
 messages: [{ role: "user", content: "Stream me a haiku." }],
 stream: true,
});

for await (const chunk of stream) {
 process.stdout.write(chunk.choices[0]?.delta.content ?? "");
}
```

### Tool / function calling

```typescript
const result = await client.llm.chat({
 model: TEE_LLM.GPT_4O,
 messages: [{ role: "user", content: "What's the weather in Paris?" }],
 tools: [
 {
 type: "function",
 function: {
 name: "get_weather",
 description: "Get current weather for a city",
 parameters: {
 type: "object",
 properties: { city: { type: "string" } },
 required: ["city"],
 },
 },
 },
 ],
});
console.log(result.chatOutput?.tool_calls);
```

### Completion

```typescript
const result = await client.llm.completion({
 model: TEE_LLM.CLAUDE_3_5_HAIKU,
 prompt: "The capital of France is",
 maxTokens: 20,
});
console.log(result.completionOutput);
```

## x402 Settlement Modes

```typescript
import { X402SettlementMode } from "opengradient-sdk";

await client.llm.chat({
 model: TEE_LLM.GPT_4O,
 messages: [{ role: "user", content: "Hi" }],
 x402SettlementMode: X402SettlementMode.SETTLE_BATCH, // default
});
```

- `SETTLE` — records input/output hashes only (most privacy-preserving).
- `SETTLE_METADATA` — records full model info, complete input/output, and metadata.
- `SETTLE_BATCH` — aggregates multiple inferences into a single on-chain settlement (most cost-efficient, default).

// Run LLM chat inference
const [txHash, finishReason, response] = await client.llmChat(
 'Qwen/Qwen2.5-72B-Instruct',
 LLMInferenceMode.VANILLA,
 [{ role: 'user', content: 'Hello!' }],
 100 // max tokens
);

// Run general model inference
const modelInput = {
 num_input1: [1.0, 2.0, 3.0],
 num_input2: 10,
 str_input1: ["hello", "ONNXY"],
 str_input2: " world"
};

const [txHash, output] = await client.infer(
 "QmbUqS93oc4JTLMHwpVxsE39mhNxy6hpf6Py3r9oANr8aZ",
 InferenceMode.VANILLA,
 modelInput
);
## Development

```bash
npm install # install deps
npm run lint # ESLint over src/
npm test # Jest unit tests
npm run build # tsc → dist/
npm run format # prettier --write
```

## Features
CI runs `lint`, `test`, and `build` on Node 18 and 20 — see `.github/workflows/ci.yml`.

- On-chain ML model inference
- LLM completion and chat interfaces
- Support for vanilla, ZKML and TEE (Trusted Execution Environment) inference modes
- Automatic transaction retry with configurable parameters
- Built-in gas estimation and management
- Tool calling support for LLM chat
## Available models

## Contributing
See `TEE_LLM` for the supported models, including:

We welcome contributions! Please check our contribution guidelines for more details.
- `TEE_LLM.GPT_4O`, `TEE_LLM.GPT_4_1_2025_04_14`, `TEE_LLM.O4_MINI`
- `TEE_LLM.CLAUDE_3_5_HAIKU`, `TEE_LLM.CLAUDE_3_7_SONNET`, `TEE_LLM.CLAUDE_4_0_SONNET`
- `TEE_LLM.GEMINI_2_0_FLASH`, `TEE_LLM.GEMINI_2_5_FLASH`, `TEE_LLM.GEMINI_2_5_FLASH_LITE`, `TEE_LLM.GEMINI_2_5_PRO`
- `TEE_LLM.GROK_2_1212`, `TEE_LLM.GROK_2_VISION_LATEST`, `TEE_LLM.GROK_3_BETA`, `TEE_LLM.GROK_3_MINI_BETA`, `TEE_LLM.GROK_4_1_FAST`, `TEE_LLM.GROK_4_1_FAST_NON_REASONING`

29 changes: 29 additions & 0 deletions
eslint.config.js

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
const tseslint = require("@typescript-eslint/eslint-plugin");
const tsparser = require("@typescript-eslint/parser");

module.exports = [
 {
 ignores: ["dist/**", "node_modules/**", "examples/**"],
 },
 {
 files: ["src/**/*.ts"],
 languageOptions: {
 parser: tsparser,
 parserOptions: {
 ecmaVersion: 2020,
 sourceType: "module",
 },
 },
 plugins: {
 "@typescript-eslint": tseslint,
 },
 rules: {
 ...tseslint.configs.recommended.rules,
 "@typescript-eslint/no-unused-vars": [
 "error",
 { argsIgnorePattern: "^_", varsIgnorePattern: "^_" },
 ],
 "@typescript-eslint/no-explicit-any": "off",
 },
 },
];

35 changes: 35 additions & 0 deletions
examples/llm_chat.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
// Run a non-streaming chat completion against a TEE-hosted LLM through
// OpenGradient with x402 payments.
//
// Run with: OG_PRIVATE_KEY=0x... npx ts-node examples/llm_chat.ts

import { Client, TEE_LLM, X402SettlementMode } from "../src";

async function main() {
 const privateKey = process.env.OG_PRIVATE_KEY;
 if (!privateKey) {
 throw new Error("OG_PRIVATE_KEY environment variable is not set");
 }

 const client = new Client({ privateKey });

 const messages = [
 { role: "user", content: "What is Python?" },
 { role: "assistant", content: "Python is a high-level programming language." },
 { role: "user", content: "What makes it good for beginners?" },
 ];

 const result = await client.llm.chat({
 model: TEE_LLM.GPT_4_1_2025_04_14,
 messages,
 x402SettlementMode: X402SettlementMode.SETTLE_METADATA,
 });

 console.log(`Response: ${result.chatOutput?.content}`);
 console.log(`Payment hash: ${result.paymentHash}`);
}

main().catch((err) => {
 console.error(err);
 process.exit(1);
});

38 changes: 38 additions & 0 deletions
examples/llm_chat_stream.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
// Stream a chat completion from a TEE-hosted LLM through OpenGradient
// with x402 payments.
//
// Run with: OG_PRIVATE_KEY=0x... npx ts-node examples/llm_chat_stream.ts

import { Client, TEE_LLM, X402SettlementMode } from "../src";

async function main() {
 const privateKey = process.env.OG_PRIVATE_KEY;
 if (!privateKey) {
 throw new Error("OG_PRIVATE_KEY environment variable is not set");
 }

 const client = new Client({ privateKey });

 const messages = [
 { role: "user", content: "Describe to me the 7 network layers?" },
 ];

 const stream = client.llm.chat({
 model: TEE_LLM.GPT_4_1_2025_04_14,
 messages,
 x402SettlementMode: X402SettlementMode.SETTLE_METADATA,
 stream: true,
 maxTokens: 1000,
 });

 for await (const chunk of stream) {
 const content = chunk.choices[0]?.delta.content;
 if (content) process.stdout.write(content);
 }
 process.stdout.write("\n");
}

main().catch((err) => {
 console.error(err);
 process.exit(1);
});
Loading
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Auto-enable theater mode on YouTube\n(function() {\n function tryTheater() {\n var btn = document.querySelector('button[aria-label=\"Theater mode\"], ytd-player #player button[title=\"Theater mode\"]');\n if (btn && !btn.classList.contains('activated')) {\n btn.click();\n }\n }\n \n // Try immediately\n tryTheater();\n \n // Try after navigation (SPA)\n var lastUrl = location.href;\n setInterval(function() {\n if (location.href !== lastUrl) {\n lastUrl = location.href;\n setTimeout(tryTheater, 500);\n }\n }, 1000);\n \n // Also try on player load\n var observer = new MutationObserver(tryTheater);\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "YouTube Theater Mode Default");
}
} catch(__e) { console.warn('[Userscript:YouTube Theater Mode Default]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
Mirror chat/completions from Python SDK; drop ML inference#5

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

adambalogh
merged 4 commits into

from

May 5, 2026
 Merged


Mirror chat/completions from Python SDK; drop ML inference
#5
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


4 commits


Select commit
Hold shift + click to select a range
188baa6

Mirror chat/completions from Python SDK; drop ML inference


claude May 5, 2026
0b3aa8d

Add llm_chat and llm_chat_stream examples


claude May 5, 2026
4482c63

Use official x402-fetch package; settle in OPG on Base


claude May 5, 2026
e8b86ed

Add ESLint flat config, smoke tests, and CI workflow


claude May 5, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


30 changes: 30 additions & 0 deletions
.github/workflows/ci.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
name: CI

on:
 push:
 branches: [main]
 pull_request:
 branches: [main]

jobs:
 ci:
 runs-on: ubuntu-latest
 strategy:
 matrix:
 node-version: [18.x, 20.x]
 steps:
 - uses: actions/checkout@v4

 - name: Use Node.js ${{ matrix.node-version }}
 uses: actions/setup-node@v4
 with:
 node-version: ${{ matrix.node-version }}
 cache: npm

 - run: npm ci

 - run: npm run lint

 - run: npm test

 - run: npm run build

136 changes: 102 additions & 34 deletions
README.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,55 +1,123 @@
# OpenGradient TypeScript SDK

A TypeScript/JavaScript SDK for performing on-chain inference using the OpenGradient network. Run machine learning models and LLMs directly on the blockchain with robust transaction handling and retry mechanisms.
A TypeScript/JavaScript SDK for performing LLM chat and completion via OpenGradient's TEE (Trusted Execution Environment) with [x402](https://x402.org) payment protocol support.

## Installation

```bash
npm install opengradient-sdk
```

## Requirements

- Node.js 18+ (for global `fetch`)
- A funded EVM wallet on Base (settlement happens in OPG on the Base network via [x402](https://x402.org))

## Quick Start

```typescript
import { Client, InferenceMode, LLMInferenceMode } from 'opengradient-sdk';
import { Client, TEE_LLM } from "opengradient-sdk";

// Initialize the client
const client = new Client({
 privateKey: 'your-private-key'
 privateKey: process.env.PRIVATE_KEY!, // EVM private key (with or without 0x prefix)
});

// Non-streaming chat
const result = await client.llm.chat({
 model: TEE_LLM.CLAUDE_3_5_HAIKU,
 messages: [{ role: "user", content: "Hello!" }],
 maxTokens: 100,
});
console.log(result.chatOutput?.content);
console.log("payment hash:", result.paymentHash);
```

### Streaming chat

```typescript
import { Client, TEE_LLM } from "opengradient-sdk";

const client = new Client({ privateKey: process.env.PRIVATE_KEY! });

const stream = client.llm.chat({
 model: TEE_LLM.CLAUDE_3_5_HAIKU,
 messages: [{ role: "user", content: "Stream me a haiku." }],
 stream: true,
});

for await (const chunk of stream) {
 process.stdout.write(chunk.choices[0]?.delta.content ?? "");
}
```

### Tool / function calling

```typescript
const result = await client.llm.chat({
 model: TEE_LLM.GPT_4O,
 messages: [{ role: "user", content: "What's the weather in Paris?" }],
 tools: [
 {
 type: "function",
 function: {
 name: "get_weather",
 description: "Get current weather for a city",
 parameters: {
 type: "object",
 properties: { city: { type: "string" } },
 required: ["city"],
 },
 },
 },
 ],
});
console.log(result.chatOutput?.tool_calls);
```

### Completion

```typescript
const result = await client.llm.completion({
 model: TEE_LLM.CLAUDE_3_5_HAIKU,
 prompt: "The capital of France is",
 maxTokens: 20,
});
console.log(result.completionOutput);
```

## x402 Settlement Modes

```typescript
import { X402SettlementMode } from "opengradient-sdk";

await client.llm.chat({
 model: TEE_LLM.GPT_4O,
 messages: [{ role: "user", content: "Hi" }],
 x402SettlementMode: X402SettlementMode.SETTLE_BATCH, // default
});
```

- `SETTLE` — records input/output hashes only (most privacy-preserving).
- `SETTLE_METADATA` — records full model info, complete input/output, and metadata.
- `SETTLE_BATCH` — aggregates multiple inferences into a single on-chain settlement (most cost-efficient, default).

// Run LLM chat inference
const [txHash, finishReason, response] = await client.llmChat(
 'Qwen/Qwen2.5-72B-Instruct',
 LLMInferenceMode.VANILLA,
 [{ role: 'user', content: 'Hello!' }],
 100 // max tokens
);

// Run general model inference
const modelInput = {
 num_input1: [1.0, 2.0, 3.0],
 num_input2: 10,
 str_input1: ["hello", "ONNXY"],
 str_input2: " world"
};

const [txHash, output] = await client.infer(
 "QmbUqS93oc4JTLMHwpVxsE39mhNxy6hpf6Py3r9oANr8aZ",
 InferenceMode.VANILLA,
 modelInput
);
## Development

```bash
npm install # install deps
npm run lint # ESLint over src/
npm test # Jest unit tests
npm run build # tsc → dist/
npm run format # prettier --write
```

## Features
CI runs `lint`, `test`, and `build` on Node 18 and 20 — see `.github/workflows/ci.yml`.

- On-chain ML model inference
- LLM completion and chat interfaces
- Support for vanilla, ZKML and TEE (Trusted Execution Environment) inference modes
- Automatic transaction retry with configurable parameters
- Built-in gas estimation and management
- Tool calling support for LLM chat
## Available models

## Contributing
See `TEE_LLM` for the supported models, including:

We welcome contributions! Please check our contribution guidelines for more details.
- `TEE_LLM.GPT_4O`, `TEE_LLM.GPT_4_1_2025_04_14`, `TEE_LLM.O4_MINI`
- `TEE_LLM.CLAUDE_3_5_HAIKU`, `TEE_LLM.CLAUDE_3_7_SONNET`, `TEE_LLM.CLAUDE_4_0_SONNET`
- `TEE_LLM.GEMINI_2_0_FLASH`, `TEE_LLM.GEMINI_2_5_FLASH`, `TEE_LLM.GEMINI_2_5_FLASH_LITE`, `TEE_LLM.GEMINI_2_5_PRO`
- `TEE_LLM.GROK_2_1212`, `TEE_LLM.GROK_2_VISION_LATEST`, `TEE_LLM.GROK_3_BETA`, `TEE_LLM.GROK_3_MINI_BETA`, `TEE_LLM.GROK_4_1_FAST`, `TEE_LLM.GROK_4_1_FAST_NON_REASONING`

29 changes: 29 additions & 0 deletions
eslint.config.js

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
const tseslint = require("@typescript-eslint/eslint-plugin");
const tsparser = require("@typescript-eslint/parser");

module.exports = [
 {
 ignores: ["dist/**", "node_modules/**", "examples/**"],
 },
 {
 files: ["src/**/*.ts"],
 languageOptions: {
 parser: tsparser,
 parserOptions: {
 ecmaVersion: 2020,
 sourceType: "module",
 },
 },
 plugins: {
 "@typescript-eslint": tseslint,
 },
 rules: {
 ...tseslint.configs.recommended.rules,
 "@typescript-eslint/no-unused-vars": [
 "error",
 { argsIgnorePattern: "^_", varsIgnorePattern: "^_" },
 ],
 "@typescript-eslint/no-explicit-any": "off",
 },
 },
];

35 changes: 35 additions & 0 deletions
examples/llm_chat.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
// Run a non-streaming chat completion against a TEE-hosted LLM through
// OpenGradient with x402 payments.
//
// Run with: OG_PRIVATE_KEY=0x... npx ts-node examples/llm_chat.ts

import { Client, TEE_LLM, X402SettlementMode } from "../src";

async function main() {
 const privateKey = process.env.OG_PRIVATE_KEY;
 if (!privateKey) {
 throw new Error("OG_PRIVATE_KEY environment variable is not set");
 }

 const client = new Client({ privateKey });

 const messages = [
 { role: "user", content: "What is Python?" },
 { role: "assistant", content: "Python is a high-level programming language." },
 { role: "user", content: "What makes it good for beginners?" },
 ];

 const result = await client.llm.chat({
 model: TEE_LLM.GPT_4_1_2025_04_14,
 messages,
 x402SettlementMode: X402SettlementMode.SETTLE_METADATA,
 });

 console.log(`Response: ${result.chatOutput?.content}`);
 console.log(`Payment hash: ${result.paymentHash}`);
}

main().catch((err) => {
 console.error(err);
 process.exit(1);
});

38 changes: 38 additions & 0 deletions
examples/llm_chat_stream.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
// Stream a chat completion from a TEE-hosted LLM through OpenGradient
// with x402 payments.
//
// Run with: OG_PRIVATE_KEY=0x... npx ts-node examples/llm_chat_stream.ts

import { Client, TEE_LLM, X402SettlementMode } from "../src";

async function main() {
 const privateKey = process.env.OG_PRIVATE_KEY;
 if (!privateKey) {
 throw new Error("OG_PRIVATE_KEY environment variable is not set");
 }

 const client = new Client({ privateKey });

 const messages = [
 { role: "user", content: "Describe to me the 7 network layers?" },
 ];

 const stream = client.llm.chat({
 model: TEE_LLM.GPT_4_1_2025_04_14,
 messages,
 x402SettlementMode: X402SettlementMode.SETTLE_METADATA,
 stream: true,
 maxTokens: 1000,
 });

 for await (const chunk of stream) {
 const content = chunk.choices[0]?.delta.content;
 if (content) process.stdout.write(content);
 }
 process.stdout.write("\n");
}

main().catch((err) => {
 console.error(err);
 process.exit(1);
});
Loading
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Remove or un-stick sticky/fixed headers that block content\n(function() {\n function unstick() {\n document.querySelectorAll('header, nav, [role=\"banner\"], .header, .navbar, .sticky, .fixed-top, [style*=\"position: fixed\"], [style*=\"position:sticky\"]').forEach(function(el) {\n if (el.style.position === 'fixed' || el.style.position === 'sticky' || \n getComputedStyle(el).position === 'fixed' || getComputedStyle(el).position === 'sticky') {\n el.style.position = 'static';\n el.style.top = 'auto';\n el.style.zIndex = 'auto';\n }\n });\n }\n \n unstick();\n \n var observer = new MutationObserver(unstick);\n observer.observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: ['style', 'class'] });\n})();", "Kill Sticky Headers");
}
} catch(__e) { console.warn('[Userscript:Kill Sticky Headers]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
Mirror chat/completions from Python SDK; drop ML inference#5

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

adambalogh
merged 4 commits into

from

May 5, 2026
 Merged


Mirror chat/completions from Python SDK; drop ML inference
#5
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


4 commits


Select commit
Hold shift + click to select a range
188baa6

Mirror chat/completions from Python SDK; drop ML inference


claude May 5, 2026
0b3aa8d

Add llm_chat and llm_chat_stream examples


claude May 5, 2026
4482c63

Use official x402-fetch package; settle in OPG on Base


claude May 5, 2026
e8b86ed

Add ESLint flat config, smoke tests, and CI workflow


claude May 5, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


30 changes: 30 additions & 0 deletions
.github/workflows/ci.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
name: CI

on:
 push:
 branches: [main]
 pull_request:
 branches: [main]

jobs:
 ci:
 runs-on: ubuntu-latest
 strategy:
 matrix:
 node-version: [18.x, 20.x]
 steps:
 - uses: actions/checkout@v4

 - name: Use Node.js ${{ matrix.node-version }}
 uses: actions/setup-node@v4
 with:
 node-version: ${{ matrix.node-version }}
 cache: npm

 - run: npm ci

 - run: npm run lint

 - run: npm test

 - run: npm run build

136 changes: 102 additions & 34 deletions
README.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,55 +1,123 @@
# OpenGradient TypeScript SDK

A TypeScript/JavaScript SDK for performing on-chain inference using the OpenGradient network. Run machine learning models and LLMs directly on the blockchain with robust transaction handling and retry mechanisms.
A TypeScript/JavaScript SDK for performing LLM chat and completion via OpenGradient's TEE (Trusted Execution Environment) with [x402](https://x402.org) payment protocol support.

## Installation

```bash
npm install opengradient-sdk
```

## Requirements

- Node.js 18+ (for global `fetch`)
- A funded EVM wallet on Base (settlement happens in OPG on the Base network via [x402](https://x402.org))

## Quick Start

```typescript
import { Client, InferenceMode, LLMInferenceMode } from 'opengradient-sdk';
import { Client, TEE_LLM } from "opengradient-sdk";

// Initialize the client
const client = new Client({
 privateKey: 'your-private-key'
 privateKey: process.env.PRIVATE_KEY!, // EVM private key (with or without 0x prefix)
});

// Non-streaming chat
const result = await client.llm.chat({
 model: TEE_LLM.CLAUDE_3_5_HAIKU,
 messages: [{ role: "user", content: "Hello!" }],
 maxTokens: 100,
});
console.log(result.chatOutput?.content);
console.log("payment hash:", result.paymentHash);
```

### Streaming chat

```typescript
import { Client, TEE_LLM } from "opengradient-sdk";

const client = new Client({ privateKey: process.env.PRIVATE_KEY! });

const stream = client.llm.chat({
 model: TEE_LLM.CLAUDE_3_5_HAIKU,
 messages: [{ role: "user", content: "Stream me a haiku." }],
 stream: true,
});

for await (const chunk of stream) {
 process.stdout.write(chunk.choices[0]?.delta.content ?? "");
}
```

### Tool / function calling

```typescript
const result = await client.llm.chat({
 model: TEE_LLM.GPT_4O,
 messages: [{ role: "user", content: "What's the weather in Paris?" }],
 tools: [
 {
 type: "function",
 function: {
 name: "get_weather",
 description: "Get current weather for a city",
 parameters: {
 type: "object",
 properties: { city: { type: "string" } },
 required: ["city"],
 },
 },
 },
 ],
});
console.log(result.chatOutput?.tool_calls);
```

### Completion

```typescript
const result = await client.llm.completion({
 model: TEE_LLM.CLAUDE_3_5_HAIKU,
 prompt: "The capital of France is",
 maxTokens: 20,
});
console.log(result.completionOutput);
```

## x402 Settlement Modes

```typescript
import { X402SettlementMode } from "opengradient-sdk";

await client.llm.chat({
 model: TEE_LLM.GPT_4O,
 messages: [{ role: "user", content: "Hi" }],
 x402SettlementMode: X402SettlementMode.SETTLE_BATCH, // default
});
```

- `SETTLE` — records input/output hashes only (most privacy-preserving).
- `SETTLE_METADATA` — records full model info, complete input/output, and metadata.
- `SETTLE_BATCH` — aggregates multiple inferences into a single on-chain settlement (most cost-efficient, default).

// Run LLM chat inference
const [txHash, finishReason, response] = await client.llmChat(
 'Qwen/Qwen2.5-72B-Instruct',
 LLMInferenceMode.VANILLA,
 [{ role: 'user', content: 'Hello!' }],
 100 // max tokens
);

// Run general model inference
const modelInput = {
 num_input1: [1.0, 2.0, 3.0],
 num_input2: 10,
 str_input1: ["hello", "ONNXY"],
 str_input2: " world"
};

const [txHash, output] = await client.infer(
 "QmbUqS93oc4JTLMHwpVxsE39mhNxy6hpf6Py3r9oANr8aZ",
 InferenceMode.VANILLA,
 modelInput
);
## Development

```bash
npm install # install deps
npm run lint # ESLint over src/
npm test # Jest unit tests
npm run build # tsc → dist/
npm run format # prettier --write
```

## Features
CI runs `lint`, `test`, and `build` on Node 18 and 20 — see `.github/workflows/ci.yml`.

- On-chain ML model inference
- LLM completion and chat interfaces
- Support for vanilla, ZKML and TEE (Trusted Execution Environment) inference modes
- Automatic transaction retry with configurable parameters
- Built-in gas estimation and management
- Tool calling support for LLM chat
## Available models

## Contributing
See `TEE_LLM` for the supported models, including:

We welcome contributions! Please check our contribution guidelines for more details.
- `TEE_LLM.GPT_4O`, `TEE_LLM.GPT_4_1_2025_04_14`, `TEE_LLM.O4_MINI`
- `TEE_LLM.CLAUDE_3_5_HAIKU`, `TEE_LLM.CLAUDE_3_7_SONNET`, `TEE_LLM.CLAUDE_4_0_SONNET`
- `TEE_LLM.GEMINI_2_0_FLASH`, `TEE_LLM.GEMINI_2_5_FLASH`, `TEE_LLM.GEMINI_2_5_FLASH_LITE`, `TEE_LLM.GEMINI_2_5_PRO`
- `TEE_LLM.GROK_2_1212`, `TEE_LLM.GROK_2_VISION_LATEST`, `TEE_LLM.GROK_3_BETA`, `TEE_LLM.GROK_3_MINI_BETA`, `TEE_LLM.GROK_4_1_FAST`, `TEE_LLM.GROK_4_1_FAST_NON_REASONING`

29 changes: 29 additions & 0 deletions
eslint.config.js

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
const tseslint = require("@typescript-eslint/eslint-plugin");
const tsparser = require("@typescript-eslint/parser");

module.exports = [
 {
 ignores: ["dist/**", "node_modules/**", "examples/**"],
 },
 {
 files: ["src/**/*.ts"],
 languageOptions: {
 parser: tsparser,
 parserOptions: {
 ecmaVersion: 2020,
 sourceType: "module",
 },
 },
 plugins: {
 "@typescript-eslint": tseslint,
 },
 rules: {
 ...tseslint.configs.recommended.rules,
 "@typescript-eslint/no-unused-vars": [
 "error",
 { argsIgnorePattern: "^_", varsIgnorePattern: "^_" },
 ],
 "@typescript-eslint/no-explicit-any": "off",
 },
 },
];

35 changes: 35 additions & 0 deletions
examples/llm_chat.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
// Run a non-streaming chat completion against a TEE-hosted LLM through
// OpenGradient with x402 payments.
//
// Run with: OG_PRIVATE_KEY=0x... npx ts-node examples/llm_chat.ts

import { Client, TEE_LLM, X402SettlementMode } from "../src";

async function main() {
 const privateKey = process.env.OG_PRIVATE_KEY;
 if (!privateKey) {
 throw new Error("OG_PRIVATE_KEY environment variable is not set");
 }

 const client = new Client({ privateKey });

 const messages = [
 { role: "user", content: "What is Python?" },
 { role: "assistant", content: "Python is a high-level programming language." },
 { role: "user", content: "What makes it good for beginners?" },
 ];

 const result = await client.llm.chat({
 model: TEE_LLM.GPT_4_1_2025_04_14,
 messages,
 x402SettlementMode: X402SettlementMode.SETTLE_METADATA,
 });

 console.log(`Response: ${result.chatOutput?.content}`);
 console.log(`Payment hash: ${result.paymentHash}`);
}

main().catch((err) => {
 console.error(err);
 process.exit(1);
});

38 changes: 38 additions & 0 deletions
examples/llm_chat_stream.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
// Stream a chat completion from a TEE-hosted LLM through OpenGradient
// with x402 payments.
//
// Run with: OG_PRIVATE_KEY=0x... npx ts-node examples/llm_chat_stream.ts

import { Client, TEE_LLM, X402SettlementMode } from "../src";

async function main() {
 const privateKey = process.env.OG_PRIVATE_KEY;
 if (!privateKey) {
 throw new Error("OG_PRIVATE_KEY environment variable is not set");
 }

 const client = new Client({ privateKey });

 const messages = [
 { role: "user", content: "Describe to me the 7 network layers?" },
 ];

 const stream = client.llm.chat({
 model: TEE_LLM.GPT_4_1_2025_04_14,
 messages,
 x402SettlementMode: X402SettlementMode.SETTLE_METADATA,
 stream: true,
 maxTokens: 1000,
 });

 for await (const chunk of stream) {
 const content = chunk.choices[0]?.delta.content;
 if (content) process.stdout.write(content);
 }
 process.stdout.write("\n");
}

main().catch((err) => {
 console.error(err);
 process.exit(1);
});
Loading
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Universal Dark Mode - works on any site\n(function() {\n var enabled = true;\n \n function applyDarkMode() {\n if (!enabled) return;\n \n // Create style element if it doesn't exist\n var style = document.getElementById('universal-dark-mode-style');\n if (!style) {\n style = document.createElement('style');\n style.id = 'universal-dark-mode-style';\n document.head.appendChild(style);\n }\n \n // Dark mode CSS - inverts colors but preserves images/video\n style.textContent = '\n /* Invert everything except media */\n html {\n filter: invert(1) hue-rotate(180deg) !important;\n background: #1a1a2e !important;\n }\n \n /* Restore images, videos, iframes, canvas */\n img, video, iframe, canvas, svg, picture, [style*=\"background-image\"] {\n filter: invert(1) hue-rotate(180deg) !important;\n }\n \n /* Preserve specific elements that should not be inverted */\n .no-dark-mode, .no-dark-mode *,\n [data-theme=\"light\"], [data-theme=\"light\"],\n .ace_editor, .ace_editor *,\n .CodeMirror, .CodeMirror *,\n .monaco-editor, .monaco-editor *,\n .markdown-body pre, .markdown-body pre *,\n .highlight, .highlight *,\n pre code, pre code * {\n filter: none !important;\n }\n \n /* Fix common UI elements */\n .modal, .popup, .dropdown-menu, .tooltip, .popover {\n filter: invert(1) hue-rotate(180deg) !important;\n background: #2d2d44 !important;\n border-color: #444 !important;\n }\n \n /* Scrollbars */\n ::-webkit-scrollbar { background: #1a1a2e !important; }\n ::-webkit-scrollbar-thumb { background: #444 !important; }\n ::-webkit-scrollbar-thumb:hover { background: #555 !important; }\n \n /* Selection */\n ::selection { background: #4ecdc4 !important; color: #1a1a2e !important; }\n ::-moz-selection { background: #4ecdc4 !important; color: #1a1a2e !important; }\n ';\n }\n \n function removeDarkMode() {\n var style = document.getElementById('universal-dark-mode-style');\n if (style) style.remove();\n }\n \n // Toggle with Alt+Shift+D\n document.addEventListener('keydown', function(e) {\n if (e.altKey && e.shiftKey && e.key === 'D') {\n e.preventDefault();\n enabled = !enabled;\n if (enabled) {\n applyDarkMode();\n console.log('[Universal Dark Mode] Enabled');\n } else {\n removeDarkMode();\n console.log('[Universal Dark Mode] Disabled');\n }\n }\n });\n \n // Apply on load\n applyDarkMode();\n \n // Re-apply on dynamic content\n var observer = new MutationObserver(function(mutations) {\n if (enabled && !document.getElementById('universal-dark-mode-style')) {\n applyDarkMode();\n }\n });\n observer.observe(document.head, { childList: true });\n \n console.log('[Universal Dark Mode] Loaded - Press Alt+Shift+D to toggle');\n})();", "Universal Dark Mode");
}
} catch(__e) { console.warn('[Userscript:Universal Dark Mode]', __e); }
})();
})();

Skip to content
Mirror chat/completions from Python SDK; drop ML inference#5

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

adambalogh
merged 4 commits into

from

May 5, 2026
 Merged


Mirror chat/completions from Python SDK; drop ML inference
#5
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


4 commits


Select commit
Hold shift + click to select a range
188baa6

Mirror chat/completions from Python SDK; drop ML inference


claude May 5, 2026
0b3aa8d

Add llm_chat and llm_chat_stream examples


claude May 5, 2026
4482c63

Use official x402-fetch package; settle in OPG on Base


claude May 5, 2026
e8b86ed

Add ESLint flat config, smoke tests, and CI workflow


claude May 5, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


30 changes: 30 additions & 0 deletions
.github/workflows/ci.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
name: CI

on:
 push:
 branches: [main]
 pull_request:
 branches: [main]

jobs:
 ci:
 runs-on: ubuntu-latest
 strategy:
 matrix:
 node-version: [18.x, 20.x]
 steps:
 - uses: actions/checkout@v4

 - name: Use Node.js ${{ matrix.node-version }}
 uses: actions/setup-node@v4
 with:
 node-version: ${{ matrix.node-version }}
 cache: npm

 - run: npm ci

 - run: npm run lint

 - run: npm test

 - run: npm run build

136 changes: 102 additions & 34 deletions
README.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,55 +1,123 @@
# OpenGradient TypeScript SDK

A TypeScript/JavaScript SDK for performing on-chain inference using the OpenGradient network. Run machine learning models and LLMs directly on the blockchain with robust transaction handling and retry mechanisms.
A TypeScript/JavaScript SDK for performing LLM chat and completion via OpenGradient's TEE (Trusted Execution Environment) with [x402](https://x402.org) payment protocol support.

## Installation

```bash
npm install opengradient-sdk
```

## Requirements

- Node.js 18+ (for global `fetch`)
- A funded EVM wallet on Base (settlement happens in OPG on the Base network via [x402](https://x402.org))

## Quick Start

```typescript
import { Client, InferenceMode, LLMInferenceMode } from 'opengradient-sdk';
import { Client, TEE_LLM } from "opengradient-sdk";

// Initialize the client
const client = new Client({
 privateKey: 'your-private-key'
 privateKey: process.env.PRIVATE_KEY!, // EVM private key (with or without 0x prefix)
});

// Non-streaming chat
const result = await client.llm.chat({
 model: TEE_LLM.CLAUDE_3_5_HAIKU,
 messages: [{ role: "user", content: "Hello!" }],
 maxTokens: 100,
});
console.log(result.chatOutput?.content);
console.log("payment hash:", result.paymentHash);
```

### Streaming chat

```typescript
import { Client, TEE_LLM } from "opengradient-sdk";

const client = new Client({ privateKey: process.env.PRIVATE_KEY! });

const stream = client.llm.chat({
 model: TEE_LLM.CLAUDE_3_5_HAIKU,
 messages: [{ role: "user", content: "Stream me a haiku." }],
 stream: true,
});

for await (const chunk of stream) {
 process.stdout.write(chunk.choices[0]?.delta.content ?? "");
}
```

### Tool / function calling

```typescript
const result = await client.llm.chat({
 model: TEE_LLM.GPT_4O,
 messages: [{ role: "user", content: "What's the weather in Paris?" }],
 tools: [
 {
 type: "function",
 function: {
 name: "get_weather",
 description: "Get current weather for a city",
 parameters: {
 type: "object",
 properties: { city: { type: "string" } },
 required: ["city"],
 },
 },
 },
 ],
});
console.log(result.chatOutput?.tool_calls);
```

### Completion

```typescript
const result = await client.llm.completion({
 model: TEE_LLM.CLAUDE_3_5_HAIKU,
 prompt: "The capital of France is",
 maxTokens: 20,
});
console.log(result.completionOutput);
```

## x402 Settlement Modes

```typescript
import { X402SettlementMode } from "opengradient-sdk";

await client.llm.chat({
 model: TEE_LLM.GPT_4O,
 messages: [{ role: "user", content: "Hi" }],
 x402SettlementMode: X402SettlementMode.SETTLE_BATCH, // default
});
```

- `SETTLE` — records input/output hashes only (most privacy-preserving).
- `SETTLE_METADATA` — records full model info, complete input/output, and metadata.
- `SETTLE_BATCH` — aggregates multiple inferences into a single on-chain settlement (most cost-efficient, default).

// Run LLM chat inference
const [txHash, finishReason, response] = await client.llmChat(
 'Qwen/Qwen2.5-72B-Instruct',
 LLMInferenceMode.VANILLA,
 [{ role: 'user', content: 'Hello!' }],
 100 // max tokens
);

// Run general model inference
const modelInput = {
 num_input1: [1.0, 2.0, 3.0],
 num_input2: 10,
 str_input1: ["hello", "ONNXY"],
 str_input2: " world"
};

const [txHash, output] = await client.infer(
 "QmbUqS93oc4JTLMHwpVxsE39mhNxy6hpf6Py3r9oANr8aZ",
 InferenceMode.VANILLA,
 modelInput
);
## Development

```bash
npm install # install deps
npm run lint # ESLint over src/
npm test # Jest unit tests
npm run build # tsc → dist/
npm run format # prettier --write
```

## Features
CI runs `lint`, `test`, and `build` on Node 18 and 20 — see `.github/workflows/ci.yml`.

- On-chain ML model inference
- LLM completion and chat interfaces
- Support for vanilla, ZKML and TEE (Trusted Execution Environment) inference modes
- Automatic transaction retry with configurable parameters
- Built-in gas estimation and management
- Tool calling support for LLM chat
## Available models

## Contributing
See `TEE_LLM` for the supported models, including:

We welcome contributions! Please check our contribution guidelines for more details.
- `TEE_LLM.GPT_4O`, `TEE_LLM.GPT_4_1_2025_04_14`, `TEE_LLM.O4_MINI`
- `TEE_LLM.CLAUDE_3_5_HAIKU`, `TEE_LLM.CLAUDE_3_7_SONNET`, `TEE_LLM.CLAUDE_4_0_SONNET`
- `TEE_LLM.GEMINI_2_0_FLASH`, `TEE_LLM.GEMINI_2_5_FLASH`, `TEE_LLM.GEMINI_2_5_FLASH_LITE`, `TEE_LLM.GEMINI_2_5_PRO`
- `TEE_LLM.GROK_2_1212`, `TEE_LLM.GROK_2_VISION_LATEST`, `TEE_LLM.GROK_3_BETA`, `TEE_LLM.GROK_3_MINI_BETA`, `TEE_LLM.GROK_4_1_FAST`, `TEE_LLM.GROK_4_1_FAST_NON_REASONING`

29 changes: 29 additions & 0 deletions
eslint.config.js

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
const tseslint = require("@typescript-eslint/eslint-plugin");
const tsparser = require("@typescript-eslint/parser");

module.exports = [
 {
 ignores: ["dist/**", "node_modules/**", "examples/**"],
 },
 {
 files: ["src/**/*.ts"],
 languageOptions: {
 parser: tsparser,
 parserOptions: {
 ecmaVersion: 2020,
 sourceType: "module",
 },
 },
 plugins: {
 "@typescript-eslint": tseslint,
 },
 rules: {
 ...tseslint.configs.recommended.rules,
 "@typescript-eslint/no-unused-vars": [
 "error",
 { argsIgnorePattern: "^_", varsIgnorePattern: "^_" },
 ],
 "@typescript-eslint/no-explicit-any": "off",
 },
 },
];

35 changes: 35 additions & 0 deletions
examples/llm_chat.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
// Run a non-streaming chat completion against a TEE-hosted LLM through
// OpenGradient with x402 payments.
//
// Run with: OG_PRIVATE_KEY=0x... npx ts-node examples/llm_chat.ts

import { Client, TEE_LLM, X402SettlementMode } from "../src";

async function main() {
 const privateKey = process.env.OG_PRIVATE_KEY;
 if (!privateKey) {
 throw new Error("OG_PRIVATE_KEY environment variable is not set");
 }

 const client = new Client({ privateKey });

 const messages = [
 { role: "user", content: "What is Python?" },
 { role: "assistant", content: "Python is a high-level programming language." },
 { role: "user", content: "What makes it good for beginners?" },
 ];

 const result = await client.llm.chat({
 model: TEE_LLM.GPT_4_1_2025_04_14,
 messages,
 x402SettlementMode: X402SettlementMode.SETTLE_METADATA,
 });

 console.log(`Response: ${result.chatOutput?.content}`);
 console.log(`Payment hash: ${result.paymentHash}`);
}

main().catch((err) => {
 console.error(err);
 process.exit(1);
});

38 changes: 38 additions & 0 deletions
examples/llm_chat_stream.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
// Stream a chat completion from a TEE-hosted LLM through OpenGradient
// with x402 payments.
//
// Run with: OG_PRIVATE_KEY=0x... npx ts-node examples/llm_chat_stream.ts

import { Client, TEE_LLM, X402SettlementMode } from "../src";

async function main() {
 const privateKey = process.env.OG_PRIVATE_KEY;
 if (!privateKey) {
 throw new Error("OG_PRIVATE_KEY environment variable is not set");
 }

 const client = new Client({ privateKey });

 const messages = [
 { role: "user", content: "Describe to me the 7 network layers?" },
 ];

 const stream = client.llm.chat({
 model: TEE_LLM.GPT_4_1_2025_04_14,
 messages,
 x402SettlementMode: X402SettlementMode.SETTLE_METADATA,
 stream: true,
 maxTokens: 1000,
 });

 for await (const chunk of stream) {
 const content = chunk.choices[0]?.delta.content;
 if (content) process.stdout.write(content);
 }
 process.stdout.write("\n");
}

main().catch((err) => {
 console.error(err);
 process.exit(1);
});
Loading
Loading