Implementation:Helicone Helicone BaseProvider

Knowledge Sources	Helicone
Domains	LLM Gateway, Provider Abstraction, TypeScript
Last Updated	2026-02-14 00:00 GMT

Overview

Concrete abstract base class for defining LLM provider integrations provided by the packages/cost/models/providers/base.ts module.

Description

BaseProvider is the abstract TypeScript class that every LLM provider in the Helicone gateway must extend. It declares abstract properties for the provider's display name, base URL, authentication type, and documentation links, as well as an abstract buildUrl method. It also provides default implementations for authenticate (Bearer token), buildRequestBody (JSON stringify with model ID injection), and buildErrorMessage (standard error extraction from JSON response). Subclasses override any method where the provider's API deviates from the default behavior.

The class is designed to be stateless -- all methods are pure functions of their arguments with no internal mutation. This makes provider instances safe to share as singletons across the entire application.

Usage

Use this class as the base when implementing a new provider for the Helicone AI gateway. Extend it, fill in the abstract properties, override buildUrl, and optionally override authenticate, buildRequestBody, or buildErrorMessage if the provider requires non-standard behavior.

Code Reference

Source Location

• Repository: Helicone
• File: packages/cost/models/providers/base.ts (lines 17-83)

Signature

export abstract class BaseProvider {
  abstract readonly displayName: string;
  abstract readonly baseUrl: string;
  abstract readonly auth: "api-key" | "oauth" | "aws-signature" | "service_account";
  abstract readonly pricingPages: string[];
  abstract readonly modelPages: string[];

  readonly supportedPlugins: PluginId[] = [];
  readonly requiredConfig?: ReadonlyArray<keyof UserEndpointConfig>;

  abstract buildUrl(endpoint: Endpoint, requestParams: RequestParams): string;

  buildModelId(
    modelProviderConfig: ModelProviderConfig,
    userEndpointConfig: UserEndpointConfig
  ): string;

  authenticate(
    authContext: AuthContext,
    endpoint: Endpoint,
    cacheProvider?: CacheProvider
  ): AuthResult | Promise<AuthResult>;

  buildRequestBody(
    endpoint: Endpoint,
    context: RequestBodyContext
  ): string | Promise<string>;

  async buildErrorMessage(response: Response): Promise<{
    message: string;
    details?: any;
  }>;
}

Import

import { BaseProvider } from "packages/cost/models/providers/base";
// or via the barrel export:
import { BaseProvider } from "packages/cost/models/providers";

I/O Contract

Inputs

Name	Type	Required	Description
endpoint	Endpoint	Yes	Resolved endpoint configuration containing provider model ID, pricing, context length, and user config
requestParams	RequestParams	Yes (buildUrl)	Request-level parameters including streaming flag and body mapping type
authContext	AuthContext	Yes (authenticate)	Credentials and request metadata for authentication header construction
context	RequestBodyContext	Yes (buildRequestBody)	Parsed request body plus format conversion utilities (toAnthropic, toChatCompletions)
response	Response	Yes (buildErrorMessage)	The HTTP response object from the provider to extract error messages from

Outputs

Name	Type	Description
buildUrl return	string	The fully qualified URL to send the proxied request to
authenticate return	Promise<AuthResult>	Object containing headers to attach to the outbound request
buildRequestBody return	Promise<string>	JSON-serialized request body in the provider's expected format
buildErrorMessage return	Promise<{ message: string; details?: any }>	Standardized error message extracted from the provider's error response

Usage Examples

Basic Usage

import { BaseProvider } from "packages/cost/models/providers/base";
import type {
  Endpoint,
  RequestParams,
  AuthContext,
  AuthResult,
  RequestBodyContext,
  PluginId,
} from "packages/cost/models/types";

export class AnthropicProvider extends BaseProvider {
  readonly displayName = "Anthropic";
  readonly baseUrl = "https://api.anthropic.com";
  readonly auth = "api-key" as const;
  readonly supportedPlugins: PluginId[] = ["web"];
  readonly pricingPages = [
    "https://docs.anthropic.com/en/docs/build-with-claude/pricing",
  ];
  readonly modelPages = [
    "https://docs.anthropic.com/en/docs/about-claude/models/all-models",
  ];

  buildUrl(endpoint: Endpoint, requestParams: RequestParams): string {
    return "https://api.anthropic.com/v1/messages";
  }

  authenticate(authContext: AuthContext, endpoint: Endpoint): AuthResult {
    const headers: Record<string, string> = {};
    headers["x-api-key"] = authContext.apiKey || "";
    headers["anthropic-version"] = "2023-06-01";
    return { headers };
  }

  buildRequestBody(endpoint: Endpoint, context: RequestBodyContext): string {
    let updatedBody = context.parsedBody;
    if (context.bodyMapping === "RESPONSES") {
      updatedBody = context.toChatCompletions(updatedBody);
    }
    const anthropicBody = context.toAnthropic(
      updatedBody,
      endpoint.providerModelId
    );
    return JSON.stringify(anthropicBody);
  }
}

Related Pages

Implements Principle

• Principle:Helicone_Helicone_Provider_Definition