openai

actor/openai

An actor.Provider for any OpenAI-compatible /chat/completions server: Ollama, LM Studio, OpenRouter, vLLM, or OpenAI itself. See ../anthropic/README.md for the sibling provider this package deliberately mirrors, and ../provider.go for the actor.Provider interface both implement.

This package exists for the local-development story: point a campaign at a model already running on your laptop — no API key, no cost, no network call beyond localhost. See spec/ideas/openai-compatible-provider.md.

Quick start

import "chatwright.dev/runtime/actor/openai"

// Ollama
provider, err := openai.New(openai.Config{
    BaseURL: "http://localhost:11434/v1",
    Model:   "qwen3.6:latest",
})

// LM Studio
provider, err := openai.New(openai.Config{
    BaseURL: "http://localhost:1234/v1",
    Model:   "your-loaded-model-id",
})

Provider satisfies actor.Provider, so it plugs directly into actor.Loop, run.NewAIGoalPart, or, for CI, into an actor.CassetteProvider — see Cassette workflow below.

Config

Structured output and graceful degradation

Propose first asks for response_format: {"type":"json_schema", ...} with strict:true — OpenAI's structured-output contract, which newer Ollama/LM Studio builds also implement, enforcing the JSON shape server-side. The schema is the same proposal contract actor/anthropic enforces: kind (send-text | click | task-done | give-up), text, action_id, rationale, all four always present (an empty string for whichever field the chosen kind does not need) — a campaign's actor.Prompt → actor.Proposal contract does not vary by provider.

Some OpenAI-compatible servers reject an unrecognised response_format with an HTTP error instead of ignoring it. When that happens — any failure status except 401/403 (authentication) or 429 (rate limit), which no change of response_format can fix — Propose retries the same prompt exactly once with response_format: {"type":"json_object"} plus the response schema restated in the system prompt (there is no server-side enforcement in this mode). The reply is still parsed strictly, through the same one-JSON-repair-attempt path response.go uses either way. If the fallback attempt also fails, Propose returns a typed *openai.FallbackFailedError naming both underlying failures — never a third attempt, never a fabricated Proposal.

Call Provider.LastResponseFormatMode() after Propose to see which mode actually served the last call (openai.ModeJSONSchema or openai.ModeJSONObjectFallback) — a test/diagnostic hook, never required for correct use.

Reasoning models and reasoning_content

Some reasoning models served through an OpenAI-compatible endpoint route their entire reply — including the proposal JSON the response contract asks for — into message.reasoning_content instead of message.content, leaving content empty while the server still bills output tokens for it. (qwen/qwen3.6-27b via LM Studio did this on 4/4 calls in the first actor-model arena run — see chatwright/runtime-go#3.)

Propose reads the first non-empty field in this order — the first hit wins outright and later fields are never even inspected:

1. message.content — the normal path; unchanged behaviour whenever this is non-empty.
2. message.reasoning_content — the LM Studio/DeepSeek-style field name.
3. message.reasoning — an alternate name a minority of other servers use.

Text recovered from either reasoning field goes through the exact same strict, one-repair-attempt parse and contract validation as content does (see response.go's responseText/parseWireProposal) — this package still never fabricates a Proposal out of reasoning prose that merely looks plausible. A reasoning field that does not hold a valid proposal surfaces as the same typed *openai.InvalidResponseError, with its Source field naming which field the text came from.

Error taxonomy

Usage and cost

Usage.Model, InputTokens, OutputTokens and Latency are read from the response and the call's wall-clock duration. Usage.Model falls back to Config.Model when the response omits "model". InputTokens/ OutputTokens stay zero — never guessed — when the response carries no "usage" block at all (some OpenAI-compatible servers omit it).

Usage.Cost is always left nil. Unlike actor/anthropic's dated pricing snapshot (a single hosted vendor with a stable published price list — see ../anthropic/pricing.go), this package fronts arbitrary local/self-hosted servers with no shared pricing source of truth, and most of them are free to run locally anyway — the whole point of this package. A caller that wants Usage.Cost populated for a hosted OpenAI-compatible endpoint with a known rate prices it themselves from InputTokens/ OutputTokens after Propose returns; the pricing-snapshot mechanism is deliberately not replicated here.

Cassette workflow (record once, replay free)

Identical to actor/anthropic's — Provider is a plain actor.Provider:

provider, err := openai.New(openai.Config{BaseURL: "http://localhost:11434/v1", Model: "qwen3.6:latest"})
cassette := actor.NewCassette("actor/openai model=qwen3.6:latest")
recorder, err := actor.NewCassetteProvider(actor.ModeRecord, provider, cassette)

// ... run the campaign/loop against recorder ...

err = recorder.Cassette().Save("testdata/cassettes/my-campaign.json")

CI replays with actor.ModeReplay and no local server running at all — see ../cassette.go and ../anthropic/README.md's own "Cassette workflow" section for the full record/commit/replay contract, which this package follows unchanged.

Testing

• go test ./actor/openai/... runs the full suite — request shape, all four proposal kinds, the JSON-repair path, the reasoning_content/ reasoning fallback fields (valid JSON, garbage, and content-wins precedence — see TestPropose_ReasoningContentFallback_ValidJSON and neighbours in provider_test.go), the finish_reason=length truncation hint (TestPropose_FinishReasonLength_SurfacesInError), the json_schema→json_object fallback (and its own failure path), the full error taxonomy, missing-usage/missing-model degradation, cassette record/replay, and a greetbot campaign end-to-end proof whose bundle validates against the chatwright.dev/sdk module's own formats/run-bundle/v1/schema.json (resolved via go list -m, see e2e_test.go's sdkSchemaPath) — entirely against a fake httptest.Server (see helpers_test.go) or a fake http.RoundTripper for the two transport-failure edge cases, never the real network.

• One optional live local-LLM smoke test, gated behind CHATWRIGHT_LIVE_LOCAL_LLM=1 and a set CHATWRIGHT_LOCAL_LLM_BASE_URL — skipped with a clear message otherwise, so go test ./... never depends on a local server being up:

  CHATWRIGHT_LIVE_LOCAL_LLM=1 \
  CHATWRIGHT_LOCAL_LLM_BASE_URL=http://localhost:11434/v1 \
  CHATWRIGHT_LOCAL_LLM_MODEL=qwen3.6:latest \
    go test ./actor/openai/ -run TestLiveLocal -v
  

  CHATWRIGHT_LOCAL_LLM_MODEL is optional — when unset, the test asks the server's own GET {baseURL}/models for its catalogue and uses whichever model comes first. See live_test.go's own doc comment for the LM Studio invocation too.