Universal.Operative.Sdk.Discrete.OpenAI 3.2.0

Universal.Operative.Sdk.Discrete.OpenAI

About

Universal.Operative.Sdk.Discrete.OpenAI plugs OpenAI into Universal.Operative.Sdk by providing two IModel adapters backed by the Universal.OpenAI.Client transport:

• ChatCompletionsModel — targets the Chat Completions endpoint. Also the right choice for the wide ecosystem of OpenAI-compatible servers (Azure OpenAI, vLLM, llama.cpp, Groq, Together, OpenRouter, LM Studio, Ollama, …).
• ResponsesModel — targets the Responses API. Prefer this for first-class OpenAI-only features: reasoning round-trip, hosted tools (web search, file search, code interpreter, image generation, MCP), and structured output shapes Chat Completions can't express. It is stateless by default (store=false) — full history is sent on every turn.

Both adapters stream provider events and fold them into the SDK's provider-neutral StreamEvent sequence, so the rest of the harness (tool dispatch, transformers, event stream) is identical regardless of which one you pick.

Persisted conversations can move between providers. At request serialization, both adapters convert provider-hosted tool activity into bounded text context, omit unsupported provider-specific blocks, and remove unmatched historical tool calls/results that OpenAI cannot replay safely.

How to Use

Installation

dotnet add package Universal.Operative.Sdk.Discrete.OpenAI

Configuration

using Universal.Operative.Sdk;
using Universal.Operative.Sdk.Discrete.OpenAI;

// Chat Completions — also works against Azure OpenAI / vLLM / OpenRouter / etc.
// via the Universal.OpenAI.Client's base-URL configuration.
IModel model = new ChatCompletionsModel("sk-...", new ChatCompletionsModel.Options
{
    ModelId = "gpt-4.1",
    MaxCompletionTokens = 4096,
    Temperature = 0.7f,
});

// Responses API — needed for reasoning round-trip and hosted tools.
IModel reasoningModel = new ResponsesModel("sk-...", new ResponsesModel.Options
{
    ModelId = "gpt-5.4",
    ReasoningEffort = ReasoningEfforts.High,
    Include = new[] { "reasoning.encrypted_content" }, // round-trip reasoning across stateless turns
});

Both constructors also accept an existing Universal.OpenAI.Client.V1.V1Client in place of a raw API key, so you can reuse a client (custom HttpClient, base address, headers) across models.

Usage

Either model drops straight into EngineBuilder:

using Universal.Operative.Sdk.Tools.Coding;

IEngine engine = EngineBuilder.FromDefaults(model)
    .AddCodingToolSet(new CodingToolSet.Options { WorkingDirectory = workspace })
    .Build();

await foreach (EngineEvent e in engine.ExecuteAsync(conversation))
{
    // handle events as usual — see Universal.Operative.Sdk's Package.md
}

AddCodingToolSet works with every model adapter as normal function tools. ResponsesModel additionally maps shell and apply_patch to native wire contracts; update_plan remains a function tool.

ParallelToolCalls (both models) controls whether OpenAI may emit more than one tool call per turn. ReasoningEffort (both) accepts the constants on Universal.OpenAI.Client.V1.Responses.ReasoningEfforts ("minimal", "low", "medium", "high"). ResponsesModel additionally exposes Truncation and ServiceTier for endpoint-specific knobs.

Prompt caching

Both adapters leave OpenAI's automatic prompt caching enabled with their default options. Keep the system instructions, tool definitions, and earlier conversation turns stable to reuse a prefix. No model response is cached by the SDK.

Both models expose PromptCacheKey, PromptCacheKeySelector, PromptCacheRetention, PromptCacheOptions, PromptCacheSystemBreakpoint, and PromptCacheBreakpointSelector. A key selector can supply a stable, application-scoped key for each conversation; its non-null result overrides PromptCacheKey. Leave these options unset to use provider defaults. PromptCacheSystemBreakpoint places an explicit breakpoint at the end of the system content (in Responses, this moves the instructions into an initial developer input message). PromptCacheBreakpointSelector marks selected user content blocks, for example the end of a large, stable reference document before a changing question. Use breakpoints only with models that support them and a prefix long enough to cache. For GPT-5.6 and later, PromptCacheOptions can set Mode = "explicit" and Ttl = "30m"; explicit-only mode requires at least one eligible breakpoint in the request or caching is disabled. Earlier models use PromptCacheRetention where supported.

Provider usage details appear in Usage.Extensions["openai"] as cachedTokens and cacheWriteTokens when returned by the provider. A zero value is reported as zero, distinct from an absent field. Cache hits can reduce input processing cost and time to the first generated token; they do not cache a whole answer.

License

Free for noncommercial use under the Universal.Operative Noncommercial License. Source is closed; commercial use requires a separate license from Andrew Ong.