feat(fireworks_ai): add Fireworks AI provider

[acrogenesis]

Description

Adds a Fireworks AI provider backed by /inference/v1/chat/completions — the same endpoint the official Fireworks Python SDK posts to, with Fireworks-specific extensions plumbed through. Covers ~92% of the Fireworks chat-completion parameter surface (sampling extras, prompt-cache keys, speculation, native response_format: json_schema with strict enforcement plus a :tool fallback mode, reasoning_effort, parallel_tool_calls, max_completion_tokens, …).

Also fixes a cross-cutting bug in the default ResponseBuilder that produced %ReasoningDetails{provider: nil, encrypted?: nil, format: nil} for every OpenAI-compatible reasoning provider (DeepSeek, Groq, Fireworks, …).

Commits

1. fix: populate provider and defaults on default ResponseBuilder reasoning_details — uses the previously-ignored provider arg and supplies sane defaults for encrypted?/format. Relaxes the comprehensive provider-test assertion from a hard-coded 5-element whitelist to "non-nil atom" now that the fix applies broadly. No behaviour change for providers with their own ResponseBuilder (Anthropic, Google, Minimax, OpenAI Responses API, OpenRouter).
2. feat(fireworks_ai): add Fireworks AI provider — provider module, comprehensive coverage suite, 28 live-recorded fixtures (kimi-k2p5 + glm-5 × 14 scenarios each), and a provider guide.
3. fix(fireworks_ai): strip reasoning_details and reasoning_content from outbound messages — extends the outbound-message scrubber: metadata, reasoning_details, and reasoning_content all survive ResponseBuilder round-tripping on assistant turns and cause Fireworks to 400 with "Extra inputs are not permitted" on the next call.

Provider quirks handled

• Caps max_tokens to 4096 for non-streaming requests (Fireworks 400s otherwise)
• Strips message-level metadata, reasoning_details, and reasoning_content from outbound assistant turns (Fireworks rejects extra fields)
• Translates canonical tool_choice to OpenAI function shape
• stream_options.include_usage is supplied by the default OpenAI-compat body builder for streaming requests
• Defaults receive_timeout to 5 minutes for slow reasoning completions

Type of Change

• Bug fix (non-breaking change fixing an issue) — default ResponseBuilder.reasoning_details for OpenAI-compatible reasoning providers
• New feature (non-breaking change adding functionality) — Fireworks AI provider
• Breaking change (fix or feature causing existing functionality to change)
• Documentation update — new guides/fireworks_ai.md

Breaking Changes

None. The ResponseBuilder fix populates fields that were previously nil; no provider was relying on those nils.

Testing

• Tests pass (mix test)
• Quality checks pass (mix quality)

Detail

• mix test test/providers/fireworks_ai_test.exs — 24 / 0
• mix test test/coverage/fireworks_ai/ — 22 / 0 in replay mode (kimi-k2p5 + glm-5)
• mix test --exclude integration --exclude live --exclude coverage — 3010 / 0 after rebasing onto latest main (Azure Responses API reasoning-effort fix)
• mix quality (format + --warnings-as-errors + credo --strict + dialyzer) — all green
• Verified no new regressions on other providers' coverage replay (same pre-existing failures as main; unrelated Azure/Google embedding and Anthropic streaming structured-output tests)
• Live fixtures recorded against the real Fireworks API; bodies confirm the native response_format: json_schema path with strict mode

Checklist

• My code follows the project's style guidelines (per-callback @doc blocks, explicit encode_body/build_body pair, module attributes grouped near top — matches Cerebras/Zenmux/OpenRouter conventions)
• I have updated the documentation accordingly (new guides/fireworks_ai.md, registered in mix.exs extras + Providers grouping)
• I have added tests that prove my fix/feature works (24 unit + 11 comprehensive coverage scenarios × 2 models)
• All new and existing tests pass
• My commits follow conventional commit format (feat:, fix:)
• I have NOT edited CHANGELOG.md (it is auto-generated by git_ops)

Known follow-ups (out of scope for this PR)

