@ysk-kit/llm 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 YSK Limited
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,39 @@
+import type { LlmMessage, LlmUsage } from '@ysk-kit/contracts';
+export type LlmInput = {
+    messages: LlmMessage[];
+    temperature?: number | undefined;
+    model?: string | undefined;
+};
+export type LlmResult = {
+    text: string;
+    model: string;
+    usage: LlmUsage;
+};
+export type LlmStreamChunk = {
+    delta: string;
+    done: boolean;
+    usage?: LlmUsage;
+};
+export interface ILlmPort {
+    model: string;
+    complete(input: LlmInput): Promise<LlmResult>;
+    stream(input: LlmInput): AsyncIterable<LlmStreamChunk>;
+}
+export declare const createFakeLlm: (opts?: {
+    text?: string;
+    model?: string;
+}) => ILlmPort;
+export declare const createOpenAiCompatibleLlm: (opts: {
+    baseUrl: string;
+    apiKey: string;
+    model: string;
+    fetchImpl?: typeof fetch;
+}) => ILlmPort;
+export declare const createLlmFromEnv: (env: {
+    NODE_ENV: string;
+    LLM_BASE_URL?: string | undefined;
+    LLM_API_KEY?: string | undefined;
+    XAI_API_KEY?: string | undefined;
+    LLM_MODEL?: string | undefined;
+}) => ILlmPort;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAE/D,MAAM,MAAM,QAAQ,GAAG;IACrB,QAAQ,EAAE,UAAU,EAAE,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC5B,CAAC;AAEF,MAAM,MAAM,SAAS,GAAG;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,QAAQ,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,CAAC,EAAE,QAAQ,CAAC;CAClB,CAAC;AAEF,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;IAC9C,MAAM,CAAC,KAAK,EAAE,QAAQ,GAAG,aAAa,CAAC,cAAc,CAAC,CAAC;CACxD;AAED,eAAO,MAAM,aAAa,GAAI,OAAO;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,KAAG,QAoBxE,CAAC;AAaF,eAAO,MAAM,yBAAyB,GAAI,MAAM;IAC9C,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B,KAAG,QAqFH,CAAC;AAEF,eAAO,MAAM,gBAAgB,GAAI,KAAK;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAChC,KAAG,QAYH,CAAC"}

package/dist/index.js

@@ -0,0 +1,128 @@
+export const createFakeLlm = (opts) => {
+    const text = opts?.text ?? 'pong';
+    const model = opts?.model ?? 'fake';
+    const usage = {
+        promptTokens: 1,
+        completionTokens: text.length,
+        totalTokens: 1 + text.length,
+    };
+    return {
+        model,
+        async complete() {
+            return { text, model, usage };
+        },
+        async *stream() {
+            const mid = Math.max(1, Math.floor(text.length / 2));
+            yield { delta: text.slice(0, mid), done: false };
+            yield { delta: text.slice(mid), done: false };
+            yield { delta: '', done: true, usage };
+        },
+    };
+};
+const toUsage = (raw) => {
+    const u = raw;
+    const promptTokens = u?.prompt_tokens ?? 0;
+    const completionTokens = u?.completion_tokens ?? 0;
+    return {
+        promptTokens,
+        completionTokens,
+        totalTokens: u?.total_tokens ?? promptTokens + completionTokens,
+    };
+};
+export const createOpenAiCompatibleLlm = (opts) => {
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const root = opts.baseUrl.replace(/\/$/, '');
+    return {
+        model: opts.model,
+        async complete(input) {
+            const res = await fetchImpl(`${root}/chat/completions`, {
+                method: 'POST',
+                headers: {
+                    'content-type': 'application/json',
+                    authorization: `Bearer ${opts.apiKey}`,
+                },
+                body: JSON.stringify({
+                    model: input.model ?? opts.model,
+                    messages: input.messages,
+                    temperature: input.temperature,
+                }),
+                signal: AbortSignal.timeout(60_000),
+            });
+            if (!res.ok) {
+                throw new Error(`LLM HTTP ${res.status}`);
+            }
+            const json = (await res.json());
+            return {
+                text: json.choices?.[0]?.message?.content ?? '',
+                model: json.model ?? opts.model,
+                usage: toUsage(json.usage),
+            };
+        },
+        async *stream(input) {
+            const res = await fetchImpl(`${root}/chat/completions`, {
+                method: 'POST',
+                headers: {
+                    'content-type': 'application/json',
+                    authorization: `Bearer ${opts.apiKey}`,
+                },
+                body: JSON.stringify({
+                    model: input.model ?? opts.model,
+                    messages: input.messages,
+                    temperature: input.temperature,
+                    stream: true,
+                    stream_options: { include_usage: true },
+                }),
+            });
+            if (!res.ok || !res.body) {
+                throw new Error(`LLM HTTP ${res.status}`);
+            }
+            const reader = res.body.getReader();
+            const decoder = new TextDecoder();
+            let buffer = '';
+            let usage;
+            while (true) {
+                const { value, done } = await reader.read();
+                if (done)
+                    break;
+                buffer += decoder.decode(value, { stream: true });
+                const lines = buffer.split('\n');
+                buffer = lines.pop() ?? '';
+                for (const line of lines) {
+                    const trimmed = line.trim();
+                    if (!trimmed.startsWith('data:'))
+                        continue;
+                    const data = trimmed.slice(5).trim();
+                    if (data === '[DONE]') {
+                        yield { delta: '', done: true, ...(usage ? { usage } : {}) };
+                        return;
+                    }
+                    try {
+                        const json = JSON.parse(data);
+                        if (json.usage)
+                            usage = toUsage(json.usage);
+                        const delta = json.choices?.[0]?.delta?.content ?? '';
+                        if (delta)
+                            yield { delta, done: false };
+                    }
+                    catch {
+                        /* ignore partial JSON */
+                    }
+                }
+            }
+            yield { delta: '', done: true, ...(usage ? { usage } : {}) };
+        },
+    };
+};
+export const createLlmFromEnv = (env) => {
+    const apiKey = env.LLM_API_KEY || env.XAI_API_KEY;
+    const model = env.LLM_MODEL && env.LLM_MODEL.length > 0 ? env.LLM_MODEL : 'grok-4.7';
+    if (apiKey) {
+        return createOpenAiCompatibleLlm({
+            baseUrl: env.LLM_BASE_URL && env.LLM_BASE_URL.length > 0 ? env.LLM_BASE_URL : 'https://api.x.ai/v1',
+            apiKey,
+            model,
+        });
+    }
+    return createFakeLlm({ model });
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@ysk-kit/llm",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@ysk-kit/contracts": "1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.5.2",
+    "typescript": "^6.0.3",
+    "vitest": "^5.0.2"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "vitest run --passWithNoTests",
+    "build": "tsc -p tsconfig.build.json"
+  }
+}