@xsai/text-responses 0.0.0-stage → 1.0.0-beta.1

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Moeru AI
+
+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/README.md

@@ -1,3 +1,25 @@
-# Temporary Holding Version
+# @xsai/text-responses
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<!-- automd:file src="/docs/snippets/text-responses.md" -->
+
+```sh
+pnpm add @xsai/text @xsai/text-responses
+```
+
+```ts
+import { generateText } from '@xsai/text'
+import { responses } from '@xsai/text-responses'
+
+const model = responses({
+  apiKey: process.env.OPENAI_API_KEY,
+  baseURL: 'https://api.openai.com/v1/',
+  model: 'gpt-6-luna',
+})
+
+const { text } = await generateText(model, { input: 'Say hello.' })
+console.log(text)
+```
+
+<!-- /automd -->
+
+Read the [documentation](https://xsai.js.org/text/adapters).

package/dist/index.d.ts

@@ -0,0 +1,74 @@
+import { HttpOptions } from '@xsai/shared';
+import { LanguageModel } from '@xsai/text';
+
+type UrlCitationParam = {
+    /**
+     * The citation type. Always `url_citation`.
+     */
+    type: 'url_citation';
+    /**
+     * The index of the first character of the citation in the message.
+     */
+    start_index: number;
+    /**
+     * The index of the last character of the citation in the message.
+     */
+    end_index: number;
+    /**
+     * The URL of the cited resource.
+     */
+    url: string;
+    /**
+     * The title of the cited resource.
+     */
+    title: string;
+};
+
+type ResponsesAnnotation = UrlCitationParam | {
+    container_id: string;
+    end_index: number;
+    file_id: string;
+    filename: string;
+    index?: null | number;
+    start_index: number;
+    type: 'container_file_citation';
+} | {
+    file_id: string;
+    filename: string;
+    index: number;
+    type: 'file_citation';
+} | {
+    file_id: string;
+    index: number;
+    type: 'file_path';
+};
+interface ResponsesPartMetadata {
+    citations?: ResponsesAnnotation[];
+}
+
+interface ResponsesProviderOptions {
+    frequencyPenalty?: number;
+    include?: readonly string[];
+    parallelToolCalls?: boolean;
+    presencePenalty?: number;
+    /** @default `false` */
+    store?: boolean;
+    tools?: readonly ResponsesProviderTool[];
+}
+interface ResponsesProviderTool {
+    [key: string]: unknown;
+    type: string;
+}
+
+declare module '@xsai/text' {
+    interface LanguageModelProviderOptions {
+        responses?: ResponsesProviderOptions;
+    }
+    interface PartProviderMetadata {
+        responses?: ResponsesPartMetadata;
+    }
+}
+declare const responses: (options: HttpOptions) => LanguageModel;
+
+export { responses };
+export type { ResponsesAnnotation, ResponsesPartMetadata, ResponsesProviderOptions, ResponsesProviderTool };

package/dist/index.js

@@ -0,0 +1,467 @@
+import { XSAIError, requestURL } from '@xsai/shared';
+import { resolveSchema, WireEventStream, wireRequest } from '@xsai/text/internal';
+
+const SUPPORTED_FORMATS = /* @__PURE__ */ new Set([
+  "date",
+  "date-time",
+  "duration",
+  "email",
+  "hostname",
+  "ipv4",
+  "ipv6",
+  "time",
+  "uuid"
+]);
+const normalizeSchema = (schema) => {
+  const normalized = { ...schema };
+  const normalize = (schema2) => typeof schema2 === "boolean" ? schema2 : normalizeSchema(schema2);
+  if (normalized.$ref != null)
+    return { $ref: normalized.$ref };
+  if (normalized.type === "object" || normalized.properties != null) {
+    normalized.properties ??= {};
+    normalized.properties = Object.fromEntries(Object.entries(normalized.properties).map(([name, property]) => [name, normalize(property)]));
+    normalized.additionalProperties = false;
+    normalized.required = Object.keys(normalized.properties);
+  }
+  if (normalized.$defs != null)
+    normalized.$defs = Object.fromEntries(Object.entries(normalized.$defs).map(([name, definition]) => [name, normalize(definition)]));
+  if (normalized.definitions != null)
+    normalized.definitions = Object.fromEntries(Object.entries(normalized.definitions).map(([name, definition]) => [name, normalize(definition)]));
+  if (normalized.items != null) {
+    normalized.items = Array.isArray(normalized.items) ? normalized.items.map(normalize) : normalize(normalized.items);
+  }
+  if (normalized.oneOf != null) {
+    const oneOf = normalized.oneOf;
+    delete normalized.oneOf;
+    normalized.anyOf = normalized.anyOf == null ? oneOf : normalized.anyOf.concat(oneOf);
+  }
+  if (normalized.anyOf != null)
+    normalized.anyOf = normalized.anyOf.map(normalize);
+  delete normalized.allOf;
+  delete normalized.not;
+  delete normalized.if;
+  delete normalized.then;
+  delete normalized.else;
+  if (normalized.format != null && !SUPPORTED_FORMATS.has(normalized.format))
+    delete normalized.format;
+  return normalized;
+};
+
+const normalizeSchemaName = (title) => title == null || title === "" ? "output" : title.replace(/[^\w-]/g, "_").slice(0, 64);
+const normalizeFormat = (outputFormat) => {
+  if (outputFormat == null)
+    return void 0;
+  const { schema } = resolveSchema(outputFormat);
+  const normalized = normalizeSchema(schema);
+  return {
+    format: {
+      description: normalized.description,
+      name: normalizeSchemaName(normalized.title),
+      schema: normalized,
+      strict: true,
+      type: "json_schema"
+    }
+  };
+};
+
+const normalizeInputTextPart = (part) => ({
+  text: part.text,
+  type: "input_text"
+});
+const normalizeOutputTextPart = (part) => ({
+  // TODO: Move citations to a first-class TextPart field.
+  // The generated OpenResponses type lists only URL citations.
+  annotations: part.providerMetadata?.responses?.citations,
+  text: part.text,
+  type: "output_text"
+});
+const normalizeImagePart = (part) => ({
+  detail: part.detail,
+  image_url: part.data.toString(),
+  type: "input_image"
+});
+const normalizeFilePart = (part) => {
+  const data = part.data.toString();
+  const protocol = URL.parse(data)?.protocol;
+  return protocol === "http:" || protocol === "https:" ? { file_url: data, type: "input_file" } : { file_data: data, type: "input_file" };
+};
+const normalizeReasoningPart$1 = (part) => {
+  const summary = [];
+  let encryptedContent;
+  for (const partContent of part.content) {
+    switch (partContent.type) {
+      case "encrypted":
+      case "redacted":
+        encryptedContent = partContent.text;
+        break;
+      case "summary":
+        summary.push({ text: partContent.text, type: "summary_text" });
+        break;
+    }
+  }
+  return {
+    encrypted_content: encryptedContent,
+    id: part.id,
+    summary,
+    type: "reasoning"
+  };
+};
+const normalizeToolCallPart = (part) => ({
+  arguments: part.arguments,
+  call_id: part.callId,
+  id: part.id,
+  name: part.name,
+  type: "function_call"
+});
+const normalizeToolResultContent = (content) => {
+  switch (content.type) {
+    case "image":
+      return normalizeImagePart(content);
+    case "text":
+      return normalizeInputTextPart(content);
+  }
+};
+const normalizeToolResultPart = (part) => ({
+  call_id: part.callId,
+  output: Array.isArray(part.output) ? part.output.map(normalizeToolResultContent) : part.output,
+  type: "function_call_output"
+});
+const normalizeAssistantMessage = (message, source) => {
+  const createMessageItem = (content2, includeId2 = true) => ({
+    content: content2,
+    id: includeId2 ? message.id : void 0,
+    role: "assistant",
+    type: "message"
+  });
+  if (typeof message.content === "string")
+    return [createMessageItem([{ text: message.content, type: "output_text" }])];
+  const items = [];
+  let content = [];
+  let includeId = true;
+  const flushContent = () => {
+    if (content.length === 0)
+      return;
+    items.push(createMessageItem(content, includeId));
+    content = [];
+    includeId = false;
+  };
+  for (const part of message.content) {
+    switch (part.type) {
+      case "provider":
+        if (part.source === source) {
+          flushContent();
+          items.push(part.value);
+        }
+        break;
+      case "reasoning":
+        flushContent();
+        items.push(normalizeReasoningPart$1(part));
+        break;
+      case "refusal":
+        content.push({ refusal: part.refusal, type: "refusal" });
+        break;
+      case "text":
+        content.push(normalizeOutputTextPart(part));
+        break;
+      case "tool-call":
+        flushContent();
+        items.push(normalizeToolCallPart(part));
+        break;
+    }
+  }
+  flushContent();
+  return items;
+};
+const normalizeUserMessage = (message) => {
+  const createMessageItem = (content2) => ({
+    content: content2,
+    role: "user",
+    type: "message"
+  });
+  if (typeof message.content === "string")
+    return [createMessageItem(message.content)];
+  const items = [];
+  let content = [];
+  const flushContent = () => {
+    if (content.length === 0)
+      return;
+    items.push(createMessageItem(content));
+    content = [];
+  };
+  for (const part of message.content) {
+    switch (part.type) {
+      case "file":
+        content.push(normalizeFilePart(part));
+        break;
+      case "image":
+        content.push(normalizeImagePart(part));
+        break;
+      case "text":
+        content.push(normalizeInputTextPart(part));
+        break;
+      case "tool-result":
+        flushContent();
+        items.push(normalizeToolResultPart(part));
+        break;
+    }
+  }
+  flushContent();
+  return items;
+};
+const normalizeMessage = (message, source) => {
+  switch (message.role) {
+    case "assistant":
+      return normalizeAssistantMessage(message, source);
+    case "developer":
+      return [{
+        content: typeof message.content === "string" ? message.content : message.content.map(normalizeInputTextPart),
+        role: "developer",
+        type: "message"
+      }];
+    case "system":
+      return [{
+        content: typeof message.content === "string" ? message.content : message.content.map(normalizeInputTextPart),
+        role: "system",
+        type: "message"
+      }];
+    case "user":
+      return normalizeUserMessage(message);
+  }
+};
+const normalizeInput = (input, source) => typeof input === "string" ? [{ content: input, role: "user", type: "message" }] : input.flatMap((message) => normalizeMessage(message, source));
+
+const normalizeToolChoice = (toolChoice) => toolChoice == null ? void 0 : typeof toolChoice === "string" ? toolChoice : { name: toolChoice.name, type: "function" };
+
+const normalizeTools = (tools) => tools?.map((tool) => ({
+  description: tool.description,
+  name: tool.name,
+  parameters: normalizeSchema(tool.inputSchema.schema),
+  strict: true,
+  type: "function"
+}));
+const mergeTools = (providerTools, tools) => {
+  const merged = [
+    ...providerTools ?? [],
+    ...normalizeTools(tools) ?? []
+  ];
+  return merged.length === 0 ? void 0 : merged;
+};
+
+const normalizeUsage = (usage) => ({
+  cacheReadInputTokens: usage.input_tokens_details?.cached_tokens,
+  inputTokens: usage.input_tokens,
+  outputTokens: usage.output_tokens,
+  reasoningTokens: usage.output_tokens_details?.reasoning_tokens,
+  totalTokens: usage.total_tokens
+});
+const normalizeToolCall = (item) => ({
+  arguments: item.arguments,
+  callId: item.call_id,
+  id: item.id,
+  name: item.name,
+  type: "tool-call"
+});
+const contentPartKey = (outputIndex, contentIndex) => `${outputIndex}:${contentIndex}`;
+const normalizeContentPart = (part) => {
+  if (part.type === "refusal")
+    return { refusal: part.refusal, type: "refusal" };
+  if (part.type === "output_text") {
+    const citations = part.annotations;
+    return {
+      ...citations?.length ? { providerMetadata: { responses: { citations } } } : {},
+      text: part.text,
+      type: "text"
+    };
+  }
+  return void 0;
+};
+const normalizeReasoningPart = (item) => {
+  const reasoningContent = [
+    ...(item.summary ?? []).flatMap((part) => part.type === "summary_text" ? [{ text: part.text, type: "summary" }] : []),
+    ...(item.content ?? []).flatMap((part) => part.type === "reasoning_text" ? [{ text: part.text, type: "text" }] : [])
+  ];
+  if (item.encrypted_content != null)
+    reasoningContent.push({ text: item.encrypted_content, type: "encrypted" });
+  return { content: reasoningContent, id: item.id, type: "reasoning" };
+};
+const normalizeFinishReason = (response) => {
+  if (response.status !== "incomplete")
+    return void 0;
+  const reason = response.incomplete_details?.reason;
+  switch (reason) {
+    case "content_filter":
+      return "content-filter";
+    case "max_output_tokens":
+      return "length";
+    case null:
+    case void 0:
+      return void 0;
+    default:
+      return reason;
+  }
+};
+const normalizeStatus = (response) => {
+  switch (response.status) {
+    case "cancelled":
+      return "cancelled";
+    case "completed":
+      return "completed";
+    case "failed":
+      return "failed";
+    case "incomplete":
+      return "incomplete";
+    default:
+      throw new Error(`unknown response status: ${response.status}`);
+  }
+};
+class ResponsesEventStream extends WireEventStream {
+  constructor(source, includeRawEvents = false) {
+    const normalizeOutputItem = (item, index) => {
+      if (item.type === "function_call_output")
+        return { parts: [] };
+      if (item.type === "function_call")
+        return { parts: [{ content: normalizeToolCall(item), init: { callId: item.call_id, id: item.id, name: item.name } }] };
+      if (item.type === "message") {
+        const parts = item.content.flatMap((part, contentIndex) => {
+          const content = normalizeContentPart(part);
+          return content == null ? [] : [{ content, key: contentPartKey(index, contentIndex) }];
+        });
+        return { messageId: item.id, parts };
+      }
+      if (item.type === "reasoning")
+        return { parts: [{ content: normalizeReasoningPart(item) }] };
+      return { parts: [{ content: { source, type: "provider", value: item } }] };
+    };
+    const onItemAdded = (builder, item, index) => {
+      const normalized = normalizeOutputItem(item, index);
+      for (const part of normalized.parts) {
+        if (part.content.type !== "provider")
+          builder.start(part.key ?? index, part.content.type, part.init);
+      }
+      if (normalized.messageId != null)
+        builder.meta({ messageId: normalized.messageId });
+    };
+    const onItemDone = (builder, item, index) => {
+      const normalized = normalizeOutputItem(item, index);
+      for (const part of normalized.parts) {
+        const key = part.key ?? index;
+        builder.start(key, part.content.type, part.init);
+        builder.end(key, { content: part.content });
+      }
+      return normalized;
+    };
+    const finishResponse = (builder, response) => {
+      const status = normalizeStatus(response);
+      if (response.usage != null)
+        builder.meta({ usage: normalizeUsage(response.usage) });
+      const output = response.output.map((item, index) => onItemDone(builder, item, index));
+      const message = {
+        content: output.flatMap((item) => item.parts.map((part) => part.content)),
+        id: output.findLast((item) => item.messageId != null)?.messageId,
+        role: "assistant"
+      };
+      if (status === "failed") {
+        const error = new XSAIError("model-error", response.error?.message ?? "response failed", {
+          cause: response.error ?? void 0
+        });
+        builder.fail(error, message);
+        return;
+      }
+      const reason = normalizeFinishReason(response) ?? (status === "completed" && message.content.some((part) => part.type === "refusal") ? "refusal" : void 0);
+      builder.done(status, reason, message);
+    };
+    super((event, builder) => {
+      switch (event.type) {
+        case "error":
+          builder.fail(new XSAIError("model-error", event.error.message, {
+            cause: event.error
+          }));
+          break;
+        case "response.completed":
+        case "response.failed":
+        case "response.incomplete":
+          finishResponse(builder, event.response);
+          break;
+        case "response.content_part.added": {
+          const content = normalizeContentPart(event.part);
+          if (content != null)
+            builder.start(contentPartKey(event.output_index, event.content_index), content.type);
+          break;
+        }
+        case "response.content_part.done": {
+          const content = normalizeContentPart(event.part);
+          if (content != null) {
+            const key = contentPartKey(event.output_index, event.content_index);
+            builder.start(key, content.type);
+            builder.end(key, { content });
+          }
+          break;
+        }
+        case "response.created":
+          break;
+        case "response.function_call_arguments.delta":
+        case "response.reasoning.delta":
+        case "response.reasoning_summary_text.delta":
+          builder.delta(event.output_index, event.delta);
+          break;
+        case "response.function_call_arguments.done":
+          break;
+        case "response.in_progress":
+        case "response.output_text.done":
+        case "response.queued":
+        case "response.reasoning.done":
+        case "response.reasoning_summary_part.added":
+        case "response.reasoning_summary_part.done":
+        case "response.reasoning_summary_text.done":
+          break;
+        case "response.output_item.added":
+          if (event.item != null)
+            onItemAdded(builder, event.item, event.output_index);
+          break;
+        case "response.output_item.done":
+          if (event.item != null)
+            onItemDone(builder, event.item, event.output_index);
+          break;
+        case "response.output_text.delta":
+        case "response.refusal.delta": {
+          const key = contentPartKey(event.output_index, event.content_index);
+          builder.start(key, event.type === "response.refusal.delta" ? "refusal" : "text");
+          builder.delta(key, event.delta);
+          break;
+        }
+        case "response.reasoning_text.delta":
+          builder.start(event.output_index, "reasoning");
+          builder.delta(event.output_index, event.delta);
+          break;
+      }
+    }, includeRawEvents);
+  }
+}
+
+const responses = (options) => async (modelOptions) => {
+  const source = requestURL("responses", options.baseURL).toString();
+  const providerOptions = modelOptions.providerOptions?.responses;
+  return wireRequest({
+    body: {
+      frequency_penalty: providerOptions?.frequencyPenalty,
+      include: providerOptions?.include,
+      input: normalizeInput(modelOptions.input, source),
+      instructions: modelOptions.instructions,
+      max_output_tokens: modelOptions.maxOutputTokens,
+      model: options.model,
+      parallel_tool_calls: providerOptions?.parallelToolCalls,
+      presence_penalty: providerOptions?.presencePenalty,
+      reasoning: modelOptions.reasoningEffort == null ? void 0 : { effort: modelOptions.reasoningEffort },
+      store: providerOptions?.store ?? false,
+      stream: true,
+      temperature: modelOptions.temperature,
+      text: normalizeFormat(modelOptions.outputFormat),
+      tool_choice: normalizeToolChoice(modelOptions.toolChoice),
+      tools: mergeTools(providerOptions?.tools, modelOptions.tools),
+      top_p: modelOptions.topP
+    },
+    path: source
+  }, options, modelOptions, new ResponsesEventStream(source, modelOptions.includeRawEvents));
+};
+
+export { responses };

package/package.json

@@ -1,6 +1,51 @@
 {
   "name": "@xsai/text-responses",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "type": "module",
+  "version": "1.0.0-beta.1",
+  "description": "extra-small AI SDK: OpenAI Responses API model for @xsai/text.",
+  "author": "Moeru AI",
+  "license": "MIT",
+  "homepage": "https://xsai.js.org",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/moeru-ai/xsai.git",
+    "directory": "packages/text-responses"
+  },
+  "bugs": "https://github.com/moeru-ai/xsai/issues",
+  "keywords": [
+    "xsai",
+    "ai",
+    "openai",
+    "responses",
+    "responses-api"
+  ],
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "@xsai/text": "1.0.0-beta.1"
+  },
+  "dependencies": {
+    "@xsai/shared": "1.0.0-beta.1"
+  },
+  "devDependencies": {
+    "@xsai/text": "1.0.0-beta.1",
+    "zod": "^4.3.6"
+  },
+  "scripts": {
+    "build": "pkgroll --clean-dist",
+    "sync": "openapi-ts",
+    "test": "vitest run --exclude e2e/**",
+    "test:watch": "vitest"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts"
 }