@astack-tech/integrations 0.1.1-beta.6 → 0.2.0-beta.8

package/CHANGELOG.md

@@ -0,0 +1,50 @@
+# @astack-tech/integrations
+
+## 0.2.0-beta.8
+
+### Minor Changes
+
+- 9aab43a: Add `ModelProvider.OpenAICompatible`, a provider for any API that speaks the OpenAI chat completions protocol: OpenAI and the compatible endpoints of DeepSeek, Qwen, Moonshot, Ollama, vLLM and others. Pass `model`, and `baseURL` for providers other than OpenAI; `name` labels errors and logs. `Deepseek` is now this provider with DeepSeek's defaults; its options, methods, ports and exported types are unchanged. The neutral message, tool and usage types are exported next to the `Deepseek*` names.
+
+### Patch Changes
+
+- Updated dependencies [1aba97f]
+  - @astack-tech/core@0.2.0-beta.3
+
+## 0.2.0-beta.7
+
+### Minor Changes
+
+- e71dd3b: Deepseek satisfies the `ModelProvider` interface of `@astack-tech/components` without a cast. Unset request options are omitted, an empty `choices` array fails with a clear error, non-object tool arguments become `{}`, and the pipeline fallback text is `API call failed`. API errors are logged only when `verbose` is set. Node.js 20 or later is required.
+
+### Patch Changes
+
+- Updated dependencies [e71dd3b]
+  - @astack-tech/core@0.2.0-beta.2
+
+## 0.1.1-beta.6
+
+### Patch Changes
+
+- Updated dependencies
+  - @astack-tech/core@0.2.0-beta.1
+
+## 0.1.1-beta.2
+
+### Patch Changes
+
+- rebuild package
+
+## 0.1.1-beta.1
+
+### Patch Changes
+
+- fix agent tool finder
+
+## 0.1.1-beta.0
+
+### Patch Changes
+
+- beta release
+- Updated dependencies
+  - @astack-tech/core@0.1.1-beta.0

package/README.md

