@animalabs/membrane 0.1.0

package/src/types/index.ts

@@ -0,0 +1,154 @@
+/**
+ * Type exports for membrane
+ */
+
+// Content blocks
+export type {
+  CacheControl,
+  MediaSource,
+  Base64Source,
+  UrlSource,
+  ContentBlock,
+  TextContent,
+  ImageContent,
+  DocumentContent,
+  AudioContent,
+  VideoContent,
+  GeneratedImageContent,
+  ToolUseContent,
+  ToolResultContent,
+  ThinkingContent,
+  RedactedThinkingContent,
+} from './content.js';
+
+export {
+  isTextContent,
+  isImageContent,
+  isDocumentContent,
+  isAudioContent,
+  isVideoContent,
+  isGeneratedImageContent,
+  isToolUseContent,
+  isToolResultContent,
+  isThinkingContent,
+  isRedactedThinkingContent,
+  isMediaContent,
+} from './content.js';
+
+// Messages
+export type {
+  MessageMetadata,
+  NormalizedMessage,
+} from './message.js';
+
+export {
+  textMessage,
+  extractText,
+  hasMedia,
+  hasToolUse,
+} from './message.js';
+
+// Tools
+export type {
+  ToolParameter,
+  ToolDefinition,
+  ToolCall,
+  ToolResult,
+  ToolResultContentBlock,
+  ToolContext,
+  ParsedToolCalls,
+} from './tools.js';
+
+// Request
+export type {
+  GenerationConfig,
+  StopSequenceStrategy,
+  StopSequenceConfig,
+  RequestOptions,
+  NormalizedRequest,
+  ToolMode,
+} from './request.js';
+
+// Response
+export type {
+  StopReason,
+  BasicUsage,
+  DetailedUsage,
+  CostBreakdown,
+  StopInfo,
+  ModelInfo,
+  TimingInfo,
+  CacheInfo,
+  ResponseDetails,
+  RawAccess,
+  NormalizedResponse,
+  AbortedResponse,
+} from './response.js';
+
+export { isAbortedResponse } from './response.js';
+
+// Provider
+export type {
+  ProviderQuirks,
+  MediaCapabilities,
+  ProviderCapabilities,
+  ModelPricing,
+  ModelDefinition,
+  ModelRegistry,
+  ModelFilter,
+  ProviderAdapter,
+  ProviderRequest,
+  ProviderRequestOptions,
+  ProviderResponse,
+  StreamCallbacks,
+} from './provider.js';
+
+// Streaming
+export type {
+  StreamState,
+  StreamOptions,
+  CompleteOptions,
+  OnChunkCallback,
+  OnContentBlockCallback,
+  OnToolCallsCallback,
+  OnPreToolContentCallback,
+  OnUsageCallback,
+  OnBlockCallback,
+  BlockEvent,
+  BlockDelta,
+} from './streaming.js';
+
+// Errors
+export type {
+  MembraneErrorType,
+  ErrorInfo,
+} from './errors.js';
+
+export {
+  MembraneError,
+  rateLimitError,
+  contextLengthError,
+  invalidRequestError,
+  authError,
+  serverError,
+  networkError,
+  timeoutError,
+  abortError,
+  safetyError,
+  unsupportedError,
+  classifyError,
+} from './errors.js';
+
+// Config
+export type {
+  RetryConfig,
+  MediaConfig,
+  MembraneHooks,
+  MembraneLogger,
+  MembraneConfig,
+} from './config.js';
+
+export {
+  DEFAULT_RETRY_CONFIG,
+  DEFAULT_MEDIA_CONFIG,
+} from './config.js';

package/src/types/message.ts