• top_k is documented in the core schema as a top-level option but crashes at runtime for every OpenAI-compatible provider that doesn't explicitly register it (Fireworks included). Fireworks users currently pass it via provider_options: [top_k: 40]. The cleaner fix is a one-line addition to extra_option_keys in provider/defaults.ex plus per-provider drop rules where the wire doesn't accept it — better handled as its own PR with cross-cutting test coverage.
• Multimodal video parts (video_url, max_frames, sample_fps, spatial_limit) — only Google has end-to-end video plumbing today; would need shared ContentPart work.
• Two-model fixture density (kimi-k2p5, glm-5) is in line with Cerebras (4) and Groq (8); expand if maintainers want broader coverage.

Related Issues

Closes #

[palantir-valiot]

Review Summary

This PR adds a Fireworks AI provider and fixes a cross-cutting bug in the default ResponseBuilder. After reviewing the implementation, tests, fixtures, and documentation, I find the changes well-structured and correct.

Key Changes Reviewed

1. Bug fix in ResponseBuilder — Correctly populates provider, encrypted?, and format defaults for reasoning details from thinking chunks. The previous implementation ignored the provider argument and left fields as nil, which affected all OpenAI-compatible reasoning providers (DeepSeek, Groq, Fireworks, etc.). The comprehensive test assertion relaxation from a hardcoded whitelist to "non-nil atom" is the right call.

2. Fireworks AI provider — Follows the established provider pattern (OpenAI-compatible endpoint with custom build_body/1 and translate_options/3). Provider-specific quirks are handled appropriately:

   • max_tokens capped to 4096 for non-streaming requests with a warning
   • Message-level metadata stripped to avoid Fireworks 400s
   • Canonical tool_choice translated to OpenAI function shape
   • stream_options.include_usage set automatically for streaming
   • Default receive_timeout of 5 minutes for slow reasoning completions
   • reasoning_effort mapped correctly to Fireworks string values

3. Structured output — The dual-mode implementation (:auto/:json_schema native path and :tool fallback) is clean and correctly delegates to the default prepare request pipeline.

4. Tests & fixtures — 23 unit tests cover provider contract, request preparation, authentication, body encoding, option translation, reasoning effort rendering, tool choice translation, extended parameters, structured output modes, and stream options. The 28 live-recorded fixtures (kimi-k2p5 + glm-5 across 14 scenarios each) provide good coverage.

5. Documentation — The provider guide is thorough and accurately documents the top_k namespace collision workaround and the "max" reasoning effort escape hatch.

Verdict

No issues found. The PR is clean, low-risk, and ready to merge.

[palantir-valiot]

Overall Assessment

Clean, well-structured provider implementation that follows existing codebase patterns. The cross-cutting ResponseBuilder fix is correct and the test coverage (23 unit tests, 22 coverage replay tests, 28 fixtures) is thorough.

Findings

Severity	Finding
Moderate	fireworks_json_schema_strict: false in provider_options is ignored due to `
Low	Same `

Positive Notes

• The ResponseBuilder reasoning-details fix correctly uses the previously-ignored provider argument and supplies sensible defaults for encrypted? and format.
• Fireworks-specific quirks (max_tokens capping, message metadata stripping, tool_choice translation, stream_options.include_usage) are handled appropriately.
• Provider guide is comprehensive and covers the top_k namespace collision workaround clearly.
• Fixture coverage with two models (kimi-k2p5, glm-5) is in line with other providers.

Suggested Follow-up

Consider fixing the || pattern in both structured_output_mode/1 and prepare_object_via_json_schema/4 to use Keyword.fetch/2 or a sentinel value so that explicit false values in provider_options are respected.

[palantir-valiot]

Review Summary

This PR adds a well-structured Fireworks AI provider and fixes a cross-cutting bug in the default ResponseBuilder for reasoning details. After reviewing the provider module, tests, fixtures, and the ResponseBuilder fix, I found no bugs.

ResponseBuilder Fix

The change in lib/req_llm/provider/defaults/response_builder.ex correctly uses the previously-ignored provider argument and supplies sensible defaults (encrypted?: false, format: "openai-reasoning-content-v1") for ReasoningDetails. The comprehensive test assertion relaxation from a hard-coded whitelist to "non-nil atom" is the appropriate follow-up.

Fireworks AI Provider

The provider module follows existing patterns correctly:

