@animalabs/membrane 0.1.0

package/src/types/config.ts

@@ -0,0 +1,172 @@
+/**
+ * Configuration types for membrane
+ */
+
+import type { ModelRegistry } from './provider.js';
+import type { ErrorInfo } from './errors.js';
+import type { NormalizedRequest } from './request.js';
+import type { NormalizedResponse } from './response.js';
+
+// ============================================================================
+// Retry Config
+// ============================================================================
+
+export interface RetryConfig {
+  /** Maximum number of retry attempts (default: 3) */
+  maxRetries: number;
+  
+  /** Initial retry delay in milliseconds (default: 1000) */
+  retryDelayMs: number;
+  
+  /** Backoff multiplier (default: 2) */
+  backoffMultiplier: number;
+  
+  /** Maximum retry delay (default: 30000) */
+  maxRetryDelayMs: number;
+}
+
+// ============================================================================
+// Media Processing Config
+// ============================================================================
+
+export interface MediaConfig {
+  images: {
+    /** Maximum input image size in bytes */
+    maxSizeBytes: number;
+    
+    /** Maximum dimensions */
+    maxDimensions?: { width: number; height: number };
+    
+    /** Auto-resize if exceeds limits */
+    autoResize: boolean;
+    
+    /** JPEG quality for resizing (0-100) */
+    resizeQuality?: number;
+    
+    /** Relocate images to user turns in prefill mode */
+    relocateInPrefillMode: boolean;
+  };
+  
+  documents?: {
+    /** Maximum document size */
+    maxSizeBytes: number;
+  };
+  
+  audio?: {
+    /** Maximum duration in seconds */
+    maxDurationSec: number;
+  };
+  
+  video?: {
+    /** Maximum duration in seconds */
+    maxDurationSec: number;
+  };
+}
+
+// ============================================================================
+// Hooks
+// ============================================================================
+
+export interface MembraneHooks {
+  /**
+   * Called before sending request to provider
+   * Can modify the raw request
+   */
+  beforeRequest?: (
+    request: NormalizedRequest,
+    rawRequest: unknown
+  ) => unknown | Promise<unknown>;
+  
+  /**
+   * Called after receiving response from provider
+   * Can modify the response
+   */
+  afterResponse?: (
+    response: NormalizedResponse,
+    rawResponse: unknown
+  ) => NormalizedResponse | Promise<NormalizedResponse>;
+  
+  /**
+   * Called on error, before retry decision
+   * Return 'retry' to retry, 'abort' to stop
+   */
+  onError?: (
+    error: ErrorInfo,
+    attempt: number
+  ) => 'retry' | 'abort' | Promise<'retry' | 'abort'>;
+}
+
+// ============================================================================
+// Logger Interface
+// ============================================================================
+
+export interface MembraneLogger {
+  debug(message: string, data?: Record<string, unknown>): void;
+  info(message: string, data?: Record<string, unknown>): void;
+  warn(message: string, data?: Record<string, unknown>): void;
+  error(message: string, data?: Record<string, unknown>): void;
+}
+
+// ============================================================================
+// Membrane Config
+// ============================================================================
+
+export interface MembraneConfig {
+  /** Model registry for capability lookup */
+  registry?: ModelRegistry;
+
+  /** Default model to use */
+  defaultModel?: string;
+
+  /**
+   * Participant name to recognize as assistant in prefill mode.
+   * Messages with this participant will be formatted as assistant turns.
+   * Default: 'Claude'
+   */
+  assistantParticipant?: string;
+
+  /**
+   * Maximum number of participants to include in auto-generated stop sequences.
+   * In prefill mode, membrane generates stop sequences like "\nUsername:" to prevent
+   * the model from speaking as other participants.
+   * 
+   * Set to 0 to disable participant-based stop sequences (allows frags/quotes).
+   * Default: 10
+   */
+  maxParticipantsForStop?: number;
+
+  /** Retry configuration */
+  retry?: Partial<RetryConfig>;
+
+  /** Media processing configuration */
+  media?: Partial<MediaConfig>;
+
+  /** Lifecycle hooks */
+  hooks?: MembraneHooks;
+
+  /** Logger instance */
+  logger?: MembraneLogger;
+
+  /** Enable debug logging */
+  debug?: boolean;
+}
+
+// ============================================================================
+// Default Config
+// ============================================================================
+
+export const DEFAULT_RETRY_CONFIG: RetryConfig = {
+  maxRetries: 3,
+  retryDelayMs: 1000,
+  backoffMultiplier: 2,
+  maxRetryDelayMs: 30000,
+};
+
+export const DEFAULT_MEDIA_CONFIG: MediaConfig = {
+  images: {
+    maxSizeBytes: 5 * 1024 * 1024, // 5MB (Anthropic limit)
+    autoResize: true,
+    resizeQuality: 85,
+    relocateInPrefillMode: true,
+  },
+};

