llm-sdk-js 0.2.0

package/dist/types.d.ts

@@ -0,0 +1,184 @@
+export type ProviderName = "openai" | "anthropic" | "groq" | "ollama" | "local";
+/** e.g. `anthropic/claude-sonnet-4-5` */
+export type ModelRef = `${ProviderName}/${string}` | (string & {});
+export type Role = "system" | "user" | "assistant" | "tool";
+export interface Message {
+    role: Role;
+    content: string;
+    name?: string;
+    /** Present on assistant turns after tool use. */
+    toolCalls?: ToolCall[];
+    /** Present on tool turns — id of the call being answered. */
+    toolCallId?: string;
+}
+export interface RetryOptions {
+    attempts?: number;
+    baseDelay?: number;
+    maxDelay?: number;
+}
+export interface CacheOptions {
+    /** e.g. `"1h"`, `"30m"`, or milliseconds. */
+    ttl?: string | number;
+    /** Cache even when `temperature > 0` (off by default). */
+    includeNonDeterministic?: boolean;
+}
+export interface ProviderOverrideConfig {
+    apiKey?: string;
+    baseUrl?: string;
+    timeoutMs?: number;
+}
+export interface CallOptions {
+    model?: ModelRef;
+    primary?: ModelRef;
+    fallbacks?: ModelRef[];
+    retry?: RetryOptions;
+    /** Total budget across all attempts (ms). */
+    timeout?: number;
+    cache?: CacheOptions | false;
+    temperature?: number;
+    maxTokens?: number;
+    system?: string;
+    messages?: Message[];
+    raw?: Partial<Record<ProviderName, Record<string, unknown>>>;
+    tools?: ToolDefinition[];
+    /** Fail over on content filter / refusal (off by default). */
+    allowContentFilterFailover?: boolean;
+}
+export interface ToolDefinition {
+    name: string;
+    description?: string;
+    schema?: unknown;
+}
+export interface ToolCall {
+    id: string;
+    name: string;
+    args: unknown;
+}
+export interface Usage {
+    input: number;
+    output: number;
+}
+export interface AttemptRecord {
+    provider: ProviderName | string;
+    model: string;
+    error?: string;
+    ms: number;
+}
+export interface CompleteResult {
+    text: string;
+    provider: ProviderName | string;
+    model: string;
+    usage: Usage;
+    cost: number;
+    /** `true` when `model` had no row in the price table — `cost` is `0` because it's unpriced, not free. */
+    unknownModel: boolean;
+    cached: boolean;
+    latencyMs: number;
+    attempts: AttemptRecord[];
+    toolCalls: ToolCall[];
+}
+export interface CompleteInput {
+    system?: string;
+    messages?: Message[];
+    prompt?: string;
+    maxTokens?: number;
+    temperature?: number;
+    tools?: ToolDefinition[];
+}
+export type CompleteArg = string | CompleteInput;
+export interface ExtractInput<S = unknown> {
+    prompt: string;
+    system?: string;
+    schema: S;
+    /** Prompt hint when the schema has no inferable `.shape`. */
+    schemaDescription?: string;
+}
+/** Standard Schema phantom marker (Zod v4, Valibot, ArkType, …). */
+interface StandardSchemaLike<Output> {
+    readonly "~standard": {
+        readonly types?: {
+            readonly output: Output;
+        };
+    };
+}
+/** Zod v3 output phantom (`z.infer`). */
+interface ZodV3Like<Output> {
+    readonly _output: Output;
+}
+/** Infer schema output type; falls back to `unknown`. */
+export type InferSchemaOutput<S> = S extends StandardSchemaLike<infer O> ? O : S extends ZodV3Like<infer O> ? O : unknown;
+export interface ExtractResult<T = unknown> {
+    data: T;
+    text: string;
+    provider: ProviderName | string;
+    model: string;
+    usage: Usage;
+    cost: number;
+    /** `true` when `model` had no row in the price table — `cost` is `0` because it's unpriced, not free. */
+    unknownModel: boolean;
+    cached: boolean;
+    latencyMs: number;
+    attempts: AttemptRecord[];
+}
+export interface RouteConfig extends CallOptions {
+    primary?: ModelRef;
+    fallbacks?: ModelRef[];
+}
+export interface RouterConfig extends CallOptions {
+    primary?: ModelRef;
+    fallbacks?: ModelRef[];
+    routes?: Record<string, RouteConfig>;
+    default?: string;
+    onFallback?: (from: ModelRef, to: ModelRef, err: unknown) => void;
+    providers?: Partial<Record<ProviderName, ProviderOverrideConfig>>;
+    /** Custom adapter for a provider name (replaces the built-in). */
+    adapters?: Record<string, Adapter>;
+}
+export interface StreamChunk {
+    text: string;
+    done?: boolean;
+}
+export interface StreamHandle {
+    [Symbol.asyncIterator](): AsyncIterator<StreamChunk>;
+    result(): Promise<CompleteResult>;
+}
+/** Per-attempt request passed to adapters (no retry/cache). */
+export interface AdapterRequest {
+    model: string;
+    messages: Message[];
+    temperature?: number;
+    maxTokens?: number;
+    tools?: ToolDefinition[];
+    raw?: Record<string, unknown>;
+    signal?: AbortSignal;
+}
+export interface AdapterResponse {
+    text: string;
+    usage: Usage;
+    toolCalls: ToolCall[];
+    finishReason?: string;
+}
+export interface AdapterContext {
+    apiKey?: string;
+    baseUrl?: string;
+    timeoutMs?: number;
+}
+export interface AdapterStreamDelta {
+    type: "delta";
+    text: string;
+}
+export interface AdapterStreamDone {
+    type: "done";
+    usage: Usage;
+    toolCalls: ToolCall[];
+    finishReason?: string;
+}
+export type AdapterStreamEvent = AdapterStreamDelta | AdapterStreamDone;
+export interface Adapter {
+    readonly name: ProviderName | string;
+    complete(request: AdapterRequest): Promise<AdapterResponse>;
+    /** Tool call deltas are accumulated across the stream and surfaced on the `done` event. */
+    stream(request: AdapterRequest): AsyncIterable<AdapterStreamEvent>;
+}
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "llm-sdk-js",
+  "version": "0.2.0",
+  "description": "TypeScript LLM router — smart fallbacks, named routes, cost tracking, and caching. Zero runtime dependencies.",
+  "homepage": "https://llm-sdk.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ALPHACOD3RS/llm-sdk.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ALPHACOD3RS/llm-sdk/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup && tsc --emitDeclarationOnly --declaration --declarationMap",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit -p tsconfig.check.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs",
+    "clean": "rm -rf dist",
+    "changeset": "changeset",
+    "release": "changeset publish"
+  },
+  "keywords": [
+    "llm",
+    "sdk",
+    "router",
+    "fallback",
+    "openai",
+    "anthropic",
+    "groq",
+    "caching"
+  ],
+  "author": "ALPHACOD3RS",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "sideEffects": false,
+  "peerDependencies": {
+    "zod": ">=3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "zod": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@changesets/cli": "^3.0.2",
+    "@lobehub/icons-static-svg": "^1.94.0",
+    "@types/node": "^25.3.5",
+    "tsup": "^8.5.1",
+    "tsx": "^4.23.12",
+    "typescript": "^5.9.3",
+    "vitepress": "^1.6.4",
+    "vitest": "^4.0.18",
+    "zod": "^4.4.3"
+  }
+}