refactor(providers): batch/file facet surfaces and bailian chat-adapter hook

[SantiagoDePolonia]

What

Phase 2 of the provider consolidation started in #486. Two changes:

1. Batch/file facet surfaces. After #486, three packages (groq, bailian, xai) carried verbatim copies of the same ten batch/file delegation one-liners — past the "repeated pattern justifies the abstraction" bar. New embeddable facets in the openai package:

• openai.BatchSurface — exactly the core.NativeBatchProvider method set (compile-guarded)
• openai.FileSurface — exactly the core.NativeFileProvider method set (compile-guarded)

Partial-surface providers embed the facets they support; the router's interface-assertion capability discovery sees precisely the advertised set, and a future batch/file endpoint added to CompatibleProvider gets wired in one place (the facet) instead of three copies.

2. bailian's chat adapter moves into the engine. The max_tokens → max_completion_tokens mapping (Bailian deprecated max_tokens in April 2026) becomes the AdaptChatRequest hook from #486. ChatCompletion/StreamChatCompletion become plain delegation, and Responses-via-chat picks the adaptation up through the engine rather than relying on the "override chat ⇒ must override responses" discipline. The raw passthrough-body adaptation (untyped JSON) is unchanged.

Also drops bailian's redundant resp.Provider = "bailian" re-stamping in file methods — the shared engine already stamps its configured provider name.

Deliberately not done

The architecture review flagged the openai-vs-vllm passthrough_semantics files as near-dupes. Verified against current code: they are 9–10-line data tables whose every line differs (provider-prefixed operation names; vllm adds /completions). azure/openrouter already reuse openai's enricher where the tables are truly identical. Nothing to share — skipped.

User-visible impact

None. Every delegated body was a verbatim copy of the engine method it now calls; the bailian adapter's behavior (including respect-existing-max_completion_tokens precedence and forward-original-on-error) is preserved, with its unit tests updated only for the new (req, error) hook signature.

Wrapper sizes: groq 161→122, bailian 282→232 (the two adapters are the irreducible quirk), xai 269→213.

Tests

Full suite, -race on internal/providers/..., lint 0 issues, pre-commit green. Facets are compile-guarded against the capability interfaces and exercised through the existing groq/bailian/xai httptest suites.

Remaining phase (separate PR): remove the 16 test-only NewWithHTTPClient constructors.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features
  • Expanded batch job and file management capabilities across compatible AI providers, including batch creation/results and full file lifecycle (upload, list, retrieve, delete, and fetch file content).
• Bug Fixes
  • Improved chat completion token-limit handling by reliably mapping max_tokens to max_completion_tokens for compatible providers.
  • Preserves an explicitly provided max_completion_tokens value.
  • If request adaptation fails, continues using the original request to reduce the chance of lost or altered settings.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 46084131-7e47-4717-989a-7dc81788cf0b

📥 Commits

Reviewing files that changed from the base of the PR and between 8465355 and f59cc30.

📒 Files selected for processing (1)

• internal/providers/bailian/bailian.go

---

📝 Walkthrough

Walkthrough

Adds reusable batch/file delegation surfaces for OpenAI-compatible providers, reuses them in Groq and xAI, and changes Bailian chat request adaptation to a hook-based function that returns an error and is wired through provider configuration.

Changes

Provider Surfaces and Adapter Refactor

Layer / File(s)	Summary
New batch and file surfaces internal/providers/openai/surfaces.go	Adds BatchSurface and FileSurface wrappers around CompatibleProvider, with delegation methods for batch and file operations and interface assertions.
Groq and xAI adopt embedded surfaces internal/providers/groq/groq.go, internal/providers/xai/xai.go	Groq and xAI providers embed BatchSurface and FileSurface, constructors initialize them from CompatibleProvider, and explicit batch/file forwarding methods are removed.
Bailian adapter hook and request mapping internal/providers/bailian/bailian.go	Bailian provider construction wires AdaptChatRequest into compatibleConfig, chat methods delegate directly to CompatibleProvider, and adaptChatRequest replaces the prior request rewrite logic with error-returning handling for max_tokens mapping.
Bailian adaptation tests internal/providers/bailian/bailian_test.go	Bailian adaptation tests now call adaptChatRequest and assert the returned error alongside the adapted request.

