feat(llm): add openai-responses provider (OpenAI Responses API)

[nicoloboschi]

What

Adds a new LLM provider openai-responses that calls the OpenAI Responses API (client.responses.create → /v1/responses) instead of chat/completions.

Why

Reasoning models such as gpt-5.6-terra reject reasoning_effort combined with function tools on /v1/chat/completions:

reasoning_effort="low"   -> HTTP 400
reasoning_effort absent  -> HTTP 400
reasoning_effort="none"  -> succeeds

Reflect is a tool-calling search loop, so on chat/completions the only non-400 setting ("none") also strips reasoning from reflect's final synthesis (single effort knob per op). The Responses API models the chain-of-thought as a first-class reasoning item, so reasoning and function tools coexist — reflect's search loop runs with a real reasoning_effort and still calls tools.

Design

OpenAIResponsesLLM is a standalone LLMInterface implementation. It is OpenAI-only and deliberately does not subclass the multi-vendor OpenAICompatibleLLM (chat/completions) class — so it can never route through chat.completions and carries none of the groq/ollama/deepseek special-casing. It reuses only a few provider-agnostic pure helpers (text-tag stripping, quota-defer parsing). The shared chat retry loop is untouched (no regression risk to the ~13 existing OpenAI-compatible providers).

Translations:

• chat messages → Responses input items (assistant tool_calls → function_call; role="tool" → function_call_output keyed by call_id)
• nested {"type":"function","function":{…}} tools → flattened {"type":"function","name":…,"parameters":…}
• flat reasoning_effort → reasoning={"effort": …}
• response_format → text={"format": {…}} (strict json_schema, or the soft schema-in-prompt + json_object fallback)
• reads response.output_text + function_call items from response.output; usage from usage.input_tokens/output_tokens (reasoning split out of visible output)

Conversation is replayed statelessly each turn (store=False, no previous_response_id); server-side reasoning reuse across turns is a future optimization.

Generic LLM config flags

Honors extra_body, timeout, and per-call temperature / max_completion_tokens / max_retries. It additionally wires two generic flags the chat/completions path drops:

• openai_service_tier → the native Responses service_tier param (e.g. flex)
• default_headers → the OpenAI SDK client (proxy / request-tracing)

OpenAI-compatible endpoints

Like the openai (Chat Completions) provider, openai-responses honors a custom HINDSIGHT_API_LLM_BASE_URL, so any OpenAI-compatible endpoint that exposes /v1/responses (gateways, Azure-style deployments) works the same way as a Chat Completions one.

Docs

• Models page (developer/models.mdx): new provider in the grid, a dedicated "OpenAI Responses API" tip, and the OpenAI-Compatible tip now states explicitly that the openai provider uses Chat Completions while openai-responses uses the Responses API — both usable against compatible custom endpoints.
• configuration.md provider list + Chat-Completions/Responses compatible-endpoint examples.
• .env.example (+ embed template sync); docs skill mirror regenerated.

Wiring

• Provider registration + factory dispatch (llm_wrapper.py).
• PROVIDER_DEFAULT_MODELS["openai-responses"] = "gpt-5.6".
• openai floor bumped to >=1.66.0 for the Responses API surface.

Tests

tests/test_openai_responses_provider.py (19 tests) mock responses.create and cover registration/wiring, request shaping (reasoning object, temperature omission for reasoning models, max_output_tokens, strict/soft structured output, truncation → OutputTooLongError), message-history translation, tool-choice mapping, response parsing, and the generic-flag wiring (extra_body, service_tier, default_headers). The load-bearing test pins that reasoning and tools are sent together on the tool path.

Live validation (real gpt-5.6-terra)

• plain + reasoning, strict structured output ✅
• reasoning + tools together (reasoning_tokens > 0 in the same request as a function call) ✅
• stateless function_call / function_call_output replay → final answer ✅
• full run_reflect_agent end-to-end (stubbed retrieval, no DB): the agent drove the Responses tool loop through recall to a correct synthesized answer ✅

Usage

export HINDSIGHT_API_LLM_PROVIDER=openai-responses
export HINDSIGHT_API_LLM_MODEL=gpt-5.6            # or gpt-5.6-terra
export HINDSIGHT_API_LLM_REASONING_EFFORT=high    # now rides alongside tools

🤖 Generated with Claude Code