Added json_schema support

[lesleyxyz]

Summary by Sourcery

Add support for OpenAI-compatible json_schema response_format by wiring JSON Schema through to the Claude CLI, and preferring validated result content in both streaming and non-streaming responses when a schema is provided.

New Features:

• Support OpenAI-style response_format.json_schema in ChatCompletionRequest to request structured, schema-validated output.
• Allow passing a JSON Schema through to the Claude CLI via the --json-schema flag for validated result generation.
• Enable APIs to optionally prefer the CLI's final result payload as assistant content in both streaming and non-streaming responses when json_schema is used.

Enhancements:

• Extend streaming and non-streaming response builders to conditionally use the CLI result field as the final assistant message content.
• Propagate a prefer_result_content flag through streaming utilities and response creation helpers to control result-vs-message content selection.

[gemini-code-assist]

Caution

The consumer version of Gemini Code Assist on GitHub has been sunset. All code review activity has officially ceased.

[sourcery-ai]

Reviewer's Guide

Adds OpenAI-compatible json_schema response_format support end-to-end, wiring a JSON Schema from the chat request into the Claude CLI via --json-schema, and preferring structured result content in both streaming and non‑streaming responses when json_schema is used, plus a convenience Docker Compose file.

Sequence diagram for json_schema propagation and result preference

sequenceDiagram
    actor Client
    participant API as create_chat_completion
    participant Manager as ClaudeManager.create_session
    participant Start as ClaudeManager.start
    participant CLI as Claude_CLI
    participant StreamResp as create_sse_response
    participant NonStreamResp as create_non_streaming_response

    Client->>API: ChatCompletionRequest(response_format.json_schema)
    API->>API: _extract_json_schema(request)
    API->>Manager: create_session(prompt, model, system_prompt, json_schema)
    Manager->>Start: start(prompt, model, system_prompt, json_schema)
    Start->>CLI: run --json-schema <json_schema>

    alt request.stream
        API->>StreamResp: create_sse_response(..., prefer_result_content=json_schema is not None)
        StreamResp->>StreamResp: OpenAIStreamConverter.__init__(prefer_result_content)
        CLI-->>StreamResp: stream messages with result
        StreamResp->>StreamResp: convert_stream()
    else non-streaming
        API->>NonStreamResp: _collect_non_streaming_response(..., prefer_result_content=json_schema is not None)
        NonStreamResp->>NonStreamResp: create_non_streaming_response(..., prefer_result_content)
        NonStreamResp->>NonStreamResp: _extract_result_content(messages)
    end

Loading

File-Level Changes

Change	Details	Files
Prefer CLI result payload as assistant content when structured output is requested.	Extend OpenAIStreamConverter to accept a prefer_result_content flag and, on final messages, optionally stream message.result as the assistant content before closing. Plumb prefer_result_content through StreamingManager.create_stream and create_sse_response so API callers can opt into using result content for streaming responses. In non-streaming responses, add _extract_result_content to find the final normalized result message and override complete_content when prefer_result_content is enabled.	claude_code_api/utils/streaming.py
Expose OpenAI-style json_schema response_format on the chat API and enable structured-output behavior when present.	Define JSONSchemaSpec and ResponseFormat Pydantic models to represent OpenAI-compatible response_format.json_schema on ChatCompletionRequest. Add response_format field to ChatCompletionRequest and implement _extract_json_schema to validate and extract the JSON schema from incoming requests. Update create_chat_completion to parse json_schema from the request and use its presence to toggle prefer_result_content for both streaming and non-streaming paths.	claude_code_api/models/openai.py claude_code_api/api/chat.py
Wire JSON Schema through ClaudeManager into the Claude CLI process via --json-schema.	Extend ClaudeManager.start, _start_with_fallback_models, and create_session to accept an optional json_schema dict. When json_schema is provided, append a --json-schema argument (JSON-encoded) to the CLI command line, and treat --json-schema as a redacted argument in safe logging. Ensure fallback model startup path also forwards json_schema so structured-output behavior is preserved across model retries.	claude_code_api/core/claude_manager.py
Add a Docker Compose configuration for running the Claude Code API locally with Claude Max subscription and OAuth proxy.	Introduce docker/custom.yml defining claude-code-api service with build context, ports, environment variables for Claude Max and OAuth proxy, and volumes for Claude state/config. Configure healthcheck and restart policy suitable for local or dev deployments.	docker/custom.yml

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[qodo-free-for-open-source-projects]

PR Summary by Qodo

Add OpenAI json_schema response_format passthrough to Claude Code CLI

✨ Enhancement ⚙️ Configuration changes 🕐 20-40 Minutes

AI Description