@@ -0,0 +1,89 @@
+/**
+ * Normalized message types
+ */
+
+import type { ContentBlock, CacheControl } from './content.js';
+
+// Re-export CacheControl for consumers
+export type { CacheControl } from './content.js';
+
+// ============================================================================
+// Message Metadata
+// ============================================================================
+
+export interface MessageMetadata {
+  /** Original timestamp */
+  timestamp?: Date;
+  
+  /** Source ID from originating system (Discord message ID, UI message ID, etc.) */
+  sourceId?: string;
+  
+  /** Cache control for this message */
+  cacheControl?: CacheControl;
+  
+  /** Stream routing (for VEIL/connectome compatibility) */
+  streamId?: string;
+  
+  /** Additional metadata (pass-through) */
+  [key: string]: unknown;
+}
+
+// ============================================================================
+// Normalized Message
+// ============================================================================
+
+/**
+ * A message from a single participant.
+ * This is the core abstraction - no artificial "user" vs "assistant" roles.
+ */
+export interface NormalizedMessage {
+  /** Participant name: "Alice", "Bob", "Claude", etc. */
+  participant: string;
+  
+  /** Content blocks */
+  content: ContentBlock[];
+  
+  /** Message metadata */
+  metadata?: MessageMetadata;
+}
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+/**
+ * Create a simple text message
+ */
+export function textMessage(participant: string, text: string, metadata?: MessageMetadata): NormalizedMessage {
+  return {
+    participant,
+    content: [{ type: 'text', text }],
+    metadata,
+  };
+}
+
+/**
+ * Extract all text content from a message
+ */
+export function extractText(message: NormalizedMessage): string {
+  return message.content
+    .filter((block): block is { type: 'text'; text: string } => block.type === 'text')
+    .map((block) => block.text)
+    .join('\n');
+}
+
+/**
+ * Check if message has any media content
+ */
+export function hasMedia(message: NormalizedMessage): boolean {
+  return message.content.some((block) =>
+    ['image', 'document', 'audio', 'video'].includes(block.type)
+  );
+}
+
+/**
+ * Check if message has tool use
+ */
+export function hasToolUse(message: NormalizedMessage): boolean {
+  return message.content.some((block) => block.type === 'tool_use');
+}

package/src/types/provider.ts

