feat(sdk): make Begin inputs discoverable on Session.ask (#14842)

### 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

@@ -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":