Documentation
¶
Overview ¶
Package adapterkit holds the helpers every first-party adapter needs but no vendor SDK touches: schema rendering, the terminal-error rule (with the context-overflow mapping and the marker table mw's retry classifier reads), and the FilePart exactly-one guard. They lived as byte-identical copies in all three adapters until the 2026-09-18 review flagged the drift risk; they move here rather than into the root's public API — THE-END-GOAL principle 3 names internal/ as the tool that keeps the guaranteed surface small, and Go's path-based internal rule lets github.com/weftgo/weft/{openai,anthropic,google} and weft/mw import the package while third-party adapters cannot. Helpers that mention an SDK type (the stream readers) stay per-adapter by design (ADR 0013).
Index ¶
- Constants
- func CaptureRaw(r *http.Request, next func(*http.Request) (*http.Response, error), ...) (*http.Response, error)
- func CloneHeaders(h http.Header) http.Header
- func CloneJSON(v any) any
- func Endpoint(baseURL, envValue, defaultHost string) string
- func FilePartSource(p core.FilePart) error
- func IsContextOverflow(err error) bool
- func MergeBody(body []byte, extra map[string]any) ([]byte, error)
- func NextCallID(used map[string]bool, ordinal int) string
- func RawTransport(base http.RoundTripper, sensitive []string) http.RoundTripper
- func SchemaMap(s *core.Schema) map[string]any
- func TerminalErr(ctx context.Context, err error) error
- func WireFacts(server string, body map[string]any, headers http.Header) (string, []string, []string)
Constants ¶
const RawCap = 256 << 10
RawCap is the most of one wire body the adapters keep for a raw record (ADR 0028 §12): 256 KiB, the core's own cap. What is past it is counted, never buffered.
Variables ¶
This section is empty.
Functions ¶
func CaptureRaw ¶ added in v0.14.0
func CaptureRaw(r *http.Request, next func(*http.Request) (*http.Response, error), sensitive []string) (*http.Response, error)
CaptureRaw sends r through next and, when the run's reporter wants raw records (core.Reporter.WantsRaw, asked before anything is buffered), reports the exchange as one core.RawPair: the request line, the headers minus sensitive (the adapter's SDK's own list — the core strips its floor again, case-insensitively) and the body; the status, headers and body of the response, the body teed as the caller reads it — a streamed response is the raw SSE bytes as received — and reported once, at its EOF, read error or Close. Each body is kept up to RawCap and the rest counted.
It is reporting, never behaviour: the request the next layer gets carries the same bytes, the response the caller reads is the same stream, and a capture that fails (the request body cannot be read) drops the pair with a Debug line and sends the request on with the read error where the original body would have surfaced it. One call per HTTP request: an SDK's own transport retries report one pair each.
func CloneHeaders ¶ added in v0.3.0
CloneHeaders copies h with each value slice cloned — ExtraHeaders' construction-time snapshot, the same isolation CloneJSON gives ExtraBody.
func CloneJSON ¶ added in v0.3.0
CloneJSON deep-copies a JSON-shaped value — the container shapes MergeBody recurses through (maps and slices), with everything else returned as is: scalars and structs are copied by their interface conversion already, and only the decoded-JSON shapes alias. The ExtraBody options snapshot the caller's map at construction with this, so a Model stays safe for concurrent runs while the caller keeps mutating what it passed (ADR 0013's Models-are-immutable stance).
func Endpoint ¶ added in v0.20.0
Endpoint is the server an adapter sends to: its BaseURL, else the SDK's environment variable env, else the provider's default host ("" when it has none to name).
func FilePartSource ¶
FilePartSource validates that a FilePart sets exactly one of Data and URL — the shape every provider's file input takes. Both or neither is a caller bug, refused wrapping ErrUnsupported before any request.
func IsContextOverflow ¶ added in v0.4.0
IsContextOverflow reports whether the error chain's text names a context-window overflow. The marker table lives in mw (the core module), where Retry's classifier reads it; the adapters delegate so the table exists once.
func MergeBody ¶ added in v0.3.0
MergeBody deep-merges extra into a JSON request body and returns the re-encoded bytes: nested maps merge recursively, every other value — scalars, arrays, null — replaces. The caller's key wins on conflict at every level; this is the one semantic all three adapters' ExtraBody options share, matching genai's native recursiveMapMerge (ADR 0013's 2026-09-22 amendment). A body that is not a JSON object fails, rather than being silently replaced.
func NextCallID ¶
NextCallID synthesises the id for a streamed tool call whose server omitted one: "call_<n>" with n starting at ordinal+1, skipping ids the step has already claimed and marking the chosen id in used. Skipping matters: a repeated id within one step fails the run with ErrModelContract — the exact failure the synthesis exists to prevent — when a server populates some ids of the step itself (llama.cpp-style) with the same call_<n> shape.
func RawTransport ¶ added in v0.14.0
func RawTransport(base http.RoundTripper, sensitive []string) http.RoundTripper
RawTransport wraps base (nil: http.DefaultTransport) so every request through it is captured as CaptureRaw does — for an SDK that offers no per-request middleware (google's genai, whose client takes an *http.Client).
func SchemaMap ¶
SchemaMap renders a core.Schema as the plain JSON map the vendors' tool-parameter fields expect (openai-go's FunctionParameters, anthropic-sdk-go's InputSchema). Nil stays nil: a schema-less tool takes the provider's default shape. The rendering goes through json.Marshal, which honours Schema.MarshalJSON — so a schema parsed with core.ParseSchema reaches the provider as its verbatim foreign bytes (enum, oneOf and all), where the hand-built map this replaced degraded them to the struct's own vocabulary. One rendering change rode along: an unconstrained node (a recursion cut, an interface field) marshalled as {"type": ""} before and is {} now (ADR 0003's 2026-09-19 amendment).
func TerminalErr ¶
TerminalErr reports a stream's terminal error the way the Model contract expects: ctx.Err() when the caller's context ended (the vendor SDKs wrap cancellation in their own error types, and the reader goroutine can exit its handshake with a nil SDK error); a context-window overflow wrapped in core.ErrContextOverflow when the provider's error names one (ADR 0020 §5 — the caller routes it to compaction, and mw.Retry never retries it); the error unchanged otherwise — so callers can errors.As the SDK's type.
func WireFacts ¶ added in v0.20.0
func WireFacts(server string, body map[string]any, headers http.Header) (string, []string, []string)
WireFacts is what the first-party adapters answer to the core's optional WireFacts convention (the request record's wire, UX-S2-09): the endpoint they send to, ExtraBody's top-level keys and ExtraHeaders' names — names only, never a value. server is "" when the adapter cannot know it (an injected client). The core sanitises and bounds what it is handed.
Types ¶
This section is empty.
Source Files