@@ -0,0 +1,249 @@
+/**
+ * Provider capability and registry types
+ */
+
+// ============================================================================
+// Provider Quirks
+// ============================================================================
+
+export interface ProviderQuirks {
+  /** Anthropic: must trim trailing whitespace from assistant messages */
+  trimAssistantTrailingWhitespace?: boolean;
+  
+  /** Most providers: require alternating user/assistant roles */
+  requiresAlternatingRoles?: boolean;
+  
+  /** Prefill mode: images must be in user turns */
+  imagesMustBeInUserTurn?: boolean;
+  
+  /** Whether stop sequence is consumed (not in output) or present */
+  stopSequenceConsumed?: boolean;
+  
+  /** Parameters to strip from request (provider rejects them) */
+  rejectParams?: string[];
+  
+  /** Provider-specific notes */
+  notes?: string;
+}
+
+// ============================================================================
+// Media Capabilities
+// ============================================================================
+
+export interface MediaCapabilities {
+  // Input support
+  imageInput: boolean;
+  pdfInput: boolean;
+  audioInput: boolean;
+  videoInput: boolean;
+  
+  // Output support
+  imageGeneration: boolean;
+  
+  // Limits
+  maxImageSizeBytes?: number;
+  maxImageDimensions?: { width: number; height: number };
+  maxPdfPages?: number;
+  maxAudioDurationSec?: number;
+  maxVideoDurationSec?: number;
+  
+  // Supported formats
+  imageFormats?: string[];  // ['image/jpeg', 'image/png', ...]
+  audioFormats?: string[];  // ['audio/mpeg', 'audio/wav', ...]
+  videoFormats?: string[];  // ['video/mp4', 'video/webm', ...]
+}
+
+// ============================================================================
+// Provider Capabilities
+// ============================================================================
+
+export interface ProviderCapabilities {
+  // Mode support
+  supportsPrefill: boolean;
+  supportsChat: boolean;
+  supportsCaching: boolean;
+  supportsThinking: boolean;
+  supportsStreaming: boolean;
+  
+  // Media
+  media: MediaCapabilities;
+  
+  // Limits
+  maxContextTokens: number;
+  maxOutputTokens: number;
+  maxStopSequences: number;
+  maxCacheBreakpoints?: number;
+  
+  // Quirks
+  quirks: ProviderQuirks;
+}
+
+// ============================================================================
+// Model Pricing
+// ============================================================================
+
+export interface ModelPricing {
+  /** Cost per million input tokens */
+  inputPerMillion: number;
+  
+  /** Cost per million output tokens */
+  outputPerMillion: number;
+  
+  /** Cost per million cache write tokens */
+  cacheWritePerMillion?: number;
+  
+  /** Cost per million cache read tokens */
+  cacheReadPerMillion?: number;
+  
+  /** Currency code */
+  currency: string;
+}
+
+// ============================================================================
+// Model Information
+// ============================================================================
+
+export interface ModelDefinition {
+  /** Unique model identifier */
+  id: string;
+  
+  /** Provider (anthropic, openrouter, google, etc.) */
+  provider: string;
+  
+  /** Display name for UI */
+  displayName: string;
+  
+  /** Capabilities */
+  capabilities: ProviderCapabilities;
+  
+  /** Pricing (optional) */
+  pricing?: ModelPricing;
+  
+  /** Aliases that resolve to this model */
+  aliases?: string[];
+  
+  /** Whether model is deprecated */
+  deprecated?: boolean;
+  
+  /** Successor model if deprecated */
+  successorId?: string;
+}
+
+// ============================================================================
+// Model Registry Interface
+// ============================================================================
+
+export interface ModelRegistry {
+  /** Get capabilities for a model */
+  getCapabilities(modelId: string): ProviderCapabilities | undefined;
+  
+  /** Get pricing for a model */
+  getPricing(modelId: string): ModelPricing | undefined;
+  
+  /** Get quirks for a model */
+  getQuirks(modelId: string): ProviderQuirks | undefined;
+  
+  /** Get full model definition */
+  getModel(modelId: string): ModelDefinition | undefined;
+  
+  /** Resolve alias to canonical model ID */
+  resolveModel(idOrAlias: string): string;
+  
+  /** List all models (optionally filtered) */
+  listModels(filter?: ModelFilter): ModelDefinition[];
+}
+
+export interface ModelFilter {
+  provider?: string;
+  supportsPrefill?: boolean;
+  supportsThinking?: boolean;
+  supportsImageGeneration?: boolean;
+  includeDeprecated?: boolean;
+}
+
+// ============================================================================
+// Provider Adapter Interface
+// ============================================================================
+
+export interface ProviderAdapter {
+  /** Provider name */
+  readonly name: string;
+  
+  /** Check if this adapter handles a model */
+  supportsModel(modelId: string): boolean;
+  
+  /** Make a completion request (non-streaming) */
+  complete(
+    request: ProviderRequest,
+    options?: ProviderRequestOptions
+  ): Promise<ProviderResponse>;
+  
+  /** Make a streaming request */
+  stream(
+    request: ProviderRequest,
+    callbacks: StreamCallbacks,
+    options?: ProviderRequestOptions
+  ): Promise<ProviderResponse>;
+}
+
+// Internal types used by adapters
+export interface ProviderRequest {
+  /** Raw messages in provider format */
+  messages: unknown[];
+  
+  /** System prompt - can be string or content blocks with cache_control */
+  system?: string | unknown[];
+  
+  /** Model ID */
+  model: string;
+  
+  /** Max tokens */
+  maxTokens: number;
+  
+  /** Temperature */
+  temperature?: number;
+  
+  /** Stop sequences */
+  stopSequences?: string[];
+  
+  /** Tools in provider format */
+  tools?: unknown[];
+  
+  /** Additional provider-specific params */
+  extra?: Record<string, unknown>;
+}
+
+export interface ProviderRequestOptions {
+  signal?: AbortSignal;
+  timeoutMs?: number;
+}
+
+export interface ProviderResponse {
+  /** Raw response content */
+  content: unknown;
+  
+  /** Stop reason in provider format */
+  stopReason: string;
+  
+  /** Which stop sequence triggered */
+  stopSequence?: string;
+  
+  /** Usage in provider format */
+  usage: {
+    inputTokens: number;
+    outputTokens: number;
+    cacheCreationTokens?: number;
+    cacheReadTokens?: number;
+  };
+  
+  /** Model that actually ran */
+  model: string;
+  
+  /** Raw response for debugging */
+  raw: unknown;
+}
+
+export interface StreamCallbacks {
+  onChunk: (chunk: string) => void;
+  onContentBlock?: (index: number, block: unknown) => void;
+}