@@ -1 +1,96 @@
-> @astack-tech/integrations
+# @astack-tech/integrations
+
+<img src="https://raw.githubusercontent.com/astack-tech/astack/master/assets/brand/readme-banner.png" alt="AStack" width="100%">
+
+[![npm](https://img.shields.io/npm/v/@astack-tech/integrations?color=111&label=npm)](https://www.npmjs.com/package/@astack-tech/integrations) [![license](https://img.shields.io/npm/l/@astack-tech/integrations?color=111)](https://github.com/astack-tech/astack/blob/master/LICENSE) [![node](https://img.shields.io/node/v/@astack-tech/integrations?color=111)](https://nodejs.org)
+
+Model providers for AStack. Each provider is a component: call it directly, use it in a pipeline, or pass it to an agent.
+
+[Website](https://astack.tech) · [Docs](https://astack.tech/docs) · [Examples](https://astack.tech/examples) · [GitHub](https://github.com/astack-tech/astack)
+
+## Install
+
+```bash
+npm install @astack-tech/integrations @astack-tech/core
+```
+
+## Quick start
+
+```typescript
+import { ModelProvider } from '@astack-tech/integrations';
+
+const model = new ModelProvider.Deepseek({ apiKey: process.env['DEEPSEEK_API_KEY'] ?? '' });
+
+const text = await model.run('What is flow-based programming?');
+const reply = await model.chatCompletion([{ role: 'user', content: 'Hello' }]);
+```
+
+`Deepseek` and `OpenAICompatible` are also available from the subpath: `import { Deepseek, OpenAICompatible } from '@astack-tech/integrations/model-provider'`.
+
+## Deepseek
+
+Uses the OpenAI-compatible DeepSeek API through the official `openai` client.
+
+| Option               | Default                       | Description                                                          |
+| -------------------- | ----------------------------- | -------------------------------------------------------------------- |
+| `apiKey`             | —                             | DeepSeek API key                                                     |
+| `model`              | `deepseek-chat`               | Model name                                                           |
+| `baseURL`            | `https://api.deepseek.com/v1` | API base URL                                                         |
+| `temperature`        | `0.7`                         | Sampling temperature                                                 |
+| `maxTokens`, `topP`  | not sent                      | Optional sampling limits                                             |
+| `systemPrompt`       | none                          | Added before every request                                           |
+| `rawTools` / `tools` | none                          | Tools as `{ name, description, parameters }` or in the OpenAI format |
+| `verbose`            | `false`                       | Log API errors to the console                                        |
+
+| Method                                                          | Returns                                                        |
+| --------------------------------------------------------------- | -------------------------------------------------------------- |
+| `run(prompt)`                                                   | Text                                                           |
+| `run(messages)`, `chatCompletion(messages, { temporaryTools })` | Assistant message with `content`, `tool_calls` and `usage`     |
+| `streamChatCompletion(messages, options)`                       | Async generator of text, tool-call and usage chunks            |
+| `generateCompletion(prompt)`                                    | Text, or the JSON assistant message when the model calls tools |
+
+| Pipeline input port | Output port  |
+| ------------------- | ------------ |
+| `prompt`            | `completion` |
+| `messages`          | `message`    |
+
+`Deepseek` satisfies the `ModelProvider` interface of `@astack-tech/components`, so it can drive `Agent` and `StreamingAgent` directly.
+
+## OpenAICompatible
+
+Calls any API that speaks the OpenAI chat completions protocol: OpenAI and the compatible endpoints of DeepSeek, Qwen, Moonshot, Ollama, vLLM and others. `Deepseek` is this provider with DeepSeek's defaults, so methods, ports and the other options are the same.
+
+```typescript
+import { ModelProvider } from '@astack-tech/integrations';
+
+const model = new ModelProvider.OpenAICompatible({
+  apiKey: process.env['OPENAI_API_KEY'] ?? '',
+  model: 'gpt-4o-mini',
+});
+```
+
+| Option    | Default                     | Description                      |
+| --------- | --------------------------- | -------------------------------- |
+| `apiKey`  | —                           | API key of the provider          |
+| `model`   | —                           | Model name (required)            |
+| `baseURL` | `https://api.openai.com/v1` | API base URL                     |
+| `name`    | `The model API`             | Provider name in errors and logs |
+
+## Learn more
+
+- [API reference](https://astack.tech/docs/api/integrations): every export, generated from the source
+- [Model providers](https://astack.tech/docs/model-providers), including how to write your own
+- Example: [chat](https://astack.tech/examples/chat)
+
+## The AStack packages
+
+| Package                                                                                | Purpose                                    |
+| -------------------------------------------------------------------------------------- | ------------------------------------------ |
+| [`@astack-tech/core`](https://www.npmjs.com/package/@astack-tech/core)                 | `Component`, `Pipeline` and ports          |
+| [`@astack-tech/components`](https://www.npmjs.com/package/@astack-tech/components)     | Agents, text splitting and tool invocation |
+| [`@astack-tech/tools`](https://www.npmjs.com/package/@astack-tech/tools)               | Tool definitions for agents                |
+| [`@astack-tech/integrations`](https://www.npmjs.com/package/@astack-tech/integrations) | Model providers                            |
+
+## License
+
+[MIT](./LICENSE). AStack is in public beta: APIs can change between beta releases. See [CHANGELOG.md](./CHANGELOG.md).

package/dist/index.cjs

@@ -37,310 +37,265 @@ module.exports = __toCommonJS(src_exports);
 // src/model-provider/index.ts
 var model_provider_exports = {};
 __export(model_provider_exports, {
-  Deepseek: () => deepseek_default
+  Deepseek: () => deepseek_default,
+  OpenAICompatible: () => openai_compatible_default
 });
 
-// src/model-provider/deepseek/index.ts
+// src/model-provider/openai-compatible/index.ts
 var import_core = require("@astack-tech/core");
 var import_openai = __toESM(require("openai"), 1);
-var Deepseek = class extends import_core.Component {
+var DEFAULT_BASE_URL = "https://api.openai.com/v1";
+var DEFAULT_NAME = "The model API";
+var DEFAULT_TEMPERATURE = 0.7;
+var FALLBACK_TEXT = "API call failed";
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function toApiTool(tool) {
+  if (isRecord(tool) && tool["type"] === "function") {
+    return tool;
+  }
+  const raw = isRecord(tool) ? tool : {};
+  const { name, description, parameters } = raw;
+  return {
+    type: "function",
+    function: {
+      name: typeof name === "string" ? name : "",
+      description: typeof description === "string" ? description : "",
+      parameters: isRecord(parameters) ? parameters : {}
+    }
+  };
+}
+function parseArguments(raw) {
+  if (raw.trim().length === 0) {
+    return {};
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    return isRecord(parsed) ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+function mapUsage(usage) {
+  return {
+    completion_tokens: usage.completion_tokens ?? 0,
+    prompt_tokens: usage.prompt_tokens ?? 0,
+    total_tokens: usage.total_tokens ?? 0,
+    ...usage.prompt_cache_hit_tokens === void 0 ? {} : { prompt_cache_hit_tokens: usage.prompt_cache_hit_tokens },
+    ...usage.prompt_cache_miss_tokens === void 0 ? {} : { prompt_cache_miss_tokens: usage.prompt_cache_miss_tokens }
+  };
+}
+var OpenAICompatible = class extends import_core.Component {
+  client;
+  model;
+  temperature;
+  maxTokens;
+  topP;
+  systemPrompt;
+  tools;
+  verbose;
+  name;
   constructor(config) {
     super({});
     this.client = new import_openai.default({
       apiKey: config.apiKey,
-      baseURL: config.baseURL || "https://api.deepseek.com/v1",
+      baseURL: config.baseURL ?? DEFAULT_BASE_URL,
       dangerouslyAllowBrowser: config.dangerouslyAllowBrowser ?? false
     });
-    this.model = config.model || "deepseek-chat";
-    this.temperature = config.temperature ?? 0.7;
+    this.model = config.model;
+    this.name = config.name ?? DEFAULT_NAME;
+    this.temperature = config.temperature ?? DEFAULT_TEMPERATURE;
     this.maxTokens = config.maxTokens;
     this.topP = config.topP;
     this.systemPrompt = config.systemPrompt;
-    if (config.rawTools && config.rawTools.length > 0) {
-      this.tools = config.rawTools.map((tool) => ({
-        type: "function",
-        function: {
-          name: tool.name,
-          description: tool.description,
-          parameters: tool.parameters || {}
-        }
-      }));
-    } else {
-      this.tools = config.tools;
-    }
+    this.verbose = config.verbose ?? false;
+    this.tools = config.rawTools !== void 0 && config.rawTools.length > 0 ? config.rawTools.map(toApiTool) : config.tools;
     import_core.Component.Port.I("prompt").attach(this);
     import_core.Component.Port.I("messages").attach(this);
     import_core.Component.Port.O("completion").attach(this);
     import_core.Component.Port.O("message").attach(this);
   }
   /**
-   * 生成文本完成
-   * @param prompt 提示文本
-   * @returns 生成的文本
+   * Generates a completion for a single prompt.
+   *
+   * @returns The text answer, or the JSON-encoded assistant message when it contains tool calls.
    */
   async generateCompletion(prompt) {
-    const messages = [];
-    if (this.systemPrompt) {
-      messages.push({
-        role: "system",
-        content: this.systemPrompt
-      });
-    }
-    messages.push({
-      role: "user",
-      content: prompt
+    const response = await this.client.chat.completions.create({
+      ...this.baseRequest(),
+      messages: [...this.systemMessages(), { role: "user", content: prompt }],
+      ...this.toolsParam(this.tools)
     });
-    const requestParams = {
-      model: this.model,
-      messages,
-      temperature: this.temperature,
-      max_tokens: this.maxTokens,
-      top_p: this.topP
-    };
-    if (this.tools && this.tools.length > 0) {
-      requestParams.tools = this.tools;
+    const message = this.firstMessage(response);
+    if (message.tool_calls !== void 0 && message.tool_calls.length > 0) {
+      return JSON.stringify(message);
     }
-    const response = await this.client.chat.completions.create(requestParams);
-    if (response.choices[0].message.tool_calls && response.choices[0].message.tool_calls.length > 0) {
-      return JSON.stringify(response.choices[0].message);
-    }
-    return response.choices[0].message.content || "";
+    return message.content ?? "";
   }
   /**
-   * 流式处理对话消息
-   * @param messages 对话消息数组
-   * @param options 可选的调用选项，包含临时工具列表
-   * @returns 生成的流式响应消息异步生成器
+   * Sends a conversation and returns the assistant reply.
    */
-  async *streamChatCompletion(messages, options) {
-    const formattedMessages = [];
-    if (this.systemPrompt) {
-      formattedMessages.push({
-        role: "system",
-        content: this.systemPrompt
-      });
+  async chatCompletion(messages, options) {
+    const response = await this.client.chat.completions.create({
+      ...this.baseRequest(),
+      messages: this.formatMessages(messages),
+      ...this.toolsParam(options?.temporaryTools ?? this.tools)
+    });
+    const message = this.firstMessage(response);
+    const result = { role: "assistant", content: message.content ?? "" };
+    if (response.usage !== void 0) {
+      result.usage = mapUsage(response.usage);
     }
-    formattedMessages.push(
-      ...messages.map((msg) => {
-        const formattedMsg = {
-          role: msg.role,
-          content: msg.content
-        };
-        if (msg.role === "tool" && msg.tool_call_id) {
-          formattedMsg.tool_call_id = msg.tool_call_id;
-        }
-        return formattedMsg;
-      })
-    );
-    const requestParams = {
-      model: this.model,
-      messages: formattedMessages,
-      temperature: this.temperature,
-      max_tokens: this.maxTokens,
-      top_p: this.topP,
-      stream: true
-      // 开启流式模式
-    };
-    const toolsToUse = options?.temporaryTools || this.tools;
-    if (toolsToUse && toolsToUse.length > 0) {
-      const formattedTools = toolsToUse.map((tool) => {
-        const typedTool = tool;
-        if (typedTool.type === "function") {
-          return tool;
+    if (message.tool_calls !== void 0 && message.tool_calls.length > 0) {
+      result.tool_calls = message.tool_calls.map((toolCall) => {
+        if (toolCall.type !== "function") {
+          throw new Error(`Unsupported tool call type: ${toolCall.type}`);
         }
+        const rawArguments = toolCall.function.arguments;
         return {
+          id: toolCall.id,
           type: "function",
           function: {
-            name: typedTool.name,
-            description: typedTool.description,
-            parameters: typedTool.parameters || {}
-          }
+            name: toolCall.function.name,
+            arguments: rawArguments.length > 0 ? rawArguments : "{}"
+          },
+          tool_name: toolCall.function.name,
+          arguments: parseArguments(rawArguments)
         };
       });
-      requestParams.tools = formattedTools;
     }
-    const stream = await this.client.chat.completions.create(requestParams);
+    return result;
+  }
+  /**
+   * Streams the assistant reply. Each chunk holds a text delta, tool-call deltas, or usage.
+   */
+  async *streamChatCompletion(messages, options) {
+    const stream = await this.client.chat.completions.create({
+      ...this.baseRequest(),
+      messages: this.formatMessages(messages),
+      ...this.toolsParam(options?.temporaryTools ?? this.tools),
+      stream: true
+    });
     for await (const chunk of stream) {
       const delta = chunk.choices[0]?.delta;
       if (delta?.content) {
-        yield {
-          role: "assistant",
-          content: delta.content
-        };
+        yield { role: "assistant", content: delta.content };
       }
       if (delta?.tool_calls) {
         yield {
           role: "assistant",
           content: "",
-          // eslint-disable-next-line @typescript-eslint/no-explicit-any
-          tool_calls: delta.tool_calls.map((toolCall) => ({
-            id: toolCall.id || "",
-            function: {
-              name: toolCall.function?.name || "",
-              arguments: toolCall.function?.arguments || ""
-            },
-            type: "function",
-            tool_name: toolCall.function?.name || "",
-            arguments: toolCall.function?.arguments || ""
-          }))
+          tool_calls: delta.tool_calls.map((toolCall) => {
+            const name = toolCall.function?.name ?? "";
+            const args = toolCall.function?.arguments ?? "";
+            return {
+              id: toolCall.id ?? "",
+              type: "function",
+              function: { name, arguments: args },
+              tool_name: name,
+              arguments: args
+            };
+          })
         };
       }
       if (chunk.usage) {
-        yield {
-          role: "assistant",
-          content: "",
-          usage: {
-            completion_tokens: chunk.usage.completion_tokens || 0,
-            prompt_tokens: chunk.usage.prompt_tokens || 0,
-            prompt_cache_hit_tokens: chunk.usage.prompt_cache_hit_tokens,
-            prompt_cache_miss_tokens: chunk.usage.prompt_cache_miss_tokens,
-            total_tokens: chunk.usage.total_tokens || 0
-          }
-        };
+        yield { role: "assistant", content: "", usage: mapUsage(chunk.usage) };
       }
     }
   }
   /**
-   * 处理对话消息
-   * @param messages 对话消息数组
-   * @param options 可选的调用选项，包含临时工具列表
-   * @returns 生成的响应消息
+   * Runs the model outside a pipeline.
+   *
+   * @param input - A prompt string or a list of messages.
    */
-  async chatCompletion(messages, options) {
-    const formattedMessages = [];
-    if (this.systemPrompt) {
-      formattedMessages.push({
-        role: "system",
-        content: this.systemPrompt
-      });
-    }
-    formattedMessages.push(
-      ...messages.map((msg) => {
-        const formattedMsg = {
-          role: msg.role,
-          content: msg.content
-        };
-        if (msg.role === "tool" && msg.tool_call_id) {
-          formattedMsg.tool_call_id = msg.tool_call_id;
+  run(input) {
+    return typeof input === "string" ? this.generateCompletion(input) : this.chatCompletion(input);
+  }
+  /**
+   * Connects the `prompt` and `messages` input ports to the model.
+   * API errors produce a fallback value so the pipeline keeps flowing.
+   */
+  _transform($i, $o) {
+    $i("prompt").receive((prompt) => {
+      this.generateCompletion(prompt).then(
+        (completion) => {
+          $o("completion").send(completion);
+        },
+        (error) => {
+          this.logError(error);
+          $o("completion").send(FALLBACK_TEXT);
         }
-        return formattedMsg;
-      })
-    );
-    const requestParams = {
+      );
+    });
+    $i("messages").receive((messages) => {
+      this.chatCompletion(messages).then(
+        (message) => {
+          $o("message").send(message);
+        },
+        (error) => {
+          this.logError(error);
+          $o("message").send({ role: "assistant", content: FALLBACK_TEXT });
+        }
+      );
+    });
+  }
+  baseRequest() {
+    return {
       model: this.model,
-      messages: formattedMessages,
       temperature: this.temperature,
-      max_tokens: this.maxTokens,
-      top_p: this.topP
+      ...this.maxTokens === void 0 ? {} : { max_tokens: this.maxTokens },
+      ...this.topP === void 0 ? {} : { top_p: this.topP }
     };
-    const toolsToUse = options?.temporaryTools || this.tools;
-    if (toolsToUse && toolsToUse.length > 0) {
-      const formattedTools = toolsToUse.map((tool) => {
-        const typedTool = tool;
-        if (typedTool.type === "function") {
-          return tool;
-        }
-        return {
-          type: "function",
-          function: {
-            name: typedTool.name,
-            description: typedTool.description,
-            parameters: typedTool.parameters || {}
-          }
-        };
-      });
-      requestParams.tools = formattedTools;
-    }
-    const response = await this.client.chat.completions.create(requestParams);
-    const responseMessage = response.choices[0].message;
-    const result = {
-      role: "assistant",
-      content: responseMessage.content || ""
-    };
-    if (response.usage) {
-      const usage = response.usage;
-      result.usage = {
-        completion_tokens: usage.completion_tokens || 0,
-        prompt_tokens: usage.prompt_tokens || 0,
-        prompt_cache_hit_tokens: usage.prompt_cache_hit_tokens,
-        prompt_cache_miss_tokens: usage.prompt_cache_miss_tokens,
-        total_tokens: usage.total_tokens || 0
-      };
-    }
-    if (responseMessage.tool_calls && responseMessage.tool_calls.length > 0) {
-      result.tool_calls = responseMessage.tool_calls.map((toolCall) => {
-        if (toolCall.type !== "function" || !("function" in toolCall)) {
-          throw new Error(`Unsupported tool call type: ${toolCall.type}`);
-        }
-        let args;
-        const rawArgs = toolCall.function.arguments;
-        if (typeof rawArgs === "string") {
-          const raw = rawArgs;
-          try {
-            args = raw && raw.trim().length > 0 ? JSON.parse(raw) : {};
-          } catch {
-            args = {};
-          }
-        } else if (rawArgs && typeof rawArgs === "object") {
-          args = rawArgs;
-        } else {
-          args = {};
-        }
-        return {
-          id: toolCall.id,
-          // 满足 Agent 组件期望的格式
-          function: {
-            name: toolCall.function.name,
-            arguments: toolCall.function.arguments || "{}"
-          },
-          type: "function",
-          // 满足内部 ToolCall 接口
-          tool_name: toolCall.function.name,
-          arguments: args
-        };
-      });
-    }
-    return result;
+  }
+  toolsParam(tools) {
+    return tools !== void 0 && tools.length > 0 ? { tools: tools.map(toApiTool) } : {};
+  }
+  systemMessages() {
+    return this.systemPrompt ? [{ role: "system", content: this.systemPrompt }] : [];
   }
   /**
-   * 在独立模式下运行组件
-   * @param input 输入参数，可以是提示文本或对话消息数组
-   * @returns 生成的文本或响应消息
+   * Converts input messages to API messages. Assistant `tool_calls` are not forwarded:
+   * agents send tool results back as user messages, and the API rejects assistant tool
+   * calls that are not followed by tool messages.
    */
-  async run(input) {
-    if (typeof input === "string") {
-      return this.generateCompletion(input);
-    } else {
-      return this.chatCompletion(input);
+  formatMessages(messages) {
+    return [
+      ...this.systemMessages(),
+      ...messages.map(
+        (message) => ({
+          role: message.role,
+          content: message.content,
+          ...message.role === "tool" && message.tool_call_id ? { tool_call_id: message.tool_call_id } : {}
+        })
+      )
+    ];
+  }
+  firstMessage(response) {
+    const choice = response.choices[0];
+    if (choice === void 0) {
+      throw new Error(`${this.name} returned no choices.`);
     }
+    return choice.message;
   }
-  /**
-   * 在流水线中运行组件
-   * @param $i 输入端口
-   * @param $o 输出端口
-   */
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  _transform($i, $o) {
-    $i("prompt").receive(async (prompt) => {
-      try {
-        const completion = await this.generateCompletion(prompt);
-        $o("completion").send(completion);
-      } catch (error) {
-        console.error("Deepseek API \u8C03\u7528\u9519\u8BEF:", error);
-        $o("completion").send("API \u8C03\u7528\u9519\u8BEF");
-      }
-    });
-    $i("messages").receive(async (messages) => {
-      try {
-        const responseMessage = await this.chatCompletion(messages);
-        $o("message").send(responseMessage);
-      } catch (error) {
-        console.error("Deepseek API \u8C03\u7528\u9519\u8BEF:", error);
-        $o("message").send({
-          role: "assistant",
-          content: "API \u8C03\u7528\u9519\u8BEF"
-        });
-      }
+  logError(error) {
+    if (this.verbose) {
+      console.error(`[${this.name}] API call failed:`, error);
+    }
+  }
+};
+var openai_compatible_default = OpenAICompatible;
+
+// src/model-provider/deepseek/index.ts
+var DEFAULT_BASE_URL2 = "https://api.deepseek.com/v1";
+var DEFAULT_MODEL = "deepseek-chat";
+var Deepseek = class extends openai_compatible_default {
+  constructor(config) {
+    super({
+      ...config,
+      model: config.model ?? DEFAULT_MODEL,
+      baseURL: config.baseURL ?? DEFAULT_BASE_URL2,
+      name: "DeepSeek"
     });
   }
 };