@superdurable/connectors-sdk 0.1.0 → 0.2.0

package/dist/textgen/openaichat/index.js

@@ -0,0 +1,232 @@
+import {
+  ProviderReportedError,
+  temperatureAccepted,
+  validateStructuredOutputRules
+} from "../../chunk-466BPS3M.js";
+import {
+  readErrorTokens
+} from "../../chunk-BG65RPGH.js";
+import "../../chunk-IHG6ADQG.js";
+
+// src/textgen/openaichat/index.ts
+function requestField(value) {
+  return /^[a-z][a-z0-9_]{0,63}$/.test(value);
+}
+function validateSettings(field, streaming, efforts, structured) {
+  if (field && field !== "max_tokens" && field !== "max_completion_tokens") throw new TypeError("profile max tokens field is invalid");
+  if (streaming && streaming !== "never" && streaming !== "always") throw new TypeError("profile streaming policy is invalid");
+  for (const [effort, value] of Object.entries(efforts ?? {})) {
+    if (!["none", "minimal", "low", "medium", "high", "xhigh", "max"].includes(effort)) throw new TypeError(`profile reasoning effort ${JSON.stringify(effort)} is unknown`);
+    if (!value || !requestField(value)) throw new TypeError("profile reasoning effort wire value is invalid");
+  }
+  if (structured) validateStructuredOutputRules(structured);
+}
+function newWireFormat(profile) {
+  if (!profile) throw new TypeError("openaichat profile is required");
+  if (!profile.providerName?.trim()) throw new TypeError("openaichat profile provider name is required");
+  if (profile.chatCompletionsPath && (!profile.chatCompletionsPath.startsWith("/") || /[?# ]/.test(profile.chatCompletionsPath))) throw new TypeError("openaichat profile chat completions path is invalid");
+  if (profile.instructionsRole && !["system", "developer"].includes(profile.instructionsRole)) throw new TypeError("openaichat profile instructions role is invalid");
+  validateSettings(profile.maxTokensField, profile.streaming, profile.reasoningEfforts, profile.structuredOutput);
+  const credentialHeader = profile.credentialHeader?.name ? profile.credentialHeader : { name: "Authorization", prefix: "Bearer " };
+  const reserved = new Set([credentialHeader.name, "Content-Type", "Content-Length", "Accept", "Host"].map((name) => name.toLowerCase()));
+  for (const [name, value] of Object.entries(profile.fixedHeaders ?? {})) {
+    if (!/^[!#$%&'*+.^_`|~0-9A-Za-z-]{1,128}$/.test(name) || reserved.has(name.toLowerCase()) || !/^[\x20-\x7e]*$/.test(value)) throw new TypeError("openaichat profile fixed header is invalid or reserved");
+  }
+  for (const field of profile.allowedRequestFields ?? []) if (!requestField(field)) throw new TypeError("openaichat profile allowed request field is invalid");
+  for (const [index, rule] of (profile.modelRules ?? []).entries()) {
+    if (!!rule.modelIDPrefix === !!rule.modelIDPattern) throw new TypeError(`openaichat profile model rule ${index} must set exactly one model matcher`);
+    if (rule.modelIDPattern && (!rule.modelIDPattern.startsWith("^") || !rule.modelIDPattern.endsWith("$"))) throw new TypeError(`openaichat profile model rule ${index} pattern must be anchored`);
+    if (rule.modelIDPattern) {
+      try {
+        new RegExp(rule.modelIDPattern);
+      } catch {
+        throw new TypeError(`openaichat profile model rule ${index} pattern is invalid`);
+      }
+    }
+    validateSettings(rule.maxTokensField, rule.streaming, rule.reasoningEfforts, rule.structuredOutput);
+  }
+  const allowed = profile.allowedRequestFields?.length ? new Set(profile.allowedRequestFields) : void 0;
+  if (allowed) {
+    const required = ["model", "messages"];
+    if (profile.streaming === "always" || profile.modelRules?.some((rule) => rule.streaming === "always")) required.push("stream");
+    if (required.includes("stream") && profile.shouldRequestStreamUsage) required.push("stream_options");
+    for (const field of required) if (!allowed.has(field)) throw new TypeError(`openaichat profile allowed request fields must include ${JSON.stringify(field)}, which the wire format sends`);
+  }
+  const baseSettings = {
+    rules: {
+      temperature: profile.temperature ?? temperatureAccepted(),
+      reasoningEfforts: profile.reasoningEfforts ?? {},
+      structuredOutput: profile.structuredOutput ?? { mode: "none" }
+    },
+    maxTokensField: profile.maxTokensField ?? "max_tokens",
+    streaming: profile.streaming ?? "never"
+  };
+  const settingsForModel = (model) => {
+    for (const rule of profile.modelRules ?? []) {
+      const matches = rule.modelIDPrefix ? model.startsWith(rule.modelIDPrefix) : new RegExp(rule.modelIDPattern ?? "^$").test(model);
+      if (!matches) continue;
+      return {
+        rules: {
+          temperature: rule.temperature ?? baseSettings.rules.temperature,
+          reasoningEfforts: rule.reasoningEfforts ?? baseSettings.rules.reasoningEfforts,
+          structuredOutput: rule.structuredOutput ?? baseSettings.rules.structuredOutput
+        },
+        maxTokensField: rule.maxTokensField ?? baseSettings.maxTokensField,
+        streaming: rule.streaming ?? baseSettings.streaming
+      };
+    }
+    return baseSettings;
+  };
+  const pointers = profile.errorTokenPointers ?? ["/error/type", "/error/code"];
+  const reportedError = (body) => new ProviderReportedError(readErrorTokens(body, pointers));
+  return {
+    providerName: profile.providerName,
+    modelIDRule: "body",
+    features: { supportsInstructions: true, supportsStructuredOutput: true, supportsMaxOutputTokens: true, supportsTemperature: true, supportsReasoningEffort: true },
+    credentialHeader,
+    rulesForModel: (model) => settingsForModel(model).rules,
+    encodeRequest: ({ request, rules }) => {
+      const settings = settingsForModel(request.model ?? "");
+      const messages = [];
+      if (request.instructions) messages.push({ role: profile.instructionsRole ?? "system", content: request.instructions });
+      for (const message of request.messages) messages.push({ role: message.role, content: message.text });
+      const body = { model: request.model, messages };
+      if (request.maxOutputTokens) body[settings.maxTokensField] = request.maxOutputTokens;
+      if (request.temperature != null) body.temperature = request.temperature;
+      if (request.reasoningEffort) body.reasoning_effort = rules.reasoningEfforts[request.reasoningEffort];
+      if (request.structuredOutput) {
+        if (rules.structuredOutput.mode === "jsonSchema") {
+          const jsonSchema = { name: request.structuredOutput.name, schema: request.structuredOutput.schema };
+          if (request.structuredOutput.description) jsonSchema.description = request.structuredOutput.description;
+          if (profile.shouldSendStrictJSONSchema) jsonSchema.strict = true;
+          body.response_format = { type: "json_schema", json_schema: jsonSchema };
+        } else if (rules.structuredOutput.mode === "jsonObjectWithInstruction") body.response_format = { type: "json_object" };
+      }
+      const isStreaming = settings.streaming === "always";
+      if (isStreaming) {
+        body.stream = true;
+        if (profile.shouldRequestStreamUsage) body.stream_options = { include_usage: true };
+      }
+      if (allowed) {
+        for (const field of Object.keys(body).sort()) if (!allowed.has(field)) throw new TypeError(`the provider does not accept the ${JSON.stringify(field)} request field`);
+      }
+      return { path: profile.chatCompletionsPath ?? "/chat/completions", body: Buffer.from(JSON.stringify(body)), headers: { ...profile.fixedHeaders }, isStreaming };
+    },
+    decodeResponse: (body) => {
+      const completion = parseObject(body);
+      if (completion.error !== void 0 && completion.error !== null) throw reportedError(body);
+      validateCompletion(completion);
+      const choice = firstChoice(completion.choices);
+      if (!choice) throw new TypeError("chat completion has no choice");
+      const response = { parts: [], servedModel: stringOrEmpty(completion.model), responseId: stringOrEmpty(completion.id), usage: readUsage(completion.usage) };
+      appendDelta(response, choice.message, void 0);
+      if (typeof choice.finish_reason === "string") response.providerFinishReason = choice.finish_reason;
+      return response;
+    },
+    decodeStreamEvent: (event, state, writeTextDelta) => {
+      if (event.data.trim() === "[DONE]") {
+        if (!state.hasFinished) throw new TypeError("chat completion stream ended without a finish reason");
+        state.isDone = true;
+        return;
+      }
+      const chunk = parseObject(Buffer.from(event.data));
+      if (chunk.error !== void 0 && chunk.error !== null) throw reportedError(Buffer.from(event.data));
+      validateCompletion(chunk);
+      state.response.responseId ||= stringOrEmpty(chunk.id);
+      state.response.servedModel ||= stringOrEmpty(chunk.model);
+      if (chunk.usage !== void 0 && chunk.usage !== null) state.response.usage = readUsage(chunk.usage);
+      const choice = firstChoice(chunk.choices);
+      if (!choice) return;
+      appendDelta(state.response, choice.delta, writeTextDelta);
+      if (typeof choice.finish_reason === "string" && choice.finish_reason) {
+        state.response.providerFinishReason = choice.finish_reason;
+        state.hasFinished = true;
+      }
+    },
+    finishReasons: { stop: "stop", length: "length", content_filter: "contentPolicy", ...profile.finishReasons },
+    errorRules: [...profile.errorRules ?? []],
+    errorTokenPointers: [...pointers],
+    requestIDHeaders: [...profile.requestIDHeaders ?? ["x-request-id"]],
+    rateLimitHeaders: [...profile.rateLimitHeaders ?? []],
+    stallTimeoutMs: profile.stallTimeoutMs ?? 0
+  };
+}
+function parseObject(body) {
+  const parsed = JSON.parse(Buffer.from(body).toString());
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new TypeError("completion must be an object");
+  return parsed;
+}
+function stringOrEmpty(value) {
+  return typeof value === "string" ? value : "";
+}
+function firstChoice(value) {
+  return Array.isArray(value) ? value.find((choice) => choice && typeof choice === "object" && (choice.index == null || choice.index === 0)) : void 0;
+}
+function validateCompletion(completion) {
+  for (const field of ["id", "model"]) if (completion[field] != null && typeof completion[field] !== "string") throw new TypeError("chat completion identifier must be text");
+  if (completion.choices != null && !Array.isArray(completion.choices)) throw new TypeError("chat completion choices must be an array");
+  for (const choice of completion.choices ?? []) {
+    if (choice === null) continue;
+    if (typeof choice !== "object" || Array.isArray(choice)) throw new TypeError("chat completion choice must be an object");
+    const fields = choice;
+    if (fields.index != null && (!Number.isInteger(fields.index) || !Number.isSafeInteger(fields.index))) throw new TypeError("chat completion choice index must be an integer");
+    if (fields.finish_reason != null && typeof fields.finish_reason !== "string") throw new TypeError("chat completion finish reason must be text");
+    for (const name of ["message", "delta"]) if (fields[name] != null && (typeof fields[name] !== "object" || Array.isArray(fields[name]))) throw new TypeError("chat completion delta must be an object");
+  }
+  if (completion.usage != null && (typeof completion.usage !== "object" || Array.isArray(completion.usage))) throw new TypeError("chat completion usage must be an object");
+  if (completion.usage != null) {
+    const usage = completion.usage;
+    for (const name of ["prompt_tokens_details", "completion_tokens_details"]) {
+      if (usage[name] != null && (typeof usage[name] !== "object" || Array.isArray(usage[name]))) throw new TypeError("chat completion usage details must be an object");
+    }
+  }
+}
+function appendDelta(response, value, writeTextDelta) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return;
+  const delta = value;
+  if (delta.reasoning_content !== void 0 && delta.reasoning_content !== null && typeof delta.reasoning_content !== "string") throw new TypeError("chat reasoning content must be text");
+  if (delta.refusal !== void 0 && delta.refusal !== null && typeof delta.refusal !== "string") throw new TypeError("chat refusal must be text");
+  if (typeof delta.reasoning_content === "string" && delta.reasoning_content) appendPart(response, { text: delta.reasoning_content, isReasoning: true });
+  if (typeof delta.refusal === "string" && delta.refusal) response.isRefusal = true;
+  const content = delta.content;
+  let texts = [];
+  if (typeof content === "string") texts = [content];
+  else if (Array.isArray(content)) {
+    for (const part of content) {
+      if (part === null) continue;
+      if (!part || typeof part !== "object" || Array.isArray(part)) throw new TypeError("chat content part must be an object");
+      if (part.type != null && typeof part.type !== "string" || part.text != null && typeof part.text !== "string") throw new TypeError("chat content part fields must be text");
+      if (part.type === "text" && part.text) texts.push(part.text);
+    }
+  } else if (content !== void 0 && content !== null) throw new TypeError("chat content must be text or typed parts");
+  for (const text of texts) if (text) {
+    appendPart(response, { text });
+    writeTextDelta?.(text);
+  }
+}
+function appendPart(response, part) {
+  const last = response.parts.at(-1);
+  if (last && !!last.isReasoning === !!part.isReasoning) last.text += part.text;
+  else response.parts.push(part);
+}
+function readUsage(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return {};
+  const usage = value;
+  const tokenCount = (item) => {
+    if (item == null) return 0;
+    if (typeof item !== "number" || !Number.isSafeInteger(item)) throw new TypeError("chat token count must be an integer");
+    return item;
+  };
+  const prompt = usage.prompt_tokens_details;
+  const completion = usage.completion_tokens_details;
+  return {
+    inputTokens: tokenCount(usage.prompt_tokens),
+    outputTokens: tokenCount(usage.completion_tokens),
+    totalTokens: tokenCount(usage.total_tokens),
+    cachedInputTokens: tokenCount(prompt?.cached_tokens),
+    reasoningTokens: tokenCount(completion?.reasoning_tokens)
+  };
+}
+export {
+  newWireFormat
+};

package/dist/textgen/textgentest/index.d.ts

@@ -0,0 +1,106 @@
+import { C as CredentialHeader, U as Usage, T as TextGenerationRequest } from '../../wire_format-stEVruMs.js';
+import { T as TextGenerationQuery } from '../../query-CeUaW9xU.js';
+import '../../types-D6De3sry.js';
+import 'zod';
+import '../../credentials-JqG97kJ5.js';
+import '@superdurable/dex';
+import '../../providerhttp/index.js';
+import 'node:http';
+import '../../operation-CASLOg86.js';
+
+/** One delayed piece of an event-stream reply. Durations are milliseconds. */
+interface FakeStreamChunk {
+    /** Delay after the prior piece. */ delayMs?: number;
+    /** Bytes to flush. */ data: string;
+}
+/** One scripted response, with zero status meaning HTTP 200. */
+interface FakeReply {
+    /** HTTP status. */ statusCode?: number;
+    /** Public response headers. */ headers?: Record<string, string>;
+    /** Initial body bytes. */ body?: string;
+    /** Silence before headers or a dropped connection, in milliseconds. */ delayMs?: number;
+    /** Ordered flushed body chunks. */ streamChunks?: readonly FakeStreamChunk[];
+    /** Drop the connection before sending headers. */ shouldDropConnection?: boolean;
+}
+/** Credential-redacted record of one provider request. */
+interface RecordedRequest {
+    /** HTTP method. */ method: string;
+    /** Request path and query. */ path: string;
+    /** Request headers, excluding the credential slot. */ headers: Record<string, string>;
+    /** Request body, bounded and credential-redacted. */ body: Buffer;
+    /** Receipt time. */ receivedAt: Date;
+    /** Whether the credential appeared in the declared header. */ hasCredentialInSlot: boolean;
+    /** Whether the credential appeared anywhere else. */ hasCredentialOutsideSlot: boolean;
+}
+/** Scripted loopback provider for shared text-generation exchange tests. */
+declare class FakeProvider {
+    #private;
+    private constructor();
+    /** Start one fixture server; close it after the suite. */
+    static start(credentialHeader: CredentialHeader, credential: string): Promise<FakeProvider>;
+    /** Return the loopback base URL. */
+    baseURL(): string;
+    /** Queue replies in request order. */
+    enqueueReplies(...replies: FakeReply[]): void;
+    /** Return a snapshot of sanitized requests. */
+    requests(): readonly RecordedRequest[];
+    /** Stop the fixture and all active connections. */
+    close(): Promise<void>;
+    private serveRequest;
+    private recordRequest;
+    private waitForDelay;
+}
+
+/** Values the provider-specific dialect must render for the exchange suite. */
+interface GeneratedReply {
+    /** User-visible answer. */ text: string;
+    /** Provider's model echo. */ servedModel: string;
+    /** Provider response identity. */ responseId: string;
+    /** Distinct token counts for field mapping checks. */ usage: Usage;
+}
+/** Provider-specific wire rendering and request parsing for shared exchange cases. */
+interface ProviderDialect {
+    /** Declared credential location. */ credentialHeader: CredentialHeader;
+    /** Connection's configured model. */ connectionModel: string;
+    /** Different valid request model. */ alternateModel: string;
+    /** Optional response header read into the receipt. */ requestIDHeader?: string;
+    /** Read the sent model from one sanitized request. */ readRequestModel(request: RecordedRequest): string;
+    /** Render a normal completion with all usage counts. */ generatedReply(reply: GeneratedReply): FakeReply;
+    /** Render an output-limit stop. */ truncatedReply(reply: GeneratedReply): FakeReply;
+    /** Render a content-policy stop or refusal. */ blockedReply(reply: GeneratedReply): FakeReply;
+    /** Render one provider status and private message. */ errorReply(statusCode: number, message: string): FakeReply;
+    /** Render provider quota exhaustion. */ quotaExhaustedReply(message: string): FakeReply;
+    /** Render malformed 2xx output. */ malformedReply(): FakeReply;
+    /** Render a 2xx embedded error when supported. */ reportedErrorReply?(token: string, message: string): FakeReply;
+    /** Render an interrupted event stream when the dialect streams. */ interruptedStreamReply?(reply: GeneratedReply): FakeReply;
+    /** Render a complete body for a streaming request when supported. */ unstreamedReply?(reply: GeneratedReply): FakeReply;
+    /** JSON pointers whose optional fields must be absent in the basic request. */ optionalRequestFieldPointers?: readonly string[];
+}
+/** Loopback connection passed to a connector's ordinary query factory. */
+interface FakeConnection {
+    /** Fake provider base URL. */ baseURL: string;
+    /** Configured provider model. */ model: string;
+    /** Canary API key; never put it in Flow state. */ apiKey: string;
+    /** Successful-response byte limit. */ maxResponseBytes: number;
+    /** Optional minimum exchange timeout for a silent-provider Dex scenario. */ requestTimeoutMs?: number;
+}
+/** One shared exchange suite invocation for a connector dialect. */
+interface TextGenerationExchangeSuite {
+    /** Provider-specific request and response shapes. */ dialect: ProviderDialect;
+    /** Build the connector's normal generateText Query. */ newQuery(connection: FakeConnection): TextGenerationQuery | Promise<TextGenerationQuery>;
+    /** Connector-specific invalid requests that must cause zero provider calls. */ locallyRejectedRequests?: readonly TextGenerationRequest[];
+}
+/** Run Go-equivalent model, branch, error, safety, and stream exchanges. */
+declare function runTextGenerationExchangeSuite(suite: TextGenerationExchangeSuite): Promise<void>;
+
+/** Real Dex Worker/Client scenarios for one provider's ordinary Query factory. */
+interface TextGenerationDexScenarioSuite {
+    /** Provider wire dialect shared with the exchange suite. */ dialect: ProviderDialect;
+    /** Build the ordinary connector Query with a request timeout of at least 15 seconds. */
+    newQuery(connection: FakeConnection): TextGenerationQuery | Promise<TextGenerationQuery>;
+    /** Dex FlowService address; defaults to DEX_SERVER_ADDRESS or 127.0.0.1:18891. */ serverAddress?: string;
+}
+/** Exercise retry, model precedence, Streams, heartbeat, unwired branches, and Worker loss through Dex. */
+declare function runTextGenerationDexScenarios(suite: TextGenerationDexScenarioSuite): Promise<void>;
+
+export { type FakeConnection, FakeProvider, type FakeReply, type FakeStreamChunk, type GeneratedReply, type ProviderDialect, type RecordedRequest, type TextGenerationDexScenarioSuite, type TextGenerationExchangeSuite, runTextGenerationDexScenarios, runTextGenerationExchangeSuite };