nadir-sdk 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,268 @@
+interface ChatMessage {
+    role: "system" | "user" | "assistant" | "tool";
+    content: string | null;
+    tool_calls?: unknown[];
+    cache_control?: Record<string, unknown>;
+}
+interface ReasoningConfig {
+    effort?: "low" | "medium" | "high";
+    max_tokens?: number;
+}
+interface ProviderPreferences {
+    order?: string[];
+    ignore?: string[];
+    sort?: string;
+    require_parameters?: string[];
+}
+interface ChatCompletionCreateParams {
+    messages: ChatMessage[];
+    model?: string;
+    temperature?: number;
+    max_tokens?: number;
+    top_p?: number;
+    frequency_penalty?: number;
+    presence_penalty?: number;
+    stream?: boolean;
+    response_format?: Record<string, unknown>;
+    reasoning?: ReasoningConfig;
+    provider?: ProviderPreferences;
+    route?: "fallback";
+    fallback_models?: string[];
+    transforms?: string[];
+    layers?: {
+        routing?: boolean;
+        fallback?: boolean;
+        optimize?: boolean;
+    };
+    tools?: unknown[];
+    tool_choice?: unknown;
+    [key: string]: unknown;
+}
+interface Message {
+    role: string;
+    content: string | null;
+    tool_calls?: unknown[];
+}
+interface Choice {
+    index: number;
+    message?: Message;
+    delta?: Message;
+    finish_reason: string | null;
+}
+interface Usage {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+    reasoning_tokens?: number;
+    cache_creation_input_tokens?: number;
+    cache_read_input_tokens?: number;
+}
+interface NadirMetadata {
+    model_selection_type?: string;
+    strategy?: string;
+    selected_model?: string;
+    complexity_score?: number;
+    analyzer_used?: string;
+    tier?: string;
+    confidence?: number;
+    cost?: Record<string, unknown>;
+    benchmark_comparison?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+interface ChatCompletion {
+    id: string;
+    object: string;
+    created: number;
+    model: string;
+    choices: Choice[];
+    usage?: Usage;
+    nadir_metadata?: NadirMetadata;
+}
+interface ChatCompletionChunk {
+    id: string;
+    object: string;
+    created: number;
+    model: string;
+    choices: Choice[];
+    usage?: Usage;
+}
+interface CreateClusterParams {
+    name: string;
+    description?: string;
+    examples?: string[];
+    classification_criteria?: string;
+}
+interface CreateOrganizationParams {
+    name: string;
+    slug: string;
+    plan_type?: string;
+}
+interface RecommendParams {
+    prompt: string;
+    system_message?: string;
+    models?: string[];
+    providers?: string[];
+    max_models?: number;
+}
+
+/**
+ * Async iterable wrapper around an SSE response stream.
+ *
+ * Usage:
+ * ```ts
+ * for await (const chunk of stream) {
+ *   process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
+ * }
+ * ```
+ */
+declare class Stream<T> implements AsyncIterable<T> {
+    private reader;
+    private decoder;
+    private buffer;
+    private done;
+    private parse;
+    constructor(body: ReadableStream<Uint8Array>, parse: (data: unknown) => T);
+    [Symbol.asyncIterator](): AsyncIterator<T>;
+    private processBuffer;
+}
+
+/**
+ * Nadir Node.js SDK — OpenAI-compatible client for the Nadir LLM router.
+ *
+ * @example
+ * ```ts
+ * import { NadirClient } from "nadir-sdk";
+ *
+ * const client = new NadirClient({ apiKey: "ndr_..." });
+ *
+ * // Chat completion — Nadir picks the optimal model
+ * const response = await client.chat.completions.create({
+ *   messages: [{ role: "user", content: "Hello!" }],
+ * });
+ * console.log(response.choices[0].message?.content);
+ *
+ * // Streaming
+ * const stream = await client.chat.completions.create({
+ *   messages: [{ role: "user", content: "Tell me a story" }],
+ *   stream: true,
+ * });
+ * for await (const chunk of stream) {
+ *   process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
+ * }
+ * ```
+ */
+
+interface NadirClientOptions {
+    /** Nadir API key (`ndr_...`). Falls back to `NADIR_API_KEY` env var. */
+    apiKey?: string;
+    /** API base URL. Falls back to `NADIR_BASE_URL` env var. */
+    baseURL?: string;
+    /** Request timeout in milliseconds (default 120_000). */
+    timeout?: number;
+}
+declare class Completions {
+    private client;
+    constructor(client: NadirClient);
+    /** Create a chat completion (non-streaming). */
+    create(params: ChatCompletionCreateParams & {
+        stream?: false;
+    }): Promise<ChatCompletion>;
+    /** Create a streaming chat completion. */
+    create(params: ChatCompletionCreateParams & {
+        stream: true;
+    }): Promise<Stream<ChatCompletionChunk>>;
+    /** Create a chat completion (overload resolution). */
+    create(params: ChatCompletionCreateParams): Promise<ChatCompletion | Stream<ChatCompletionChunk>>;
+}
+declare class Chat {
+    readonly completions: Completions;
+    constructor(client: NadirClient);
+}
+declare class SmartExport {
+    private client;
+    constructor(client: NadirClient);
+    status(): Promise<Record<string, unknown>>;
+    train(clusterId: string, options?: {
+        baseModel?: string;
+    }): Promise<Record<string, unknown>>;
+    exportData(clusterId: string, options?: {
+        format?: string;
+    }): Promise<Record<string, unknown>>;
+    listJobs(): Promise<Record<string, unknown>>;
+    getJob(jobId: string): Promise<Record<string, unknown>>;
+    cancelJob(jobId: string): Promise<Record<string, unknown>>;
+}
+declare class Clustering {
+    private client;
+    constructor(client: NadirClient);
+    classify(prompt: string): Promise<Record<string, unknown>>;
+    listClusters(): Promise<Record<string, unknown>>;
+    createCluster(params: CreateClusterParams): Promise<Record<string, unknown>>;
+}
+declare class Organizations {
+    private client;
+    constructor(client: NadirClient);
+    list(): Promise<Record<string, unknown>>;
+    create(params: CreateOrganizationParams): Promise<Record<string, unknown>>;
+    get(orgId: string): Promise<Record<string, unknown>>;
+}
+declare class NadirClient {
+    private readonly apiKey;
+    private readonly baseURL;
+    private readonly timeout;
+    /** OpenAI-compatible chat completions namespace. */
+    readonly chat: Chat;
+    /** Smart Export / distillation endpoints. */
+    readonly smartExport: SmartExport;
+    /** Prompt clustering endpoints. */
+    readonly clustering: Clustering;
+    /** Organization management endpoints. */
+    readonly organizations: Organizations;
+    constructor(options?: NadirClientOptions);
+    /** Get a model recommendation without making an LLM call. */
+    recommend(params: RecommendParams): Promise<Record<string, unknown>>;
+    /** List available models. */
+    listModels(): Promise<Record<string, unknown>>;
+    /** List user presets. */
+    listPresets(): Promise<Record<string, unknown>>;
+    /** Check API health. */
+    health(): Promise<Record<string, unknown>>;
+    /** @internal */
+    _request<T = Record<string, unknown>>(method: string, path: string, body?: unknown): Promise<T>;
+    /** @internal — returns the raw Response (for streaming). */
+    _rawRequest(method: string, path: string, body?: unknown): Promise<Response>;
+}
+
+/** Base error for all Nadir API errors. */
+declare class NadirError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    readonly errorType: string | undefined;
+    constructor(message: string, options?: {
+        status?: number;
+        body?: unknown;
+        errorType?: string;
+    });
+}
+/** Raised on 401 Unauthorized — invalid or missing API key. */
+declare class AuthenticationError extends NadirError {
+    constructor(message: string, body?: unknown);
+}
+/** Raised on 429 Too Many Requests. */
+declare class RateLimitError extends NadirError {
+    readonly retryAfter: number | undefined;
+    constructor(message: string, options?: {
+        body?: unknown;
+        retryAfter?: number;
+    });
+}
+/** Raised on server errors (4xx/5xx) not covered by a more specific class. */
+declare class APIError extends NadirError {
+    constructor(message: string, status: number, body?: unknown);
+}
+/** Raised when the SDK cannot reach the Nadir API. */
+declare class ConnectionError extends NadirError {
+    constructor(message: string);
+}
+
+export { APIError, AuthenticationError, type ChatCompletion, type ChatCompletionChunk, type ChatCompletionCreateParams, type ChatMessage, type Choice, ConnectionError, type CreateClusterParams, type CreateOrganizationParams, type Message, NadirClient, type NadirClientOptions, NadirError, type NadirMetadata, type ProviderPreferences, RateLimitError, type ReasoningConfig, type RecommendParams, Stream, type Usage };

