vllm-i64 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,432 @@
+/**
+ * vllm-i64 SDK — Type definitions
+ *
+ * All interfaces for requests, responses, and API objects.
+ *
+ * INL - 2025
+ */
+interface ChatMessage {
+    role: "system" | "user" | "assistant" | "tool";
+    content: string | null;
+    tool_calls?: ToolCall[];
+    tool_call_id?: string;
+    name?: string;
+}
+interface ToolCall {
+    id: string;
+    type: "function";
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+interface ToolDefinition {
+    type: "function";
+    function: {
+        name: string;
+        description: string;
+        parameters: Record<string, unknown>;
+    };
+}
+interface ChatCompletionRequest {
+    model?: string;
+    messages: ChatMessage[];
+    temperature?: number;
+    top_p?: number;
+    top_k?: number;
+    max_tokens?: number;
+    stream?: boolean;
+    tools?: ToolDefinition[];
+    tool_choice?: string | {
+        type: string;
+        function: {
+            name: string;
+        };
+    };
+    stop?: string | string[];
+    repetition_penalty?: number;
+    logprobs?: boolean;
+}
+interface ChatCompletionChoice {
+    index: number;
+    message: ChatMessage;
+    finish_reason: "stop" | "length" | "tool_calls";
+    logprobs?: unknown;
+}
+interface ChatCompletionResponse {
+    id: string;
+    object: "chat.completion";
+    created: number;
+    model: string;
+    choices: ChatCompletionChoice[];
+    usage?: UsageInfo;
+}
+interface CompletionRequest {
+    model?: string;
+    prompt: string;
+    max_tokens?: number;
+    temperature?: number;
+    top_p?: number;
+    top_k?: number;
+    stream?: boolean;
+    stop?: string | string[];
+}
+interface CompletionResponse {
+    id: string;
+    object: "text_completion";
+    created: number;
+    model: string;
+    choices: {
+        text: string;
+        index: number;
+        finish_reason: "stop" | "length";
+    }[];
+    usage?: UsageInfo;
+}
+interface UsageInfo {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+}
+interface StreamDelta {
+    id: string;
+    choices: {
+        index: number;
+        delta: {
+            role?: string;
+            content?: string;
+        };
+        finish_reason: string | null;
+    }[];
+}
+interface HealthResponse {
+    status: "ok" | "degraded" | "error";
+    uptime_seconds: number;
+    model_loaded: boolean;
+    kv_cache_usage_pct?: number;
+    gpu?: GpuInfo;
+    [key: string]: unknown;
+}
+interface GpuInfo {
+    free_mb: number;
+    total_mb: number;
+    used_mb: number;
+    utilization_pct: number;
+}
+interface ModelInfo {
+    id: string;
+    object: "model";
+    owned_by: string;
+}
+interface CacheStats {
+    num_blocks: number;
+    used_blocks: number;
+    free_blocks: number;
+    block_size: number;
+    active_seqs: number;
+    usage_pct: number;
+    prefix_cached_blocks?: number;
+    prefix_unique_hashes?: number;
+    lru_evictions_total?: number;
+    swapped_seqs?: number;
+    [key: string]: unknown;
+}
+interface CachePurgeResult {
+    status: string;
+    purged_blocks: number;
+}
+interface MonitorSnapshot {
+    timestamp: number;
+    uptime_s: number;
+    requests_served: number;
+    active_requests: number;
+    peak_batch_size: number;
+    scheduler: Record<string, number>;
+    engine: {
+        total_steps: number;
+        total_tokens_generated: number;
+    };
+    kv_cache?: CacheStats;
+    perf?: {
+        avg_step_ms: number;
+        tok_per_s: number;
+        forward_pct: number;
+    };
+    gpu?: {
+        free_mb: number;
+        total_mb: number;
+        utilization_pct: number;
+    };
+    lora?: {
+        loaded_adapters: number;
+        adapters: string[];
+    };
+}
+interface ExpertStats {
+    num_experts: number;
+    total_tokens: number;
+    distribution: number[];
+    counts: number[];
+    imbalance: number;
+}
+interface LoRAAdapter {
+    id: number;
+    name: string;
+}
+interface LoRALoadParams {
+    adapter_id: number;
+    path: string;
+    name?: string;
+    scaling?: number;
+}
+interface LoRALoadResult {
+    status: string;
+    adapter_id: number;
+    name: string;
+}
+interface LoRAUnloadResult {
+    status: string;
+    adapter_id: number;
+}
+interface LoRAListResult {
+    adapters: LoRAAdapter[];
+}
+interface RAGIndexParams {
+    text?: string;
+    file?: string;
+}
+interface RAGIndexResult {
+    status: string;
+    chunks: number;
+}
+interface RAGSearchResult {
+    query: string;
+    results: RAGResult[];
+    count: number;
+}
+interface RAGResult {
+    text: string;
+    score: number;
+    [key: string]: unknown;
+}
+interface RAGStatsResult {
+    enabled: boolean;
+    total_chunks: number;
+    dimension: number;
+}
+
+/**
+ * vllm-i64 SDK — HTTP Client core
+ *
+ * Handles fetch, auth, timeouts, and SSE streaming.
+ * Endpoint modules use this as their base.
+ *
+ * INL - 2025
+ */
+
+interface ClientOptions {
+    apiKey?: string;
+    timeoutMs?: number;
+}
+declare class HttpClient {
+    readonly baseUrl: string;
+    private apiKey?;
+    private timeout;
+    constructor(baseUrl?: string, options?: ClientOptions);
+    fetch(path: string, init?: RequestInit): Promise<Response>;
+    get<T>(path: string): Promise<T>;
+    post<T>(path: string, body: unknown): Promise<T>;
+    readSSE(res: Response): AsyncGenerator<string, void, undefined>;
+    readSSERaw(res: Response): AsyncGenerator<StreamDelta, void, undefined>;
+}
+
+/**
+ * Chat completions endpoint.
+ *
+ * INL - 2025
+ */
+
+declare class ChatEndpoint {
+    private http;
+    constructor(http: HttpClient);
+    /**
+     * Chat completion (non-streaming).
+     *
+     * @example
+     * ```ts
+     * const res = await client.chat.create([{ role: "user", content: "Hi" }]);
+     * console.log(res.choices[0].message.content);
+     * ```
+     */
+    create(messages: ChatMessage[], options?: Omit<ChatCompletionRequest, "messages" | "stream">): Promise<ChatCompletionResponse>;
+    /**
+     * Streaming chat — yields content strings.
+     *
+     * @example
+     * ```ts
+     * for await (const chunk of client.chat.stream([{ role: "user", content: "Hi" }])) {
+     *   process.stdout.write(chunk);
+     * }
+     * ```
+     */
+    stream(messages: ChatMessage[], options?: Omit<ChatCompletionRequest, "messages" | "stream">): AsyncGenerator<string, void, undefined>;
+    /**
+     * Streaming chat — yields raw SSE delta objects.
+     */
+    streamRaw(messages: ChatMessage[], options?: Omit<ChatCompletionRequest, "messages" | "stream">): AsyncGenerator<StreamDelta, void, undefined>;
+}
+
+/**
+ * Text completions endpoint.
+ *
+ * INL - 2025
+ */
+
+declare class CompletionsEndpoint {
+    private http;
+    constructor(http: HttpClient);
+    /** Text completion (non-streaming). */
+    create(prompt: string, options?: Omit<CompletionRequest, "prompt" | "stream">): Promise<CompletionResponse>;
+    /** Streaming text completion — yields text chunks. */
+    stream(prompt: string, options?: Omit<CompletionRequest, "prompt" | "stream">): AsyncGenerator<string, void, undefined>;
+    /** Submit multiple prompts at once. */
+    batch(prompts: string[], options?: {
+        max_tokens?: number;
+        temperature?: number;
+    }): Promise<{
+        results: CompletionResponse[];
+    }>;
+}
+
+/**
+ * KV cache management endpoints.
+ *
+ * INL - 2025
+ */
+
+declare class CacheEndpoint {
+    private http;
+    constructor(http: HttpClient);
+    /** Get KV cache statistics. */
+    stats(): Promise<CacheStats>;
+    /** Purge prefix cache (admin). */
+    purge(): Promise<CachePurgeResult>;
+}
+
+/**
+ * LoRA adapter management endpoints.
+ *
+ * INL - 2025
+ */
+
+declare class LoRAEndpoint {
+    private http;
+    constructor(http: HttpClient);
+    /** Load a LoRA adapter (admin). */
+    load(params: LoRALoadParams): Promise<LoRALoadResult>;
+    /** Unload a LoRA adapter (admin). */
+    unload(adapter_id: number): Promise<LoRAUnloadResult>;
+    /** List loaded adapters. */
+    list(): Promise<LoRAListResult>;
+}
+
+/**
+ * Monitoring, health, and expert routing endpoints.
+ *
+ * INL - 2025
+ */
+
+declare class MonitorEndpoint {
+    private http;
+    constructor(http: HttpClient);
+    /** Health check with engine stats. */
+    health(): Promise<HealthResponse>;
+    /** Check if server is reachable and ready. */
+    isReady(): Promise<boolean>;
+    /** List available models. */
+    models(): Promise<{
+        data: ModelInfo[];
+    }>;
+    /** Live monitoring snapshot (batch, KV, perf, GPU). */
+    snapshot(): Promise<MonitorSnapshot>;
+    /** Latency percentiles and request stats. */
+    metrics(): Promise<Record<string, unknown>>;
+    /** Expert routing distribution (MoE models). */
+    experts(): Promise<ExpertStats>;
+    /** Cancel a running request. */
+    cancel(requestId: string): Promise<{
+        status: string;
+    }>;
+}
+
+/**
+ * RAG (Retrieval-Augmented Generation) endpoints.
+ *
+ * INL - 2025
+ */
+
+declare class RAGEndpoint {
+    private http;
+    constructor(http: HttpClient);
+    /** Index text or a file. */
+    index(params: RAGIndexParams): Promise<RAGIndexResult>;
+    /** Search indexed documents. */
+    search(query: string, k?: number): Promise<RAGSearchResult>;
+    /** Get RAG index statistics. */
+    stats(): Promise<RAGStatsResult>;
+}
+
+/**
+ * vllm-i64 — TypeScript SDK
+ *
+ * Zero-dependency client for the vllm-i64 inference engine.
+ *
+ * @example
+ * ```ts
+ * import { I64Client } from "vllm-i64";
+ *
+ * const client = new I64Client("http://localhost:8000");
+ *
+ * // Chat
+ * const res = await client.chat.create([{ role: "user", content: "Hello!" }]);
+ *
+ * // Stream
+ * for await (const chunk of client.chat.stream([{ role: "user", content: "Hi" }])) {
+ *   process.stdout.write(chunk);
+ * }
+ *
+ * // Admin
+ * await client.monitor.snapshot();
+ * await client.cache.purge();
+ * await client.lora.load({ adapter_id: 1, path: "/models/v2" });
+ * ```
+ *
+ * INL - 2025
+ */
+
+declare class I64Client {
+    private http;
+    /** Chat completions (streaming + non-streaming, tool_calls). */
+    readonly chat: ChatEndpoint;
+    /** Text completions (streaming + batch). */
+    readonly completions: CompletionsEndpoint;
+    /** KV cache management (stats, purge). */
+    readonly cache: CacheEndpoint;
+    /** LoRA adapter management (load, unload, list). */
+    readonly lora: LoRAEndpoint;
+    /** Monitoring, health, metrics, expert routing. */
+    readonly monitor: MonitorEndpoint;
+    /** RAG — index, search, stats. */
+    readonly rag: RAGEndpoint;
+    /**
+     * Create a vllm-i64 client.
+     *
+     * @param baseUrl - Server URL (default: http://localhost:8000)
+     * @param options - API key and timeout
+     */
+    constructor(baseUrl?: string, options?: ClientOptions);
+    /** Server base URL. */
+    get baseUrl(): string;
+}
+
+export { CacheEndpoint, type CachePurgeResult, type CacheStats, type ChatCompletionChoice, type ChatCompletionRequest, type ChatCompletionResponse, ChatEndpoint, type ChatMessage, type ClientOptions, type CompletionRequest, type CompletionResponse, CompletionsEndpoint, type ExpertStats, type GpuInfo, type HealthResponse, HttpClient, I64Client, type LoRAAdapter, LoRAEndpoint, type LoRAListResult, type LoRALoadParams, type LoRALoadResult, type LoRAUnloadResult, type ModelInfo, MonitorEndpoint, type MonitorSnapshot, RAGEndpoint, type RAGIndexParams, type RAGIndexResult, type RAGResult, type RAGSearchResult, type RAGStatsResult, type StreamDelta, type ToolCall, type ToolDefinition, type UsageInfo, I64Client as default };