[PR] [api][java][python] Render a flat RowTypeInfo output schema as JSON Schema in the ReAct Agent prompt [flink-agents]

["sangkyoonnam (via GitHub)" <gi...@apache.org>]

sangkyoonnam opened a new pull request, #1270:
URL: https://github.com/apache/flink-agents/pull/1270

   Linked issue: #1256
   
   ### Purpose of change
   
   For a flat `RowTypeInfo` output schema with only string, boolean or numeric fields, the ReAct Agent now describes the schema to the model as JSON Schema instead of the type's string form, in both languages. For `Row(name STRING, count INT)` the prompt now carries `{"type":"object","properties":{"name":{"type":"string"},"count":{"type":"integer"}},"required":["name","count"],"additionalProperties":false}` where it used to carry `Row(name: String, count: Integer)` (Java) or `RowTypeInfo(name: String, count: Integer)` (Python). The string form names the fields and Flink types but not the JSON shape to return. Native schema-document support (`AUTO` and `NATIVE` for a `RowTypeInfo`) is deferred to a follow-up PR.
   
   #### Runtime flow
   
   1. The `ReActAgent` constructor (both languages) builds the schema text once. For a `RowTypeInfo` it calls `RowTypeJsonSchema.render` (Java, `@Internal`) or `render_row_type_json_schema` (Python), and uses the string form, as before, when that returns `null`/`None`.
   2. The text goes into both registered prompts, schema and native-schema.
   3. `startAction` / `start_action` picks one of them, as before, and inserts it into the request. The stored output schema, the native capability decision and response conversion are unchanged.
   
   Mapping: string to `string`, boolean to `boolean`, byte/short/int/long/big integer to `integer`, float/double/big decimal to `number`.
   
   #### Key decisions
   
   - Same text in both languages: properties in field order, compact separators, non-ASCII written as is, and lowercase hex in `\u` escapes (Jackson writes uppercase by default, so the Java writer turns that off).
   - Char, date and instant fields have no mapping, so the row keeps the string form: the response is copied into the `Row` without conversion, and a `string` value would have the wrong type there.
   - Every field is required. The bare property types also exclude `null`; nullability is deferred.
   - A row built without names renders Java's default names `f0`, `f1`, ... in both languages. Python reads them without `get_field_names()`, which would start the JVM.
   - Python rows with duplicate names or a name count that differs from the type count, which Java rejects, keep the string form.
   
   ### Behavioral Semantics
   
   #### Interaction decisions
   
   | Row fields | Java | Python |
   |---|---|---|
   | All string, boolean or numeric | JSON Schema | JSON Schema |
   | A basic char, date, instant or void field | string form, as before | string form, as before (char, instant) |
   | A nested or non-basic field (Python SQL date included) | construction fails in `OutputSchema`, as before | string form; serializing `OutputSchema` fails, as before |
   
   #### Behavioral contracts
   
   - A mapped row's prompt lists the properties in field order.
   - All properties are `required`.
   - `additionalProperties` is `false`.
   - Java and Python produce the same text for the same row, including escaped field names.
   - A row built without names uses `f0`, `f1`, ... as property names.
   - A row with an unmapped field keeps the string form in both prompts.
   
   #### Failure behavior
   
   - An unmapped field: the renderer returns `null`/`None` and the agent falls back to the string form.
   - A non-basic field: unchanged (table above).
   - A Python row with duplicate or mismatched names: the renderer returns `None` and the agent keeps the string form, as before.
   - A Jackson serialization failure in the Java renderer is rethrown as a `RuntimeException`, not absorbed into the fallback.
   
   ### Tests
   
   | Contract | Tests |
   |---|---|
   | Field order | `rendersFlatRowInFieldOrder`, `test_renders_flat_row_in_field_order` |
   | Every field required | same two tests (shared expected string) |
   | `additionalProperties: false` | same two tests |
   | Numeric mapping | `mapsNumericTypes`, `test_maps_numeric_types` |
   | Same text in both languages, escaped names | `escapesFieldNamesLikePython`, `test_escapes_field_names_like_java` (shared expected string) |
   | Default names for an unnamed row | `rendersDefaultFieldNames`, `test_unnamed_row_uses_default_names_without_the_jvm` (shared expected string), `test_unnamed_unmapped_row_returns_none_without_the_jvm`; the Python tests fail if the JVM starts |
   | Duplicate or mismatched Python names keep the string form | `test_returns_none_for_names_java_rejects` (empty, fewer, duplicate), `test_row_type_info_with_duplicate_names_keeps_the_prompt_fallback` (both prompts) |
   | Unmapped field keeps the string form | `returnsNullForFieldsWithoutJsonType`, `test_returns_none_for_fields_without_json_type`, `testRowTypeSchemaWithoutJsonTypeKeepsItsText` and `test_row_type_info_without_json_type_keeps_the_prompt_fallback` (both prompts) |
   | Both prompts carry the schema | `testRowTypeSchemaPromptCarriesJsonSchema`, `testRowTypeSchemaRegistersNativeSchemaPrompt`, `test_row_type_info_output_schema_renders_json_schema_in_the_prompt`, `test_row_type_info_output_schema_registers_the_native_schema_prompt` |
   
   Coverage by risk: parity is pinned by shared expected strings, the fallbacks by prompt-level tests in both languages.
   
   Not verified: nested or non-basic rows on the new path (unchanged, untested), and any model's response to the new prompt. The response side still copies JSON values into the `Row` without converting them to the field types, and a missing field gives `null` in Java but a `KeyError` in Python; both are outside this PR.
   
   <details><summary>Verification runs</summary>
   
   `api` tests pass on JDK 17 (748 run, 13 skipped), the Python `api` and `plan` tests pass (1305), and `tools/lint.sh -c` passes on JDK 11. JDK 21 lint passes too, but it skips Spotless there.
   
   </details>
   
   ### API
   
   Existing signatures and accepted schema kinds are unchanged. Rows with only string, boolean or numeric fields get different prompt text; other rows keep theirs. Native support and response conversion are unchanged. `RowTypeJsonSchema` is new and `@Internal`; `render_row_type_json_schema` is a new function in `flink_agents.api.agents.types`.
   
   ### Documentation
   
   - [ ] `doc-needed`
   - [ ] `doc-not-needed`
   - [x] `doc-included`
   
   ### Was this patch authored or co-authored using generative AI tooling?
   
   - [x] Yes
   - [ ] No
   
   Generated-by: Claude Code 2.1.296 (Claude Opus 5.5)
   


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@flink.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] [api][java][python] Render a flat RowTypeInfo output schema as JSON Schema in the ReAct Agent prompt [flink-agents]

["wenjin272 (via GitHub)" <gi...@apache.org>]

wenjin272 merged PR #1270:
URL: https://github.com/apache/flink-agents/pull/1270


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@flink.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] [api][java][python] Render a flat RowTypeInfo output schema as JSON Schema in the ReAct Agent prompt [flink-agents]

["sangkyoonnam (via GitHub)" <gi...@apache.org>]

sangkyoonnam commented on PR #1270:
URL: https://github.com/apache/flink-agents/pull/1270#issuecomment-6262743354

   Rebased onto `main` and resolved the conflict in `types.py`, preserving #1265's `contains_open_object` changes and this PR's `RowType` rendering.
   


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@flink.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org