package/dist/index.d.ts

@@ -0,0 +1,268 @@
+interface ChatMessage {
+    role: "system" | "user" | "assistant" | "tool";
+    content: string | null;
+    tool_calls?: unknown[];
+    cache_control?: Record<string, unknown>;
+}
+interface ReasoningConfig {
+    effort?: "low" | "medium" | "high";
+    max_tokens?: number;
+}
+interface ProviderPreferences {
+    order?: string[];
+    ignore?: string[];
+    sort?: string;
+    require_parameters?: string[];
+}
+interface ChatCompletionCreateParams {
+    messages: ChatMessage[];
+    model?: string;
+    temperature?: number;
+    max_tokens?: number;
+    top_p?: number;
+    frequency_penalty?: number;
+    presence_penalty?: number;
+    stream?: boolean;
+    response_format?: Record<string, unknown>;
+    reasoning?: ReasoningConfig;
+    provider?: ProviderPreferences;
+    route?: "fallback";
+    fallback_models?: string[];
+    transforms?: string[];
+    layers?: {
+        routing?: boolean;
+        fallback?: boolean;
+        optimize?: boolean;
+    };
+    tools?: unknown[];
+    tool_choice?: unknown;
+    [key: string]: unknown;
+}
+interface Message {
+    role: string;
+    content: string | null;
+    tool_calls?: unknown[];
+}
+interface Choice {
+    index: number;
+    message?: Message;
+    delta?: Message;
+    finish_reason: string | null;
+}
+interface Usage {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+    reasoning_tokens?: number;
+    cache_creation_input_tokens?: number;
+    cache_read_input_tokens?: number;
+}
+interface NadirMetadata {
+    model_selection_type?: string;
+    strategy?: string;
+    selected_model?: string;
+    complexity_score?: number;
+    analyzer_used?: string;
+    tier?: string;
+    confidence?: number;
+    cost?: Record<string, unknown>;
+    benchmark_comparison?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+interface ChatCompletion {
+    id: string;
+    object: string;
+    created: number;
+    model: string;
+    choices: Choice[];
+    usage?: Usage;
+    nadir_metadata?: NadirMetadata;
+}
+interface ChatCompletionChunk {
+    id: string;
+    object: string;
+    created: number;
+    model: string;
+    choices: Choice[];
+    usage?: Usage;
+}
+interface CreateClusterParams {
+    name: string;
+    description?: string;
+    examples?: string[];
+    classification_criteria?: string;
+}
+interface CreateOrganizationParams {
+    name: string;
+    slug: string;
+    plan_type?: string;
+}
+interface RecommendParams {
+    prompt: string;
+    system_message?: string;
+    models?: string[];
+    providers?: string[];
+    max_models?: number;
+}
+
+/**
+ * Async iterable wrapper around an SSE response stream.
+ *
+ * Usage:
+ * ```ts
+ * for await (const chunk of stream) {
+ *   process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
+ * }
+ * ```
+ */
+declare class Stream<T> implements AsyncIterable<T> {
+    private reader;
+    private decoder;
+    private buffer;
+    private done;
+    private parse;
+    constructor(body: ReadableStream<Uint8Array>, parse: (data: unknown) => T);
+    [Symbol.asyncIterator](): AsyncIterator<T>;
+    private processBuffer;
+}
+
+/**
+ * Nadir Node.js SDK — OpenAI-compatible client for the Nadir LLM router.
+ *
+ * @example
+ * ```ts
+ * import { NadirClient } from "nadir-sdk";
+ *
+ * const client = new NadirClient({ apiKey: "ndr_..." });
+ *
+ * // Chat completion — Nadir picks the optimal model
+ * const response = await client.chat.completions.create({
+ *   messages: [{ role: "user", content: "Hello!" }],
+ * });
+ * console.log(response.choices[0].message?.content);
+ *
+ * // Streaming
+ * const stream = await client.chat.completions.create({
+ *   messages: [{ role: "user", content: "Tell me a story" }],
+ *   stream: true,
+ * });
+ * for await (const chunk of stream) {
+ *   process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
+ * }
+ * ```
+ */
+
+interface NadirClientOptions {
+    /** Nadir API key (`ndr_...`). Falls back to `NADIR_API_KEY` env var. */
+    apiKey?: string;
+    /** API base URL. Falls back to `NADIR_BASE_URL` env var. */
+    baseURL?: string;
+    /** Request timeout in milliseconds (default 120_000). */
+    timeout?: number;
+}
+declare class Completions {
+    private client;
+    constructor(client: NadirClient);
+    /** Create a chat completion (non-streaming). */
+    create(params: ChatCompletionCreateParams & {
+        stream?: false;
+    }): Promise<ChatCompletion>;
+    /** Create a streaming chat completion. */
+    create(params: ChatCompletionCreateParams & {
+        stream: true;
+    }): Promise<Stream<ChatCompletionChunk>>;
+    /** Create a chat completion (overload resolution). */
+    create(params: ChatCompletionCreateParams): Promise<ChatCompletion | Stream<ChatCompletionChunk>>;
+}
+declare class Chat {
+    readonly completions: Completions;
+    constructor(client: NadirClient);
+}
+declare class SmartExport {
+    private client;
+    constructor(client: NadirClient);
+    status(): Promise<Record<string, unknown>>;
+    train(clusterId: string, options?: {
+        baseModel?: string;
+    }): Promise<Record<string, unknown>>;
+    exportData(clusterId: string, options?: {
+        format?: string;
+    }): Promise<Record<string, unknown>>;
+    listJobs(): Promise<Record<string, unknown>>;
+    getJob(jobId: string): Promise<Record<string, unknown>>;
+    cancelJob(jobId: string): Promise<Record<string, unknown>>;
+}
+declare class Clustering {
+    private client;
+    constructor(client: NadirClient);
+    classify(prompt: string): Promise<Record<string, unknown>>;
+    listClusters(): Promise<Record<string, unknown>>;
+    createCluster(params: CreateClusterParams): Promise<Record<string, unknown>>;
+}
+declare class Organizations {
+    private client;
+    constructor(client: NadirClient);
+    list(): Promise<Record<string, unknown>>;
+    create(params: CreateOrganizationParams): Promise<Record<string, unknown>>;
+    get(orgId: string): Promise<Record<string, unknown>>;
+}
+declare class NadirClient {
+    private readonly apiKey;
+    private readonly baseURL;
+    private readonly timeout;
+    /** OpenAI-compatible chat completions namespace. */
+    readonly chat: Chat;
+    /** Smart Export / distillation endpoints. */
+    readonly smartExport: SmartExport;
+    /** Prompt clustering endpoints. */
+    readonly clustering: Clustering;
+    /** Organization management endpoints. */
+    readonly organizations: Organizations;
+    constructor(options?: NadirClientOptions);
+    /** Get a model recommendation without making an LLM call. */
+    recommend(params: RecommendParams): Promise<Record<string, unknown>>;
+    /** List available models. */
+    listModels(): Promise<Record<string, unknown>>;
+    /** List user presets. */
+    listPresets(): Promise<Record<string, unknown>>;
+    /** Check API health. */
+    health(): Promise<Record<string, unknown>>;
+    /** @internal */
+    _request<T = Record<string, unknown>>(method: string, path: string, body?: unknown): Promise<T>;
+    /** @internal — returns the raw Response (for streaming). */
+    _rawRequest(method: string, path: string, body?: unknown): Promise<Response>;
+}
+
+/** Base error for all Nadir API errors. */
+declare class NadirError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    readonly errorType: string | undefined;
+    constructor(message: string, options?: {
+        status?: number;
+        body?: unknown;
+        errorType?: string;
+    });
+}
+/** Raised on 401 Unauthorized — invalid or missing API key. */
+declare class AuthenticationError extends NadirError {
+    constructor(message: string, body?: unknown);
+}
+/** Raised on 429 Too Many Requests. */
+declare class RateLimitError extends NadirError {
+    readonly retryAfter: number | undefined;
+    constructor(message: string, options?: {
+        body?: unknown;
+        retryAfter?: number;
+    });
+}
+/** Raised on server errors (4xx/5xx) not covered by a more specific class. */
+declare class APIError extends NadirError {
+    constructor(message: string, status: number, body?: unknown);
+}
+/** Raised when the SDK cannot reach the Nadir API. */
+declare class ConnectionError extends NadirError {
+    constructor(message: string);
+}
+
+export { APIError, AuthenticationError, type ChatCompletion, type ChatCompletionChunk, type ChatCompletionCreateParams, type ChatMessage, type Choice, ConnectionError, type CreateClusterParams, type CreateOrganizationParams, type Message, NadirClient, type NadirClientOptions, NadirError, type NadirMetadata, type ProviderPreferences, RateLimitError, type ReasoningConfig, type RecommendParams, Stream, type Usage };