package/src/types/content.ts

@@ -0,0 +1,181 @@
+/**
+ * Content block types for normalized messages
+ */
+
+// ============================================================================
+// Cache Control (Anthropic prompt caching)
+// ============================================================================
+
+export interface CacheControl {
+  type: 'ephemeral';
+}
+
+// ============================================================================
+// Media Source
+// ============================================================================
+
+export interface Base64Source {
+  type: 'base64';
+  data: string;
+  mediaType: string;
+}
+
+export interface UrlSource {
+  type: 'url';
+  url: string;
+}
+
+export type MediaSource = Base64Source | UrlSource;
+
+// ============================================================================
+// Text Content
+// ============================================================================
+
+export interface TextContent {
+  type: 'text';
+  text: string;
+  /** Cache control for Anthropic prompt caching */
+  cache_control?: CacheControl;
+}
+
+// ============================================================================
+// Media Input Content
+// ============================================================================
+
+export interface ImageContent {
+  type: 'image';
+  source: MediaSource;
+  tokenEstimate?: number;
+}
+
+export interface DocumentContent {
+  type: 'document';
+  source: Base64Source;
+  filename?: string;
+}
+
+export interface AudioContent {
+  type: 'audio';
+  source: Base64Source;
+  duration?: number; // seconds
+}
+
+export interface VideoContent {
+  type: 'video';
+  source: Base64Source;
+  duration?: number; // seconds
+}
+
+// ============================================================================
+// Media Output Content (Generated)
+// ============================================================================
+
+export interface GeneratedImageContent {
+  type: 'generated_image';
+  data: string;
+  mimeType: string;
+  isPreview?: boolean; // Streaming: preview vs final
+}
+
+// ============================================================================
+// Tool Content
+// ============================================================================
+
+export interface ToolUseContent {
+  type: 'tool_use';
+  id: string;
+  name: string;
+  input: Record<string, unknown>;
+}
+
+export interface ToolResultContent {
+  type: 'tool_result';
+  toolUseId: string;
+  content: string | ContentBlock[];
+  isError?: boolean;
+}
+
+// ============================================================================
+// Thinking Content
+// ============================================================================
+
+export interface ThinkingContent {
+  type: 'thinking';
+  thinking: string;
+  signature?: string;
+}
+
+export interface RedactedThinkingContent {
+  type: 'redacted_thinking';
+}
+
+// ============================================================================
+// Union Type
+// ============================================================================
+
+export type ContentBlock =
+  // Text
+  | TextContent
+  // Media Input
+  | ImageContent
+  | DocumentContent
+  | AudioContent
+  | VideoContent
+  // Media Output
+  | GeneratedImageContent
+  // Tools
+  | ToolUseContent
+  | ToolResultContent
+  // Thinking
+  | ThinkingContent
+  | RedactedThinkingContent;
+
+// ============================================================================
+// Type Guards
+// ============================================================================
+
+export function isTextContent(block: ContentBlock): block is TextContent {
+  return block.type === 'text';
+}
+
+export function isImageContent(block: ContentBlock): block is ImageContent {
+  return block.type === 'image';
+}
+
+export function isDocumentContent(block: ContentBlock): block is DocumentContent {
+  return block.type === 'document';
+}
+
+export function isAudioContent(block: ContentBlock): block is AudioContent {
+  return block.type === 'audio';
+}
+
+export function isVideoContent(block: ContentBlock): block is VideoContent {
+  return block.type === 'video';
+}
+
+export function isGeneratedImageContent(block: ContentBlock): block is GeneratedImageContent {
+  return block.type === 'generated_image';
+}
+
+export function isToolUseContent(block: ContentBlock): block is ToolUseContent {
+  return block.type === 'tool_use';
+}
+
+export function isToolResultContent(block: ContentBlock): block is ToolResultContent {
+  return block.type === 'tool_result';
+}
+
+export function isThinkingContent(block: ContentBlock): block is ThinkingContent {
+  return block.type === 'thinking';
+}
+
+export function isRedactedThinkingContent(block: ContentBlock): block is RedactedThinkingContent {
+  return block.type === 'redacted_thinking';
+}
+
+export function isMediaContent(
+  block: ContentBlock
+): block is ImageContent | DocumentContent | AudioContent | VideoContent {
+  return ['image', 'document', 'audio', 'video'].includes(block.type);
+}

