Add structured output

Author: Solveit

00_core.ipynb

@@ -73,6 +73,7 @@
     "from anthropic.types import (Usage, TextBlock, ServerToolUseBlock,\n",
     "                             WebSearchToolResultBlock, Message, ToolUseBlock,\n",
     "                             ThinkingBlock, ServerToolUsage)\n",
+    "from anthropic.types.beta import (BetaMessage)\n",
     "from anthropic.resources import messages\n",
     "\n",
     "import toolslm\n",
@@ -533,7 +534,7 @@
     "This is the first exported public function or class we're creating (the previous export was of a variable). In the rendered version of the notebook for these you'll see 4 things, in this order (unless the symbol starts with a single `_`, which indicates it's *private*):\n",
     "\n",
     "- The signature (with the symbol name as a heading, with a horizontal rule above)\n",
-    "- A table of paramater docs (if provided)\n",
+    "- A table of parameter docs (if provided)\n",
     "- The doc string (in italics).\n",
     "- The source code (in a collapsible \"Exported source\" block)\n",
     "\n",
@@ -646,7 +647,7 @@
    "source": [
     "#| exports\n",
     "@patch\n",
-    "def _repr_markdown_(self:(Message)):\n",
+    "def _repr_markdown_(self:(Message,BetaMessage)):\n",
     "    det = '\\n- '.join(f'{k}: `{v}`' for k,v in self.model_dump().items())\n",
     "    cts = re.sub(r'\\$', '$', contents(self))  # escape `$` for jupyter latex\n",
     "    return f\"\"\"{cts}\n",
@@ -1145,7 +1146,8 @@
     "        self.model,self.use = model,usage()\n",
     "        self.text_only = model in text_only_models\n",
     "        self.log = [] if log else None\n",
-    "        self.c = (cli or Anthropic(default_headers={'anthropic-beta': 'prompt-caching-2024-07-31'}))\n",
+    "        betas = ['prompt-caching-2024-07-31', 'structured-outputs-2025-11-13']\n",
+    "        self.c = (cli or Anthropic(default_headers={'anthropic-beta': ','.join(betas)}))\n",
     "        self.cache = cache"
    ]
   },
@@ -1376,9 +1378,10 @@
     "#| exports\n",
     "@patch\n",
     "def _precall(self:Client, msgs, prefill, sp, temp, maxtok, maxthinktok, stream,\n",
-    "             stop, tools, tool_choice, kwargs):\n",
+    "             stop, tools, tool_choice, output_format, kwargs):\n",
     "    if tools: kwargs['tools'] = [get_schema(o) if callable(o) else o for o in listify(tools)]\n",
     "    if tool_choice: kwargs['tool_choice'] = mk_tool_choice(tool_choice)\n",
+    "    if output_format: kwargs['output_format'] = output_format\n",
     "    if maxthinktok: \n",
     "        kwargs['thinking'] = {'type':'enabled', 'budget_tokens':maxthinktok} \n",
     "        temp,prefill = 1,''\n",
@@ -1414,12 +1417,13 @@
     "             stop=None, # Stop sequence\n",
     "             tools:Optional[list]=None, # List of tools to make available to Claude\n",
     "             tool_choice:Optional[dict]=None, # Optionally force use of some tool\n",
+    "             output_format:Optional[dict]=None, # Optionally force output to conform with a JSON schema\n",
     "             cb=None, # Callback to pass result to when complete\n",
     "             **kwargs):\n",
     "    \"Make a call to Claude.\"\n",
     "    msgs,kwargs = self._precall(msgs, prefill, sp, temp, maxtok, maxthinktok, stream,\n",
-    "                                stop, tools, tool_choice, kwargs)\n",
-    "    m = self.c.messages\n",
+    "                                stop, tools, tool_choice, output_format, kwargs)\n",
+    "    m = self.c.beta.messages if output_format else self.c.messages\n",
     "    f = m.stream if stream else m.create\n",
     "    res = f(model=self.model, messages=msgs, **kwargs)\n",
     "    def _cb(v):\n",
@@ -1846,6 +1850,72 @@
     "print(c.stop_reason, c.stop_sequence)"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "17fa5c5f",
+   "metadata": {},
+   "source": [
+    "We can force the next message to be [structured output](https://docs.claude.com/en/docs/build-with-claude/structured-outputs) based on a JSON schema we provide."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "feb75ba4",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/markdown": [
+       "{\"first_name\":\"Johno\",\"last_name\":\"Ohjohn\"}\n",
+       "\n",
+       "<details>\n",
+       "\n",
+       "- id: `msg_019Jy7ge2pTDFih4Zt5kCUvS`\n",
+       "- container: `None`\n",
+       "- content: `[{'citations': None, 'text': '{\"first_name\":\"Johno\",\"last_name\":\"Ohjohn\"}', 'type': 'text'}]`\n",
+       "- context_management: `None`\n",
+       "- model: `claude-sonnet-4-5-20250929`\n",
+       "- role: `assistant`\n",
+       "- stop_reason: `end_turn`\n",
+       "- stop_sequence: `None`\n",
+       "- type: `message`\n",
+       "- usage: `{'cache_creation': {'ephemeral_1h_input_tokens': 0, 'ephemeral_5m_input_tokens': 0}, 'cache_creation_input_tokens': 0, 'cache_read_input_tokens': 0, 'input_tokens': 193, 'output_tokens': 21, 'server_tool_use': None, 'service_tier': 'standard'}`\n",
+       "\n",
+       "</details>"
+      ],
+      "text/plain": [
+       "BetaMessage(id='msg_019Jy7ge2pTDFih4Zt5kCUvS', container=None, content=[BetaTextBlock(citations=None, text='{\"first_name\":\"Johno\",\"last_name\":\"Ohjohn\"}', type='text')], context_management=None, model='claude-sonnet-4-5-20250929', role='assistant', stop_reason='end_turn', stop_sequence=None, type='message', usage=BetaUsage(cache_creation=BetaCacheCreation(ephemeral_1h_input_tokens=0, ephemeral_5m_input_tokens=0), cache_creation_input_tokens=0, cache_read_input_tokens=0, input_tokens=193, output_tokens=21, server_tool_use=None, service_tier='standard'))"
+      ]
+     },
+     "execution_count": null,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "of = {\n",
+    "    \"type\": \"json_schema\",\n",
+    "    \"schema\": {\n",
+    "        \"type\": \"object\",\n",
+    "        \"properties\": {\n",
+    "            \"first_name\": {\"type\": \"string\"},\n",
+    "            \"last_name\": {\"type\": \"string\"},\n",
+    "        },\n",
+    "        \"required\": [\"first_name\", \"last_name\"],\n",
+    "        \"additionalProperties\": False\n",
+    "    }\n",
+    "}\n",
+    "\n",
+    "c(\"The first name is Johno, the last name is Ohjohn\", output_format=of)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "e0edc13f",
+   "metadata": {},
+   "source": []
+  },
   {
    "cell_type": "markdown",
    "id": "fbdc1914",