• Add OpenAI-compatible response_format.type='json_schema' request support.
• Pass JSON Schema to Claude Code via CLI --json-schema and surface validated result.
• Provide a docker compose template for running the API with Claude Max + OAuth proxy.

Diagram

graph TD
  A["OpenAI Client"] --> B["FastAPI /chat/completions"] --> C["ChatCompletionRequest\n(response_format)"] --> D["ClaudeManager/ClaudeProcess\n(--json-schema)"] --> E{{"Claude Code CLI"}} --> F["streaming.py\n(result vs assistant)"] --> G["OpenAI-compatible Response"]

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Validate schema in API (jsonschema) instead of CLI --json-schema

• ➕ Avoids large JSON payloads on the process command line
• ➕ Keeps schema enforcement consistent even if CLI flags change
• ➕ Can return richer 4xx validation errors to clients
• ➖ Duplicates validation logic that the CLI already provides
• ➖ Requires choosing/maintaining a JSON Schema validator and versioning behavior
• ➖ Does not guarantee the CLI-produced output is the same as validated output

2. Pass schema via temp file or stdin instead of command-line argument

• ➕ Avoids command-line length limits and shell/history leakage concerns
• ➕ Keeps runtime behavior the same while improving robustness
• ➖ More implementation complexity (temp-file lifecycle, permissions, Windows quirks)
• ➖ Harder to debug without careful logging/redaction

Recommendation: Current approach (forwarding response_format.json_schema to the Claude Code CLI and preferring the CLI’s final result) is the right default because it aligns behavior with the underlying tool’s structured-output enforcement. Consider a follow-up to pass the schema via temp file/stdin if large schemas or command-line size limits become a concern.

Files changed (5) +151 / -10

Enhancement (4) +118 / -10

chat.pyExtract response_format.json_schema and plumb prefer_result_content +34/-3

Extract response_format.json_schema and plumb prefer_result_content

• Adds request parsing for response_format.type='json_schema' and errors when the schema payload is missing. Passes the extracted schema into session creation and toggles streaming/non-streaming response building to prefer the CLI’s validated 'result' content when a schema is used.

claude_code_api/api/chat.py

claude_manager.pyAdd --json-schema support when launching Claude Code subprocess +9/-1

Add --json-schema support when launching Claude Code subprocess

• Extends Claude process startup/session creation to accept an optional json_schema dict and serialize it into the CLI command via --json-schema. Updates command redaction logic to avoid logging schema content.

claude_code_api/core/claude_manager.py

openai.pyAdd ResponseFormat + JSONSchemaSpec models to ChatCompletionRequest +34/-0

Add ResponseFormat + JSONSchemaSpec models to ChatCompletionRequest

• Introduces OpenAI-compatible response_format modeling, including a JSONSchemaSpec with alias handling for the 'schema' field. Extends ChatCompletionRequest to accept response_format for structured output requests.

claude_code_api/models/openai.py

streaming.pyPrefer CLI 'result' payload for schema-based structured output +41/-6

Prefer CLI 'result' payload for schema-based structured output

• Adds a prefer_result_content flag through the streaming converter/manager and non-streaming response builder. When enabled, extracts the final 'result' message payload and uses it as assistant content, improving correctness for --json-schema validated outputs.

claude_code_api/utils/streaming.py

Other (1) +33 / -0

custom.ymlAdd docker compose template for running claude-code-api locally +33/-0

Add docker compose template for running claude-code-api locally

• Adds a compose file that builds the API image, binds API/OAuth proxy ports to localhost, sets Claude Max + workspace/OAuth proxy env vars, and persists Claude config via volumes with a healthcheck.

docker/custom.yml

[sourcery-ai]

Hey - I've left some high level feedback:

