fix: handle Responses API text.format parameter correctly

[replicas-connector]

Summary

• Fixes the Responses API text.format parameter handling bug
• When using structured JSON output with OpenAI's Responses API, customers were getting error: Unsupported parameter: 'response_format'. In the Responses API, this parameter has moved to 'text.format'.

Root Cause

• Chat Completions API uses: response_format: { type: 'json_schema', json_schema: {...} }
• Responses API uses: text: { format: { type: 'json_schema', json_schema: {...} } }

Helicone's mapper incorrectly defined response_format in the Responses API types and didn't convert text.format properly.

Changes

1. packages/llm-mapper/transform/types/responses.ts

   • Removed response_format from ResponsesRequestBody (invalid for Responses API)
   • Added ResponsesTextFormat interface with proper type definition
   • Updated text field to include format with json_schema support

2. packages/llm-mapper/transform/providers/responses/request/toChatCompletions.ts

   • Updated response_format conversion to read from text.format instead of response_format
   • Added proper json_schema spreading when present

3. packages/llm-mapper/mappers/openai/responses.ts

   • Updated OpenAIResponseRequest interface to use text.format instead of response_format
   • Added proper type definitions for format options

4. packages/tests/llm-mapper/openai-chat-to-responses-converters.test.ts

   • Added tests for json_schema format conversion
   • Added tests for json_object format conversion
   • Added tests for text format conversion
   • Added tests for undefined format handling
   • Added tests for verbosity preservation with format

Test plan

• All existing llm-mapper tests pass (192 tests)
• New text.format tests pass (6 new tests)
• Tests cover json_schema, json_object, and text format types
• Tests verify response_format is undefined when text.format is not provided

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
helicone	Ready	Preview, Comment	Feb 4, 2026 7:58pm
helicone-bifrost	Ready	Preview, Comment	Feb 4, 2026 7:58pm
helicone-eu	Ready	Preview, Comment	Feb 4, 2026 7:58pm

[greptile-apps]

Your free trial has ended. If you'd like to continue receiving code reviews, you can add a payment method here.

[supabase]

This pull request has been ignored for the connected project bolqqmqbrciybnypvklh because there are no changes detected in supbase/supabase directory. You can change this behaviour in Project Integrations Settings ↗︎.

---

Preview Branches by Supabase.
Learn more about Supabase Branching ↗︎.

[supabase]

This pull request has been ignored for the connected project lmahfbbnchpworytrrqk because there are no changes detected in .supabase/supabase directory. You can change this behaviour in Project Integrations Settings ↗︎.

---

Preview Branches by Supabase.
Learn more about Supabase Branching ↗︎.

[claude]

Claude finished @replicas-connector[bot]'s task —— View job

---

PR Review Complete

I've analyzed the code changes for the Responses API text.format parameter handling fix. Here's my comprehensive review:

Score: 9/10 - Excellent fix with proper implementation

This is a well-executed fix that correctly addresses the API difference between OpenAI's Chat Completions and Responses APIs. The implementation is solid with comprehensive test coverage.

Suggestions Summary:

✅ Strengths:

• Correct API mapping: Properly handles the difference between response_format (Chat Completions) and text.format (Responses API)
• Type safety: Well-defined TypeScript interfaces with proper type definitions
• Comprehensive tests: 6 new test cases covering all format types (json_schema, json_object, text)
• Clean implementation: Follows existing patterns in the codebase
• Proper documentation: Clear comments explaining the API differences

🔍 Code Quality Analysis:

1. Type Definitions (packages/llm-mapper/transform/types/responses.ts:127-135)

   • ✅ ResponsesTextFormat interface is well-structured
   • ✅ Properly supports all three format types: text, json_schema, json_object
   • ✅ Optional json_schema field with comprehensive schema definition

2. Request Transformation (packages/llm-mapper/transform/providers/responses/request/toChatCompletions.ts:238-245)

   • ✅ Clean conversion from text.format to response_format
   • ✅ Proper spreading of json_schema object when present
   • ✅ Correctly returns undefined when no format is specified

3. Mapper Updates (packages/llm-mapper/mappers/openai/responses.ts:52-63)

   • ✅ Interface correctly reflects the new API structure
   • ✅ Removes invalid response_format field from Responses API types
   • ✅ Maintains backward compatibility

4. Test Coverage (packages/__tests__/llm-mapper/openai-chat-to-responses-converters.test.ts:355-469)

   • ✅ Tests all three format types with proper assertions
   • ✅ Verifies undefined behavior when format is not provided
   • ✅ Tests preservation of other text fields (verbosity) alongside format

🚀 Minor Suggestions for Improvement:

1. Edge Case Handling: Consider adding validation for malformed json_schema objects, though this is likely handled upstream
2. Error Messages: The current implementation gracefully handles missing fields, which is appropriate for this transformation layer

🔒 Security Assessment:

• ✅ No security concerns identified
• ✅ Proper input validation through TypeScript types
• ✅ No injection vulnerabilities in the transformation logic

📋 Performance:

• ✅ Efficient transformations with minimal object creation
• ✅ Conditional spreading only when necessary
• ✅ No performance regressions expected

Verification Notes:

• The fix correctly addresses the root cause described in the PR
• Implementation follows the established patterns in the codebase
• Type definitions are consistent with the OpenAI API specifications
• Test coverage validates the core functionality and edge cases

This is a high-quality fix that properly resolves the text.format parameter handling bug while maintaining code quality standards and comprehensive test coverage.

---