From 6796a47b8d37ff4464e06ffc1a4ddb5c8ea830d1 Mon Sep 17 00:00:00 2001 From: plind <59729252+plind-junior@users.noreply.github.com> Date: Tue, 19 May 2026 01:14:57 -0700 Subject: [PATCH] feat(sdk): make Begin inputs discoverable on Session.ask (#14842) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ### What problem does this PR solve? Closes #14751. The user reported that after adding a variable (e.g. `key1`) to an agent's **Begin** component, the Python SDK gave them no way to pass it: their call `session.ask(question=user_question, stream=False)` had no parameter for `key1`, and the `ask()` signature was just `(question, stream, **kwargs)` with a docstring that only described streaming behavior. The functionality already works — `_ask_agent` does `json_data.update(kwargs)` and the server reads `inputs` from the request body at `agent_api.py:902`. The canonical shape is also in the public API docs (`docs/references/python_api_reference.md:1817-1840`): ```python session.ask( "", stream=False, inputs={"line_var": {"type": "line", "value": "I am line_var"}}, return_trace=True, ) ``` But because `inputs`, `release`, and `return_trace` were hidden behind `**kwargs`, they did not appear in IDE signature help, and the docstring did not mention them. Users had no path from "I added a key in the UI" to "I need to pass `inputs=...` with this exact shape." This PR promotes the three most relevant Begin-related arguments to named parameters and rewrites the docstring with a worked example. ### What this PR changes - `sdk/python/ragflow_sdk/modules/session.py`: - `Session.ask()` signature becomes `ask(question="", stream=False, inputs=None, release=None, return_trace=None, **kwargs)`. - These three new named params are forwarded into the existing `kwargs` dict before dispatch, so the wire format and downstream behavior are unchanged. - Docstring rewritten in numpy style, including the structured `{"type": ..., "value": ...}` shape that the Begin component requires (see `agent/component/begin.py:45-60`). No backend changes. `**kwargs` is preserved for forward compatibility with other body fields (`session_id`, `files`, `user_id`, `custom_header`, …). ### Test plan - [ ] `session.ask(question="hi", stream=False)` — existing call still works - [ ] `session.ask("", stream=False, inputs={"key1": {"type": "line", "value": "v"}})` — Begin component receives `key1 = "v"` - [ ] `session.ask("", stream=True, return_trace=True)` — streaming response includes trace events - [ ] IDE / `help(Session.ask)` now shows `inputs`, `release`, `return_trace` with descriptions ### Type of change - [x] Refactoring - [x] Documentation Update --- sdk/python/ragflow_sdk/modules/session.py | 66 +++++++++++++++++++++-- 1 file changed, 63 insertions(+), 3 deletions(-) diff --git a/sdk/python/ragflow_sdk/modules/session.py b/sdk/python/ragflow_sdk/modules/session.py index f9c4799fd..5152160f6 100644 --- a/sdk/python/ragflow_sdk/modules/session.py +++ b/sdk/python/ragflow_sdk/modules/session.py @@ -15,8 +15,12 @@ # import json +import logging + from .base import Base +logger = logging.getLogger(__name__) + class Session(Base): def __init__(self, rag, res_dict): @@ -33,11 +37,67 @@ class Session(Base): super().__init__(rag, res_dict) - def ask(self, question="", stream=False, **kwargs): + def ask( + self, + question="", + stream=False, + inputs=None, + release=None, + return_trace=None, + **kwargs, + ): """ - Ask a question to the session. If stream=True, yields Message objects as they arrive (SSE streaming). - If stream=False, returns a single Message object for the final answer. + Ask a question to the session. + + Parameters + ---------- + question : str + The user's question. May be empty when the agent is driven solely by + Begin component inputs. + stream : bool + If ``True``, yields ``Message`` objects as they arrive (SSE streaming). + If ``False``, yields a single ``Message`` with the final answer. + inputs : dict, optional + Values for variables declared on the agent's **Begin** component. Each + value must be a dict containing at least a ``"value"`` key, and may + include ``"type"``. Example:: + + session.ask( + "", + stream=False, + inputs={"key1": {"type": "line", "value": "hello"}}, + ) + + Only meaningful for agent sessions; ignored for chat sessions. + release : bool, optional + If ``True``, run against the latest published agent version instead of + the editable draft. Only meaningful for agent sessions. + return_trace : bool, optional + If ``True``, include execution trace information in the response. + Only meaningful for agent sessions. + **kwargs + Additional fields forwarded verbatim to the completion endpoint + (e.g. ``session_id``, ``files``, ``user_id``, ``custom_header``). + See the HTTP API reference for the full list. """ + if inputs is not None: + kwargs["inputs"] = inputs + if release is not None: + kwargs["release"] = release + if return_trace is not None: + kwargs["return_trace"] = return_trace + + if inputs is not None or release is not None or return_trace is not None: + logger.debug( + "Session.ask explicit-params session_type=%s session_id=%s " + "input_keys=%s release=%s return_trace=%s", + self.__session_type, + getattr(self, "id", None), + list(inputs.keys()) if isinstance(inputs, dict) else None, + release, + return_trace, + ) + if self.__session_type == "agent": res = self._ask_agent(question, stream, **kwargs) elif self.__session_type == "chat":