Documentation
¶
Overview ¶
Package openai is the weft adapter for the OpenAI Chat Completions API and OpenAI-compatible servers (gateways, local models), wrapping the official openai-go SDK. weft never owns the HTTP: every request goes through the SDK's client, and the SDK's stream type is the contract.
Mapping highlights (ADR 0013 has the full tables):
- Text deltas pass through as ModelTextDelta; tool-call argument fragments also surface live as ModelToolCallDelta progress while the assembled call is buffered by delta index and emitted whole as a ModelToolCall before ModelFinish — the core's uniform-streaming rent.
- Stop reasons map to weft's three; anything unmapped keeps its raw value on ModelFinish.Raw.
- A RoleTool message fans out to one OpenAI tool message per result; assistant ReasoningParts are dropped (Chat Completions has no reasoning input).
- SequentialTools sets parallel_tool_calls: false.
- ModelRequest.Thinking maps by dialect: reasoning_effort for the official API and unrecognized hosts; a thinking object injected into the request body (per-request SDK middleware) for the known gateway hosts — z.ai, bigmodel.cn, moonshot.ai/cn — whose param the typed params cannot carry. Dialect(...) overrides detection; Off has no effort form and sends nothing there (ADR 0013 amendment 9 has the full table).
Retry stance: transport retries (429, 5xx, net.Error) belong to the SDK via MaxRetries; the weft loop never retries a model call, and logic retries are model-seam middleware.
The Responses API (reasoning items, built-in tools) is not wrapped here; it would be an openai/responses sub-package.
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Model ¶
Model returns a weft.Model backed by the OpenAI Chat Completions API (or any compatible server, via BaseURL). A Model is immutable and safe for concurrent runs.
Example ¶
Constructing a model performs no I/O; a key ($OPENAI_API_KEY) is read only when a run starts. Swap providers by swapping this one line.
package main
import (
"context"
"github.com/weftgo/weft"
"github.com/weftgo/weft/openai"
)
func main() {
m := openai.Model("gpt-4o-mini")
echo := weft.Tool("echo", "Echo a message.", func(ctx context.Context, in struct {
Message string `json:"message" jsonschema:"the text to repeat"`
}) (string, error) {
return in.Message, nil
})
agt := weft.New(m, echo)
_ = agt // a run is agt.Generate(ctx, weft.Prompt("Echo: hello"))
}
Output:
Types ¶
type Option ¶
type Option interface {
// contains filtered or unexported methods
}
Option configures the adapter at construction, the same functional style as the core. The zero configuration reads $OPENAI_API_KEY (and $OPENAI_BASE_URL); the SDK's transport default applies (2 retries on 429/5xx/connection errors).
func BaseURL ¶
BaseURL points the adapter at an OpenAI-compatible server — gateways, local models. Also read from $OPENAI_BASE_URL when the option is not given. The provider name stays "openai": a base URL host is not a provider identity and would leak into telemetry cardinality.
func Client ¶
Client uses an already-configured SDK client (Azure endpoints, custom transports, test doubles); it overrides BaseURL, APIKey, and MaxRetries. The WEFT_MODEL_REQUESTS kill switch guards egress from clients the adapter builds from credentials; an injected client's destinations are the caller's responsibility — which is why it stays reachable under deny (ADR 0013's kill-switch clause).
func Dialect ¶ added in v0.2.0
func Dialect(d ThinkingDialect) Option
Dialect pins the thinking wire form instead of detecting it from the base URL. It matters for custom gateways behind hosts the adapter does not recognize and for clients whose endpoint it cannot inspect.
Example ¶
The thinking wire form is detected from the base URL (reasoning_effort for the official API and unrecognized hosts, a thinking object for the known gateways); Dialect pins it when detection can't know — a custom gateway behind an unrecognized host, or a client whose endpoint the adapter cannot inspect.
package main
import (
"github.com/weftgo/weft/openai"
)
func main() {
m := openai.Model("kimi-k2.7",
openai.BaseURL("https://gw.internal/v1"),
openai.Dialect(openai.DialectObject))
_ = m // runs now send thinking:{"type":...} per weft.Thinking
}
Output:
func IdleTimeout ¶
IdleTimeout is the maximum gap between two stream chunks before the call fails wrapping weft.ErrStreamIdle (default 60s; zero disables it). The ctx deadline stays the hard limit on the whole call — a slow but actively streaming response is never killed.
func MaxRetries ¶
MaxRetries forwards to the SDK's transport retry configuration (429/5xx/connection errors only). Only n > 0 is forwarded: the SDK's own default (2) applies otherwise, and 0 cannot disable it — keep a zero-retry client via Client(c) if you need one. The weft loop never retries a model call; logic retries are model-seam middleware (TODO §4.1).
func MaxTokens ¶
MaxTokens caps a step's output tokens (max_completion_tokens). Zero keeps the provider default.
func Temperature ¶
Temperature sets the sampling temperature; it is not sent unless the option is given.
type ThinkingDialect ¶ added in v0.2.0
type ThinkingDialect int
ThinkingDialect selects how weft's ThinkingConfig reaches an OpenAI-compatible server: the official API takes reasoning_effort, while gateways such as z.ai and Moonshot take a thinking object the SDK's typed params have no field for. DialectAuto (the default) detects from the base URL; the explicit dialects override detection.
const ( DialectAuto ThinkingDialect = iota // DialectEffort sends reasoning_effort ("low"|"medium"|"high") — // the official Chat Completions knob. DialectEffort // DialectObject injects thinking:{"type":"enabled"|"disabled"} // into the request body — the z.ai and Moonshot shape. DialectObject // DialectNone never sends thinking parameters, for strict // compatible servers that reject unknown fields. DialectNone )
Source Files
Directories