joeyutong opened a new pull request, #1316: URL: https://github.com/apache/flink-agents/pull/1316
Linked issue: #1308, following the documentation walkthrough in #1283. The Java KeyedStream finding is handled separately by #1312. ### Purpose of change Fix the remaining nine walkthrough findings: - Setup: apply the Apple Silicon setuptools constraint to both older pip and newer isolated builds, and keep the reader in the repository after building from source. - Quickstart: document the finite-input window limitation, describe printed analysis results accurately, and set Python single-Agent parallelism to one in both the guide and runnable example. - Examples and site: restore the missing JSONL newline so all 3163 Java input reviews are read, and keep menu styling out of browser titles. - Integrate: explain the insert-only Table input requirement and make Python scalar output work with a single-column Table. The implementation description below covers Python output conversion and title rendering. The other changes are documentation, a matching example setting, and input data. #### Runtime flow and key decisions The existing Row conversion operator decodes an Agent output, adapts it with `to_row`, and passes it to PyFlink's Row encoder. A scalar supplying the only physical column is now wrapped in `Row(value)`. Structured adaptation uses a private recursive helper so this outer wrapping cannot turn a null nested ROW into `Row(None)`. Raw and atomic DataStream views keep their existing conversion paths. The shared title helper returns the page name. The sidebar renderer adds its icon/bold markup locally, so browser titles and other consumers do not receive menu markup. The Quickstart keeps its one-minute processing-time windows and finite file source; the new note explains that the job can finish before a window emits, leaving some or all suggestions absent. ### Behavioral Semantics #### Interaction decisions | Output and target | Behavior | | --- | --- | | Scalar, one physical Row/Table column | Wrap as `Row(value)` | | Scalar, multiple physical columns | Existing unsupported conversion behavior | | Row, dictionary, or matching positional sequence | Existing field adaptation | | Nested ROW, MAP, or ARRAY fields | Existing recursive ROW conversion and field values | | Raw or atomic DataStream output | Preserve the original scalar | | Title consumer | No styling | Icon | Bold | Both | | --- | --- | --- | --- | --- | | Browser/other title consumers | Page name | Page name | Page name | Page name | | Sidebar | Page name | Icon and name | Styled name | Icon and styled name | #### Behavioral contracts and failure behavior 1. JSON scalar outputs can populate a compatible single physical column through either DataStream or Table input. 2. Nested null ROWs and collection fields retain their existing shape; existing structured outputs still adapt by field name/order. 3. Creating a Row/Table view does not change another raw or scalar DataStream view of the same Agent output. 4. Menu styling is rendered in the sidebar without appearing in browser titles. Incompatible column types and scalar-to-multiple-column conversion still fail through the existing conversion/encoder checks. No retries, fallbacks, or external-service handling are added. Insert-only input is an existing Table conversion requirement, now documented. ### Tests | Contract | Coverage | | --- | --- | | Scalar to one physical column from both input APIs | `test_scalar_output_to_single_column_table` runs real model-free Agent jobs; `test_to_row_wraps_scalar_in_single_column` covers the event serialization boundary | | Preserve nested null/collection and structured values | `test_to_row_preserves_nested_row_and_collection_fields` and existing Row/dict/positional conversion tests | | Independent raw/scalar/Row views and computed columns | `test_scalar_table_view_preserves_scalar_datastream_views` | | Plain browser titles with sidebar formatting | Hugo 0.110.0 build; generated HTML checks across 80 titles and the Quickstart sidebar | Local results (Python 3.12, PyFlink 2.3.0, JDK 21): 66 focused conversion/terminal tests passed; 8 real scalar Agent jobs passed. The broader unit selection passed 2778 tests with 16 skipped after excluding the existing Mem0 compatibility failure described below. The unfiltered unit run had 2 failures and 20 setup errors in `test_mem0_long_term_memory.py`: Mem0 0.1.115's factory expects a class-name string but receives the adapter's tuple. The same failure was reproduced using unmodified main (`8d2df12e`); that module is unchanged by this PR. The full unit suite is therefore not claimed green. Other checks passed: current-source `tools/build.sh --java`, strict JSONL validation, rebuilt examples JAR resource byte comparison, two real Flink source-reading jobs (DataStream/Jackson and Table/JSON: 3163 rows each, including the previously skipped review), documentation/snippet consistency, Ruff/Spotless, and `tools/check-license.sh`. Not verified: model-backed Ollama Quickstarts (no service/model available), other Python/Flink/JDK combinations, and recovery/cancellation behavior. The window change documents the limitation and does not add end-of-input flushing. ### API No public signature changes. Python single-column Row/Table adaptation now accepts the scalar values already promised by the integration guide. Existing structured and raw/atomic output paths retain their contracts. The Python single-Agent example explicitly uses parallelism one instead of inheriting the environment default. ### Documentation - [x] `doc-included` ### Was this patch authored or co-authored using generative AI tooling? - [x] Yes - [ ] No Generated-by: Codex CLI 0.163.0-alpha.11.1 (GPT-6) -- 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: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