• OpenAI-compatible base with Fireworks-specific extensions plumbed through build_body/1
• max_tokens capping to 4096 for non-streaming requests is implemented and tested
• Message-level metadata stripping is handled defensively (both atom and string keys)
• tool_choice translation and stream_options.include_usage injection are correct
• Structured output supports both native json_schema and tool-call fallback modes
• reasoning_effort atom-to-string rendering covers the full Fireworks surface area

Tests & Fixtures

• 23 provider unit tests cover request preparation, encoding, option translation, and response decoding
• 28 live-recorded fixtures (kimi-k2p5 + glm-5 across 14 scenarios each) provide good coverage
• The comprehensive test matrix integrates cleanly with the existing provider test framework

Minor Observation (non-blocking)

add_stream_options/2 unconditionally overwrites stream_options with %{include_usage: true} for streaming requests. This is intentional per the PR description, but it prevents users from passing additional Fireworks-specific stream_options fields should they be introduced in the future. A Map.merge would be more forward-compatible.

Verdict: Clean, low-risk PR. Approving.

[palantir-valiot]

Review Summary

This PR adds a Fireworks AI provider and fixes a cross-cutting bug in the default ResponseBuilder. After reviewing the provider implementation, tests, fixtures, documentation, and the ResponseBuilder fix, I find the PR to be well-structured and correct.

Overall Assessment: Approve

Key Observations

1. ResponseBuilder Fix (Correct) — The change in lib/req_llm/provider/defaults/response_builder.ex properly uses the previously-ignored provider argument and supplies sensible defaults (encrypted?: false, format: "openai-reasoning-content-v1"). The comprehensive test assertion relaxation from a hard-coded 5-element whitelist to "any non-nil atom" is the right follow-up.

2. Fireworks Provider Structure (Correct) — The provider follows the established OpenAI-compatible provider pattern (similar to Groq, DeepSeek, Cerebras). It correctly:

   • Delegates to ReqLLM.Provider.Defaults for standard operations
   • Overrides prepare_request/4 for :object operations with two structured-output strategies (:json_schema native and :tool fallback)
   • Caps non-streaming max_tokens to 4096 with a warning in translate_options/3
   • Strips message-level metadata, reasoning_details, and reasoning_content from outbound messages to avoid Fireworks 400s on multi-turn conversations
   • Renders canonical reasoning_effort atoms to Fireworks string values
   • Defaults receive_timeout to 5 minutes for slow reasoning completions

3. Test Coverage (Good) — 23 focused unit tests cover provider contract, request preparation, authentication, body encoding, option translation, reasoning effort rendering, tool choice translation, structured output modes, stream options, and response decoding. The 28 live-recorded fixtures for kimi-k2p5 and glm-5 provide comprehensive coverage.

4. Documentation (Good) — The provider guide accurately documents all Fireworks-specific options, the max_tokens > 4096 constraint, the top_k namespace collision workaround, and the three structured-output strategies.

Minor Notes

• The config/test.exs change raises the global receive_timeout and stream_receive_timeout to 5 minutes for the entire test suite. This appears intentional to accommodate slow reasoning models, but be aware it affects all providers' tests.
• The Fireworks provider depends on ReqLLM.Providers.OpenAI.AdapterHelpers for translate_tool_choice_format/0 and enforce_strict_recursive/1. This is consistent with other OpenAI-compatible providers in the codebase and is not an issue.
• No blocking issues found.

[palantir-valiot]

Overall Assessment

Clean, well-structured PR that adds Fireworks AI provider support and fixes a cross-cutting bug in the default ResponseBuilder. No blocking issues found.

Findings

#	Severity	Description
1	Info	config/test.exs adds global 5-minute timeouts that affect all providers, not just Fireworks. Verify this is intentional for the test suite.
2	Info	prepare_object_via_json_schema/4 sets operation: :object in opts but delegates to prepare_request with :chat. This is correct (endpoint routing), but worth confirming telemetry/fixture tagging handles the mixed operation value as expected.

What was reviewed

