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]

Reply via email to