OpenAiLanguageModel

The OpenAiLanguageModel module adapts OpenAI-compatible chat completions providers to Effect AI's LanguageModel service. It builds a model service from a model id, translates prompts, files, tools, structured output schemas, and provider-specific options into OpenAiClient requests, and maps normal or streaming chat completion results back into Effect AI response content and metadata.

5 exports Added in v4.0.0 Source

Configuration

withConfigOverride

Added in v4.0.0 Source

Provides scoped config overrides for OpenAI-compatible language model operations.

When to use

Use to override request configuration for a single language model effect without changing the defaults supplied to model, make, or layer.

Details

Existing Config values from the Effect context are merged with overrides, and the override values take precedence.

See

Config for the configuration shape

Signature

declare const withConfigOverride: {
  (
    overrides: {
      readonly background?: boolean | null;
      readonly conversation?: string | null;
      readonly fileIdPrefixes?: ReadonlyArray<string>;
      readonly include?: ReadonlyArray<IncludeEnum> | null;
      readonly instructions?: string | null;
      readonly max_output_tokens?: number | null;
      readonly max_tool_calls?: number | null;
      readonly metadata?: Readonly<Record<string, string>> | null;
      readonly modalities?: ReadonlyArray<"text" | "audio">;
      readonly model?: string;
      readonly parallel_tool_calls?: boolean | null;
      readonly previous_response_id?: string | null;
      readonly prompt_cache_key?: string | null;
      readonly prompt_cache_retention?: "in-memory" | "24h" | null;
      readonly reasoning?: unknown;
      readonly safety_identifier?: string | null;
      readonly seed?: number;
      readonly service_tier?: string;
      readonly store?: boolean | null;
      readonly strictJsonSchema?: boolean;
      readonly temperature?: number | null;
      readonly text?: {
        readonly verbosity?: "low" | "medium" | "high";
      };
      readonly top_logprobs?: number;
      readonly top_p?: number | null;
      readonly truncation?: "auto" | "disabled" | null;
      readonly user?: string | null;
    } & {
      [x: string]: unknown;
    },
  ): <A, E, R>(self: Effect<A, E, R>) => Effect<A, E, Exclude<R, Config>>;
  <A, E, R>(
    self: Effect<A, E, R>,
    overrides: {
      readonly background?: boolean | null;
      readonly conversation?: string | null;
      readonly fileIdPrefixes?: ReadonlyArray<string>;
      readonly include?: ReadonlyArray<IncludeEnum> | null;
      readonly instructions?: string | null;
      readonly max_output_tokens?: number | null;
      readonly max_tool_calls?: number | null;
      readonly metadata?: Readonly<Record<string, string>> | null;
      readonly modalities?: ReadonlyArray<"text" | "audio">;
      readonly model?: string;
      readonly parallel_tool_calls?: boolean | null;
      readonly previous_response_id?: string | null;
      readonly prompt_cache_key?: string | null;
      readonly prompt_cache_retention?: "in-memory" | "24h" | null;
      readonly reasoning?: unknown;
      readonly safety_identifier?: string | null;
      readonly seed?: number;
      readonly service_tier?: string;
      readonly store?: boolean | null;
      readonly strictJsonSchema?: boolean;
      readonly temperature?: number | null;
      readonly text?: {
        readonly verbosity?: "low" | "medium" | "high";
      };
      readonly top_logprobs?: number;
      readonly top_p?: number | null;
      readonly truncation?: "auto" | "disabled" | null;
      readonly user?: string | null;
    } & {
      [x: string]: unknown;
    },
  ): Effect<A, E, Exclude<R, Config>>;
};

Constructors

make

Added in v4.0.0 Source

Creates an OpenAI-compatible LanguageModel service from a model identifier and optional request defaults.

When to use

Use to construct an OpenAI-compatible chat-completions language model service backed by OpenAiClient.

Details

The returned effect requires OpenAiClient. Request defaults from the config option are merged with any Config service in the context, with context values taking precedence. The service supports both generateText and streamText.

See

layer for providing the service as a Layer
model for creating a model descriptor for AiModel.provide

Signature

declare const make: (
  ...args: [
    {
      readonly config?: ModelConfig;
      readonly model: string;
    },
  ]
) => Effect<Service, never, OpenAiClient>;

model

Added in v4.0.0 Source

Creates an OpenAI-compatible model descriptor that can be provided with Effect.provide.

When to use

Use when you want an OpenAI-compatible language model value that carries provider and model metadata and can be supplied directly to an Effect program.

See

layer for creating a LanguageModel.LanguageModel layer directly
make for constructing the language model service effectfully

Signature

declare function model(
  model: string,
  config?: ModelConfig,
): Model<"openai", LanguageModel, OpenAiClient>;

Layers

layer

Added in v4.0.0 Source

Creates a layer for the OpenAI-compatible language model.

When to use

Use when composing application layers and you want OpenAI-compatible APIs to satisfy LanguageModel.LanguageModel while supplying OpenAiClient from another layer.

See

make for constructing the language model service effectfully
model for creating an AI model descriptor

Signature

declare function layer(options: {
  readonly config?: ModelConfig;
  readonly model: string;
}): Layer<LanguageModel, never, OpenAiClient>;

Services

Config

Added in v4.0.0 Source

Context service for OpenAI language model configuration.

When to use

Use as the context service for OpenAI-compatible language model request configuration, especially when a scoped operation should override the defaults supplied to model, make, or layer.

See

withConfigOverride for scoping language model request overrides

Signature

declare class Config extends Shape<"@effect/ai-openai-compat/OpenAiLanguageModel/Config", {
  readonly background?: boolean | null;
  readonly conversation?: string | null;
  readonly fileIdPrefixes?: readonly Array<string>;
  readonly include?: readonly Array<IncludeEnum> | null;
  readonly instructions?: string | null;
  readonly max_output_tokens?: number | null;
  readonly max_tool_calls?: number | null;
  readonly metadata?: Readonly<Record<string, string>> | null;
  readonly modalities?: readonly Array<"text" | "audio">;
  readonly model?: string;
  readonly parallel_tool_calls?: boolean | null;
  readonly previous_response_id?: string | null;
  readonly prompt_cache_key?: string | null;
  readonly prompt_cache_retention?: "in-memory" | "24h" | null;
  readonly reasoning?: unknown;
  readonly safety_identifier?: string | null;
  readonly seed?: number;
  readonly service_tier?: string;
  readonly store?: boolean | null;
  readonly strictJsonSchema?: boolean;
  readonly temperature?: number | null;
  readonly text?: {
    readonly verbosity?: "low" | "medium" | "high";
  };
  readonly top_logprobs?: number;
  readonly top_p?: number | null;
  readonly truncation?: "auto" | "disabled" | null;
  readonly user?: string | null;
} & {
  [x: string]: unknown;
}, this> {
  constructor(_: never);
}