@tangle-network/tcloud 0.1.4 → 0.2.0

package/dist/{shielded-BTi_OftW.d.ts → client-CcuHG7_w.d.ts}

@@ -1,5 +1,3 @@
-import { Hex } from 'viem';
-
 /** Core types for the tcloud SDK */
 interface TCloudConfig {
     /** API base URL (default: https://router.tangle.tools/v1) */
@@ -16,6 +14,22 @@ interface TCloudConfig {
     privacy?: PrivacyConfig;
     /** Spending limits and metering */
     limits?: SpendingLimits;
+    /** Retry configuration for transient failures */
+    retry?: RetryConfig | false;
+    /** Default request timeout in ms (default: 60000). Set 0 to disable. */
+    timeout?: number;
+}
+interface RetryConfig {
+    /** Max retry attempts (default: 3) */
+    maxRetries?: number;
+    /** Initial backoff in ms (default: 500) */
+    initialBackoffMs?: number;
+    /** Max backoff in ms (default: 30000) */
+    maxBackoffMs?: number;
+    /** Backoff multiplier (default: 2) */
+    multiplier?: number;
+    /** HTTP status codes that trigger retry (default: [429, 500, 502, 503, 504]) */
+    retryableStatuses?: number[];
 }
 interface SpendingLimits {
     /** Max USD to spend per request. Rejects if estimated cost exceeds this. */
@@ -183,6 +197,39 @@ interface VideoResponse {
     url?: string;
     error?: string;
 }
+/** Request body for POST /v1/avatar/generate */
+interface AvatarGenerateRequest {
+    /** URL to narration audio (wav/mp3) */
+    audio_url: string;
+    /** URL to face image, OR omit and use avatar_id */
+    image_url?: string;
+    /** Preset avatar identifier (provider-specific) */
+    avatar_id?: string;
+    /** Target duration in seconds (capped by operator's max_duration_seconds) */
+    duration_seconds?: number;
+    /** Output format (default: "mp4") */
+    output_format?: string;
+}
+/** Response from POST /v1/avatar/generate (202 Accepted) */
+interface AvatarGenerateResponse {
+    job_id: string;
+    status: 'queued' | 'processing' | 'completed' | 'failed';
+    result?: AvatarResult;
+    error?: string;
+}
+/** Result payload within a completed avatar job */
+interface AvatarResult {
+    video_url: string;
+    duration_seconds: number;
+    format: string;
+}
+/** Response from GET /v1/avatar/jobs/:id */
+interface AvatarJobStatus {
+    job_id: string;
+    status: 'queued' | 'processing' | 'completed' | 'failed';
+    result?: AvatarResult;
+    error?: string;
+}
 interface PrivacyConfig {
     /** 'direct' — no proxy (default). 'relayer' — route through tcloud-relayer. 'socks5' — route through SOCKS5 proxy (e.g. Tor). */
     mode: 'direct' | 'relayer' | 'socks5';
@@ -238,6 +285,19 @@ interface ChatOptions {
     };
     /** Tools / function calling */
     tools?: any[];
+    /** Tool choice strategy or specific tool */
+    toolChoice?: 'none' | 'auto' | 'required' | {
+        type: 'function';
+        function: {
+            name: string;
+        };
+    };
+    /**
+     * Provider-specific parameters passed through to the upstream API.
+     * These are spread into the request body alongside standard fields.
+     * Example: `{ thinking: { type: 'enabled', budget_tokens: 8000 } }`
+     */
+    providerOptions?: Record<string, unknown>;
 }
 interface ChatCompletion {
     id: string;
@@ -294,6 +354,16 @@ interface Operator {
     avgLatencyMs: number;
     totalRequests: number;
     stakeTnt: number;
+    /** GPU model name (e.g. "A100", "H100") */
+    gpuModel?: string;
+    /** Number of GPUs available */
+    gpuCount?: number;
+    /** Total VRAM across all GPUs in MiB */
+    totalVramMib?: number;
+    /** Whether this operator is TEE-attested */
+    teeAttested?: boolean;
+    /** TEE provider if attested (e.g. "aws_nitro") */
+    teeProvider?: string;
     models: {
         modelId: string;
         inputPrice: number;
@@ -310,6 +380,27 @@ interface CreditBalance {
         createdAt: string;
     }[];
 }
+/** Status event from an async job SSE stream */
+interface JobEvent {
+    status: 'queued' | 'processing' | 'completed' | 'failed' | 'cancelled';
+    progress?: number;
+    result?: Record<string, unknown>;
+    error?: string;
+    timestamp: number;
+}
+/** Options for watchJob() */
+interface WatchJobOptions {
+    /** Operator endpoint URL (if not using default routing) */
+    operatorUrl?: string;
+    /** Callback for each event (useful for progress tracking) */
+    onEvent?: (event: JobEvent) => void;
+    /** Timeout in ms (default: 5 minutes) */
+    timeout?: number;
+    /** Model to route to (for operator discovery) */
+    model?: string;
+    /** SSE bearer token (replaces API key for operator SSE auth) */
+    sseToken?: string;
+}
 interface SpendAuth {
     commitment: string;
     serviceId: string;
@@ -321,6 +412,69 @@ interface SpendAuth {
     signature: string;
 }
 
+/**
+ * Private Router — operator rotation strategies for privacy-preserving inference.
+ *
+ * Each strategy determines how requests are distributed across operators
+ * to minimize the information any single operator can gather about a user's
+ * conversation patterns.
+ */
+interface OperatorInfo {
+    slug: string;
+    endpointUrl: string;
+    region: string;
+    reputationScore: number;
+    avgLatencyMs: number;
+    models: string[];
+}
+type RoutingStrategy = 'round-robin' | 'random' | 'geo-distributed' | 'min-exposure' | 'latency-aware';
+interface PrivateRouterConfig {
+    strategy: RoutingStrategy;
+    /** Max requests to same operator before forced rotation */
+    maxRequestsPerOperator: number;
+    /** Minimum number of distinct operators to use */
+    minOperators: number;
+    /** Region preferences (operators in these regions preferred) */
+    preferRegions?: string[];
+    /** Exclude specific operators */
+    excludeOperators?: string[];
+    /** Enable context summarization between operator switches (reduces info leakage) */
+    summarizeOnSwitch: boolean;
+}
+declare class PrivateRouter {
+    private config;
+    private operators;
+    private usage;
+    private currentIndex;
+    private totalRequests;
+    constructor(config?: Partial<PrivateRouterConfig>);
+    /** Set the available operator pool */
+    setOperators(operators: OperatorInfo[]): void;
+    /** Select the next operator for a request */
+    selectOperator(model: string): OperatorInfo | null;
+    /** Should we summarize context before this request? (operator is changing) */
+    shouldSummarize(model: string): boolean;
+    /** Get privacy stats */
+    getStats(): {
+        totalRequests: number;
+        operatorsUsed: number;
+        operatorBreakdown: {
+            slug: string;
+            requests: number;
+            lastUsed: number;
+        }[];
+        strategy: RoutingStrategy;
+    };
+    private roundRobin;
+    private random;
+    private geoDistributed;
+    private minExposure;
+    private latencyAware;
+    private recordUsage;
+    private getLastUsedOperator;
+    private peekNextOperator;
+}
+
 /**
  * Core HTTP client for Tangle AI Cloud.
  * Shared between CLI and SDK.
@@ -334,8 +488,14 @@ declare class TCloudClient {
     private spendAuthFn?;
     private privacy?;
     private limits?;
+    private retryConfig;
+    private timeoutMs;
     private _totalSpent;
     private _requestCount;
+    readonly privateRouter?: PrivateRouter;
+    private _cachedOperators;
+    private _operatorsCachedAt;
+    private static readonly OPERATORS_TTL_MS;
     constructor(config?: TCloudConfig);
     /** Set the SpendAuth signer for private mode */
     setSpendAuthSigner(fn: () => Promise<SpendAuth>): void;
@@ -361,8 +521,36 @@ declare class TCloudClient {
     };
     /** Check spending limits before a request. Throws TCloudError if blocked. */
     private checkLimits;
+    /** Ensure the private router has operators loaded (with TTL-based caching) */
+    private ensureRouterOperators;
     /** Track cost after a response, using actual pricing from response headers when available */
     private trackCost;
+    /**
+     * Core fetch with retry + timeout. All helpers build on this.
+     * Retries on retryable status codes with exponential backoff + jitter.
+     */
+    private _doFetch;
+    /**
+     * Shared request helper for billable JSON API calls.
+     * Enforces: checkLimits → fetch with retry/timeout → error parsing → requestCount.
+     */
+    private _request;
+    /**
+     * Shared request helper for read-only/non-billable JSON API calls.
+     * No limits check, no request counting.
+     */
+    private _fetch;
+    /**
+     * Shared request helper for billable calls that return non-JSON (e.g. ArrayBuffer).
+     */
+    private _requestRaw;
+    /**
+     * Prepare headers for chat requests — operator routing + SpendAuth.
+     * Shared between chat() and chatStream() to eliminate duplication.
+     */
+    private _prepareChatRequest;
+    /** Build the chat completions request body */
+    private _chatBody;
     /** Chat completion (non-streaming) */
     chat(options: ChatOptions): Promise<ChatCompletion>;
     /** Chat completion (streaming) — returns an async iterator of chunks */
@@ -435,6 +623,53 @@ declare class TCloudClient {
     videoGenerate(options: VideoGenerateOptions): Promise<VideoResponse>;
     /** Get video generation status */
     videoStatus(id: string): Promise<VideoResponse>;
+    /** Generate an avatar video (lip-synced talking head from audio + face image).
+     *  Returns 202 with a job_id for async polling via avatarJobStatus(). */
+    avatarGenerate(options: AvatarGenerateRequest): Promise<AvatarGenerateResponse>;
+    /** Poll an avatar generation job by ID. */
+    avatarJobStatus(jobId: string): Promise<AvatarJobStatus>;
+    /** Poll an avatar job until it reaches a terminal state (completed/failed).
+     *  Returns the final job status. Throws on failure. */
+    pollAvatarJob(jobId: string, options?: {
+        intervalMs?: number;
+        timeoutMs?: number;
+    }): Promise<AvatarJobStatus>;
+    /**
+     * Watch an async job via SSE until it reaches a terminal state.
+     * Works with avatar, video, and training blueprint operators.
+     *
+     * @param jobId - The job ID returned by the creation endpoint
+     * @param options - Optional: operatorUrl override, onEvent callback
+     * @returns The final JobEvent (completed/failed/cancelled)
+     */
+    watchJob(jobId: string, options?: WatchJobOptions): Promise<JobEvent>;
+    /** Create a vector collection on the operator's vector store */
+    createCollection(options: {
+        name: string;
+        dimensions: number;
+        distance_metric?: string;
+    }): Promise<any>;
+    /** List collections on the operator's vector store */
+    listCollections(): Promise<any>;
+    /** Upsert vectors into a collection */
+    upsertVectors(collection: string, vectors: Array<{
+        id: string;
+        vector: number[];
+        metadata?: Record<string, any>;
+    }>): Promise<any>;
+    /** Similarity search in a collection */
+    queryVectors(collection: string, options: {
+        vector: number[];
+        top_k?: number;
+        filter?: Record<string, any>;
+    }): Promise<any>;
+    /** RAG query — embed text + search collection in one call */
+    ragQuery(options: {
+        query: string;
+        collection: string;
+        top_k?: number;
+        embedding_model?: string;
+    }): Promise<any>;
     /** Search models by name, provider, or capability */
     searchModels(query: string): Promise<Model[]>;
     /** Estimate cost for a request (without sending it) */
@@ -447,67 +682,47 @@ declare class TCloudClient {
         outputCost: number;
         total: number;
     }>;
+    /**
+     * Get a pricing spectrum across resource tiers for a model.
+     *
+     * Uses REAL per-operator pricing from `operator.models[].inputPrice`.
+     * Each tier filters operators by GPU count and TEE capability, then
+     * reports the cheapest and most expensive operator for that config.
+     *
+     * @param options.model - Model ID to price (falls back to client default)
+     * @param options.tiers - Number of tiers (1-7, default 5)
+     */
+    pricingSpectrum(options: {
+        model?: string;
+        tiers?: number;
+    }): Promise<PricingTier[]>;
+}
+interface TierConfig {
+    name: string;
+    cpu: number;
+    ramGb: number;
+    gpu: number;
+    tee: boolean;
+}
+interface PricingTier {
+    tier: string;
+    config: TierConfig;
+    /** Raw cheapest per-input-token price (for programmatic use) */
+    cheapestPrice?: number;
+    /** Raw priciest per-input-token price (undefined if same as cheapest) */
+    priciestPrice?: number;
+    /** Formatted cheapest price */
+    cheapest: string;
+    /** Formatted priciest price (undefined if only one price point) */
+    priciest?: string;
+    /** Operators matching GPU/TEE requirements */
+    availableOperators: number;
+    /** Operators that also serve the requested model at a listed price */
+    operatorsWithModel: number;
 }
 declare class TCloudError extends Error {
     status: number;
     constructor(status: number, message: string);
 }
 
-/**
- * tcloud/shielded — Ephemeral wallet generation, SpendAuth signing, private inference.
- *
- * import { TCloud } from 'tcloud'
- * const client = TCloud.shielded()  // anonymous, no API key
- */
-
-interface ShieldedWallet {
-    /** Ephemeral spending private key (hex) */
-    privateKey: Hex;
-    /** Derived address */
-    address: string;
-    /** Credit account commitment */
-    commitment: Hex;
-    /** Random salt */
-    salt: Hex;
-}
-/** Generate a new ephemeral shielded wallet */
-declare function generateWallet(): ShieldedWallet;
-/** Sign a SpendAuth for a request */
-declare function signSpendAuth(wallet: ShieldedWallet, params: {
-    serviceId: bigint;
-    jobIndex: number;
-    amount: bigint;
-    operator: Hex;
-    nonce: bigint;
-    expiry: bigint;
-    chainId: number;
-    creditsAddress: Hex;
-}): Promise<SpendAuth>;
-/** Estimate cost in tsUSD base units (6 decimals) */
-declare function estimateCost(inputTokens: number, maxOutputTokens: number, inputPricePerM?: number, outputPricePerM?: number): bigint;
-interface AutoReplenishOptions {
-    minBalance: bigint;
-    replenishAmount: bigint;
-    checkIntervalMs?: number;
-    fundingSource: 'relayer' | 'direct';
-    relayerUrl?: string;
-    fundingWalletKey?: Hex;
-    tokenAddress?: Hex;
-}
-/**
- * Create a shielded TCloudClient that signs SpendAuth automatically.
- * Every request is anonymous — no API key, no identity.
- */
-declare function createShieldedClient(config?: TCloudConfig & {
-    wallet?: ShieldedWallet;
-    operatorAddress?: Hex;
-    chainId?: number;
-    creditsAddress?: Hex;
-    serviceId?: bigint;
-    autoReplenish?: AutoReplenishOptions;
-}): TCloudClient & {
-    wallet: ShieldedWallet;
-    stopAutoReplenish: () => void;
-};
-
-export { type AutoReplenishOptions as A, type BatchJobResponse as B, type ChatCompletion as C, type EmbeddingOptions as E, type FineTuningJob as F, type ImageGenerateOptions as I, type Model as M, type Operator as O, type PrivacyConfig as P, type RerankOptions as R, type ShieldedWallet as S, TCloudClient as T, type VideoGenerateOptions as V, type TCloudConfig as a, type BatchRequest as b, type ChatCompletionChunk as c, type ChatMessage as d, type ChatOptions as e, type CompletionOptions as f, generateWallet as g, type CompletionResponse as h, type CreditBalance as i, type EmbeddingResponse as j, type FineTuningJobOptions as k, type ImageResponse as l, type RerankResponse as m, type RoutingConfig as n, type ShieldedConfig as o, type SpendAuth as p, type SpendingLimits as q, TCloudError as r, type TranscriptionResponse as s, type VideoResponse as t, createShieldedClient as u, estimateCost as v, signSpendAuth as w };
+export { type AvatarGenerateRequest as A, type BatchJobResponse as B, type ChatCompletion as C, type TranscriptionResponse as D, type EmbeddingOptions as E, type FineTuningJob as F, type VideoResponse as G, type ImageGenerateOptions as I, type JobEvent as J, type Model as M, type Operator as O, type PricingTier as P, type RerankOptions as R, type ShieldedConfig as S, TCloudClient as T, type VideoGenerateOptions as V, type WatchJobOptions as W, type TCloudConfig as a, type AvatarGenerateResponse as b, type AvatarJobStatus as c, type AvatarResult as d, type BatchRequest as e, type ChatCompletionChunk as f, type ChatMessage as g, type ChatOptions as h, type CompletionOptions as i, type CompletionResponse as j, type CreditBalance as k, type EmbeddingResponse as l, type FineTuningJobOptions as m, type ImageResponse as n, type OperatorInfo as o, type PrivacyConfig as p, PrivateRouter as q, type PrivateRouterConfig as r, type RerankResponse as s, type RetryConfig as t, type RoutingConfig as u, type RoutingStrategy as v, type SpendAuth as w, type SpendingLimits as x, TCloudError as y, type TierConfig as z };