0g-orbit 0.2.2 → 0.2.3

package/src/fine-tuning.ts

@@ -1,330 +0,0 @@
-import { Wallet } from 'ethers'
-import {
-    createZGComputeNetworkBroker,
-    type ZGComputeNetworkBroker,
-} from '@0glabs/0g-serving-broker'
-import type { NetworkConfig } from './networks.js'
-import type {
-    DatasetUploadResult,
-    CreateTaskOptions,
-    FineTuneTask,
-    FineTuneModel,
-    FineTuneProvider,
-    FineTuneStatus,
-} from './types.js'
-import { FineTuningError } from './errors.js'
-import { withRetry } from './retry.js'
-import { StorageClient } from './storage.js'
-
-const DEFAULT_TRAINING_PARAMS = {
-    nEpochs: 3,
-    batchSize: 4,
-    learningRate: 5e-5,
-    loraRank: 8,
-    loraAlpha: 16,
-}
-
-export class FineTuningClient {
-    private broker: ZGComputeNetworkBroker | null = null
-    private initialized = false
-    private wallet: Wallet
-    private network: NetworkConfig
-    private storageClient: StorageClient
-
-    constructor(network: NetworkConfig, wallet: Wallet, storageClient: StorageClient) {
-        this.network = network
-        this.wallet = wallet
-        this.storageClient = storageClient
-    }
-
-    private async ensureBroker(): Promise<ZGComputeNetworkBroker> {
-        if (this.broker && this.initialized) return this.broker
-
-        try {
-            this.broker = await createZGComputeNetworkBroker(
-                this.wallet as any,
-                this.network.ledgerContractAddress,
-                this.network.inferenceContractAddress,
-                this.network.fineTuningContractAddress
-            )
-            this.initialized = true
-            return this.broker
-        } catch (err: unknown) {
-            const msg = err instanceof Error ? err.message : String(err)
-            throw new FineTuningError(
-                `Failed to initialize fine-tuning broker: ${msg}`,
-                'Check your network connection and wallet private key. The compute contracts may be temporarily unavailable.'
-            )
-        }
-    }
-
-    // --- Dataset ---
-
-    /**
-     * Upload a dataset to 0G Storage for fine-tuning.
-     * Uses the existing StorageClient for upload, returning the root hash
-     * needed to create a fine-tuning task.
-     */
-    async uploadDataset(filePath: string): Promise<DatasetUploadResult> {
-        return withRetry(
-            async () => {
-                try {
-                    const result = await this.storageClient.store(filePath)
-                    return {
-                        root: result.root,
-                        txHash: result.txHash,
-                    }
-                } catch (err: unknown) {
-                    const msg = err instanceof Error ? err.message : String(err)
-                    throw new FineTuningError(
-                        `Failed to upload dataset: ${msg}`,
-                        'Check that the dataset file exists, is valid JSONL, and you have sufficient OG balance.'
-                    )
-                }
-            },
-            { maxAttempts: 3 }
-        )
-    }
-
-    // --- Tasks ---
-
-    /**
-     * Create a fine-tuning task. Requires a dataset already uploaded to 0G Storage.
-     */
-    async createTask(options: CreateTaskOptions): Promise<FineTuneTask> {
-        const broker = await this.ensureBroker()
-
-        if (!broker.fineTuning) {
-            throw new FineTuningError(
-                'Fine-tuning broker not available.',
-                'Fine-tuning requires a Wallet signer (not JsonRpcSigner).'
-            )
-        }
-
-        const params = { ...DEFAULT_TRAINING_PARAMS, ...options.trainingParams }
-
-        return withRetry(
-            async () => {
-                try {
-                    // Acknowledge the provider signer (required before task creation)
-                    await broker.fineTuning!.acknowledgeProviderSigner(
-                        options.providerAddress
-                    )
-
-                    // Write training params as JSON string (broker expects a file path,
-                    // but the underlying createTask reads the file content — we'll pass
-                    // the JSON string directly via a temp file approach)
-                    const { writeFileSync, unlinkSync } = await import('node:fs')
-                    const { tmpdir } = await import('node:os')
-                    const { join } = await import('node:path')
-                    const { randomBytes } = await import('node:crypto')
-
-                    const tempPath = join(tmpdir(), `orbit-params-${randomBytes(8).toString('hex')}.json`)
-                    writeFileSync(tempPath, JSON.stringify(params))
-
-                    let taskId: string
-                    try {
-                        taskId = await broker.fineTuning!.createTask(
-                            options.providerAddress,
-                            options.model,
-                            options.dataset,
-                            tempPath
-                        )
-                    } finally {
-                        try { unlinkSync(tempPath) } catch { /* ignore cleanup errors */ }
-                    }
-
-                    return {
-                        id: taskId,
-                        model: options.model,
-                        dataset: options.dataset,
-                        provider: options.providerAddress,
-                        status: 'init' as FineTuneStatus,
-                    }
-                } catch (err: unknown) {
-                    const msg = err instanceof Error ? err.message : String(err)
-                    if (msg.includes('User opted not to continue')) {
-                        throw new FineTuningError(msg, 'The provider has pending tasks in queue. Try again later or use a different provider.')
-                    }
-                    throw new FineTuningError(
-                        `Failed to create task: ${msg}`,
-                        'Verify the model name, dataset hash, and provider address. Run orbit.listModels() to see available options.'
-                    )
-                }
-            },
-            { maxAttempts: 2 }
-        )
-    }
-
-    /**
-     * Get the status of a fine-tuning task.
-     */
-    async getTask(providerAddress: string, taskId: string): Promise<FineTuneTask> {
-        const broker = await this.ensureBroker()
-
-        if (!broker.fineTuning) {
-            throw new FineTuningError('Fine-tuning broker not available.')
-        }
-
-        try {
-            const task = await broker.fineTuning.getTask(providerAddress, taskId)
-            return this.mapTask(task, providerAddress)
-        } catch (err: unknown) {
-            const msg = err instanceof Error ? err.message : String(err)
-            if (msg.includes('No task found') || msg.includes('not found')) {
-                throw new FineTuningError(
-                    `Task "${taskId}" not found for provider ${providerAddress}.`,
-                    'Check the task ID and provider address. Run orbit.listTasks() to see your tasks.'
-                )
-            }
-            throw new FineTuningError(`Failed to get task: ${msg}`)
-        }
-    }
-
-    /**
-     * Get the training log for a fine-tuning task.
-     */
-    async getTaskLog(providerAddress: string, taskId: string): Promise<string> {
-        const broker = await this.ensureBroker()
-
-        if (!broker.fineTuning) {
-            throw new FineTuningError('Fine-tuning broker not available.')
-        }
-
-        try {
-            return await broker.fineTuning.getLog(providerAddress, taskId)
-        } catch (err: unknown) {
-            const msg = err instanceof Error ? err.message : String(err)
-            throw new FineTuningError(`Failed to get task log: ${msg}`)
-        }
-    }
-
-    /**
-     * List all fine-tuning tasks for a given provider.
-     */
-    async listTasks(providerAddress: string): Promise<FineTuneTask[]> {
-        const broker = await this.ensureBroker()
-
-        if (!broker.fineTuning) {
-            throw new FineTuningError('Fine-tuning broker not available.')
-        }
-
-        try {
-            const tasks = await broker.fineTuning.listTask(providerAddress)
-            return tasks.map((t) => this.mapTask(t, providerAddress))
-        } catch (err: unknown) {
-            const msg = err instanceof Error ? err.message : String(err)
-            throw new FineTuningError(`Failed to list tasks: ${msg}`)
-        }
-    }
-
-    // --- Models ---
-
-    /**
-     * Download a fine-tuned model. Combines acknowledge + download.
-     * The task must be in 'delivered' status.
-     */
-    async downloadModel(
-        providerAddress: string,
-        taskId: string,
-        outputPath: string
-    ): Promise<void> {
-        const broker = await this.ensureBroker()
-
-        if (!broker.fineTuning) {
-            throw new FineTuningError('Fine-tuning broker not available.')
-        }
-
-        return withRetry(
-            async () => {
-                try {
-                    await broker.fineTuning!.acknowledgeModel(
-                        providerAddress,
-                        taskId,
-                        outputPath
-                    )
-                } catch (err: unknown) {
-                    const msg = err instanceof Error ? err.message : String(err)
-                    if (msg.includes('No deliverable found')) {
-                        throw new FineTuningError(
-                            `Model not ready for task "${taskId}". The task may still be training.`,
-                            'Check task status with orbit.getFineTuneTask(). The task must be in "delivered" status.'
-                        )
-                    }
-                    throw new FineTuningError(
-                        `Failed to download model: ${msg}`,
-                        'Ensure the task is in "delivered" status and the output path is writable.'
-                    )
-                }
-            },
-            { maxAttempts: 2 }
-        )
-    }
-
-    /**
-     * List available base models for fine-tuning.
-     */
-    async listModels(): Promise<FineTuneModel[]> {
-        const broker = await this.ensureBroker()
-
-        if (!broker.fineTuning) {
-            throw new FineTuningError('Fine-tuning broker not available.')
-        }
-
-        try {
-            const [standardModels, customizedModels] = await broker.fineTuning.listModel()
-
-            const models: FineTuneModel[] = []
-
-            for (const [name, config] of standardModels) {
-                models.push({ name, config })
-            }
-
-            for (const [name, config] of customizedModels) {
-                models.push({ name, config })
-            }
-
-            return models
-        } catch (err: unknown) {
-            const msg = err instanceof Error ? err.message : String(err)
-            throw new FineTuningError(`Failed to list models: ${msg}`)
-        }
-    }
-
-    /**
-     * List fine-tuning service providers.
-     */
-    async listProviders(): Promise<FineTuneProvider[]> {
-        const broker = await this.ensureBroker()
-
-        if (!broker.fineTuning) {
-            throw new FineTuningError('Fine-tuning broker not available.')
-        }
-
-        try {
-            const services = await broker.fineTuning.listService()
-            return services.map((s: any) => ({
-                address: s.provider ?? '',
-                url: s.url ?? '',
-                models: s.models ?? [],
-            }))
-        } catch (err: unknown) {
-            const msg = err instanceof Error ? err.message : String(err)
-            throw new FineTuningError(`Failed to list providers: ${msg}`)
-        }
-    }
-
-    // --- Helpers ---
-
-    private mapTask(task: any, providerAddress: string): FineTuneTask {
-        return {
-            id: task.id ?? '',
-            model: task.preTrainedModelHash ?? '',
-            dataset: task.datasetHash ?? '',
-            provider: providerAddress,
-            status: (task.progress?.toLowerCase() ?? 'init') as FineTuneStatus,
-            createdAt: task.createdAt,
-            updatedAt: task.updatedAt,
-        }
-    }
-}

