wenjin272 opened a new issue, #1093: URL: https://github.com/apache/flink-agents/issues/1093
### Search before asking - [x] I searched in the [issues](https://github.com/apache/flink-agents/issues) and found nothing similar. ### Description The Python tool schema utilities currently mix several responsibilities in `flink_agents.api.tools.utils`: - deriving a Pydantic argument model from a Python callable signature, docstring, defaults, annotations, and injected parameters; - reconstructing API schema models from serialized JSON Schema; - converting tool schemas across the Java/Python bridge. This no longer matches the current API/plan boundary. The API-layer `FunctionTool` is a declarative descriptor that carries a function reference and injected-argument declarations, while callable introspection and executable `ToolMetadata` derivation happen in the plan layer. The Java implementation already places the corresponding reflection-based `SchemaUtils` in `plan.tools`. Keeping `create_schema_from_function` in the API module makes an implementation-specific compilation step look like part of the API contract. It also turns the generic `utils.py` module into a coupling point for API serialization, plan construction, and runtime bridge code. In addition, Python metadata derivation is partly duplicated between `plan.tools.function_tool` and `runtime.python_java_utils`. The desired boundary is: - keep the tool schema contract and its API-level serialization/deserialization in the API module; - move Python-callable introspection and schema/metadata derivation to a dedicated plan-layer component; - let both normal plan construction and the cross-language runtime bridge reuse the same metadata builder; - move Java/Python bridge-specific schema conversion out of the generic API utility where appropriate; - preserve the existing serialized schema and tool behavior unless a separate API change is explicitly agreed. #### Acceptance criteria - The API module no longer owns Python-callable introspection or plan-time metadata derivation. - Plan construction and the runtime bridge use one shared callable-to-tool-metadata implementation. - The `runtime -> plan -> api` dependency direction remains intact. - Java and Python place equivalent schema-derivation responsibilities at consistent architectural layers. - Focused tests cover docstrings, `Annotated` metadata, defaults, missing annotations/descriptions, and injected arguments after the move. - Existing tool schema serialization and cross-language behavior remain unchanged. This is related to #814, which added direct tests for the existing utilities, but addresses the architectural boundary rather than the earlier test-coverage gap. ### Are you willing to submit a PR? - [x] 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]