package/src/types/request.ts

@@ -0,0 +1,131 @@
+/**
+ * Request types for membrane
+ */
+
+import type { NormalizedMessage } from './message.js';
+import type { ToolDefinition } from './tools.js';
+
+// ============================================================================
+// Generation Config
+// ============================================================================
+
+export interface GenerationConfig {
+  /** Model identifier */
+  model: string;
+  
+  /** Maximum tokens to generate */
+  maxTokens: number;
+  
+  /** Temperature (0-2) */
+  temperature?: number;
+  
+  /** Top P nucleus sampling */
+  topP?: number;
+  
+  /** Top K sampling (provider-specific) */
+  topK?: number;
+  
+  /** Presence penalty (provider-specific) */
+  presencePenalty?: number;
+  
+  /** Frequency penalty (provider-specific) */
+  frequencyPenalty?: number;
+  
+  /** Enable thinking/reasoning mode */
+  thinking?: {
+    enabled: boolean;
+    budgetTokens?: number;
+  };
+  
+  /** Image generation config (Gemini) */
+  imageGeneration?: {
+    enabled: boolean;
+    modalities: ('TEXT' | 'IMAGE')[];
+    aspectRatio?: '1:1' | '16:9' | '9:16' | '4:3' | '3:4';
+    imageSize?: 'SMALL' | 'MEDIUM' | 'LARGE';
+  };
+}
+
+// ============================================================================
+// Stop Sequence Config
+// ============================================================================
+
+export type StopSequenceStrategy = 
+  | 'none'              // Trust API stop sequences only
+  | 'post-facto'        // Disable API sequences, check in code
+  | 'resume-on-unclosed'; // Resume if stopped inside XML block
+
+export interface StopSequenceConfig {
+  /** Stop sequences to use */
+  sequences: string[];
+  
+  /** Strategy for handling false positives */
+  strategy?: StopSequenceStrategy;
+  
+  /** Max resumptions for 'resume-on-unclosed' strategy */
+  maxResumptions?: number;
+  
+  /** Additional sequences only checked post-facto (not sent to API) */
+  postFactoOnly?: string[];
+}
+
+// ============================================================================
+// Request Options
+// ============================================================================
+
+export interface RequestOptions {
+  /** Abort signal for cancellation */
+  signal?: AbortSignal;
+  
+  /** Request timeout in milliseconds */
+  timeoutMs?: number;
+  
+  /** Request ID for correlation */
+  requestId?: string;
+  
+  /** Tags for filtering/attribution */
+  tags?: Record<string, string>;
+}
+
+// ============================================================================
+// Tool Mode
+// ============================================================================
+
+export type ToolMode = 
+  | 'xml'     // XML injection in prefill mode (chatperx style)
+  | 'native'  // Native API tool support (Anthropic tool_use, OpenAI tool_calls)
+  | 'auto';   // Automatically choose based on provider/mode
+
+// ============================================================================
+// Normalized Request
+// ============================================================================
+
+export interface NormalizedRequest {
+  /** Conversation messages */
+  messages: NormalizedMessage[];
+  
+  /** System prompt */
+  system?: string;
+  
+  /** Generation configuration */
+  config: GenerationConfig;
+  
+  /** Tool definitions */
+  tools?: ToolDefinition[];
+  
+  /** Tool execution mode (default: 'auto') */
+  toolMode?: ToolMode;
+  
+  /** Stop sequence configuration */
+  stopSequences?: StopSequenceConfig | string[];
+  
+  /**
+   * Maximum participants to include in auto-generated stop sequences (prefill mode).
+   * Set to 0 to disable participant-based stop sequences (allows frags/quotes).
+   * If not specified, uses membrane config default (10).
+   */
+  maxParticipantsForStop?: number;
+  
+  /** Provider-specific parameters (pass-through) */
+  providerParams?: Record<string, unknown>;
+}