yunfengzhou-hub opened a new issue, #785: URL: https://github.com/apache/flink-agents/issues/785
### Search before asking - [x] I searched in the [issues](https://github.com/apache/flink-agents/issues) and found nothing similar. ### Description Found during manual verification of the prompts documentation section (#739). The utility function `format_string` in `python/flink_agents/api/prompts/utils.py:38` has the signature: ```python def format_string(text: str, **kwargs: str) -> str: ``` When a user creates a prompt containing `{text}` as a template variable: ```python prompt = Prompt.from_text("Summarize this {text}") result = prompt.format_string(text="some content") ``` The call chain `LocalPrompt.format_string(**kwargs)` → `utils.format_string(self.template, **kwargs)` raises: ``` TypeError: format_string() got multiple values for argument 'text' ``` This is because Python does not allow a keyword argument in `**kwargs` to share a name with a positional parameter, even when the positional argument is passed positionally. The internal parameter name `text` leaks into the user-facing API, but users have no visibility into this — the public method `Prompt.format_string(self, **kwargs)` has no `text` parameter. `{text}` is an extremely natural variable name for prompt templates (e.g., "Summarize the following {text}", "Translate this {text} to French"). Users cannot predict this restriction without reading the internal source. Note: a related but separate issue exists for `SafeFormatter` brace handling (#781). This issue is specifically about the parameter name collision. ### Suggested fix Rename the positional parameter in `utils.format_string` from `text` to `template` (or `_text`, `fmt`, etc.): ```python # python/flink_agents/api/prompts/utils.py:38 def format_string(template: str, **kwargs: str) -> str: """Format a string with kwargs.""" formatter = SafeFormatter(kwargs=kwargs) return formatter.format(template) ``` This is a one-line change to an internal (non-public) function. No downstream compatibility impact — `format_string` is only called positionally within the codebase. ### How to reproduce ```python from flink_agents.api.prompts.prompt import LocalPrompt p = LocalPrompt(template="Summarize: {text}") p.format_string(text="hello world") # TypeError: format_string() got multiple values for argument 'text' ``` ### Version and environment Flink Agents 0.3.0 (`main`). Python `utils.format_string`; the Java `Prompt.formatMessages` does not have this issue (Java does not have kwargs name collision). ### 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]
