@lgrammel/ds4-provider 0.0.1

package/README.md

@@ -0,0 +1,96 @@
+# @lgrammel/ds4-provider
+
+AI SDK provider for running DeepSeek V4 Flash locally through
+[DwarfStar 4](https://github.com/antirez/ds4). The package bundles the DS4
+native sources and builds the Node.js addon on install; you only need to provide
+a compatible GGUF model file.
+
+## Getting Started
+
+Install the package and the AI SDK:
+
+```sh
+pnpm add @lgrammel/ds4-provider ai
+```
+
+Install requirements:
+
+- Node.js 18 or newer.
+- A working native build toolchain for `node-gyp`.
+- A DS4-compatible DeepSeek V4 Flash GGUF.
+
+Download a model using DS4's downloader:
+
+```sh
+git clone https://github.com/antirez/ds4.git
+cd ds4
+./download_model.sh q2-imatrix
+```
+
+The DS4 project recommends `q2-imatrix` for 96/128 GB RAM machines and
+`q4-imatrix` for machines with at least 256 GB RAM. The script downloads from
+`https://huggingface.co/antirez/deepseek-v4-gguf` and creates
+`./ds4flash.gguf`.
+
+Point the provider at the downloaded file:
+
+```sh
+export DS4_MODEL_PATH=/path/to/ds4/ds4flash.gguf
+```
+
+## Agent TUI Example
+
+Install the example dependencies:
+
+```sh
+pnpm add @lgrammel/ds4-provider @lgrammel/agent-tui ai zod dotenv
+pnpm add -D tsx typescript @types/node
+```
+
+Create `agent.ts`:
+
+```ts
+import "dotenv/config";
+
+import { runAgentTUI } from "@lgrammel/agent-tui";
+import { ds4 } from "@lgrammel/ds4-provider";
+import { ToolLoopAgent, tool } from "ai";
+import { z } from "zod";
+
+const model = ds4({
+  modelId: "deepseek-v4-flash",
+  modelPath: process.env.DS4_MODEL_PATH ?? "./ds4flash.gguf",
+  contextSize: Number(process.env.DS4_CONTEXT_SIZE ?? 32768),
+});
+
+await runAgentTUI({
+  name: "DS4 Agent",
+  agent: new ToolLoopAgent({
+    model,
+    instructions: "You are a concise local coding agent.",
+    tools: {
+      localTime: tool({
+        description: "Get the current local time.",
+        inputSchema: z.object({}),
+        execute: () => ({ time: new Date().toLocaleString() }),
+      }),
+    },
+  }),
+  reasoning: "auto-collapsed",
+  contextSize: Number(process.env.DS4_CONTEXT_SIZE ?? 32768),
+});
+```
+
+Run it:
+
+```sh
+DS4_MODEL_PATH=/path/to/ds4/ds4flash.gguf pnpm tsx agent.ts
+```
+
+## Credit
+
+This package is a Node.js / AI SDK integration for
+[DwarfStar 4](https://github.com/antirez/ds4), the local inference engine by
+Salvatore Sanfilippo (`antirez`) for DeepSeek V4 Flash. DS4 provides the native
+runtime, model format expectations, Metal/CUDA work, and GGUF download flow; this
+package only wraps that engine for use from JavaScript.

package/binding.gyp

@@ -0,0 +1,75 @@
+{
+  "targets": [
+    {
+      "target_name": "ds4_binding",
+      "sources": [
+        "native/binding.cpp",
+        "ds4/ds4.c"
+      ],
+      "include_dirs": [
+        "<!@(node -p \"require('node-addon-api').include\")",
+        "ds4"
+      ],
+      "dependencies": [
+        "<!(node -p \"require('node-addon-api').gyp\")"
+      ],
+      "defines": [
+        "NAPI_DISABLE_CPP_EXCEPTIONS"
+      ],
+      "cflags": [
+        "-O3",
+        "-ffast-math",
+        "-Wall",
+        "-Wextra"
+      ],
+      "cflags_cc": [
+        "-std=c++17",
+        "-O3",
+        "-Wall",
+        "-Wextra"
+      ],
+      "conditions": [
+        [
+          "OS=='mac'",
+          {
+            "sources": [
+              "ds4/ds4_metal.m"
+            ],
+            "xcode_settings": {
+              "CLANG_ENABLE_OBJC_ARC": "YES",
+              "OTHER_CFLAGS": [
+                "-O3",
+                "-ffast-math",
+                "-mcpu=native"
+              ],
+              "OTHER_CPLUSPLUSFLAGS": [
+                "-std=c++17"
+              ]
+            },
+            "libraries": [
+              "-framework Foundation",
+              "-framework Metal"
+            ]
+          }
+        ],
+        [
+          "OS!='mac'",
+          {
+            "defines": [
+              "DS4_NO_GPU",
+              "_GNU_SOURCE"
+            ],
+            "cflags": [
+              "-march=native",
+              "-fno-finite-math-only"
+            ],
+            "libraries": [
+              "-lm",
+              "-pthread"
+            ]
+          }
+        ]
+      ]
+    }
+  ]
+}

package/dist/ds4-language-model.d.ts

@@ -0,0 +1,71 @@
+import type { LanguageModelV4, LanguageModelV4CallOptions, LanguageModelV4Content, LanguageModelV4FinishReason, LanguageModelV4GenerateResult, LanguageModelV4Message, LanguageModelV4StreamResult, LanguageModelV4ToolCall } from "@ai-sdk/provider";
+import { type ChatMessage } from "./native-binding.js";
+export interface DS4ProviderSettings {
+    /**
+     * Path to a DS4-compatible GGUF model.
+     */
+    modelPath: string;
+    /**
+     * Optional MTP GGUF file path.
+     */
+    mtpPath?: string;
+    /**
+     * AI SDK model id.
+     *
+     * @default "deepseek-v4-flash"
+     */
+    modelId?: string;
+    contextSize?: number;
+    threads?: number;
+    backend?: "metal" | "cuda" | "cpu";
+    mtpDraftTokens?: number;
+    mtpMargin?: number;
+    warmWeights?: boolean;
+    quality?: boolean;
+    /**
+     * Show native DS4 startup logs on stderr.
+     *
+     * @default false
+     */
+    debug?: boolean;
+    topK?: number;
+    minP?: number;
+    seed?: number;
+}
+export interface DS4LanguageModelConfig extends DS4ProviderSettings {
+    modelId: string;
+}
+interface ToolParseResult {
+    content: LanguageModelV4Content[];
+    finishReason?: LanguageModelV4FinishReason;
+    toolCalls: LanguageModelV4ToolCall[];
+    toolDsml?: string;
+}
+export declare class DS4LanguageModel implements LanguageModelV4 {
+    private readonly config;
+    readonly specificationVersion = "v4";
+    readonly provider = "ds4";
+    readonly modelId: string;
+    readonly supportedUrls: {};
+    private readonly topK?;
+    private readonly minP?;
+    private readonly seed?;
+    private readonly toolReplay;
+    private readonly toolReplayIds;
+    private modelHandle;
+    private initPromise;
+    constructor(config: DS4LanguageModelConfig);
+    doGenerate(options: LanguageModelV4CallOptions): Promise<LanguageModelV4GenerateResult>;
+    doStream(options: LanguageModelV4CallOptions): Promise<LanguageModelV4StreamResult>;
+    dispose(): Promise<void>;
+    private ensureModelLoaded;
+    private buildGenerateOptions;
+    private createStream;
+    private runWithAbortSignal;
+    private convertMessages;
+    private rememberToolCalls;
+}
+export declare function convertMessages(messages: LanguageModelV4Message[], options?: Pick<LanguageModelV4CallOptions, "toolChoice" | "tools">, toolReplay?: ReadonlyMap<string, string>, toolReplayIds?: ReadonlyMap<string, string[]>): ChatMessage[];
+export declare function parseGeneratedContent(text: string, initialInReasoning?: boolean): ToolParseResult;
+export {};
+//# sourceMappingURL=ds4-language-model.d.ts.map

package/dist/ds4-language-model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ds4-language-model.d.ts","sourceRoot":"","sources":["../src/ds4-language-model.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,eAAe,EACf,0BAA0B,EAC1B,sBAAsB,EACtB,2BAA2B,EAC3B,6BAA6B,EAC7B,sBAAsB,EAEtB,2BAA2B,EAC3B,uBAAuB,EAGxB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAOL,KAAK,WAAW,EAIjB,MAAM,qBAAqB,CAAC;AAE7B,MAAM,WAAW,mBAAmB;IAClC;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,KAAK,CAAC;IACnC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;OAIG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,sBAAuB,SAAQ,mBAAmB;IACjE,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,UAAU,eAAe;IACvB,OAAO,EAAE,sBAAsB,EAAE,CAAC;IAClC,YAAY,CAAC,EAAE,2BAA2B,CAAC;IAC3C,SAAS,EAAE,uBAAuB,EAAE,CAAC;IACrC,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAYD,qBAAa,gBAAiB,YAAW,eAAe;IAc1C,OAAO,CAAC,QAAQ,CAAC,MAAM;IAbnC,QAAQ,CAAC,oBAAoB,QAAQ;IACrC,QAAQ,CAAC,QAAQ,SAAS;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,aAAa,KAAM;IAE5B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA6B;IACxD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA+B;IAC7D,OAAO,CAAC,WAAW,CAAuB;IAC1C,OAAO,CAAC,WAAW,CAA8B;gBAEpB,MAAM,EAAE,sBAAsB;IAOrD,UAAU,CAAC,OAAO,EAAE,0BAA0B,GAAG,OAAO,CAAC,6BAA6B,CAAC;IA0BvF,QAAQ,CAAC,OAAO,EAAE,0BAA0B,GAAG,OAAO,CAAC,2BAA2B,CAAC;IAyBnF,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;YAOhB,iBAAiB;IAgC/B,OAAO,CAAC,oBAAoB;IAkC5B,OAAO,CAAC,YAAY;YA+IN,kBAAkB;IA6ChC,OAAO,CAAC,eAAe;IAOvB,OAAO,CAAC,iBAAiB;CAa1B;AAED,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,sBAAsB,EAAE,EAClC,OAAO,GAAE,IAAI,CAAC,0BAA0B,EAAE,YAAY,GAAG,OAAO,CAAM,EACtE,UAAU,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,EACxC,aAAa,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,GAC5C,WAAW,EAAE,CA4Cf;AAmGD,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,kBAAkB,UAAQ,GAAG,eAAe,CAsB/F"}