nimgent/providers/openai

This page is generated from the module’s exported API and ## documentation comments.

OpenAI-family HTTP provider.

Native OpenAI uses the Responses API (store: false, reasoning replay). OpenRouter, Hyper, Mistral, OpenCode’s Chat protocol, and any */chat/completions URL use Chat Completions. Provider wire fields such as session_id, cache_control, and HTTP-Referer stay optional on this type.

Constants

defaultOpenAiEndpoint

Default OpenAI Responses endpoint.

defaultOpenAiEndpoint = "https://api.openai.com/v1/responses"

defaultOpenAiChatEndpoint

Default OpenAI Chat Completions endpoint.

defaultOpenAiChatEndpoint = "https://api.openai.com/v1/chat/completions"

defaultOpenRouterEndpoint

Default OpenRouter endpoint.

defaultOpenRouterEndpoint = "https://openrouter.ai/api/v1/chat/completions"

defaultHyperEndpoint

Default Hyper endpoint.

defaultHyperEndpoint = "https://hyper.charm.land/v1/chat/completions"

defaultMistralEndpoint

Default Mistral endpoint.

defaultMistralEndpoint = "https://api.mistral.ai/v1/chat/completions"

defaultOpenCodeEndpoint

Default OpenCode endpoint.

defaultOpenCodeEndpoint = "https://opencode.ai/zen/go/v1/chat/completions"

defaultOpenCodeZenEndpoint

Default OpenCode Zen endpoint.

defaultOpenCodeZenEndpoint = "https://opencode.ai/zen/v1/chat/completions"

Procedures

gatewayBase

The gateway root the protocol paths hang off, or “” when url is not a recognized endpoint. https://host/v1/chat/completions → https://host/v1, which is also where Gemini’s /models/<id>:generateContent lives.

proc gatewayBase(url: string): string {.raises: [], tags: [], forbids: [].}

Returns: string.

Arguments

Name	Type	Default
`url`	`string`

siblingEndpoint

A gateway endpoint’s sibling path, or “” when no known path is present.

proc siblingEndpoint(url, sibling: string): string {.raises: [], tags: [],
    forbids: [].}

Returns: string.

Arguments

Name	Type	Default
`url`	`string`
`sibling`	`string`

openAI

Responses API by default. A */chat/completions URL stays on that wire format.

proc openAI(apiKey: string; endpoint = ""; timeoutSeconds = 300; userAgent = ""): OpenAIProvider {.
    raises: [], tags: [], forbids: [].}

Returns: OpenAIProvider.

Arguments

Name	Type	Default
`apiKey`	`string`
`endpoint`	`inferred`	`""`
`timeoutSeconds`	`inferred`	`300`
`userAgent`	`inferred`	`""`

openRouter

Create an OpenRouter provider.

proc openRouter(apiKey: string; endpoint = ""; timeoutSeconds = 300;
                siteUrl = ""; siteName = ""; userAgent = ""): OpenRouterProvider {.
    raises: [], tags: [], forbids: [].}

Returns: OpenRouterProvider.

Arguments

Name	Type	Default
`apiKey`	`string`
`endpoint`	`inferred`	`""`
`timeoutSeconds`	`inferred`	`300`
`siteUrl`	`inferred`	`""`
`siteName`	`inferred`	`""`
`userAgent`	`inferred`	`""`

hyper

Hyper’s documented agent API is Chat Completions. Their /v1/responses pass-through 400s OpenAI input items, so this stays on chat.

proc hyper(apiKey: string; endpoint = ""; timeoutSeconds = 300; userAgent = ""): HyperProvider {.
    raises: [], tags: [], forbids: [].}

Returns: HyperProvider.

Arguments

Name	Type	Default
`apiKey`	`string`
`endpoint`	`inferred`	`""`
`timeoutSeconds`	`inferred`	`300`
`userAgent`	`inferred`	`""`

openCodeChat

Create an OpenCode provider using Chat Completions.

proc openCodeChat(apiKey: string; endpoint = ""; timeoutSeconds = 300;
                  userAgent = "nimgent"): OpenCodeProvider {.raises: [],
    tags: [], forbids: [].}

Returns: OpenCodeProvider.

Arguments

Name	Type	Default
`apiKey`	`string`
`endpoint`	`inferred`	`""`
`timeoutSeconds`	`inferred`	`300`
`userAgent`	`inferred`	`"nimgent"`

openCodeResponses

Create an OpenCode provider using the Responses API.

proc openCodeResponses(apiKey: string; endpoint = ""; timeoutSeconds = 300;
                       userAgent = "nimgent"): OpenCodeProvider {.raises: [],
    tags: [], forbids: [].}

