wenjin272 opened a new pull request, #1391: URL: https://github.com/apache/flink-agents/pull/1391
Fixes #1385 ### Purpose of change `embed` now returns `EmbeddingResult` containing vectors and optional token usage. Callers no longer choose a separate method for usage or content blocks. This gives embedding connections and setups one result contract across Java, Python, and cross-language calls. #### Runtime flow A setup merges model defaults with per-call parameters and delegates to its connection. Java string and single-block overloads call the block-batch implementation and unwrap one vector. Providers validate supported content, invoke their service, and return vectors plus available usage. The language bridges preserve the input shape and usage; vector stores and Mem0 extract the vectors they need. #### Key decisions - Keep string and single-block conveniences, but require Java providers to implement only `embed(List<? extends DataContentBlock>, Map)`. - Keep text-only validation in providers so the base contract can support media. A shared helper validates the whole batch before any service call. - Keep Python wire-format parsing inside the plan bridge. The API utility contains provider-neutral operations only. - Remove the parallel usage/block methods instead of maintaining duplicate entry points. ### Behavioral Semantics #### Interaction decisions | Input / provider | Result | | --- | --- | | One string or supported block | One vector in `EmbeddingResult` | | Batch of supported inputs | A vector list in input order, including a one-item batch | | Media sent to a text-only provider | Reject before invoking the service | | Usage reported / unavailable | Preserve usage / use `null` or `None` | | Direct / cross-language invocation | Preserve single versus batch shape and optional usage | #### Behavioral contracts - Setups preserve per-call parameter overrides. - Single-input Java conveniences require exactly one returned vector. - Batch calls preserve input order; each block represents a separate embedding input. - Both bridges preserve result shape and optional usage for connections and setups, including calls through async workers. - Java OpenAI, Ollama, and Bedrock validate the entire text-only batch before service invocation. Bedrock retains ordered results and usage aggregation across its per-text requests. #### Failure behavior Unsupported media raises an unsupported-content error; null batches or entries are rejected by the Java text-input helper. A wrong single-result count raises `IllegalStateException`. The Java-to-Python bridge rejects malformed map/list/usage fields and uninitialized resources instead of dropping usage or falling back to another method. Existing provider SDK retry/error handling remains in place; this refactor adds no retry or fallback layer. Empty-batch service behavior remains provider-specific. ### Tests | Contract | Coverage | | --- | --- | | Per-call overrides survive setup delegation | `BaseEmbeddingModelSetupEmbeddingResultTest`, `test_embedding_result.py`, both runtime E2E suites | | Single-input Java result has exactly one vector | `testSingleInputRequiresExactlyOneVector` | | Batch order and single/batch shapes are preserved | Base contract tests, `EmbeddingResultBridgeTest`, both runtime E2E suites (including empty and one-item batches) | | Optional usage survives both bridges | Bridge unit tests, real Pemja test, both runtime E2E suites | | Async workers preserve the same result contract | `EmbeddingAsyncCrossLanguageTest` and `embedding_async_cross_language_test.py`; barriers require overlapping provider calls | | Text-only providers reject media before service calls | Java provider tests and Python embedding provider tests | | Bedrock preserves batch order and aggregates usage | `BedrockEmbeddingModelTest` | | Malformed bridge results fail explicitly | Python connection/setup bridge tests; exhaustive malformed usage-field coverage was not added | Local validation: clean full Java build; 85 focused Java tests passed (including the real Pemja bridge), with 10 external-service cases skipped; 56 focused Python tests passed. Four additional full Flink E2E cases passed: Java-to-Python and Python-to-Java, each synchronous and concurrent. Spotless, Ruff, and the Hugo documentation build passed. Not verified: live external model/vector-store services, checkpoint recovery/replay of embedding results, or the full repository test matrix. The new E2E providers are deterministic fixtures running through real Flink jobs and language bridges. <details> <summary>E2E execution and artifact provenance</summary> Java E2E: `mvn -B --no-transfer-progress test -pl e2e-test/flink-agents-end-to-end-tests-resource-cross-language -am -Dtest=EmbeddingAsyncCrossLanguageTest -Dsurefire.failIfNoSpecifiedTests=false`. Python E2E: `python -m pytest python/flink_agents/e2e_tests/e2e_tests_resource_cross_language/embedding_async_cross_language_test.py -q`. Tests used Java 11, Python 3.11, and Flink 2.3. Java common/thin distribution JARs and the cross-language test JAR were rebuilt before Python E2E execution; `PYTHONPATH` included the current source tree and active environment's purelib directory. Each direction exercises both resource types, string/text/image inputs, mixed and empty batches, and usage present/absent. Async tests use two workers and a two-party provider barrier. </details> ### API Breaking API cleanup: Java `embed` returns `EmbeddingResult` rather than raw vectors; Java text batches must use `TextBlock` lists. Custom Java connections implement the block-batch overload. Remove `embedWithUsage`, `embedBlocksWithUsage`, and Python `embed_with_usage`; callers use `embed` and extract `getEmbeddings()` / `.embeddings` when only vectors are needed. Python keeps string and content-block inputs, including string batches. Resource names and YAML declarations are unchanged. ### 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: Codex CLI 0.153.4 (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]