package/src/types/errors.ts

@@ -0,0 +1,277 @@
+/**
+ * Error types for membrane
+ */
+
+// ============================================================================
+// Error Types
+// ============================================================================
+
+export type MembraneErrorType =
+  | 'rate_limit'
+  | 'context_length'
+  | 'invalid_request'
+  | 'auth'
+  | 'server'
+  | 'network'
+  | 'timeout'
+  | 'abort'
+  | 'safety'
+  | 'unsupported'
+  | 'unknown';
+
+// ============================================================================
+// Error Info (for hooks and logging)
+// ============================================================================
+
+export interface ErrorInfo {
+  /** Normalized error type */
+  type: MembraneErrorType;
+  
+  /** Human-readable message */
+  message: string;
+  
+  /** Whether this error is retryable */
+  retryable: boolean;
+  
+  /** Retry after (milliseconds) - for rate limits */
+  retryAfterMs?: number;
+  
+  /** HTTP status code if available */
+  httpStatus?: number;
+  
+  /** Provider-specific error code */
+  providerErrorCode?: string;
+  
+  /** Raw error object */
+  rawError: unknown;
+}
+
+// ============================================================================
+// Membrane Error Class
+// ============================================================================
+
+export class MembraneError extends Error {
+  readonly type: MembraneErrorType;
+  readonly retryable: boolean;
+  readonly retryAfterMs?: number;
+  readonly httpStatus?: number;
+  readonly providerErrorCode?: string;
+  readonly rawError?: unknown;
+
+  constructor(info: ErrorInfo) {
+    super(info.message);
+    this.name = 'MembraneError';
+    this.type = info.type;
+    this.retryable = info.retryable;
+    this.retryAfterMs = info.retryAfterMs;
+    this.httpStatus = info.httpStatus;
+    this.providerErrorCode = info.providerErrorCode;
+    this.rawError = info.rawError;
+  }
+
+  toErrorInfo(): ErrorInfo {
+    return {
+      type: this.type,
+      message: this.message,
+      retryable: this.retryable,
+      retryAfterMs: this.retryAfterMs,
+      httpStatus: this.httpStatus,
+      providerErrorCode: this.providerErrorCode,
+      rawError: this.rawError,
+    };
+  }
+}
+
+// ============================================================================
+// Error Factory Functions
+// ============================================================================
+
+export function rateLimitError(message: string, retryAfterMs?: number, raw?: unknown): MembraneError {
+  return new MembraneError({
+    type: 'rate_limit',
+    message,
+    retryable: true,
+    retryAfterMs,
+    httpStatus: 429,
+    rawError: raw,
+  });
+}
+
+export function contextLengthError(message: string, raw?: unknown): MembraneError {
+  return new MembraneError({
+    type: 'context_length',
+    message,
+    retryable: false,
+    httpStatus: 400,
+    rawError: raw,
+  });
+}
+
+export function invalidRequestError(message: string, raw?: unknown): MembraneError {
+  return new MembraneError({
+    type: 'invalid_request',
+    message,
+    retryable: false,
+    httpStatus: 400,
+    rawError: raw,
+  });
+}
+
+export function authError(message: string, raw?: unknown): MembraneError {
+  return new MembraneError({
+    type: 'auth',
+    message,
+    retryable: false,
+    httpStatus: 401,
+    rawError: raw,
+  });
+}
+
+export function serverError(message: string, httpStatus?: number, raw?: unknown): MembraneError {
+  return new MembraneError({
+    type: 'server',
+    message,
+    retryable: true,
+    httpStatus: httpStatus ?? 500,
+    rawError: raw,
+  });
+}
+
+export function networkError(message: string, raw?: unknown): MembraneError {
+  return new MembraneError({
+    type: 'network',
+    message,
+    retryable: true,
+    rawError: raw,
+  });
+}
+
+export function timeoutError(message: string, raw?: unknown): MembraneError {
+  return new MembraneError({
+    type: 'timeout',
+    message,
+    retryable: true,
+    rawError: raw,
+  });
+}
+
+export function abortError(message: string = 'Request was aborted'): MembraneError {
+  return new MembraneError({
+    type: 'abort',
+    message,
+    retryable: false,
+    rawError: undefined,
+  });
+}
+
+export function safetyError(message: string, raw?: unknown): MembraneError {
+  return new MembraneError({
+    type: 'safety',
+    message,
+    retryable: false,
+    rawError: raw,
+  });
+}
+
+export function unsupportedError(message: string): MembraneError {
+  return new MembraneError({
+    type: 'unsupported',
+    message,
+    retryable: false,
+    rawError: undefined,
+  });
+}
+
+// ============================================================================
+// Error Classification
+// ============================================================================
+
+export function classifyError(error: unknown): ErrorInfo {
+  if (error instanceof MembraneError) {
+    return error.toErrorInfo();
+  }
+
+  if (error instanceof Error) {
+    const message = error.message.toLowerCase();
+    
+    // Rate limit
+    if (message.includes('rate') || message.includes('429') || message.includes('too many')) {
+      return {
+        type: 'rate_limit',
+        message: error.message,
+        retryable: true,
+        httpStatus: 429,
+        rawError: error,
+      };
+    }
+    
+    // Context length
+    if (message.includes('context') || message.includes('too long') || message.includes('maximum')) {
+      return {
+        type: 'context_length',
+        message: error.message,
+        retryable: false,
+        rawError: error,
+      };
+    }
+    
+    // Auth
+    if (message.includes('auth') || message.includes('401') || message.includes('api key')) {
+      return {
+        type: 'auth',
+        message: error.message,
+        retryable: false,
+        httpStatus: 401,
+        rawError: error,
+      };
+    }
+    
+    // Network
+    if (message.includes('network') || message.includes('econnreset') || message.includes('socket')) {
+      return {
+        type: 'network',
+        message: error.message,
+        retryable: true,
+        rawError: error,
+      };
+    }
+    
+    // Timeout
+    if (message.includes('timeout') || message.includes('timed out')) {
+      return {
+        type: 'timeout',
+        message: error.message,
+        retryable: true,
+        rawError: error,
+      };
+    }
+    
+    // Abort
+    if (message.includes('abort') || error.name === 'AbortError') {
+      return {
+        type: 'abort',
+        message: error.message,
+        retryable: false,
+        rawError: error,
+      };
+    }
+    
+    // Server error
+    if (message.includes('500') || message.includes('502') || message.includes('503') || message.includes('504')) {
+      return {
+        type: 'server',
+        message: error.message,
+        retryable: true,
+        rawError: error,
+      };
+    }
+  }
+
+  // Unknown
+  return {
+    type: 'unknown',
+    message: error instanceof Error ? error.message : String(error),
+    retryable: false,
+    rawError: error,
+  };
+}