Returns: OpenCodeProvider.

Arguments

Name	Type	Default
`apiKey`	`string`
`endpoint`	`inferred`	`""`
`timeoutSeconds`	`inferred`	`300`
`userAgent`	`inferred`	`"nimgent"`

openCodeMessages

Create an OpenCode provider using the Anthropic Messages API.

proc openCodeMessages(apiKey: string; endpoint = ""; timeoutSeconds = 300;
                      userAgent = "nimgent"): AnthropicProvider {.raises: [],
    tags: [], forbids: [].}

Returns: AnthropicProvider.

Arguments

Name	Type	Default
`apiKey`	`string`
`endpoint`	`inferred`	`""`
`timeoutSeconds`	`inferred`	`300`
`userAgent`	`inferred`	`"nimgent"`

openCodeGoogle

The gateway’s Gemini models on the native Google surface: the same key and gateway root, /models/<id>:generateContent instead of an OpenAI path.

proc openCodeGoogle(apiKey: string; endpoint = ""; timeoutSeconds = 300;
                    userAgent = "nimgent"): GoogleProvider {.raises: [],
    tags: [], forbids: [].}

Returns: GoogleProvider.

Arguments

Name	Type	Default
`apiKey`	`string`
`endpoint`	`inferred`	`""`
`timeoutSeconds`	`inferred`	`300`
`userAgent`	`inferred`	`"nimgent"`

openCode

OpenCode’s gateways expose separate wire protocols. nimgent keeps that choice explicit; Nimlet may add catalog-aware routing above these adapters.

proc openCode(apiKey: string; endpoint = ""; timeoutSeconds = 300;
              userAgent = "nimgent"; protocol = ocChat): Provider {.
    raises: [ProviderError], tags: [], forbids: [].}

Returns: Provider.

Arguments

Name	Type	Default
`apiKey`	`string`
`endpoint`	`inferred`	`""`
`timeoutSeconds`	`inferred`	`300`
`userAgent`	`inferred`	`"nimgent"`
`protocol`	`inferred`	`ocChat`

openCodeZen

OpenCode Zen’s full catalog: the same protocols as the Go subscription, on the plain /zen/v1 gateway.

proc openCodeZen(apiKey: string; endpoint = ""; timeoutSeconds = 300;
                 userAgent = "nimgent"; protocol = ocChat): Provider {.
    raises: [ProviderError], tags: [], forbids: [].}

Returns: Provider.

Arguments

Name	Type	Default
`apiKey`	`string`
`endpoint`	`inferred`	`""`
`timeoutSeconds`	`inferred`	`300`
`userAgent`	`inferred`	`"nimgent"`
`protocol`	`inferred`	`ocChat`

mistral

Create a Mistral provider.

proc mistral(apiKey: string; endpoint = ""; timeoutSeconds = 300; userAgent = ""): MistralProvider {.
    raises: [], tags: [], forbids: [].}

Returns: MistralProvider.

Arguments

Name	Type	Default
`apiKey`	`string`
`endpoint`	`inferred`	`""`
`timeoutSeconds`	`inferred`	`300`
`userAgent`	`inferred`	`""`

endpointFor

Endpoint this model goes to. A per-model route wins over endpoint.

proc endpointFor(provider: OpenAIProvider; model: string): string {.
    raises: [Exception], tags: [RootEffect], forbids: [].}

Returns: string.

Arguments

Name	Type	Default
`provider`	`OpenAIProvider`
`model`	`string`

usesResponsesFor

Whether this model speaks the Responses wire format on that endpoint.

proc usesResponsesFor(provider: OpenAIProvider; model: string): bool {.
    raises: [Exception], tags: [RootEffect], forbids: [].}

Returns: bool.

Arguments

Name	Type	Default
`provider`	`OpenAIProvider`
`model`	`string`

toProviderJson

Serialize OpenAI-specific request options.

proc toProviderJson(value: OpenAIOptions): JsonNode {.raises: [], tags: [],
    forbids: [].}

Returns: JsonNode.

Arguments

Name	Type	Default
`value`	`OpenAIOptions`

Types

OpenAiRoute

Select an endpoint for a model.

OpenAiRoute = proc (model: string): string {.closure.}

OpenCodeProtocol

Wire protocol used by an OpenCode gateway.

OpenCodeProtocol = enum
  ocChat, ocResponses, ocMessages, ocGoogle

OpenAIProvider

OpenAI-compatible HTTP provider configuration.

