@nestjs-adk/openai
v2.0.1
Published
OpenAI model adapter for nestjs-adk: the official SDK with a configurable baseURL, covering every OpenAI compatible API.
Readme
@nestjs-adk/openai
The OpenAI chat completions API for nestjs-adk.
One model class, and it covers more than OpenAI. Anything that speaks the chat completions API answers here through baseURL: OpenRouter, Groq, Together, Ollama, vLLM, a gateway of your own.
npm i @nestjs-adk/core @nestjs-adk/openaiThe model
import { AdkModule, AdkModuleOptions } from "@nestjs-adk/core";
import { OpenAiModel } from "@nestjs-adk/openai";
const luna = new OpenAiModel("gpt-5.6-luna", {
apiKey: process.env.OPENAI_API_KEY,
maxOutputTokens: 512,
});
@Module({ imports: [AdkModule.forRoot(AdkModuleOptions.from({ defaultModel: luna }))] })
export class AppModule {}OpenAiModel is an LlmModel, so the same object goes anywhere a model goes: defaultModel, @Agent({ model }), a failover chain, or a compaction summarizer.
apiKey defaults to OPENAI_API_KEY. It takes a Secret or a plain string: whatever it is handed is wrapped at the option boundary and revealed once, at the call that builds the SDK client. The generation parameters are typed fields, so a typo fails to compile: temperature, topP, maxOutputTokens, stopSequences, frequencyPenalty, presencePenalty. organization, headers and timeoutMs cover the transport side, and headers is how some gateways route or attribute usage.
Anything this adapter does not model goes through body, and a typed field always wins over the same key inside it:
new OpenAiModel("gpt-5.6-luna", { apiKey, body: { reasoning_effort: "none" } });That escape hatch is what makes reasoning models usable without this package tracking each one's parameters.
Another provider, same class
new OpenAiModel("meta-llama/llama-4-70b", {
baseURL: "https://openrouter.ai/api/v1",
apiKey: process.env.OPENROUTER_API_KEY,
headers: { "HTTP-Referer": "https://nebula.games" },
});
new OpenAiModel("qwen3", { baseURL: "http://localhost:11434/v1", apiKey: "ollama" });A thinking model behind a compatible endpoint, DeepSeek among them, streams its reasoning ahead of a tool call and wants it back with the call on the next request of the turn. The adapter keeps it on the call and replays it as reasoning_content whenever baseURL is set; replaysReasoning overrides either way, and the official API never receives it.
Nothing else changes: tools, streaming, sessions, approvals and cost all work the same, because the runtime only ever sees an LlmModel.
What a compatible endpoint can see
capabilities says what the endpoint behind baseURL can do. Left out, the adapter assumes the official OpenAI API, which reads images and fetches them by URL. Groq, Together, OpenRouter, DeepSeek and Ollama all answer to "compatible with OpenAI", and some of them have no vision at all:
new OpenAiModel("llama-3.1-70b-versatile", {
baseURL: "https://api.groq.com/openai/v1",
apiKey: process.env.GROQ_API_KEY,
capabilities: { mediaInput: false },
});{ mediaInput: false } makes ModelService refuse the image before the session is opened, the same way it does for any model that never declared the capability, instead of paying for the request and having the provider refuse it. mediaUrl says whether the endpoint fetches an image by URL rather than needing the bytes inline.
The context window
The runtime measures compaction against the window the model declares. A gateway serving somebody else's weights cannot be asked, so tell the adapter when you know:
new OpenAiModel("qwen3", { baseURL, apiKey, contextWindowTokens: 128_000, reservedOutputTokens: 4_000 });Without contextWindowTokens the model reports an unknown window, which the core reports through its context notice sink rather than compacting on a number nobody verified.
Structured output
StrictSchemaValidator checks a JSON Schema against what OpenAI's strict mode accepts before a request is sent, and throws NonStrictJsonSchemaError naming what is wrong. A schema OpenAI would refuse is worth catching locally rather than paying a round trip to be told.
Failures, and how failover reads them
The adapter never lets a provider error reach the runtime. OpenAiFailureMapper turns each one into a ModelFailure the core declares, and that classification is what a failover policy decides on:
| What the provider answered | What the core sees |
| --- | --- |
| a context length code | ContextExceededFailure |
| a content filter code or type | SafetyBlockedFailure |
| 429 | RateLimitedFailure |
| 408, or a timeout code | TimeoutFailure |
| 5xx, or no status with a connection error | UnavailableFailure |
| any other 4xx | InvalidRequestFailure |
| anything it cannot place | UnknownFailure |
Only rate limits, timeouts and an unavailable provider answer isTransient. A refused request is the one failure a chain must not answer by trying the next model, since every model in the chain is sent the same thing, and SequentialFailoverPolicy stops on it. A 4xx that is none of the recognised cases is classified as a refused request rather than left unknown: left unknown it reads like the provider had a bad day, and a chain would pay for every model in it to be told the same thing.
Both of this package's own errors, InvalidJsonSchemaError and NonStrictJsonSchemaError, extend AdkError and carry a stable code. Each documents itself in its own JSDoc.
Your own transport
Every call goes through OpenAiTransport. SdkOpenAiTransport is the default and uses the official SDK; replace it to route through a proxy, to record traffic, or to test without a network:
const recorded = new OpenAiModel("gpt-5.6-luna", { apiKey }, new RecordingTransport());The mappers are exported for the same reason: OpenAiRequestMapper turns a core ModelRequest into OpenAiChatRequest, and OpenAiStreamMapper turns each OpenAiStreamChunk back into a ModelChunk. Use them when you are building something adjacent; you do not need any of them to use the model.
API reference
| Symbol | What it is for |
| --- | --- |
| OpenAiModel | The model. Construct it and hand it to the core |
| OpenAiOptions, OpenAiCapabilities | Everything it takes: key, baseURL, generation parameters, window, body, capabilities |
| OpenAiTransport, SdkOpenAiTransport | The one call this adapter makes, and the SDK implementation of it |
| OpenAiClientFactory, OpenAiChatClient | How the client is built and what the adapter needs from it |
| OpenAiRequestMapper, OpenAiChatRequest | A core request as the provider receives it |
| OpenAiStreamMapper, OpenAiStreamChunk | The provider's stream as core chunks |
| OpenAiFailureMapper | A provider error as a ModelFailure |
| StrictSchemaValidator | Refuses a schema OpenAI's strict mode would refuse, before sending it |
| InvalidJsonSchemaError, NonStrictJsonSchemaError | This package's own errors, both AdkError |
Learn more
The full project lives at github.com/gabrieljsilva/nestjs-adk.
