[Bug] An output schema pydantic cannot render raises instead of taking the prompt fallback
- Dominant language
- Java
- Stars
- 452
- Forks
- 167
- Avg merge
- 5d 9h
- Merged PRs (30d)
- 49
Description
> **Decision, 2026-08-17: option 2.** Raise a clear, consistent error rather than falling back, and treat `RowTypeInfo` as a separate documented fallback. See [this comment](https://github.com/apache/flink-agents/issues/985#issuecomment-5312409060).
>
> The two options below are the original framing and are kept for the record.
### Search before asking
- [x] I searched in the [issues](https://github.com/apache/flink-agents/issues) and found nothing similar.
### Description
`OllamaChatModelConnection.chat` translates a `BaseModel` output schema by calling `model_json_schema()`. For some field types pydantic cannot produce a JSON Schema and raises `PydanticInvalidForJsonSchema`, so the chat call fails instead of falling back to the prompt-engineering path.
That is inconsistent with how the same connection treats the other schema form it cannot translate natively. A `RowTypeInfo` is skipped silently and the caller keeps the prompt fallback, while a `BaseModel` pydantic cannot render propagates an exception out of `chat`. Both cases are "this connection cannot express the schema natively", so it is not obvious they should behave differently.
There are two defensible directions, and I do not think the choice is clear cut:
1. Treat an unrenderable `BaseModel` like any other untranslatable schema and fall back to the prompt path. This makes the two cases consistent and keeps a schema from breaking a call that would otherwise succeed.
2. Keep raising, on the grounds that an unrenderable schema is a caller mistake and a silent fallback would hide it, and instead make the `RowTypeInfo` case louder.
The choice also affects what "capable" means. The connection reports native support for every model, so the caller has no way to ask in advance whether a particular schema will translate.
Exposure today is limited. No framework path passes an `output_schema` down to a connection, so this is reachable only from a direct call to the 4-arg `chat`.
The OpenAI, Azure OpenAI and Anthropic Python connections hand the class to their provider SDK rather than calling `model_json_schema()` themselves, so they raise from inside the SDK on the same input. Whatever is decided here likely applies to them as well, which is why this is filed against the behavior rather than against one connection.
### How to reproduce
```python
from typing import Callable
from pydantic import BaseModel
from flink_agents.api.agents.types import OutputSchema
class Bad(BaseModel):
cb: Callable[[int], int]
# raises pydantic.errors.PydanticInvalidForJsonSchema
connection.chat(
messages, model="qwen3", output_schema=OutputSchema(output_schema=Bad)
)
```
`Bad.model_json_schema()` on its own raises the same error, which is the call the connection makes.
### Version and environment
Flink Agents `main` (0.3-SNAPSHOT), pydantic 2.11.4, Python 3.10 to 3.12. Not platform specific.
### Are you willing to submit a PR?
- [x] I'm willing to submit a PR!
Contributor guide
Research direction
Start at OllamaChatModelConnection.chat and inspect the model_json_schema() handling, then reproduce the Bad model example from the issue. Compare that behavior with RowTypeInfo and the OpenAI, Azure OpenAI, and Anthropic connections. Done means option 2's clear error behavior is consistent and the RowTypeInfo fallback is documented.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- backend-api-design
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 55/100