• ResponseBuilder fix — The provider argument was previously ignored, producing nil provider/fmt/encrypted fields for all OpenAI-compatible reasoning providers. The fix supplies sensible defaults and the comprehensive test assertion is appropriately relaxed from a hard-coded 5-element whitelist to "non-nil atom".
• Fireworks AI provider — Follows the established OpenAI-compatible provider pattern. Key implementation details verified:
  • translate_options/3 correctly drops :reasoning_token_budget, caps non-streaming max_tokens to 4096 with a warning, and defaults receive_timeout to 5 minutes.
  • build_body/1 strips metadata, reasoning_details, and reasoning_content from outbound messages (defensive against Fireworks 400s on multi-turn conversations).
  • render_reasoning_effort/1 correctly maps canonical atoms to Fireworks string values and omits :default.
  • Structured output routing (:auto → native json_schema, :tool → tool-call fallback) is consistent with the OpenAI provider's approach.
  • tool_choice translation reuses the shared OpenAI adapter helper.
• Tests — Provider contract, encoding, option translation, reasoning effort rendering, tool choice translation, structured output modes, and stream options are all covered. 28 live-recorded fixtures provide good replay coverage for kimi-k2p5 and glm-5.
• Documentation — The provider guide is comprehensive and accurately documents quirks (max_tokens cap, metadata stripping, top_k namespace collision, unsupported endpoints).

Verdict

APPROVE — Low risk, good test coverage, follows existing conventions.

[palantir-valiot]

Overall Assessment

Clean, well-tested provider addition with a sensible cross-cutting fix for ResponseBuilder reasoning metadata. One logic bug prevents disabling strict JSON schema mode via provider_options.

Findings