package/src/index.ts

@@ -1,45 +0,0 @@
-// Main entry point
-export { Orbit } from './orbit.js'
-
-// Clients (for direct access)
-export { StorageClient } from './storage.js'
-export { InferenceClient } from './inference.js'
-export { FineTuningClient } from './fine-tuning.js'
-
-// Types
-export type {
-    OrbitConfig,
-    StoreResult,
-    StoreOptions,
-    RetrieveOptions,
-    InferResult,
-    InferOptions,
-    ServiceInfo,
-    AccountStatus,
-    DatasetUploadResult,
-    CreateTaskOptions,
-    FineTuneTask,
-    FineTuneStatus,
-    FineTuneModel,
-    FineTuneProvider,
-} from './types.js'
-
-// Network config
-export type { NetworkName, NetworkConfig } from './networks.js'
-export { NETWORKS, getNetwork } from './networks.js'
-
-// Retry utilities
-export { withRetry, isTransientError } from './retry.js'
-export type { RetryOptions } from './retry.js'
-
-// Errors
-export {
-    OrbitError,
-    ConnectionError,
-    StorageError,
-    InferenceError,
-    InsufficientBalanceError,
-    ProviderNotFoundError,
-    TimeoutError,
-    FineTuningError,
-} from './errors.js'

package/src/inference.ts

