docent-python 0.1.44a0__tar.gz → 0.1.46a0__tar.gz

{docent_python-0.1.44a0 → docent_python-0.1.46a0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docent-python
-Version: 0.1.44a0
+Version: 0.1.46a0
 Summary: Docent SDK
 Project-URL: Homepage, https://github.com/TransluceAI/docent
 Project-URL: Issues, https://github.com/TransluceAI/docent/issues

{docent_python-0.1.44a0 → docent_python-0.1.46a0}/docent/_llm_util/data_models/llm_output.py

@@ -62,6 +62,7 @@ class LLMCompletion(BaseModel):
         tool_calls: List of tool calls made during the completion.
         finish_reason: Reason why the completion finished.
         top_logprobs: Probability distribution for top token choices.
+        reasoning_tokens: Extended thinking tokens (for reasoning models).
     """
 
     text: str | None = None

{docent_python-0.1.44a0 → docent_python-0.1.46a0}/docent/_llm_util/llm_cache.py

@@ -9,6 +9,7 @@ from typing import Literal
 from docent._llm_util.data_models.llm_output import LLMOutput
 from docent._log_util import get_logger
 from docent.data_models.chat import ChatMessage, ToolInfo
+from docent.data_models.chat.response_format import ResponseFormat
 
 logger = get_logger(__name__)
 
@@ -59,6 +60,7 @@ class LLMCache:
         temperature: float = 1.0,
         logprobs: bool = False,
         top_logprobs: int | None = None,
+        response_format: ResponseFormat | None = None,
     ) -> str:
         """Create a deterministic hash key from messages and model."""
         # Convert messages to a stable string representation
@@ -71,10 +73,15 @@ class LLMCache:
             json.dumps([tool.model_dump() for tool in tools], sort_keys=True) if tools else None
         )
 
-        # Combine all parameters into a single string
-        key_str = (
-            f"{message_str}:{model_name}:{tools_str}:{tool_choice}:{reasoning_effort}:{temperature}"
+        # Convert response_format to a stable string representation if present
+        response_format_str = (
+            json.dumps(response_format.model_dump(by_alias=True), sort_keys=True)
+            if response_format
+            else None
         )
+
+        # Combine all parameters into a single string
+        key_str = f"{message_str}:{model_name}:{tools_str}:{tool_choice}:{reasoning_effort}:{temperature}:{response_format_str}"
         if logprobs:
             key_str += f":{top_logprobs}"
         return hashlib.sha256(key_str.encode()).hexdigest()
@@ -90,6 +97,7 @@ class LLMCache:
         temperature: float = 1.0,
         logprobs: bool = False,
         top_logprobs: int | None = None,
+        response_format: ResponseFormat | None = None,
     ) -> LLMOutput | None:
         """Get cached completion for a conversation if it exists."""
 
@@ -102,6 +110,7 @@ class LLMCache:
             temperature=temperature,
             logprobs=logprobs,
             top_logprobs=top_logprobs,
+            response_format=response_format,
         )
 
         with self._get_connection() as conn:
@@ -125,6 +134,7 @@ class LLMCache:
         temperature: float = 1.0,
         logprobs: bool = False,
         top_logprobs: int | None = None,
+        response_format: ResponseFormat | None = None,
     ) -> None:
         """Cache a completion for a conversation."""
 
@@ -137,6 +147,7 @@ class LLMCache:
             temperature=temperature,
             logprobs=logprobs,
             top_logprobs=top_logprobs,
+            response_format=response_format,
         )
 
         with self._get_connection() as conn:
@@ -158,6 +169,7 @@ class LLMCache:
         temperature: float = 1.0,
         logprobs: bool = False,
         top_logprobs: int | None = None,
+        response_format: ResponseFormat | None = None,
     ) -> None:
         """Cache a completion for a conversation."""
 
@@ -172,6 +184,7 @@ class LLMCache:
                 temperature=temperature,
                 logprobs=logprobs,
                 top_logprobs=top_logprobs,
+                response_format=response_format,
             )
             keys.append(key)
 

{docent_python-0.1.44a0 → docent_python-0.1.46a0}/docent/_llm_util/llm_svc.py

@@ -37,6 +37,7 @@ from docent._llm_util.providers.provider_registry import (
 )
 from docent._log_util import get_logger
 from docent.data_models.chat import ChatMessage, ToolInfo, parse_chat_message
+from docent.data_models.chat.response_format import ResponseFormat
 
 logger = get_logger(__name__)
 
@@ -90,6 +91,7 @@ async def _parallelize_calls(
     semaphore: Semaphore,
     # use_tqdm: bool,
     cache: LLMCache | None = None,
+    response_format: ResponseFormat | None = None,
 ):
     base_func = partial(
         single_output_getter,
@@ -103,6 +105,7 @@ async def _parallelize_calls(
         logprobs=logprobs,
         top_logprobs=top_logprobs,
         timeout=timeout,
+        response_format=response_format,
     )
 
     responses: list[LLMOutput | None] = [None for _ in inputs]
@@ -143,6 +146,7 @@ async def _parallelize_calls(
                     temperature=temperature,
                     logprobs=logprobs,
                     top_logprobs=top_logprobs,
+                    response_format=response_format,
                 )
                 if cache is not None
                 else None
@@ -271,6 +275,7 @@ async def _parallelize_calls(
                 temperature=temperature,
                 logprobs=logprobs,
                 top_logprobs=top_logprobs,
+                response_format=response_format,
             )
             return len(indices)
         else:
@@ -351,6 +356,7 @@ class BaseLLMService:
         validation_callback: AsyncLLMOutputStreamingCallback | None = None,
         completion_callback: AsyncLLMOutputStreamingCallback | None = None,
         use_cache: bool = False,
+        response_format: ResponseFormat | None = None,
         _api_key_overrides: dict[str, str] = dict(),
     ) -> list[LLMOutput]:
         """Request completions from a configured LLM provider."""
@@ -424,6 +430,7 @@ class BaseLLMService:
                 timeout=timeout,
                 semaphore=self._semaphore,
                 cache=cache,
+                response_format=response_format,
             )
             assert len(outputs) == len(inputs), "Number of outputs must match number of messages"
 

{docent_python-0.1.44a0 → docent_python-0.1.46a0}/docent/_llm_util/providers/anthropic.py

@@ -5,6 +5,7 @@ import backoff
 # all errors: https://docs.anthropic.com/en/api/errors
 from anthropic import (
     AsyncAnthropic,
+    AsyncStream,
     AuthenticationError,
     BadRequestError,
     NotFoundError,
@@ -12,7 +13,6 @@ from anthropic import (
     RateLimitError,
     UnprocessableEntityError,
 )
-from anthropic._types import NOT_GIVEN
 from anthropic.types import (
     InputJSONDelta,
     Message,
@@ -70,6 +70,7 @@ from docent.data_models.chat import (
     ToolInfo,
     ToolMessage,
 )
+from docent.data_models.chat.response_format import ResponseFormat
 
 logger = get_logger(__name__)
 
@@ -217,34 +218,43 @@ async def get_anthropic_chat_completion_streaming_async(
     logprobs: bool = False,
     top_logprobs: int | None = None,
     timeout: float = 5.0,
+    response_format: ResponseFormat | None = None,
 ):
+    if response_format is not None:
+        raise NotImplementedError(
+            "Structured outputs (response_format) are not implemented for Anthropic yet."
+        )
     if logprobs or top_logprobs is not None:
         raise NotImplementedError(
             "We have not implemented logprobs or top_logprobs for Anthropic yet."
         )
 
     system, input_messages = parse_chat_messages(messages)
-    input_tools = parse_tools(tools) if tools else NOT_GIVEN
 
     try:
         async with async_timeout_ctx(timeout):
-            stream = await client.messages.create(
-                model=model_name,
-                messages=input_messages,
-                thinking=(
-                    {
-                        "type": "enabled",
-                        "budget_tokens": reasoning_budget(max_new_tokens, reasoning_effort),
-                    }
-                    if reasoning_effort
-                    else NOT_GIVEN
-                ),
-                tools=input_tools,
-                tool_choice=_parse_tool_choice(tool_choice) or NOT_GIVEN,
-                max_tokens=max_new_tokens,
-                temperature=temperature,
-                system=system if system is not None else NOT_GIVEN,
-                stream=True,
+            create_kwargs: dict[str, Any] = {
+                "model": model_name,
+                "messages": input_messages,
+                "max_tokens": max_new_tokens,
+                "temperature": temperature,
+                "stream": True,
+            }
+            if reasoning_effort:
+                create_kwargs["thinking"] = {
+                    "type": "enabled",
+                    "budget_tokens": reasoning_budget(max_new_tokens, reasoning_effort),
+                }
+            if tools:
+                create_kwargs["tools"] = parse_tools(tools)
+            if tool_choice_param := _parse_tool_choice(tool_choice):
+                create_kwargs["tool_choice"] = tool_choice_param
+            if system is not None:
+                create_kwargs["system"] = system
+
+            stream = cast(
+                AsyncStream[RawMessageStreamEvent],
+                await client.messages.create(**create_kwargs),
             )
 
             llm_output_partial = None
@@ -399,6 +409,7 @@ async def get_anthropic_chat_completion_async(
     logprobs: bool = False,
     top_logprobs: int | None = None,
     timeout: float = 5.0,
+    response_format: ResponseFormat | None = None,
 ) -> LLMOutput:
     """
     Note from kevin 1/29/2025:
@@ -409,33 +420,38 @@ async def get_anthropic_chat_completion_async(
         We should actually implement this at some point, but it does not work.
     """
 
+    if response_format is not None:
+        raise NotImplementedError(
+            "Structured outputs (response_format) are not implemented for Anthropic yet."
+        )
     if logprobs or top_logprobs is not None:
         raise NotImplementedError(
             "We have not implemented logprobs or top_logprobs for Anthropic yet."
         )
 
     system, input_messages = parse_chat_messages(messages)
-    input_tools = parse_tools(tools) if tools else NOT_GIVEN
 
     try:
         async with async_timeout_ctx(timeout):
-            raw_output = await client.messages.create(
-                model=model_name,
-                messages=input_messages,
-                thinking=(
-                    {
-                        "type": "enabled",
-                        "budget_tokens": reasoning_budget(max_new_tokens, reasoning_effort),
-                    }
-                    if reasoning_effort
-                    else NOT_GIVEN
-                ),
-                tools=input_tools,
-                tool_choice=_parse_tool_choice(tool_choice) or NOT_GIVEN,
-                max_tokens=max_new_tokens,
-                temperature=temperature,
-                system=system if system is not None else NOT_GIVEN,
-            )
+            create_kwargs: dict[str, Any] = {
+                "model": model_name,
+                "messages": input_messages,
+                "max_tokens": max_new_tokens,
+                "temperature": temperature,
+            }
+            if reasoning_effort:
+                create_kwargs["thinking"] = {
+                    "type": "enabled",
+                    "budget_tokens": reasoning_budget(max_new_tokens, reasoning_effort),
+                }
+            if tools:
+                create_kwargs["tools"] = parse_tools(tools)
+            if tool_choice_param := _parse_tool_choice(tool_choice):
+                create_kwargs["tool_choice"] = tool_choice_param
+            if system is not None:
+                create_kwargs["system"] = system
+
+            raw_output = cast(Message, await client.messages.create(**create_kwargs))
 
             output = parse_anthropic_completion(raw_output, model_name)
             if output.first and output.first.finish_reason == "length" and output.first.no_text:

{docent_python-0.1.44a0 → docent_python-0.1.46a0}/docent/_llm_util/providers/google.py

@@ -28,6 +28,7 @@ from docent._llm_util.providers.common import (
 )
 from docent._log_util import get_logger
 from docent.data_models.chat import ChatMessage, Content, ContentText, ToolCall, ToolInfo
+from docent.data_models.chat.response_format import ResponseFormat
 
 
 def get_google_client_async(api_key: str | None = None) -> AsyncGoogle:
@@ -82,7 +83,12 @@ async def get_google_chat_completion_async(
     logprobs: bool = False,
     top_logprobs: int | None = None,
     timeout: float = 5.0,
+    response_format: ResponseFormat | None = None,
 ) -> LLMOutput:
+    if response_format is not None:
+        raise NotImplementedError(
+            "Structured outputs (response_format) are not implemented for Google yet."
+        )
     if logprobs or top_logprobs is not None:
         raise NotImplementedError(
             "We have not implemented logprobs or top_logprobs for Google yet."
@@ -145,7 +151,12 @@ async def get_google_chat_completion_streaming_async(
     logprobs: bool = False,
     top_logprobs: int | None = None,
     timeout: float = 5.0,
+    response_format: ResponseFormat | None = None,
 ) -> LLMOutput:
+    if response_format is not None:
+        raise NotImplementedError(
+            "Structured outputs (response_format) are not implemented for Google yet."
+        )
     if logprobs or top_logprobs is not None:
         raise NotImplementedError(
             "We have not implemented logprobs or top_logprobs for Google yet."

{docent_python-0.1.44a0 → docent_python-0.1.46a0}/docent/_llm_util/providers/openai.py

@@ -40,6 +40,10 @@ from openai.types.chat.chat_completion_message_tool_call_param import (
     Function as OpenAIFunctionParam,
 )
 from openai.types.shared_params.function_definition import FunctionDefinition
+from openai.types.shared_params.response_format_json_schema import (
+    JSONSchema,
+    ResponseFormatJSONSchema,
+)
 
 from docent._llm_util.data_models.exceptions import (
     CompletionTooLongException,
@@ -70,6 +74,7 @@ from docent.data_models.chat import (
     ToolInfo,
     ToolMessage,
 )
+from docent.data_models.chat.response_format import ResponseFormat
 
 logger = get_logger(__name__)
 DEFAULT_TIKTOKEN_ENCODING = "cl100k_base"
@@ -194,6 +199,42 @@ def parse_tools(tools: list[ToolInfo]) -> list[ChatCompletionToolParam]:
     return result
 
 
+def _build_response_format(
+    response_format: ResponseFormat | None,
+) -> ResponseFormatJSONSchema | None:
+    """Build OpenAI response_format dict from unified ResponseFormat.
+
+    Converts the unified ResponseFormat specification to OpenAI's
+    expected response_format structure for structured outputs.
+
+    Args:
+        response_format: The unified response format specification, or None.
+
+    Returns:
+        OpenAI response_format dict if provided, empty dict otherwise.
+
+    Raises:
+        ValueError: If response_format.type is not 'json_schema'.
+    """
+    if response_format is None:
+        return None
+
+    if response_format.type != "json_schema":
+        raise ValueError(
+            f"Unsupported response format type: {response_format.type}. "
+            "Only 'json_schema' is currently supported."
+        )
+
+    return ResponseFormatJSONSchema(
+        type="json_schema",
+        json_schema=JSONSchema(
+            name=response_format.name,
+            strict=response_format.strict,
+            schema=response_format.schema_,
+        ),
+    )
+
+
 @backoff.on_exception(
     backoff.expo,
     exception=(Exception,),
@@ -215,16 +256,14 @@ async def get_openai_chat_completion_streaming_async(
     logprobs: bool = False,
     top_logprobs: int | None = None,
     timeout: float = 30.0,
+    response_format: ResponseFormat | None = None,
 ):
-    input_messages = parse_chat_messages(messages)
-    input_tools = parse_tools(tools) if tools else omit
-
     try:
         async with async_timeout_ctx(timeout):
             stream = await client.chat.completions.create(
                 model=model_name,
-                messages=input_messages,
-                tools=input_tools,
+                messages=parse_chat_messages(messages),
+                tools=parse_tools(tools) if tools else omit,
                 tool_choice=tool_choice or omit,
                 max_completion_tokens=max_new_tokens,
                 temperature=temperature,
@@ -233,6 +272,7 @@ async def get_openai_chat_completion_streaming_async(
                 top_logprobs=top_logprobs,
                 stream_options={"include_usage": True},
                 stream=True,
+                response_format=_build_response_format(response_format) or omit,
             )
 
             llm_output_partial = None
@@ -406,22 +446,21 @@ async def get_openai_chat_completion_async(
     logprobs: bool = False,
     top_logprobs: int | None = None,
     timeout: float = 5.0,
+    response_format: ResponseFormat | None = None,
 ) -> LLMOutput:
-    input_messages = parse_chat_messages(messages)
-    input_tools = parse_tools(tools) if tools else omit
-
     try:
         async with async_timeout_ctx(timeout):  # type: ignore
             raw_output = await client.chat.completions.create(
                 model=model_name,
-                messages=input_messages,
-                tools=input_tools,
+                messages=parse_chat_messages(messages),
+                tools=parse_tools(tools) if tools else omit,
                 tool_choice=tool_choice or omit,
                 max_completion_tokens=max_new_tokens,
                 temperature=temperature,
                 reasoning_effort=reasoning_effort or omit,
                 logprobs=logprobs,
                 top_logprobs=top_logprobs,
+                response_format=_build_response_format(response_format) or omit,
             )
 
             # If the completion is empty and was truncated (likely due to too much reasoning), raise an exception

{docent_python-0.1.44a0 → docent_python-0.1.46a0}/docent/_llm_util/providers/openrouter.py

@@ -31,6 +31,7 @@ from docent.data_models.chat import (
     ToolInfo,
     ToolMessage,
 )
+from docent.data_models.chat.response_format import ResponseFormat
 
 logger = get_logger(__name__)
 
@@ -59,6 +60,7 @@ class OpenRouterClient:
         max_tokens: int = 32,
         temperature: float = 1.0,
         timeout: float = 30.0,
+        response_format: dict[str, Any] | None = None,
     ) -> dict[str, Any]:
         """Make an async chat completion request."""
         url = f"{self.base_url}/chat/completions"
@@ -74,6 +76,8 @@ class OpenRouterClient:
             payload["tools"] = tools
         if tool_choice:
             payload["tool_choice"] = tool_choice
+        if response_format:
+            payload["response_format"] = response_format
 
         async with aiohttp.ClientSession() as session:
             async with session.post(
@@ -203,6 +207,37 @@ def parse_tools(tools: list[ToolInfo]) -> list[dict[str, Any]]:
     return result
 
 
+def _build_response_format(response_format: ResponseFormat | None) -> dict[str, Any] | None:
+    """Convert ResponseFormat to OpenRouter's response_format parameter.
+
+    Args:
+        response_format: The unified response format specification.
+
+    Returns:
+        OpenRouter-formatted response_format dict, or None if not provided.
+
+    Raises:
+        ValueError: If response_format.type is not a supported format type.
+    """
+    if response_format is None:
+        return None
+
+    if response_format.type != "json_schema":
+        raise ValueError(
+            f"Unsupported response format type: {response_format.type}. "
+            "Only 'json_schema' is currently supported."
+        )
+
+    return {
+        "type": "json_schema",
+        "json_schema": {
+            "name": response_format.name,
+            "strict": response_format.strict,
+            "schema": response_format.schema_,
+        },
+    }
+
+
 def _parse_openrouter_tool_call(tc: dict[str, Any]) -> ToolCall:
     """Parse tool call from OpenRouter response."""
     if tc.get("type") != "function":
@@ -232,7 +267,10 @@ def _parse_openrouter_tool_call(tc: dict[str, Any]) -> ToolCall:
     )
 
 
-def parse_openrouter_completion(response: dict[str, Any], model: str) -> LLMOutput:
+def parse_openrouter_completion(
+    response: dict[str, Any],
+    model: str,
+) -> LLMOutput:
     """Parse OpenRouter completion response."""
     choices = response.get("choices", [])
     if not choices:
@@ -252,10 +290,11 @@ def parse_openrouter_completion(response: dict[str, Any], model: str) -> LLMOutp
     for choice in choices:
         message = choice.get("message", {})
         tool_calls_data = message.get("tool_calls")
+        content = message.get("content")
 
         completions.append(
             LLMCompletion(
-                text=message.get("content"),
+                text=content,
                 finish_reason=choice.get("finish_reason"),
                 tool_calls=(
                     [_parse_openrouter_tool_call(tc) for tc in tool_calls_data]
@@ -292,6 +331,7 @@ async def get_openrouter_chat_completion_async(
     logprobs: bool = False,
     top_logprobs: int | None = None,
     timeout: float = 30.0,
+    response_format: ResponseFormat | None = None,
 ) -> LLMOutput:
     """Get completion from OpenRouter."""
     if logprobs or top_logprobs is not None:
@@ -304,6 +344,7 @@ async def get_openrouter_chat_completion_async(
 
     input_messages = parse_chat_messages(messages)
     input_tools = parse_tools(tools) if tools else None
+    input_response_format = _build_response_format(response_format)
 
     response = await client.chat_completions_create(
         model=model_name,
@@ -313,6 +354,7 @@ async def get_openrouter_chat_completion_async(
         max_tokens=max_new_tokens,
         temperature=temperature,
         timeout=timeout,
+        response_format=input_response_format,
     )
 
     output = parse_openrouter_completion(response, model_name)
@@ -346,6 +388,7 @@ async def get_openrouter_chat_completion_streaming_async(
     logprobs: bool = False,
     top_logprobs: int | None = None,
     timeout: float = 30.0,
+    response_format: ResponseFormat | None = None,
 ) -> LLMOutput:
     """Get streaming completion from OpenRouter (falls back to non-streaming)."""
     logger.warning("Streaming not yet implemented for OpenRouter, using non-streaming.")
@@ -362,6 +405,7 @@ async def get_openrouter_chat_completion_streaming_async(
         logprobs=logprobs,
         top_logprobs=top_logprobs,
         timeout=timeout,
+        response_format=response_format,
     )
 
 

{docent_python-0.1.44a0 → docent_python-0.1.46a0}/docent/_llm_util/providers/provider_registry.py

@@ -26,6 +26,7 @@ from docent._llm_util.providers.openrouter import (
     get_openrouter_chat_completion_streaming_async,
 )
 from docent.data_models.chat import ChatMessage, ToolInfo
+from docent.data_models.chat.response_format import ResponseFormat
 
 
 class SingleOutputGetter(Protocol):
@@ -49,6 +50,7 @@ class SingleOutputGetter(Protocol):
         logprobs: bool,
         top_logprobs: int | None,
         timeout: float,
+        response_format: ResponseFormat | None,
     ) -> LLMOutput:
         """Get a single completion from an LLM.
 
@@ -64,6 +66,7 @@ class SingleOutputGetter(Protocol):
             logprobs: Whether to return log probabilities.
             top_logprobs: Number of most likely tokens to return probabilities for.
             timeout: Maximum time to wait for a response in seconds.
+            response_format: Optional structured output format specification.
 
         Returns:
             LLMOutput: The model's response.
@@ -93,6 +96,7 @@ class SingleStreamingOutputGetter(Protocol):
         logprobs: bool,
         top_logprobs: int | None,
         timeout: float,
+        response_format: ResponseFormat | None,
     ) -> LLMOutput:
         """Get a streaming completion from an LLM.
 
@@ -109,6 +113,7 @@ class SingleStreamingOutputGetter(Protocol):
             logprobs: Whether to return log probabilities.
             top_logprobs: Number of most likely tokens to return probabilities for.
             timeout: Maximum time to wait for a response in seconds.
+            response_format: Optional structured output format specification.
 
         Returns:
             LLMOutput: The complete model response after streaming finishes.

{docent_python-0.1.44a0 → docent_python-0.1.46a0}/docent/data_models/chat/__init__.py

@@ -10,6 +10,7 @@ from docent.data_models.chat.message import (
     parse_chat_message,
     parse_docent_chat_message,
 )
+from docent.data_models.chat.response_format import ResponseFormat
 from docent.data_models.chat.tool import (
     ToolCall,
     ToolCallContent,
@@ -28,6 +29,7 @@ __all__ = [
     "Content",
     "ContentReasoning",
     "ContentText",
+    "ResponseFormat",
     "ToolCall",
     "ToolCallContent",
     "ToolInfo",

docent_python-0.1.46a0/docent/data_models/chat/response_format.py

@@ -0,0 +1,47 @@
+"""Response format specification for structured outputs."""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+
+class ResponseFormat(BaseModel):
+    """Unified response format specification for structured outputs.
+
+    Supports JSON Schema-based constrained decoding across LLM providers.
+    Each provider converts this to their specific format:
+    - OpenAI: response_format parameter
+    - Anthropic: output_format parameter (with beta header)
+    - OpenRouter: response_format parameter (same as OpenAI)
+
+    Attributes:
+        type: The format type. Currently only "json_schema" is supported.
+        name: A name for the schema (required by all providers).
+        schema_: The JSON Schema definition as a dict.
+        strict: Whether to enforce strict schema adherence (default True).
+
+    Example:
+        ```python
+        response_format = ResponseFormat(
+            name="analysis_result",
+            schema={
+                "type": "object",
+                "properties": {
+                    "score": {"type": "number"},
+                    "explanation": {"type": "string"},
+                },
+                "required": ["score", "explanation"],
+            },
+        )
+        ```
+    """
+
+    type: Literal["json_schema"] = "json_schema"
+    name: str
+    # Named `schema_` to avoid conflict with Pydantic's internal schema methods
+    schema_: dict[str, Any] = Field(alias="schema")
+    strict: bool = True
+
+    model_config = {"populate_by_name": True}