#	Severity	File	Description
1	Medium	lib/req_llm/providers/fireworks_ai.ex	fireworks_json_schema_strict: false in provider_options is ignored due to `

What looks good

• ResponseBuilder fix correctly populates provider, encrypted?, and format for OpenAI-compatible reasoning providers instead of leaving them nil.
• Message scrubbing (strip_rejected_message_fields) is thorough and covers both atom and string keys, preventing the multi-turn HTTP 400s described in the PR.
• Test coverage is extensive: provider contract, encoding, option translation, structured output modes, streaming, and tool round-trips are all exercised.
• Documentation (guides/fireworks_ai.md) is detailed and includes the important max_tokens > 4096 streaming caveat.

Minor notes

• The render_reasoning_effort mapping of :minimal → "low" is a design choice; consider documenting it explicitly if users might expect :minimal to map to "none".
• The existing test for fireworks_json_schema_strict: false passes the option at the top level, so the provider_options bug is not currently covered.

[palantir-valiot]

Bug: false value in provider_options is ignored for fireworks_json_schema_strict.

The || operator treats false as falsy, so passing provider_options: [fireworks_json_schema_strict: false] falls through to the top-level option (which defaults to true). This makes it impossible to disable strict mode via provider_options.

Replace with an explicit nil check:

strict =
  case Keyword.get(provider_opts, :fireworks_json_schema_strict) do
    nil -> Keyword.get(opts, :fireworks_json_schema_strict, true)
    val -> val
  end

The same pattern exists in structured_output_mode/1 (line 108), though it is less likely to cause problems since the expected values are truthy atoms.

[palantir-valiot]

Review Summary

This PR adds a well-implemented Fireworks AI provider and fixes a cross-cutting bug in the default ResponseBuilder for OpenAI-compatible reasoning providers.

Overall Assessment

Clean, comprehensive, and well-tested. No blocking issues found.

Key Changes Reviewed

1. ResponseBuilder fix (lib/req_llm/provider/defaults/response_builder.ex):

   • Correctly uses the previously-ignored provider argument as a fallback for ReasoningDetails.provider.
   • Supplies sensible defaults (encrypted?: false, format: "openai-reasoning-content-v1").
   • The relaxed comprehensive-test assertion (is_atom(detail.provider) and not is_nil(detail.provider)) is the right generalization.

2. Fireworks AI provider (lib/req_llm/providers/fireworks_ai.ex):

   • OpenAI-compatible endpoint reuse is the correct architectural choice.
   • build_body/1 correctly strips metadata, reasoning_details, and reasoning_content from outbound messages while preserving top-level request metadata — this directly addresses the Fireworks "Extra inputs are not permitted" 400s on multi-turn conversations.
   • max_tokens capping to 4096 for non-streaming requests is correctly guarded by stream? check.
   • render_reasoning_effort/1 mapping (:minimal → "low") is reasonable given Fireworks's accepted values.
   • Structured output dual-mode (:auto/:json_schema native vs :tool fallback) is cleanly implemented.

3. Tests & fixtures:

   • Provider-level tests cover identity, schema, request preparation, auth, body encoding, option translation, reasoning effort rendering, tool choice translation, structured output modes, and stream options.
   • 28 live-recorded fixtures across two models (kimi-k2p5, glm-5) provide good coverage.

4. Documentation:

   • guides/fireworks_ai.md is thorough and accurately describes provider quirks (max_tokens cap, message stripping, top_k namespace collision, timeout defaults).
   • Amazon Bedrock prefix corrections (bedrock: → amazon_bedrock:) are consistent with the codebase.

Minor Notes (non-blocking)

• The encode_body strips reasoning_details... test in test/providers/fireworks_ai_test.exs constructs a message struct directly rather than exercising a full round-trip through ResponseBuilder + re-encoding. This is sufficient for unit-level coverage, but an integration-style test (message → encode → decode → re-encode) would provide even stronger confidence that the stripping survives realistic conversation flows. The fixture-based coverage tests likely cover this implicitly.

• render_reasoning_effort/1 passes unknown atoms through unchanged (last clause: defp render_reasoning_effort(other), do: other). Fireworks will reject invalid values, so this is acceptable, but consider logging a warning for unrecognized atoms to aid debugging.

Verdict: Approve. The bug fix is correct, the provider implementation follows established patterns, and the test coverage is extensive.

The merge-base changed after approval.

[palantir-valiot]

Review Summary

This PR adds the Fireworks AI provider and fixes a cross-cutting bug in the default ResponseBuilder. After reviewing the code, tests, fixtures, and documentation, I find no blocking issues.

ResponseBuilder Fix

The fix in lib/req_llm/provider/defaults/response_builder.ex correctly addresses a bug where extract_reasoning_from_thinking_chunks/2 ignored the provider argument and left encrypted?, provider, and format as nil. The new defaults (false, the passed provider atom, and "openai-reasoning-content-v1") are sensible. The relaxed comprehensive-test assertion from a hard-coded 5-element whitelist to is_atom(detail.provider) and not is_nil(detail.provider) is the right call now that the fix applies broadly to all OpenAI-compatible reasoning providers.

Fireworks AI Provider

The provider module (lib/req_llm/providers/fireworks_ai.ex) is well-structured and follows existing OpenAI-compatible provider patterns:

• Base URL & auth wiring — correct.
• translate_options/3 — drops unsupported reasoning_token_budget, sets a 5-minute default receive_timeout, and caps non-streaming max_tokens to 4096 with a warning. All correct.
• build_body/1 — strips metadata, reasoning_details, and reasoning_content from outbound messages (critical for multi-turn conversations with Fireworks), translates canonical tool_choice to OpenAI function shape, and forwards the full Fireworks-specific parameter surface. Correct.
• Structured output — three modes (:auto, :json_schema, :tool) with strict JSON schema enforcement via ReqLLM.Providers.OpenAI.AdapterHelpers.enforce_strict_recursive/1. Clean implementation.
• render_reasoning_effort/1 — correctly maps core atoms to Fireworks string values and omits :default.

Tests & Fixtures

• Provider-level tests (test/providers/fireworks_ai_test.exs) cover identity, schema, request preparation, body encoding, option translation, reasoning effort rendering, tool choice translation, structured output modes, and stream options. Good coverage.
• 28 live-recorded fixtures across two models (kimi-k2p5, glm-5) and multiple scenarios (basic, streaming, reasoning, tools, object generation, context append, token limit, usage). Comprehensive.
• The comprehensive coverage test module follows the established pattern.

Documentation

• guides/fireworks_ai.md is thorough and covers configuration, model specs, all provider options, structured output modes, and implementation notes (max_tokens cap, metadata stripping, tool_choice translation, top_k collision, streaming usage, timeout defaults).
• README and mix.exs are updated correctly to list Fireworks as the 20th supported provider.

Minor Notes (non-blocking)

• The guide mentions passing "max" reasoning effort via provider_options: [reasoning_effort: "max"]. It is worth verifying in a follow-up that values nested inside provider_options are correctly surfaced to build_body (the current implementation reads request.options[:reasoning_effort] directly). This is pre-existing behavior across providers, not a bug introduced here.
• Some fixture files lack a trailing newline. Cosmetic only.

Verdict: Clean, well-tested provider addition with a legitimate cross-cutting bug fix. Low risk.