@@ -1,256 +0,0 @@
-import { Wallet } from 'ethers'
-import {
-    createZGComputeNetworkBroker,
-    type ZGComputeNetworkBroker,
-} from '@0glabs/0g-serving-broker'
-import type { NetworkConfig } from './networks.js'
-import type { InferResult, InferOptions, ServiceInfo } from './types.js'
-import { InferenceError, ProviderNotFoundError, TimeoutError } from './errors.js'
-import { withRetry } from './retry.js'
-
-const DEFAULT_LEDGER_DEPOSIT = 0.1 // 0.1 OG initial deposit
-const AUTO_FUND_INTERVAL = 30_000 // 30 seconds
-const DEFAULT_TIMEOUT = 30_000 // 30 seconds
-
-interface ChatCompletionResponse {
-    id?: string
-    model?: string
-    choices?: Array<{ message?: { content?: string } }>
-    usage?: {
-        prompt_tokens?: number
-        completion_tokens?: number
-        total_tokens?: number
-    }
-}
-
-export class InferenceClient {
-    private broker: ZGComputeNetworkBroker | null = null
-    private wallet: Wallet
-    private network: NetworkConfig
-    private initialized = false
-
-    constructor(network: NetworkConfig, wallet: Wallet) {
-        this.network = network
-        this.wallet = wallet
-    }
-
-    private async ensureBroker(): Promise<ZGComputeNetworkBroker> {
-        if (this.broker && this.initialized) return this.broker
-
-        try {
-            // Cast wallet to avoid ESM/CJS ethers type mismatch
-            this.broker = await createZGComputeNetworkBroker(
-                this.wallet as any,
-                this.network.ledgerContractAddress,
-                this.network.inferenceContractAddress,
-                this.network.fineTuningContractAddress
-            )
-            this.initialized = true
-            return this.broker
-        } catch (err: unknown) {
-            const msg = err instanceof Error ? err.message : String(err)
-            throw new InferenceError(
-                `Failed to initialize compute broker: ${msg}`,
-                'Check your network connection and wallet private key. The compute contracts may be temporarily unavailable.'
-            )
-        }
-    }
-
-    async listServices(): Promise<ServiceInfo[]> {
-        const broker = await this.ensureBroker()
-        return withRetry(
-            async () => {
-                try {
-                    const services = await broker.inference.listService()
-                    return services.map((s: any) => ({
-                        provider: s.provider ?? s.address ?? '',
-                        model: s.model ?? '',
-                        url: s.url ?? '',
-                        inputPrice: BigInt(s.inputPrice ?? 0),
-                        outputPrice: BigInt(s.outputPrice ?? 0),
-                        verifiable: Boolean(s.verifiability ?? s.verifiable),
-                    }))
-                } catch (err: unknown) {
-                    const msg = err instanceof Error ? err.message : String(err)
-                    throw new InferenceError(
-                        `Failed to list services: ${msg}`,
-                        'The inference contract may be temporarily unavailable. Check your network connection.'
-                    )
-                }
-            },
-            { maxAttempts: 3 }
-        )
-    }
-
-    async infer(
-        model: string,
-        options: InferOptions
-    ): Promise<InferResult> {
-        const broker = await this.ensureBroker()
-
-        // Find a provider for the requested model
-        const providerAddress = options.provider ?? await this.findProvider(model)
-        const timeout = options.timeout ?? DEFAULT_TIMEOUT
-
-        try {
-            // Ensure ledger exists and has funds
-            await this.ensureLedgerFunded(broker)
-
-            // Start auto-funding for this provider
-            await broker.inference.startAutoFunding(providerAddress, {
-                interval: AUTO_FUND_INTERVAL,
-            })
-
-            // Get service metadata (endpoint + model name)
-            const { endpoint, model: providerModel } =
-                await broker.inference.getServiceMetadata(providerAddress)
-
-            // Build the request content for billing calculation
-            const content = options.messages.map((m) => m.content).join('\n')
-
-            // Get authenticated headers
-            const headers = await broker.inference.getRequestHeaders(
-                providerAddress,
-                content
-            )
-
-            // Make the OpenAI-compatible request with timeout + retry
-            const data = await withRetry(
-                () => this.fetchCompletion(endpoint, providerModel, options, headers, timeout),
-                {
-                    maxAttempts: 2,
-                    baseDelay: 2000,
-                    isRetryable: (err) => {
-                        // Don't retry timeouts (user already waited long enough)
-                        if (err instanceof TimeoutError) return false
-                        // Retry transient provider errors
-                        if (err instanceof InferenceError) {
-                            const msg = err.message
-                            return msg.includes('502') || msg.includes('503') || msg.includes('504')
-                        }
-                        return false
-                    },
-                }
-            )
-
-            // Extract chatID for TEE verification
-            const chatID = data._chatID
-
-            // Process response (caches fees + verifies TEE signature)
-            let verified: boolean | null = null
-            try {
-                verified = await broker.inference.processResponse(
-                    providerAddress,
-                    chatID,
-                    data.usage ? JSON.stringify(data.usage) : undefined
-                )
-            } catch {
-                // Verification failure is non-fatal
-                verified = null
-            }
-
-            // Stop auto-funding
-            broker.inference.stopAutoFunding(providerAddress)
-
-            return {
-                content: data.choices?.[0]?.message?.content ?? '',
-                model: data.model ?? providerModel,
-                usage: data.usage
-                    ? {
-                          promptTokens: data.usage.prompt_tokens ?? 0,
-                          completionTokens: data.usage.completion_tokens ?? 0,
-                          totalTokens: data.usage.total_tokens ?? 0,
-                      }
-                    : undefined,
-                verified,
-            }
-        } catch (err) {
-            // Clean up auto-funding on error
-            broker.inference.stopAutoFunding(providerAddress)
-
-            if (err instanceof InferenceError || err instanceof TimeoutError || err instanceof ProviderNotFoundError) throw err
-            const msg = err instanceof Error ? err.message : String(err)
-            throw new InferenceError(`Inference failed: ${msg}`)
-        }
-    }
-
-    private async fetchCompletion(
-        endpoint: string,
-        providerModel: string,
-        options: InferOptions,
-        headers: Record<string, string> | object,
-        timeout: number
-    ): Promise<ChatCompletionResponse & { _chatID?: string }> {
-        const controller = new AbortController()
-        const timer = setTimeout(() => controller.abort(), timeout)
-
-        let response: Response
-        try {
-            response = await fetch(`${endpoint}/chat/completions`, {
-                method: 'POST',
-                headers: {
-                    'Content-Type': 'application/json',
-                    ...headers,
-                },
-                body: JSON.stringify({
-                    model: providerModel,
-                    messages: options.messages,
-                    temperature: options.temperature,
-                    max_tokens: options.maxTokens,
-                }),
-                signal: controller.signal,
-            })
-        } catch (err) {
-            if (err instanceof Error && err.name === 'AbortError') {
-                throw new TimeoutError(
-                    `Inference request timed out after ${timeout / 1000}s.`
-                )
-            }
-            throw err
-        } finally {
-            clearTimeout(timer)
-        }
-
-        if (!response.ok) {
-            const body = await response.text().catch(() => '')
-            throw new InferenceError(
-                `Provider returned ${response.status}: ${body}`,
-                response.status === 429
-                    ? 'Provider is rate-limited. Wait a moment and retry, or try a different provider.'
-                    : response.status >= 500
-                      ? 'The provider is experiencing issues. Try a different provider with the provider option.'
-                      : 'Check the model name and request parameters.'
-            )
-        }
-
-        const data = (await response.json()) as ChatCompletionResponse
-        const chatID = response.headers.get('ZG-Res-Key') ?? data.id ?? undefined
-
-        return { ...data, _chatID: chatID }
-    }
-
-    private async findProvider(model: string): Promise<string> {
-        const services = await this.listServices()
-        const match = services.find(
-            (s) => s.model.toLowerCase() === model.toLowerCase()
-        )
-        if (!match) {
-            const available = [...new Set(services.map((s) => s.model))].join(', ') || 'none'
-            throw new ProviderNotFoundError(
-                `No provider found for model "${model}". Available models: ${available}`
-            )
-        }
-        return match.provider
-    }
-
-    private async ensureLedgerFunded(
-        broker: ZGComputeNetworkBroker
-    ): Promise<void> {
-        try {
-            await broker.ledger.getLedger()
-        } catch {
-            // Ledger doesn't exist yet — create it with initial deposit
-            await broker.ledger.addLedger(DEFAULT_LEDGER_DEPOSIT)
-        }
-    }
-}

