@animalabs/membrane 0.3.2 → 0.5.0

package/src/formatters/completions.ts

@@ -0,0 +1,343 @@
+/**
+ * Completions Formatter
+ *
+ * Formatter for base/completion models that use single-prompt input.
+ * Serializes conversations to "Participant: content<eot>" format.
+ *
+ * Key features:
+ * - Converts multi-turn conversations to single prompt string
+ * - Adds configurable end-of-turn tokens
+ * - Generates stop sequences from participant names
+ * - Strips images (not supported in completion models)
+ * - No XML block parsing (passthrough mode)
+ */
+
+import type {
+  NormalizedMessage,
+  ContentBlock,
+  ToolDefinition,
+  ToolCall,
+  ToolResult,
+} from '../types/index.js';
+import type {
+  PrefillFormatter,
+  StreamParser,
+  BuildOptions,
+  BuildResult,
+  FormatterConfig,
+  ProviderMessage,
+  ParseResult,
+  BlockType,
+} from './types.js';
+
+// ============================================================================
+// Configuration
+// ============================================================================
+
+export interface CompletionsFormatterConfig extends FormatterConfig {
+  /**
+   * End-of-turn token to append after each message.
+   * Set to empty string to disable.
+   * Default: '<|eot|>'
+   */
+  eotToken?: string;
+
+  /**
+   * Format for participant name prefix.
+   * Use {name} as placeholder.
+   * Default: '{name}: '
+   */
+  nameFormat?: string;
+
+  /**
+   * Message separator between turns.
+   * Default: '\n\n'
+   */
+  messageSeparator?: string;
+
+  /**
+   * Maximum participants to include in stop sequences.
+   * Default: 10
+   */
+  maxParticipantsForStop?: number;
+
+  /**
+   * Whether to warn when images are stripped.
+   * Default: true
+   */
+  warnOnImageStrip?: boolean;
+}
+
+// ============================================================================
+// Passthrough Stream Parser (same as NativeFormatter)
+// ============================================================================
+
+/**
+ * Simple pass-through parser for base models.
+ * No XML tracking - just accumulates content.
+ */
+class CompletionsStreamParser implements StreamParser {
+  private accumulated = '';
+  private blockIndex = 0;
+
+  processChunk(chunk: string): ParseResult {
+    this.accumulated += chunk;
+    const meta = {
+      type: 'text' as const,
+      visible: true,
+      blockIndex: this.blockIndex,
+    };
+    return {
+      emissions: [{
+        kind: 'content' as const,
+        text: chunk,
+        meta,
+      }],
+      content: [{ text: chunk, meta }],
+      blockEvents: [],
+    };
+  }
+
+  flush(): ParseResult {
+    return { emissions: [], content: [], blockEvents: [] };
+  }
+
+  getAccumulated(): string {
+    return this.accumulated;
+  }
+
+  reset(): void {
+    this.accumulated = '';
+    this.blockIndex = 0;
+  }
+
+  push(content: string): void {
+    this.accumulated += content;
+  }
+
+  getCurrentBlockType(): BlockType {
+    return 'text';
+  }
+
+  getBlockIndex(): number {
+    return this.blockIndex;
+  }
+
+  incrementBlockIndex(): void {
+    this.blockIndex++;
+  }
+
+  isInsideBlock(): boolean {
+    return false;
+  }
+
+  resetForNewIteration(): void {
+    // No special reset needed
+  }
+}
+
+// ============================================================================
+// Completions Formatter
+// ============================================================================
+
+export class CompletionsFormatter implements PrefillFormatter {
+  readonly name = 'completions';
+  readonly usesPrefill = true;
+
+  private config: Required<Omit<CompletionsFormatterConfig, 'unsupportedMedia' | 'warnOnStrip'>> & {
+    unsupportedMedia: 'strip'; // Always strip for completions
+    warnOnStrip: boolean;
+  };
+
+  constructor(config: CompletionsFormatterConfig = {}) {
+    this.config = {
+      eotToken: config.eotToken ?? '<|eot|>',
+      nameFormat: config.nameFormat ?? '{name}: ',
+      messageSeparator: config.messageSeparator ?? '\n\n',
+      maxParticipantsForStop: config.maxParticipantsForStop ?? 10,
+      warnOnImageStrip: config.warnOnImageStrip ?? true,
+      // Completions models don't support images - always strip
+      unsupportedMedia: 'strip',
+      warnOnStrip: config.warnOnStrip ?? true,
+    };
+  }
+
+  // ==========================================================================
+  // REQUEST BUILDING
+  // ==========================================================================
+
+  buildMessages(messages: NormalizedMessage[], options: BuildOptions): BuildResult {
+    const {
+      assistantParticipant,
+      systemPrompt,
+      additionalStopSequences,
+      maxParticipantsForStop = this.config.maxParticipantsForStop,
+    } = options;
+
+    const parts: string[] = [];
+    const participants = new Set<string>();
+    let hasStrippedImages = false;
+
+    // Add system prompt as first part if present
+    if (systemPrompt) {
+      const systemText = typeof systemPrompt === 'string'
+        ? systemPrompt
+        : systemPrompt
+            .filter((b): b is ContentBlock & { type: 'text' } => b.type === 'text')
+            .map(b => b.text)
+            .join('\n');
+
+      if (systemText) {
+        parts.push(systemText);
+      }
+    }
+
+    // Serialize each message
+    for (const message of messages) {
+      participants.add(message.participant);
+
+      const { text, hadImages } = this.extractTextContent(message.content);
+      if (hadImages) {
+        hasStrippedImages = true;
+      }
+
+      // Skip empty messages (except if it's the final completion target)
+      if (!text.trim()) {
+        continue;
+      }
+
+      // Format: "Participant: content<eot>"
+      const prefix = this.config.nameFormat.replace('{name}', message.participant);
+      const eot = this.config.eotToken;
+      parts.push(`${prefix}${text}${eot}`);
+    }
+
+    // Warn about stripped images
+    if (hasStrippedImages && this.config.warnOnImageStrip) {
+      console.warn('[CompletionsFormatter] Images were stripped from context (not supported in completions mode)');
+    }
+
+    // Add final assistant prefix (no EOT - model generates this)
+    const assistantPrefix = this.config.nameFormat.replace('{name}', assistantParticipant);
+    parts.push(assistantPrefix.trimEnd()); // Remove trailing space for cleaner completion
+
+    // Join all parts into single prompt
+    const prompt = parts.join(this.config.messageSeparator);
+
+    // Build stop sequences from participants
+    const stopSequences = this.buildStopSequences(
+      participants,
+      assistantParticipant,
+      maxParticipantsForStop,
+      additionalStopSequences
+    );
+
+    // Return as single assistant message with prompt as content
+    // The provider adapter will extract this as the prompt
+    const providerMessages: ProviderMessage[] = [
+      { role: 'assistant', content: prompt },
+    ];
+
+    return {
+      messages: providerMessages,
+      assistantPrefill: prompt,
+      stopSequences,
+    };
+  }
+
+  formatToolResults(results: ToolResult[], options?: { thinking?: boolean }): string {
+    // Completions mode typically doesn't support tools
+    // But format them as simple text if needed
+    const parts = results.map(r => {
+      const content = typeof r.content === 'string' ? r.content : JSON.stringify(r.content);
+      return `[Tool Result: ${content}]`;
+    });
+    return parts.join('\n');
+  }
+
+  // ==========================================================================
+  // RESPONSE PARSING
+  // ==========================================================================
+
+  createStreamParser(): StreamParser {
+    return new CompletionsStreamParser();
+  }
+
+  parseToolCalls(content: string): ToolCall[] {
+    // Base models don't have structured tool output
+    return [];
+  }
+
+  hasToolUse(content: string): boolean {
+    // Base models determine completion via stop sequences
+    return false;
+  }
+
+  parseContentBlocks(content: string): ContentBlock[] {
+    // Trim leading whitespace (model often starts with space after prefix)
+    const trimmed = content.replace(/^\s+/, '');
+
+    if (!trimmed) {
+      return [];
+    }
+
+    return [{ type: 'text', text: trimmed }];
+  }
+
+  // ==========================================================================
+  // PRIVATE HELPERS
+  // ==========================================================================
+
+  private extractTextContent(content: ContentBlock[]): { text: string; hadImages: boolean } {
+    const textParts: string[] = [];
+    let hadImages = false;
+
+    for (const block of content) {
+      if (block.type === 'text') {
+        textParts.push(block.text);
+      } else if (block.type === 'image') {
+        hadImages = true;
+      }
+      // Skip tool_use, tool_result, thinking blocks for base models
+    }
+
+    return {
+      text: textParts.join('\n'),
+      hadImages,
+    };
+  }
+
+  private buildStopSequences(
+    participants: Set<string>,
+    assistantParticipant: string,
+    maxParticipants: number,
+    additionalStopSequences?: string[]
+  ): string[] {
+    const stops: string[] = [];
+
+    // Get recent participants (excluding assistant)
+    let count = 0;
+    for (const participant of participants) {
+      if (participant === assistantParticipant) continue;
+      if (count >= maxParticipants) break;
+
+      // Add both "\n\nName:" and "\nName:" variants
+      const prefix = this.config.nameFormat.replace('{name}', participant).trimEnd();
+      stops.push(`\n\n${prefix}`);
+      stops.push(`\n${prefix}`);
+      count++;
+    }
+
+    // Add EOT token as stop sequence if configured
+    if (this.config.eotToken) {
+      stops.push(this.config.eotToken);
+    }
+
+    // Add any additional stop sequences
+    if (additionalStopSequences?.length) {
+      stops.push(...additionalStopSequences);
+    }
+
+    return stops;
+  }
+}

