Model Contracts

Model configuration types and schemas for provider AI models

Overview

The model contracts define TypeScript types and Effect schemas for configuring AI models across different providers. Currently focused on Codex models with support for reasoning effort and performance modes.

Model Options

CodexModelOptions

Configuration options specific to Codex models.

reasoningEffort · 'xhigh' | 'high' | 'medium' | 'low'

Controls the reasoning effort level for the model. Higher values provide more thorough analysis at the cost of increased latency.

Available values:

• xhigh - Extra high reasoning effort
• high - High reasoning effort (default)
• medium - Medium reasoning effort
• low - Low reasoning effort

fastMode · boolean

Enables fast mode for quicker responses with reduced reasoning depth.

import { Schema } from "effect";

export const CodexModelOptions = Schema.Struct({
  reasoningEffort: Schema.optional(Schema.Literals(["xhigh", "high", "medium", "low"])),
  fastMode: Schema.optional(Schema.Boolean),
});
export type CodexModelOptions = typeof CodexModelOptions.Type;

ProviderModelOptions

Top-level model options supporting multiple providers.

codex · CodexModelOptions

Provider-specific options for Codex models.

export const ProviderModelOptions = Schema.Struct({
  codex: Schema.optional(CodexModelOptions),
});
export type ProviderModelOptions = typeof ProviderModelOptions.Type;

Model Slugs

Available Models

Built-in model options organized by provider:

export const MODEL_OPTIONS_BY_PROVIDER = {
  codex: [
    { slug: "gpt-5.4", name: "GPT-5.4" },
    { slug: "gpt-5.3-codex", name: "GPT-5.3 Codex" },
    { slug: "gpt-5.3-codex-spark", name: "GPT-5.3 Codex Spark" },
    { slug: "gpt-5.2-codex", name: "GPT-5.2 Codex" },
    { slug: "gpt-5.2", name: "GPT-5.2" },
  ],
} as const;

ModelSlug Type

Flexible type allowing both built-in and custom model slugs:

type BuiltInModelSlug = ModelOptionsByProvider[ProviderKind][number]["slug"];
export type ModelSlug = BuiltInModelSlug | (string & {});

The ModelSlug type accepts any string while providing autocomplete for built-in models in TypeScript-aware editors.

Default Configuration

Default Models

export const DEFAULT_MODEL_BY_PROVIDER = {
  codex: "gpt-5.4",
} as const;

Model Aliases

Convenience aliases for model slugs:

export const MODEL_SLUG_ALIASES_BY_PROVIDER = {
  codex: {
    "5.4": "gpt-5.4",
    "5.3": "gpt-5.3-codex",
    "gpt-5.3": "gpt-5.3-codex",
    "5.3-spark": "gpt-5.3-codex-spark",
    "gpt-5.3-spark": "gpt-5.3-codex-spark",
  },
} as const;

Reasoning Effort Options

export const REASONING_EFFORT_OPTIONS_BY_PROVIDER = {
  codex: ["xhigh", "high", "medium", "low"],
} as const;

export const DEFAULT_REASONING_EFFORT_BY_PROVIDER = {
  codex: "high",
} as const;

Usage Examples

Basic Model Configuration

import { CodexModelOptions, ModelSlug } from "@t3tools/contracts";

const modelConfig: CodexModelOptions = {
  reasoningEffort: "high",
  fastMode: false,
};

const modelSlug: ModelSlug = "gpt-5.4";

Provider Model Options

import { ProviderModelOptions } from "@t3tools/contracts";

const providerOptions: ProviderModelOptions = {
  codex: {
    reasoningEffort: "medium",
    fastMode: true,
  },
};

Using Model Aliases

import { MODEL_SLUG_ALIASES_BY_PROVIDER } from "@t3tools/contracts";

const alias = "5.3";
const actualSlug = MODEL_SLUG_ALIASES_BY_PROVIDER.codex[alias];
// actualSlug === "gpt-5.3-codex"

Type Definitions

CodexReasoningEffort

export const CODEX_REASONING_EFFORT_OPTIONS = ["xhigh", "high", "medium", "low"] as const;
export type CodexReasoningEffort = (typeof CODEX_REASONING_EFFORT_OPTIONS)[number];

ModelOptionsByProvider

export type ModelOptionsByProvider = typeof MODEL_OPTIONS_BY_PROVIDER;

Related Types

See also:

• Provider Types - Provider-level configuration
• Orchestration Schemas - Thread and turn management