OpenAIProvider = ref object of Provider
  apiKey*: string
  endpoint*: string
  timeoutSeconds*: int
  siteUrl*: string
  siteName*: string          ## OpenRouter continuation hint; omitted for native OpenAI.
  includeConversationId*: bool ## Anthropic-style cache breakpoints; OpenAI caches stable prefixes itself.
  applyCache*: bool          ## Mistral prompt caching key derived from the request session ID.
  promptCacheKey*: bool      ## "max_tokens" (OpenRouter/Mistral) or "max_completion_tokens" (Chat Completions).
  maxTokensField*: string
  displayName*: string       ## True: POST /v1/responses. False: Chat Completions (OpenRouter / compat).
  useResponses*: bool
  embeddingsEndpoint*: string ## Header carrying a stable conversation id. Empty: the id stays in the body
                              ## (`includeConversationId`) or is not sent. OpenCode Zen wants `x-opencode-session`.
  sessionHeader*: string     ## Gateway-facing client identity; empty keeps the HTTP library default.
  userAgent*: string         ## Models this gateway only serves on another surface.
  route*: OpenAiRoute        ## Replayed-thinking flavor of this gateway's Chat Completions wire.
  chatReasoning*: ChatReasoning

OpenRouterProvider

OpenRouter provider configuration.

OpenRouterProvider = OpenAIProvider

HyperProvider

Hyper provider configuration.

HyperProvider = OpenAIProvider

MistralProvider

Mistral provider configuration.

MistralProvider = OpenAIProvider

OpenCodeProvider

OpenCode provider configuration.

OpenCodeProvider = OpenAIProvider

OpenAIOptions

Optional OpenAI-specific request settings.

OpenAIOptions = object
  parallelToolCalls*: Option[bool]
  store*: Option[bool]
  user*: Option[string]
  dimensions*: Option[int]   ## Embedding requests only.

Methods

nativeObjectOptions

Return native structured-output options for the model’s wire format.

method nativeObjectOptions(provider: OpenAIProvider;
                           model, name, description: string; schema: JsonNode): JsonNode {.
    raises: [Exception], tags: [RootEffect], forbids: [].}

Returns: JsonNode.

Arguments

Name	Type	Default
`provider`	`OpenAIProvider`
`model`	`string`
`name`	`string`
`description`	`string`
`schema`	`JsonNode`

nativeObjectSchemaIssues

Return schema issues for the model’s native structured-output format.

method nativeObjectSchemaIssues(provider: OpenAIProvider; model: string;
                                schema: JsonNode): seq[string] {.
    raises: [KeyError], tags: [], forbids: [].}

Returns: seq[string].

Arguments

Name	Type	Default
`provider`	`OpenAIProvider`
`model`	`string`
`schema`	`JsonNode`

generateAsync

Send a generation request through an OpenAI-compatible endpoint.

method generateAsync(provider: OpenAIProvider; request: ProviderRequest): Future[
    ProviderResponse] {.stackTrace: false, raises: [Exception, ValueError,
    ProviderError, KeyError, LibraryError, SslError, IOError], tags: [
    RootEffect, ReadIOEffect, WriteIOEffect, ReadDirEffect, ReadEnvEffect,
    TimeEffect], forbids: [].}

Returns: Future[ProviderResponse].

Arguments

Name	Type	Default
`provider`	`OpenAIProvider`
`request`	`ProviderRequest`

embedAsync

Send an embedding request through an OpenAI-compatible endpoint.

method embedAsync(provider: OpenAIProvider; request: EmbeddingRequest): Future[
    EmbeddingResponse] {.stackTrace: false, raises: [Exception, ValueError,
    ProviderError, LibraryError, SslError, IOError, KeyError], tags: [
    RootEffect, ReadDirEffect, ReadEnvEffect, TimeEffect, ReadIOEffect,
    WriteIOEffect], forbids: [].}

Returns: Future[EmbeddingResponse].

Arguments

Name	Type	Default
`provider`	`OpenAIProvider`
`request`	`EmbeddingRequest`

generateStreamAsync

Stream a generation request through an OpenAI-compatible endpoint.

method generateStreamAsync(provider: OpenAIProvider; request: ProviderRequest;
                           onEvent: StreamCallback): Future[ProviderResponse] {.
    stackTrace: false, raises: [Exception, ValueError, ProviderError,
                                LibraryError, SslError, IOError, KeyError,
                                OSError], tags: [RootEffect, ReadDirEffect,
    ReadEnvEffect, ReadIOEffect, WriteIOEffect, TimeEffect], forbids: [].}

Returns: Future[ProviderResponse].

Arguments

Name	Type	Default
`provider`	`OpenAIProvider`
`request`	`ProviderRequest`
`onEvent`	`StreamCallback`