package/src/formatters/index.ts

@@ -0,0 +1,19 @@
+/**
+ * Formatter exports
+ */
+
+// Export formatter-specific types only (avoid duplicates with types/streaming.js)
+export type {
+  PrefillFormatter,
+  StreamParser,
+  FormatterConfig,
+  BuildOptions,
+  BuildResult,
+  ParseResult,
+  BlockType,
+  ProviderMessage,
+} from './types.js';
+
+export { AnthropicXmlFormatter, type AnthropicXmlFormatterConfig } from './anthropic-xml.js';
+export { NativeFormatter, type NativeFormatterConfig } from './native.js';
+export { CompletionsFormatter, type CompletionsFormatterConfig } from './completions.js';

package/src/formatters/native.ts

@@ -0,0 +1,340 @@
+/**
+ * Native Formatter
+ *
+ * Pass-through formatter that converts messages to standard user/assistant
+ * format without prefill. Uses native API tool calling.
+ *
+ * Supports two participant modes:
+ * - 'simple': Strict two-party (Human/Assistant), no names in content
+ * - 'multiuser': Multiple participants, names prefixed to content
+ */
+
+import type {
+  NormalizedMessage,
+  ContentBlock,
+  ToolDefinition,
+  ToolCall,
+  ToolResult,
+} from '../types/index.js';
+import type {
+  PrefillFormatter,
+  StreamParser,
+  BuildOptions,
+  BuildResult,
+  FormatterConfig,
+  ProviderMessage,
+  ParseResult,
+  BlockType,
+} from './types.js';
+
+// ============================================================================
+// Configuration
+// ============================================================================
+
+export interface NativeFormatterConfig extends FormatterConfig {
+  /**
+   * Format for participant name prefix in multiuser mode.
+   * Use {name} as placeholder. Default: '{name}: '
+   */
+  nameFormat?: string;
+}
+
+// ============================================================================
+// Pass-through Stream Parser
+// ============================================================================
+
+/**
+ * Simple pass-through parser that doesn't do XML tracking.
+ * Just accumulates content and emits text chunks.
+ */
+class PassthroughParser implements StreamParser {
+  private accumulated = '';
+  private blockIndex = 0;
+
+  processChunk(chunk: string): ParseResult {
+    this.accumulated += chunk;
+    const meta = {
+      type: 'text' as const,
+      visible: true,
+      blockIndex: this.blockIndex,
+    };
+    return {
+      emissions: [{
+        kind: 'content' as const,
+        text: chunk,
+        meta,
+      }],
+      content: [{ text: chunk, meta }],
+      blockEvents: [],
+    };
+  }
+
+  flush(): ParseResult {
+    return { emissions: [], content: [], blockEvents: [] };
+  }
+
+  getAccumulated(): string {
+    return this.accumulated;
+  }
+
+  reset(): void {
+    this.accumulated = '';
+    this.blockIndex = 0;
+  }
+
+  push(content: string): void {
+    this.accumulated += content;
+  }
+
+  getCurrentBlockType(): BlockType {
+    return 'text';
+  }
+
+  getBlockIndex(): number {
+    return this.blockIndex;
+  }
+
+  incrementBlockIndex(): void {
+    this.blockIndex++;
+  }
+
+  isInsideBlock(): boolean {
+    // Pass-through mode never has nested blocks
+    return false;
+  }
+
+  resetForNewIteration(): void {
+    // No special reset needed for pass-through mode
+  }
+}
+
+// ============================================================================
+// Native Formatter
+// ============================================================================
+
+export class NativeFormatter implements PrefillFormatter {
+  readonly name = 'native';
+  readonly usesPrefill = false;
+
+  private config: Required<NativeFormatterConfig>;
+
+  constructor(config: NativeFormatterConfig = {}) {
+    this.config = {
+      nameFormat: config.nameFormat ?? '{name}: ',
+      unsupportedMedia: config.unsupportedMedia ?? 'error',
+      warnOnStrip: config.warnOnStrip ?? true,
+    };
+  }
+
+  // ==========================================================================
+  // REQUEST BUILDING
+  // ==========================================================================
+
+  buildMessages(messages: NormalizedMessage[], options: BuildOptions): BuildResult {
+    const {
+      participantMode,
+      assistantParticipant,
+      humanParticipant,
+      tools,
+      systemPrompt,
+    } = options;
+
+    const providerMessages: ProviderMessage[] = [];
+
+    // Validate simple mode participants
+    if (participantMode === 'simple' && !humanParticipant) {
+      throw new Error('NativeFormatter in simple mode requires humanParticipant option');
+    }
+
+    for (const message of messages) {
+      // Determine role
+      const isAssistant = message.participant === assistantParticipant;
+
+      // Validate participant in simple mode
+      if (participantMode === 'simple') {
+        if (!isAssistant && message.participant !== humanParticipant) {
+          throw new Error(
+            `NativeFormatter in simple mode only supports "${humanParticipant}" and "${assistantParticipant}". ` +
+            `Got: "${message.participant}". Use participantMode: 'multiuser' for multiple participants.`
+          );
+        }
+      }
+
+      const role: 'user' | 'assistant' = isAssistant ? 'assistant' : 'user';
+
+      // Convert content
+      const content = this.convertContent(message.content, message.participant, {
+        includeNames: participantMode === 'multiuser' && !isAssistant,
+      });
+
+      if (content.length === 0) {
+        continue; // Skip empty messages
+      }
+
+      providerMessages.push({ role, content });
+    }
+
+    // Merge consecutive same-role messages (API requires alternating)
+    const mergedMessages = this.mergeConsecutiveRoles(providerMessages);
+
+    // Build system content
+    let systemContent: unknown;
+    if (typeof systemPrompt === 'string') {
+      systemContent = systemPrompt;
+    } else if (Array.isArray(systemPrompt)) {
+      systemContent = systemPrompt;
+    }
+
+    // Native tools
+    const nativeTools = tools?.length ? this.convertToNativeTools(tools) : undefined;
+
+    return {
+      messages: mergedMessages,
+      systemContent,
+      stopSequences: [], // Native mode doesn't use custom stop sequences
+      nativeTools,
+    };
+  }
+
+  formatToolResults(results: ToolResult[]): string {
+    // Native mode uses API tool_result blocks, not string formatting
+    // This method is mainly for prefill modes
+    return JSON.stringify(results.map(r => ({
+      tool_use_id: r.toolUseId,
+      content: r.content,
+      is_error: r.isError,
+    })));
+  }
+
+  // ==========================================================================
+  // RESPONSE PARSING
+  // ==========================================================================
+
+  createStreamParser(): StreamParser {
+    return new PassthroughParser();
+  }
+
+  parseToolCalls(content: string): ToolCall[] {
+    // Native mode gets tool calls from API response, not from content parsing
+    // Return empty - tool calls come through the native API response
+    return [];
+  }
+
+  hasToolUse(content: string): boolean {
+    // Native mode determines tool use from API stop_reason, not content
+    return false;
+  }
+
+  parseContentBlocks(content: string): ContentBlock[] {
+    // Native mode - content is plain text
+    if (!content.trim()) {
+      return [];
+    }
+    return [{ type: 'text', text: content }];
+  }
+
+  // ==========================================================================
+  // PRIVATE HELPERS
+  // ==========================================================================
+
+  private convertContent(
+    content: ContentBlock[],
+    participant: string,
+    options: { includeNames: boolean }
+  ): unknown[] {
+    const result: unknown[] = [];
+    let hasUnsupportedMedia = false;
+
+    for (const block of content) {
+      if (block.type === 'text') {
+        let text = block.text;
+        if (options.includeNames) {
+          const prefix = this.config.nameFormat.replace('{name}', participant);
+          text = prefix + text;
+        }
+        const textBlock: Record<string, unknown> = { type: 'text', text };
+        if (block.cache_control) {
+          textBlock.cache_control = block.cache_control;
+        }
+        result.push(textBlock);
+      } else if (block.type === 'image') {
+        if (block.source.type === 'base64') {
+          result.push({
+            type: 'image',
+            source: {
+              type: 'base64',
+              media_type: block.source.mediaType,
+              data: block.source.data,
+            },
+          });
+        }
+      } else if (block.type === 'tool_use') {
+        result.push({
+          type: 'tool_use',
+          id: block.id,
+          name: block.name,
+          input: block.input,
+        });
+      } else if (block.type === 'tool_result') {
+        result.push({
+          type: 'tool_result',
+          tool_use_id: block.toolUseId,
+          content: block.content,
+          is_error: block.isError,
+        });
+      } else if (block.type === 'thinking') {
+        result.push({
+          type: 'thinking',
+          thinking: block.thinking,
+        });
+      } else if (block.type === 'document' || block.type === 'audio') {
+        hasUnsupportedMedia = true;
+      }
+    }
+
+    if (hasUnsupportedMedia) {
+      if (this.config.unsupportedMedia === 'error') {
+        throw new Error(`NativeFormatter: unsupported media type in content. Configure unsupportedMedia: 'strip' to ignore.`);
+      } else if (this.config.warnOnStrip) {
+        console.warn(`[NativeFormatter] Stripped unsupported media from message`);
+      }
+    }
+
+    return result;
+  }
+
+  private mergeConsecutiveRoles(messages: ProviderMessage[]): ProviderMessage[] {
+    if (messages.length === 0) return [];
+
+    const merged: ProviderMessage[] = [];
+    let current: ProviderMessage = messages[0]!;
+
+    for (let i = 1; i < messages.length; i++) {
+      const next: ProviderMessage = messages[i]!;
+
+      if (next.role === current.role) {
+        // Merge content arrays
+        const currentContent = Array.isArray(current.content) ? current.content : [current.content];
+        const nextContent = Array.isArray(next.content) ? next.content : [next.content];
+        current = {
+          role: current.role,
+          content: [...currentContent, ...nextContent],
+        };
+      } else {
+        merged.push(current);
+        current = next;
+      }
+    }
+
+    merged.push(current);
+    return merged;
+  }
+
+  private convertToNativeTools(tools: ToolDefinition[]): unknown[] {
+    return tools.map(tool => ({
+      name: tool.name,
+      description: tool.description,
+      input_schema: tool.inputSchema,
+    }));
+  }
+}