package/src/networks.test.ts

@@ -1,62 +0,0 @@
-import { describe, it, expect } from 'vitest'
-import { getNetwork, NETWORKS } from './networks.js'
-
-describe('NETWORKS', () => {
-    it('testnet has correct chain ID', () => {
-        expect(NETWORKS.testnet.chainId).toBe(16602n)
-    })
-
-    it('mainnet has correct chain ID', () => {
-        expect(NETWORKS.mainnet.chainId).toBe(16661n)
-    })
-
-    it('testnet has multiple fallback RPC URLs', () => {
-        expect(NETWORKS.testnet.rpcUrls.length).toBeGreaterThanOrEqual(2)
-        expect(NETWORKS.testnet.rpcUrls[0]).toBe(NETWORKS.testnet.rpcUrl)
-    })
-
-    it('mainnet has multiple fallback RPC URLs', () => {
-        expect(NETWORKS.mainnet.rpcUrls.length).toBeGreaterThanOrEqual(2)
-        expect(NETWORKS.mainnet.rpcUrls[0]).toBe(NETWORKS.mainnet.rpcUrl)
-    })
-
-    it('all contract addresses are non-empty hex strings', () => {
-        for (const net of Object.values(NETWORKS)) {
-            expect(net.flowContractAddress).toMatch(/^0x[0-9a-fA-F]+$/)
-            expect(net.ledgerContractAddress).toMatch(/^0x[0-9a-fA-F]+$/)
-            expect(net.inferenceContractAddress).toMatch(/^0x[0-9a-fA-F]+$/)
-            expect(net.fineTuningContractAddress).toMatch(/^0x[0-9a-fA-F]+$/)
-        }
-    })
-})
-
-describe('getNetwork', () => {
-    it('resolves by name', () => {
-        const net = getNetwork('testnet')
-        expect(net.name).toBe('testnet')
-        expect(net.chainId).toBe(16602n)
-    })
-
-    it('resolves by chain ID', () => {
-        const net = getNetwork(16661n)
-        expect(net.name).toBe('mainnet')
-    })
-
-    it('throws on unknown name', () => {
-        expect(() => getNetwork('devnet' as any)).toThrow('Unknown network')
-    })
-
-    it('throws on unknown chain ID', () => {
-        expect(() => getNetwork(99999n)).toThrow('Unknown chain ID')
-    })
-
-    it('returns a copy — mutations do not affect originals', () => {
-        const net = getNetwork('testnet')
-        net.rpcUrl = 'https://mutated.example.com'
-        net.rpcUrls.push('https://extra.example.com')
-
-        const fresh = getNetwork('testnet')
-        expect(fresh.rpcUrl).not.toBe('https://mutated.example.com')
-        expect(fresh.rpcUrls).not.toContain('https://extra.example.com')
-    })
-})