wenjin272 opened a new issue, #1121: URL: https://github.com/apache/flink-agents/issues/1121
### Search before asking - [x] I searched in the [issues](https://github.com/apache/flink-agents/issues) and found nothing similar. ### Description This is a child issue of #1055. #### Motivation The `api` module currently contains several concrete Java wrappers for Python resources: - `PythonChatModelConnection` - `PythonChatModelSetup` - `PythonEmbeddingModelConnection` - `PythonEmbeddingModelSetup` - `PythonVectorStore` - `PythonCollectionManageableVectorStore` These classes implement Pemja-specific Java/Python bridge behavior. They are instantiated by the plan-layer `PythonResourceProvider` and are also inspected by plan-layer execution code such as `ChatModelInvoker` and `ContextRetrievalAction`. The plan module already owns the corresponding MCP bridge implementations (`PythonMCPServer`, `PythonMCPTool`, and `PythonMCPPrompt`). Keeping some concrete Python bridge implementations in `api` mixes user-facing resource contracts with plan/runtime implementation details and makes the ownership boundary between the modules unclear. The lifecycle changes tracked by #1057 and implemented by #1058 make this boundary more visible, but this issue is a separate structural refactoring and should not be mixed into that bug fix. #### Proposed direction Move the concrete Python resource wrapper implementations from the `api` module to the `plan` module, while keeping the public resource abstractions such as `BaseChatModelConnection`, `BaseChatModelSetup`, `BaseEmbeddingModelConnection`, `BaseEmbeddingModelSetup`, and `BaseVectorStore` in `api`. The target package should make the implementation role explicit, for example under `org.apache.flink.agents.plan.resource.python`. `PythonResourceAdapter` and `PythonResourceWrapper` should be reviewed separately: if they are intended extension SPIs for user-defined cross-language resources, they can remain in `api`; otherwise, moving the complete Pemja bridge boundary out of `api` should be considered. The internal `PythonObjectScope` utility should live with the layer that owns the bridge implementation. #### Scope and compatibility considerations - Move the chat-model, embedding-model, and vector-store Python wrapper implementations and their tests as one coherent change. - Update `PythonResourceProvider`, `ChatModelInvoker`, `ContextRetrievalAction`, runtime bridge code, and cross-language tests. - Update `ResourceName` and YAML `PYTHON_WRAPPER_CLAZZ` mappings to the agreed wrapper FQCNs. - Preserve the `runtime -> plan -> api` dependency direction. - Preserve Java, Python, and YAML behavior; this refactoring should not change resource construction, invocation, or lifecycle semantics. - Assess source and binary compatibility for users importing the current wrapper classes. - Assess compatibility of serialized `ResourceDescriptor` values, YAML-generated wrapper class names, checkpoints, and existing plans that may contain the current FQCNs. Document or implement the required migration path. - Verify distribution packaging and class loading for all supported Flink versions. #### Acceptance criteria - Concrete Pemja-backed resource implementations no longer live in the `api` module unless an explicit public-extension requirement is documented. - Public resource contracts remain in `api`, and module dependencies continue to follow `runtime -> plan -> api`. - Chat, embedding, vector-store, and MCP Python wrappers have a consistent ownership layer and package structure. - Java programmatic declarations and YAML declarations still resolve Python resources successfully. - Existing lifecycle and cross-language behavior covered by #1058 remains unchanged. - Compatibility impact and migration behavior for the old wrapper FQCNs are documented and tested. - API, Plan, Runtime, serialization, YAML, and cross-language tests pass after the move. ### 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]