Estimated code review effort: 4 (Complex) | ~45 minutes

Possibly related PRs

• ENTERPILOT/GoModel#392: Introduces the Bailian max_tokens to max_completion_tokens adaptation flow that this PR reworks into adaptChatRequest.

Poem

A rabbit hops through surfaces bright,
Batch and file now share their light.
Bailian twitches its chat-map ear,
Groq and xAI both steer clear.
Hop, hop — the burrow’s neat and fast,
With adapter hooks that simply last.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly captures the provider refactor, the new batch/file surfaces, and the Bailian chat-adapter hook.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch refactor/providers-phase2

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

❌ Patch coverage is 60.00000% with 26 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
internal/providers/openai/surfaces.go	0.00%	24 Missing ⚠️
internal/providers/bailian/bailian.go	91.30%	2 Missing ⚠️

📢 Thoughts on this report? Let us know!

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@internal/providers/bailian/bailian.go`:
- Around line 34-46: The doc comment for Provider no longer matches the
implementation because BatchSurface and FileSurface are embedded, so batch/file
methods are not explicitly delegated anymore. Update the comment near Provider
to say that batch/file capabilities are exposed through embedded surfaces while
chat/passthrough behavior remains delegated through the compatible provider.
Keep the wording aligned with the actual fields on Provider and the delegation
pattern used by compatible.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: f9ee382b-8df4-4f05-a230-d018f441ff38

📥 Commits

Reviewing files that changed from the base of the PR and between a069a2c and 8465355.

📒 Files selected for processing (5)

• internal/providers/bailian/bailian.go
• internal/providers/bailian/bailian_test.go
• internal/providers/groq/groq.go
• internal/providers/openai/surfaces.go
• internal/providers/xai/xai.go

[greptile-apps]

Confidence Score: 5/5

Safe to merge with minimal risk.

The changes are localized refactors that preserve existing delegation behavior and route Bailian’s existing parameter adaptation through the shared chat hook.

No files require special attention.

T-Rex Logs

What T-Rex did

• The race-enabled provider tests were executed and completed successfully.
• The log confirms the race test run included verbose test names covering Bailian request adaptation, batch/file delegation, compatible provider file helpers, and xai/groq/openai provider behavior, and shows the Go version, PASS results, and EXIT STATUS.
• A fallback non-race command was started after the initial timeout, but it did not contribute to validation because the race run produced the required proof.

_{Ran code and verified through T-Rex}

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
participant Router
participant Provider as groq/bailian/xai Provider
participant Surface as BatchSurface/FileSurface
participant Compat as openai.CompatibleProvider
participant Upstream as Provider API

Router->>Provider: Interface assertion for batch/file capability
Provider-->>Router: Advertises embedded facet methods
Router->>Provider: CreateBatch/CreateFile/etc.
Provider->>Surface: Promoted facet method
Surface->>Compat: Delegate compatible endpoint call
Compat->>Upstream: OpenAI-compatible HTTP request
Upstream-->>Compat: Native response
Compat-->>Surface: Normalized provider-stamped response
Surface-->>Provider: Return response
Provider-->>Router: Return result

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
participant Router
participant Provider as groq/bailian/xai Provider
participant Surface as BatchSurface/FileSurface
participant Compat as openai.CompatibleProvider
participant Upstream as Provider API

Router->>Provider: Interface assertion for batch/file capability
Provider-->>Router: Advertises embedded facet methods
Router->>Provider: CreateBatch/CreateFile/etc.
Provider->>Surface: Promoted facet method
Surface->>Compat: Delegate compatible endpoint call
Compat->>Upstream: OpenAI-compatible HTTP request
Upstream-->>Compat: Native response
Compat-->>Surface: Normalized provider-stamped response
Surface-->>Provider: Return response
Provider-->>Router: Return result

Loading

_{Reviews (1): Last reviewed commit: "docs(bailian): align Provider doc with e..." | Re-trigger Greptile}