refactor(ai): always bind schema as a tool, drop with_structured_output branch

schema() is just appended to tools() and the whole set is bound in one call.
This collapses the schema-only special case: with_structured_output only added
tool_choice="any" enforcement, which is redundant now that _apply_schema parses
plain JSON text for tool-less agents -- so a schema-only agent gets its parsed
result whether the model emits the schema tool call or replies in JSON text.

Also drops the now-dead structured-dict passthrough in Runner.run.

Author: tmgbedu

fastapi_startkit/src/fastapi_startkit/ai/ai.py

@@ -85,16 +85,10 @@ def build(
 
         tools = list(agent.tools())
         schema = agent.schema()
-
         if structured and schema is not None:
-            if tools:
-                return chat_model.bind_tools([*tools, schema])
-            return chat_model.with_structured_output(schema, include_raw=True)
-
-        if tools:
-            return chat_model.bind_tools(tools)
+            tools.append(schema)
 
-        return chat_model
+        return chat_model.bind_tools(tools) if tools else chat_model
 
     def _resolve_model(self, agent: "Agent", override: str | None = None) -> str:
         return Lab.get_provider(agent.provider).get_model(override or agent.model or None)

fastapi_startkit/src/fastapi_startkit/ai/runner.py

@@ -29,9 +29,6 @@ async def run(self, messages: Sequence[Message]) -> BaseMessage:
         history: list[Message] = list(messages)
         response: AIMessage = await self.model.ainvoke(history)  # type: ignore[assignment]
 
-        if isinstance(response, dict) and "parsed" in response:
-            return response  # type: ignore[return-value]
-
         tool_calls = list(getattr(response, "tool_calls", None) or [])
         if not tool_calls:
             return response

fastapi_startkit/tests/ai/test_structured_output.py

@@ -1,12 +1,12 @@
 """Structured output.
 
-An Agent's schema() and tools() are passed to the model in a single payload:
-
-- schema + tools -> bind_tools([*tools, schema]); the model picks a real tool
-  call OR the schema as its structured answer. If it picks the schema, we parse
-  and return the structured result; otherwise we run the tool it asked for.
-- schema only -> with_structured_output(); the shape is enforced.
-- tools only / neither -> unchanged.
+An Agent's schema() is appended to its tools() and the whole set is bound to
+the model in a single payload via bind_tools([*tools, schema]). The model picks
+per turn: a real tool call (which the Runner executes) or the schema as its
+structured answer (which the Runner parses into response.parsed). If a
+schema-only agent replies with plain JSON text instead of the tool call,
+_apply_schema still parses it, so the structured result comes through either
+way.
 
 The fake/record paths bypass build(), so they keep parsing the JSON-string
 content via schema() for deterministic replay.
@@ -76,16 +76,11 @@ def _patch_init(self, fake):
     def _fake_model(self):
         class FakeModel:
             bound = None
-            structured = None
 
             def bind_tools(self, tools, **kwargs):
                 self.bound = list(tools)
                 return "BOUND"
 
-            def with_structured_output(self, schema, **kwargs):
-                self.structured = (schema, kwargs)
-                return "STRUCTURED"
-
         fake = FakeModel()
         self._patch_init(fake)
         return fake
@@ -96,16 +91,15 @@ def test_schema_and_tools_are_bound_together_in_one_payload(self):
         result = Ai().build(ToolMovieAgent())
 
         self.assertEqual(result, "BOUND")
-        self.assertIn(noop, fake.bound)
-        self.assertIn(Movie, fake.bound)
+        self.assertEqual(fake.bound, [noop, Movie])
 
-    def test_schema_only_uses_enforced_structured_output(self):
+    def test_schema_only_binds_the_schema_as_a_tool(self):
         fake = self._fake_model()
 
         result = Ai().build(MovieAgent())
 
-        self.assertEqual(result, "STRUCTURED")
-        self.assertEqual(fake.structured, (Movie, {"include_raw": True}))
+        self.assertEqual(result, "BOUND")
+        self.assertEqual(fake.bound, [Movie])
 
     def test_tools_only_binds_just_the_tools(self):
         fake = self._fake_model()
@@ -152,18 +146,6 @@ async def ainvoke(self, messages):
 
         self.assertEqual(result.content, "hello")
 
-    async def test_passes_structured_output_dict_through(self):
-        parsed = Movie(title="Inception", year=2010)
-        payload = {"raw": AIMessage(content=""), "parsed": parsed, "parsing_error": None}
-
-        class Model:
-            async def ainvoke(self, messages):
-                return payload
-
-        result = await Runner(MovieAgent(), Model()).run(["hi"])
-
-        self.assertEqual(result, payload)
-
 
 class TestResponseMapping(unittest.TestCase):
     def test_unwraps_include_raw_into_parsed_and_content(self):
@@ -191,23 +173,33 @@ def _patch(self, model):
         patcher.start()
         self.addCleanup(patcher.stop)
 
-    async def test_schema_only_populates_parsed(self):
-        parsed = Movie(title="Inception", year=2010)
+    async def test_schema_only_populates_parsed_from_the_schema_tool_call(self):
+        class FakeModel:
+            def bind_tools(self, tools, **kwargs):
+                return self
 
-        class Structured:
             async def ainvoke(self, messages):
-                return {"raw": AIMessage(content=""), "parsed": parsed, "parsing_error": None}
+                return AIMessage(content="", tool_calls=[_schema_tool_call(title="Inception", year=2010)])
+
+        self._patch(FakeModel())
+
+        response = await MovieAgent().prompt("best nolan movie")
+
+        self.assertEqual(response.parsed, Movie(title="Inception", year=2010))
 
+    async def test_schema_only_parses_plain_json_text_when_model_skips_the_tool(self):
         class FakeModel:
-            def with_structured_output(self, schema, **kwargs):
-                return Structured()
+            def bind_tools(self, tools, **kwargs):
+                return self
+
+            async def ainvoke(self, messages):
+                return AIMessage(content='{"title": "Inception", "year": 2010}')
 
         self._patch(FakeModel())
 
         response = await MovieAgent().prompt("best nolan movie")
 
-        self.assertEqual(response.parsed, parsed)
-        self.assertEqual(response.content, parsed.model_dump_json())
+        self.assertEqual(response.parsed, Movie(title="Inception", year=2010))
 
     async def test_schema_plus_tools_returns_structured_when_model_chooses_it(self):
         class FakeModel: