wenjin272 opened a new issue, #1385: URL: https://github.com/apache/flink-agents/issues/1385
### Search before asking - [x] I searched in the [issues](https://github.com/apache/flink-agents/issues) and found no existing issue covering this API refactor. ### Description The embedding model API exposes separate `embed` and `embedWithUsage` / `embed_with_usage` methods, while `chat()` consistently returns a `ChatResult` containing optional usage. Multimodal inputs also expose differences between the Java and Python embedding APIs: Java has a separate `embedBlocksWithUsage` entry point, while Python accepts content blocks through the existing methods. We should simplify the embedding API around a consistent result contract: embedding calls return `EmbeddingResult`, containing the vectors and optional usage, without requiring callers to choose a separate method to obtain usage. The refactor should cover: - Align `BaseEmbeddingModelConnection` and `BaseEmbeddingModelSetup` across Java and Python around this result contract. - Define clear single-input and batch semantics for text and content blocks, including return shapes, vector cardinality, and input ordering. The language-specific signatures can differ where necessary, but their behavior should be consistent. - Update existing providers, cross-language bridges, and callers, including vector store integrations. Preserve usage when available and represent unavailable usage explicitly. - Update documentation and tests for single and batch inputs, supported media inputs, results with and without usage, and cross-language calls. Document the public API changes and how callers should migrate. The exact input types and method signatures can be settled in the implementation proposal. The goal is to simplify the API rather than add another layer of parallel methods. This follows the [review discussion in #1374](https://github.com/apache/flink-agents/pull/1374#discussion_r4536326545). We intentionally deferred the refactor to a separate issue and PR because it affects existing providers, callers, and bridges beyond the DashScope multimodal integration. Related: #858 tracks embedding token usage metrics. This issue focuses on the public API and result contract; metrics work should be coordinated with that issue. ### Are you willing to submit a PR? - [ ] I'm willing to submit a PR! -- 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]
