providers

Core Providers Module Rules

Module Overview

The core providers module contains concrete implementations of AI provider integrations (Anthropic, OpenAI, Google, etc.) that implement the provider interfaces defined in the provider package.

Provider Implementation Rules

1. Provider Structure

• ALWAYS create a dedicated directory for each provider: core/providers/{provider-name}/
• ALWAYS implement the ProviderV1 interface from @adaline/provider
• ALWAYS use the naming pattern: Provider{ProviderName} (e.g., Anthropic, OpenAI)
• ALWAYS export the provider class as the default export
• ALWAYS include proper TypeScript generics for configuration types

2. Provider Class Implementation

• ALWAYS implement readonly version = "v1" as const
• ALWAYS implement readonly name = "{ProviderName}"
• ALWAYS use static constants for base URLs and endpoints
• ALWAYS implement private model factories for both chat and embedding models
• ALWAYS use proper type constraints for model factories

3. Model Factory Pattern

• ALWAYS create a private chatModelFactories record mapping model names to factories
• ALWAYS create a private embeddingModelFactories record mapping model names to factories
• ALWAYS each factory should include: model class, options schema, and model schema
• ALWAYS use the pattern:

private readonly chatModelFactories: Record<string, {
  model: { new (options: any): ChatModelV1 };
  modelOptions: z.ZodType<any>;
  modelSchema: ChatModelSchemaType;
}> = {
  [ModelLiteral]: {
    model: ModelClass,
    modelOptions: ModelOptionsSchema,
    modelSchema: ModelSchema,
  },
};

Model Implementation Rules

1. Chat Model Implementation

• ALWAYS extend or implement the appropriate base chat model class
• ALWAYS implement all required methods from ChatModelV1
• ALWAYS provide proper model schemas with capabilities and limits
• ALWAYS implement provider-specific API integration methods
• ALWAYS handle provider-specific response formats and errors