@hoodcompute/sdk 0.1.0

package/dist/client-CIPi_mUM.d.cts

@@ -0,0 +1,418 @@
+/**
+ * Internal HTTP transport. Handles authentication headers, timeouts, automatic
+ * retries with exponential backoff, and error normalization. Not part of the
+ * public API surface.
+ * @internal
+ */
+interface HttpClientOptions {
+    apiKey: string;
+    baseURL: string;
+    timeout: number;
+    maxRetries: number;
+    defaultHeaders?: Record<string, string>;
+    fetch?: typeof fetch;
+}
+interface RequestOptions {
+    method?: string;
+    path: string;
+    query?: Record<string, string | number | undefined>;
+    body?: unknown;
+    /** When true, the raw Response is returned without reading the body. */
+    stream?: boolean;
+    signal?: AbortSignal;
+}
+declare class HttpClient {
+    private readonly apiKey;
+    private readonly baseURL;
+    private readonly timeout;
+    private readonly maxRetries;
+    private readonly defaultHeaders;
+    private readonly fetchImpl;
+    constructor(options: HttpClientOptions);
+    /** Perform a request and return the parsed JSON body plus response headers. */
+    request<T>(options: RequestOptions): Promise<{
+        data: T;
+        response: Response;
+    }>;
+    /**
+     * Perform a request and return the raw Response. Used by the streaming path,
+     * which reads `response.body` directly. Errors are still parsed and thrown.
+     */
+    raw(options: RequestOptions): Promise<Response>;
+    private fetchWithTimeout;
+    private toError;
+    private buildUrl;
+    private buildHeaders;
+    private backoff;
+}
+
+/**
+ * Public type definitions for the HoodCompute SDK.
+ *
+ * The chat completion request and response shapes mirror the OpenAI Chat
+ * Completions API, so existing OpenAI integrations map over cleanly. Fields
+ * unique to HoodCompute (job IDs, on-chain settlement, credit accounting) are
+ * namespaced under `hoodcompute` or exposed as first-class receipt objects.
+ */
+/** Pricing tier a model is grouped under. */
+type ModelTier = "lite" | "standard" | "pro" | "max";
+/** Role of a chat message. */
+type ChatRole = "system" | "user" | "assistant";
+/** A single message in a conversation. */
+interface ChatMessage {
+    role: ChatRole;
+    content: string;
+}
+/** Parameters accepted by `client.chat.completions.create`. */
+interface ChatCompletionCreateParams {
+    /** Model ID to run, for example `qwen3-8b`. See `client.models.list()`. */
+    model: string;
+    /** Ordered list of messages in the conversation. */
+    messages: ChatMessage[];
+    /** When `true`, tokens are streamed back as they are generated. */
+    stream?: boolean;
+    /** Maximum number of tokens to generate. */
+    max_tokens?: number;
+    /** Sampling temperature, 0.0 to 2.0. */
+    temperature?: number;
+    /** Nucleus sampling probability. */
+    top_p?: number;
+    /** Stop sequence or sequences. */
+    stop?: string | string[];
+    /** Penalize repeated tokens, -2.0 to 2.0. */
+    frequency_penalty?: number;
+    /** Penalize tokens that have already appeared, -2.0 to 2.0. */
+    presence_penalty?: number;
+    /** Seed for sampling. Not guaranteed under distributed inference. */
+    seed?: number;
+}
+/** Token accounting for a completed job. */
+interface Usage {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+}
+/** A choice in a non-streaming chat completion. */
+interface ChatCompletionChoice {
+    index: number;
+    message: ChatMessage;
+    finish_reason: string | null;
+}
+/**
+ * A non-streaming chat completion response.
+ *
+ * In addition to the OpenAI-compatible fields, HoodCompute attaches the job ID
+ * and the on-chain settlement transaction so a completion can be verified
+ * independently on Robinhood Chain.
+ */
+interface ChatCompletion {
+    id: string;
+    object: "chat.completion";
+    created: number;
+    model: string;
+    choices: ChatCompletionChoice[];
+    usage: Usage;
+    /** HoodCompute job ID for this completion. */
+    jobId: string;
+    /** Robinhood Chain settlement transaction hash, once available. */
+    settlementTx: string | null;
+    /** Credits charged for this job. */
+    creditsCharged: number | null;
+    /** Credit balance remaining after this job. */
+    creditsRemaining: number | null;
+}
+/** The incremental content in a streaming chunk. */
+interface ChatCompletionDelta {
+    role?: ChatRole;
+    content?: string;
+}
+/** A choice in a streaming chat completion chunk. */
+interface ChatCompletionChunkChoice {
+    index: number;
+    delta: ChatCompletionDelta;
+    finish_reason: string | null;
+}
+/** A single Server-Sent Event chunk in a streaming completion. */
+interface ChatCompletionChunk {
+    id: string;
+    object: "chat.completion.chunk";
+    created: number;
+    model: string;
+    choices: ChatCompletionChunkChoice[];
+}
+/**
+ * On-chain receipt for a settled job.
+ *
+ * Every settled job produces a receipt whose transaction hashes resolve on the
+ * Robinhood Chain Blockscout explorer. The receipt never contains prompt or
+ * completion content.
+ */
+interface JobReceipt {
+    jobId: string;
+    model: string;
+    tier: ModelTier;
+    creditsCharged: number;
+    usdgValue: number;
+    workerAddress: string;
+    escrowTx: string;
+    settlementTx: string;
+    blockNumber: number;
+    proofHash: string;
+}
+/** Lifecycle status of a job. */
+type JobStatus = "pending" | "processing" | "settling" | "settled" | "failed" | "refunded" | "disputed";
+/** On-chain settlement detail attached to a retrieved job. */
+interface JobOnChain {
+    escrowTx: string;
+    settlementTx: string;
+    escrowAddress: string;
+    blockNumber: number;
+    proofHash: string;
+}
+/** A job record retrieved from the Jobs API. */
+interface Job {
+    id: string;
+    object: "job";
+    status: JobStatus;
+    model: string;
+    tier: ModelTier;
+    creditsCharged: number;
+    usdgValue: number;
+    workerAddress: string;
+    createdAt: string;
+    completedAt: string | null;
+    onChain: JobOnChain | null;
+    usage: Usage | null;
+}
+/** Parameters for `client.jobs.list`. */
+interface JobListParams {
+    /** Number of results to return, up to 100. Defaults to 20. */
+    limit?: number;
+    /** Return jobs created before this job ID (cursor pagination). */
+    before?: string;
+    /** Return jobs created after this job ID. */
+    after?: string;
+    /** Filter by status. */
+    status?: JobStatus;
+    /** Filter by model ID. */
+    model?: string;
+}
+/** A page of jobs. */
+interface JobList {
+    object: "list";
+    data: Job[];
+    hasMore: boolean;
+    nextCursor: string | null;
+}
+/** Result of opening a dispute on a job. */
+interface DisputeResult {
+    jobId: string;
+    disputeOpened: boolean;
+    yourHash: string;
+    workerHash: string;
+    disputeTx: string | null;
+    arbitrationWindowHours: number | null;
+}
+/** HoodCompute-specific metadata attached to a model. */
+interface ModelMeta {
+    tier: ModelTier;
+    creditsPerRequest: number;
+    creditsPer1kTokens: number;
+    activeWorkers: number;
+    medianLatencyMs: number;
+    parameters: string;
+    contextWindow: number;
+}
+/** A model available on the network. */
+interface Model {
+    id: string;
+    object: "model";
+    created: number;
+    ownedBy: string;
+    hoodcompute: ModelMeta;
+}
+/** A page of models. */
+interface ModelList {
+    object: "list";
+    data: Model[];
+}
+/** Account and credit balance for the authenticated key. */
+interface Account {
+    wallet: string;
+    creditsRemaining: number;
+    usdgValue: number;
+    lastTopupAt: string | null;
+    apiKeyCreatedAt: string | null;
+}
+
+/**
+ * Server-Sent Events parsing and the streaming chat completion object.
+ */
+
+/**
+ * Lightweight settlement metadata surfaced from a streaming response once it
+ * closes. Values are read from response headers as the network makes them
+ * available. For the full on-chain receipt, call `client.jobs.getReceipt(jobId)`.
+ */
+interface StreamReceipt {
+    jobId: string | null;
+    settlementTx: string | null;
+    escrowTx: string | null;
+    workerAddress: string | null;
+    creditsRemaining: number | null;
+}
+/**
+ * An async-iterable stream of chat completion chunks.
+ *
+ * Iterate it with `for await` to consume tokens as they arrive. Once iteration
+ * finishes, `jobId` and `receipt` are populated from the response.
+ *
+ * @example
+ * const stream = await client.chat.completions.create({ ..., stream: true })
+ * for await (const chunk of stream) {
+ *   process.stdout.write(chunk.choices[0]?.delta?.content ?? "")
+ * }
+ * console.log(stream.receipt.settlementTx)
+ */
+declare class ChatCompletionStream implements AsyncIterable<ChatCompletionChunk> {
+    /** HoodCompute job ID for this completion, from the response header. */
+    jobId: string | null;
+    /** Settlement metadata, populated once the stream finishes. */
+    receipt: StreamReceipt;
+    private readonly response;
+    constructor(response: Response);
+    [Symbol.asyncIterator](): AsyncIterator<ChatCompletionChunk>;
+    /** Convenience: collect the full concatenated text of the stream. */
+    text(): Promise<string>;
+    private readReceipt;
+}
+
+/**
+ * Chat completions. OpenAI-compatible in request and response shape, with the
+ * job ID and on-chain settlement attached to every result.
+ */
+
+declare class Completions {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Create a chat completion.
+     *
+     * Pass `stream: true` to receive a {@link ChatCompletionStream}. Otherwise a
+     * fully resolved {@link ChatCompletion} is returned.
+     */
+    create(params: ChatCompletionCreateParams & {
+        stream: true;
+    }, options?: {
+        signal?: AbortSignal;
+    }): Promise<ChatCompletionStream>;
+    create(params: ChatCompletionCreateParams & {
+        stream?: false;
+    }, options?: {
+        signal?: AbortSignal;
+    }): Promise<ChatCompletion>;
+    create(params: ChatCompletionCreateParams, options?: {
+        signal?: AbortSignal;
+    }): Promise<ChatCompletion | ChatCompletionStream>;
+}
+declare class Chat {
+    readonly completions: Completions;
+    constructor(http: HttpClient);
+}
+
+/**
+ * Models. Reflects the live worker pool: a model is listed only while at least
+ * one worker is hosting it.
+ */
+
+declare class Models {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** List every model currently available on the network. */
+    list(options?: {
+        signal?: AbortSignal;
+    }): Promise<ModelList>;
+    /** Retrieve a single model by ID, including its live worker count. */
+    retrieve(modelId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<Model>;
+}
+
+/**
+ * Jobs. Retrieve job status, fetch on-chain receipts, and open disputes.
+ */
+
+declare class Jobs {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** Retrieve a job by ID, including its on-chain settlement detail. */
+    get(jobId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<Job>;
+    /** List jobs for the authenticated key, most recent first. */
+    list(params?: JobListParams, options?: {
+        signal?: AbortSignal;
+    }): Promise<JobList>;
+    /**
+     * Fetch the on-chain receipt for a settled job. Throws if the job exists but
+     * has not settled yet.
+     */
+    getReceipt(jobId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<JobReceipt>;
+    /**
+     * Open a dispute on a completed job. Must be called within 60 seconds of
+     * receiving the final output token.
+     *
+     * @param receivedOutputHash SHA-256 of the full response text you received,
+     *   formatted as `sha256:<hex>`.
+     */
+    dispute(jobId: string, receivedOutputHash: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<DisputeResult>;
+}
+
+/**
+ * Account. The wallet and credit balance tied to the authenticated API key.
+ */
+
+declare class AccountResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** Retrieve the current account, including the live credit balance. */
+    get(options?: {
+        signal?: AbortSignal;
+    }): Promise<Account>;
+}
+
+/**
+ * The HoodCompute client. Entry point for chat completions, models, jobs, and
+ * account access against the decentralized inference network.
+ */
+
+interface HoodComputeClientOptions {
+    /**
+     * API key, formatted `hoodc_live_...`. Falls back to the
+     * `HOODCOMPUTE_API_KEY` environment variable when omitted.
+     */
+    apiKey?: string;
+    /** API base URL. Defaults to `https://api.hoodcompute.com/v1`. */
+    baseURL?: string;
+    /** Per-request timeout in milliseconds. Defaults to 120000. */
+    timeout?: number;
+    /** Automatic retries on 5xx, 429, and connection failures. Defaults to 2. */
+    maxRetries?: number;
+    /** Headers added to every request. */
+    defaultHeaders?: Record<string, string>;
+    /** Custom fetch implementation. Defaults to the global `fetch`. */
+    fetch?: typeof fetch;
+}
+declare class HoodComputeClient {
+    readonly chat: Chat;
+    readonly models: Models;
+    readonly jobs: Jobs;
+    readonly account: AccountResource;
+    constructor(options?: HoodComputeClientOptions);
+}
+
+export { type Account as A, type ChatCompletion as C, type DisputeResult as D, HoodComputeClient as H, type Job as J, type ModelTier as M, type StreamReceipt as S, type Usage as U, type ChatCompletionChoice as a, type ChatCompletionChunk as b, type ChatCompletionChunkChoice as c, type ChatCompletionCreateParams as d, type ChatCompletionDelta as e, ChatCompletionStream as f, type ChatMessage as g, type ChatRole as h, type HoodComputeClientOptions as i, type JobList as j, type JobListParams as k, type JobOnChain as l, type JobReceipt as m, type JobStatus as n, type Model as o, type ModelList as p, type ModelMeta as q };