• The new JSONSchemaSpec.strict field is accepted but never used downstream; consider either wiring this through to CLI invocation/validation or removing it to avoid implying behavior that doesn’t exist.
• The prefer_result_content flag currently switches content based solely on json_schema is not None; if you anticipate other future uses of response_format, you may want a more explicit check (e.g., response_format.type == 'json_schema') to avoid accidentally changing behavior for non-schema formats.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- The new `JSONSchemaSpec.strict` field is accepted but never used downstream; consider either wiring this through to CLI invocation/validation or removing it to avoid implying behavior that doesn’t exist.
- The `prefer_result_content` flag currently switches content based solely on `json_schema is not None`; if you anticipate other future uses of `response_format`, you may want a more explicit check (e.g., `response_format.type == 'json_schema'`) to avoid accidentally changing behavior for non-schema formats.

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[qodo-free-for-open-source-projects]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0) 🎨 UX issues (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

1. Undefined input error ✓ Resolved 🐞 Bug ≡ Correctness

Description

_extract_json_schema() raises _input_error(...), but _input_error is not defined anywhere, so
the API will raise NameError instead of returning a 4xx when response_format.type='json_schema'
is provided without json_schema. This is a runtime crash on a reachable validation path.

Code

claude_code_api/api/chat.py[R98-101]

+        raise _input_error(
+            "response_format.type is 'json_schema' but no json_schema was provided.",
+            "missing_json_schema",
+        )

Evidence

_extract_json_schema() calls _input_error(...) on missing schema, but the only error helper
defined in this module is _http_error(...) and there is no _input_error definition in the file.

claude_code_api/api/chat.py[57-63]
claude_code_api/api/chat.py[93-102]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`_extract_json_schema()` calls `_input_error(...)`, but the module only defines `_http_error(...)`. This will raise `NameError` instead of producing a client-facing error response.
### Issue Context
The API already uses `_http_error(...)` for other request validation failures; this new structured-output validation should follow the same pattern.
### Fix Focus Areas
- claude_code_api/api/chat.py[93-103]
- claude_code_api/api/chat.py[57-63]
### Suggested fix
Replace the `_input_error(...)` call with `_http_error(status.HTTP_400_BAD_REQUEST, ..., "invalid_request_error", "missing_json_schema")` (or add/define an `_input_error` helper that wraps `_http_error` with the correct status/type/code).

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Result duplicated in stream ✓ Resolved 🐞 Bug ≡ Correctness

Description

When prefer_result_content is enabled, streaming still emits assistant text chunks and then emits
message.result as an additional content chunk at the final message, so clients may receive
concatenated assistant text + result instead of just the schema-validated result. This can break
consumers expecting valid JSON-only structured output in streaming mode.

Code

claude_code_api/utils/streaming.py[R144-148]

+                    if self.prefer_result_content and message.result:
+                        yield SSEFormatter.format_event(
+                            self._build_chunk({"content": message.result.strip()})
+                        )
+                        saw_assistant_text = True

Evidence

The stream converter always yields assistant content/tool chunks for assistant messages, and then
(new behavior) yields message.result on the final message when prefer_result_content is set;
fixtures show typical streams include both assistant text and a final result field, so this will
produce mixed output.

claude_code_api/utils/streaming.py[94-149]
tests/fixtures/claude_stream_simple.jsonl[1-3]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
In `OpenAIStreamConverter.convert_stream()`, assistant message text is streamed as it arrives. When `prefer_result_content` is enabled, the code additionally streams the final `result` payload as another content delta. If the underlying CLI emits both assistant text and a final `result` (common), OpenAI clients will concatenate both and structured output becomes invalid.
### Issue Context
Non-streaming mode overwrites the final content with the extracted `result` when `prefer_result_content=True`, but streaming mode currently *appends* it.
### Fix Focus Areas
- claude_code_api/utils/streaming.py[94-149]
- tests/fixtures/claude_stream_simple.jsonl[1-3]
### Suggested fix
When `prefer_result_content=True`:
- Do **not** emit assistant text `content` deltas (either skip them entirely, or buffer and only emit the final result).
- Optionally still emit `tool_calls` deltas if they occur.
- Emit exactly one final `content` delta derived from the `result` payload (and then the normal finish_reason/[DONE]).

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

3. json_schema kwarg breaks fakes ✓ Resolved 🐞 Bug ☼ Reliability

Description

ClaudeManager now always calls process.start(..., json_schema=json_schema) even when
json_schema is None, which breaks existing test monkeypatches/fakes that still implement the old
start(prompt, model=None, system_prompt=None) signature. This will fail the unit test suite with
TypeError: unexpected keyword argument 'json_schema' on code paths that don’t use schemas.

Code

claude_code_api/core/claude_manager.py[462]

+                json_schema=json_schema,

Evidence

ClaudeManager now passes the json_schema keyword into process.start(), while unit tests
monkeypatch ClaudeProcess.start with a function that does not accept that keyword, making those
tests fail as soon as create_session() is exercised.

claude_code_api/core/claude_manager.py[439-463]
tests/test_claude_manager_unit.py[54-63]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`ClaudeManager._start_with_fallback_models()` passes the `json_schema` keyword argument unconditionally (even when `None`). Existing monkeypatched `ClaudeProcess.start` implementations in tests (and any other adapters) that don't accept this kwarg will raise `TypeError`.
### Issue Context
The real `ClaudeProcess.start()` was updated to accept `json_schema`, but your tests patch `ClaudeProcess.start` with the old signature.
### Fix Focus Areas
- claude_code_api/core/claude_manager.py[439-463]
- tests/test_claude_manager_unit.py[54-90]
### Suggested fix
In `_start_with_fallback_models()`, build kwargs and only include `json_schema` when it is not `None` (so normal non-schema flows remain backward compatible with older fakes). Optionally also update test fakes to accept `json_schema=None` or `**kwargs` to be resilient.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---