besser-agentic-framework 4.3.3__tar.gz → 4.4.0__tar.gz

{besser_agentic_framework-4.3.3/besser_agentic_framework.egg-info → besser_agentic_framework-4.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: besser-agentic-framework
-Version: 4.3.3
+Version: 4.4.0
 Summary: BESSER Agentic Framework (BAF)
 Author: Luxembourg Institute of Science and Technology
 License: MIT

{besser_agentic_framework-4.3.3 → besser_agentic_framework-4.4.0}/baf/core/agent.py

@@ -1,4 +1,6 @@
 import asyncio
+import importlib
+import inspect
 import json
 import operator
 import threading
@@ -35,6 +37,7 @@ from baf.platforms.websocket.websocket_platform import WebSocketPlatform
 from baf.platforms.github.github_platform import GitHubPlatform
 from baf.platforms.gitlab.gitlab_platform import GitLabPlatform
 from baf.platforms.a2a.a2a_platform import A2APlatform
+from baf.reasoning import Tool, Skill, Workspace
 
 
 class Agent:
@@ -66,6 +69,22 @@ class Agent:
         global_state_component (dict[State, list[State]]): Dictionary of global state components, where key is initial
             global state and values is set of states in corresponding global component
         processors (list[Processors]): List of processors used by the agent
+        _tools (dict[str, Tool]): Tools registered on the agent and exposed
+            to the predefined reasoning state. Keyed by tool name. Populated
+            by :meth:`add_tool` / :meth:`new_tool` / :meth:`load_tools`, the
+            ``@agent.tool`` decorator, and indirectly by :meth:`add_workspace`
+            / :meth:`new_workspace` (which register the universal
+            ``list_directory`` / ``read_file`` and — when at least one
+            workspace is writable — ``write_file`` / ``create_file`` /
+            ``delete_file`` tools).
+        _skills (dict[str, Skill]): Markdown-based playbooks the reasoning
+            state injects into the system prompt. Keyed by skill name.
+            Populated by :meth:`add_skill` / :meth:`new_skill` /
+            :meth:`load_skills`.
+        _workspaces (dict[str, Workspace]): Filesystem workspaces the agent
+            can browse and (when ``writable=True``) modify through the
+            universal workspace tools. Keyed by workspace name. Populated
+            by :meth:`add_workspace` / :meth:`new_workspace`.
     """
 
     def __init__(
@@ -94,6 +113,9 @@ class Agent:
         self.processors: list[Processor] = []
         self._user_profiles: Any = None
         self._agent_configurations: dict[str, Any] = {}
+        self._tools: dict[str, Tool] = {}
+        self._skills: dict[str, Skill] = {}
+        self._workspaces: dict[str, Workspace] = {}
 
         if user_profiles_path:
             self.load_user_profiles(user_profiles_path)
@@ -121,9 +143,8 @@ class Agent:
 
         Supported formats are YAML (``.yaml``, ``.yml``).
 
-        Example YAML properties file, ``config.yaml``:
-
-        .. literalinclude:: ../../../../baf/agent/test/examples/config.yaml
+        See ``baf/test/examples/config.yaml`` in the repository for a complete
+        example of an agent configuration file.
 
         Args:
             path (str): the path to the properties file
@@ -316,6 +337,267 @@ class Agent:
         self.states.append(new_state)
         return new_state
 
+    # --- Reasoning extension ----------------------------------------------- #
+
+    def add_tool(self, tool: Tool) -> Tool:
+        """Add an already-constructed :class:`~baf.reasoning.tool.Tool` to the agent.
+
+        Mirrors :meth:`add_intent`: the caller builds the wrapper, this method
+        registers it. Use :meth:`new_tool` when you want to skip the explicit
+        ``Tool(...)`` construction.
+
+        Args:
+            tool (Tool): the tool wrapper to register.
+
+        Returns:
+            Tool: the registered tool wrapper.
+        """
+        if tool.name in self._tools:
+            logger.warning(f"[Agent] Replacing existing tool '{tool.name}'")
+        self._tools[tool.name] = tool
+        logger.info(f"[Agent] Registered tool: {tool.name}")
+        return tool
+
+    def new_tool(self, fn: Callable, name: str = None, description: str = None) -> Tool:
+        """Build a :class:`~baf.reasoning.tool.Tool` from a callable and register it.
+
+        See :class:`baf.reasoning.tool.Tool` for the auto-introspection rules.
+
+        Args:
+            fn (Callable): the function to expose. May be a bound method.
+            name (str): override the tool's public name. Defaults to ``fn.__name__``.
+            description (str): override the description shown to the LLM.
+                Defaults to the first line of ``fn.__doc__``.
+
+        Returns:
+            Tool: the registered tool wrapper.
+        """
+        return self.add_tool(Tool(fn, name=name, description=description))
+
+    def load_tools(self, path: str) -> list[Tool]:
+        """Load every public top-level callable from a Python module or folder of modules.
+
+        ``path`` may be a single ``.py`` file or a folder (non-recursive). For
+        each module, every callable whose name does not start with ``_`` is
+        registered as a tool. Callables imported from other modules are skipped
+        — only those *defined* in the loaded module are considered, so importing
+        helpers in ``tools.py`` does not pollute the tool registry.
+
+        Args:
+            path (str): path to a ``.py`` file or to a folder containing them.
+
+        Returns:
+            list[Tool]: the tools that were registered (may be empty).
+        """
+        target = Path(path)
+        if not target.exists():
+            raise FileNotFoundError(f"load_tools: path does not exist: {path}")
+
+        if target.is_file():
+            files = [target]
+        else:
+            files = sorted(p for p in target.iterdir() if p.is_file() and p.suffix == ".py")
+
+        registered: list = []
+        for file in files:
+            module_name = f"baf_loaded_tools_{file.stem}"
+            spec = importlib.util.spec_from_file_location(module_name, file)
+            if spec is None or spec.loader is None:
+                logger.warning(f"[Agent] Could not load tools from {file}: no spec")
+                continue
+            module = importlib.util.module_from_spec(spec)
+            try:
+                spec.loader.exec_module(module)
+            except Exception as e:
+                logger.warning(f"[Agent] Failed to import tools from {file}: {e}")
+                continue
+            for member_name, member in inspect.getmembers(module):
+                if member_name.startswith("_"):
+                    continue
+                if not callable(member):
+                    continue
+                # Skip classes and members imported from other modules.
+                if inspect.isclass(member):
+                    continue
+                if getattr(member, "__module__", None) != module.__name__:
+                    continue
+                registered.append(self.new_tool(member))
+        return registered
+
+    def tool(self, fn: Callable = None, *, name: str = None, description: str = None):
+        """Decorator form of :meth:`new_tool`.
+
+        Usable bare (``@agent.tool``) or with arguments (``@agent.tool(name='x')``).
+        """
+        def _wrap(f: Callable) -> Callable:
+            self.new_tool(f, name=name, description=description)
+            return f
+        if fn is None:
+            return _wrap
+        return _wrap(fn)
+
+    def add_skill(self, skill: Skill) -> Skill:
+        """Add an already-constructed :class:`~baf.reasoning.skill.Skill` to the agent.
+
+        Mirrors :meth:`add_intent`. Use :meth:`new_skill` to skip the explicit
+        ``Skill(...)`` construction (especially convenient for loading from a
+        ``.md`` file path).
+
+        Args:
+            skill (Skill): the skill to register.
+
+        Returns:
+            Skill: the registered skill.
+        """
+        if skill.name in self._skills:
+            logger.warning(f"[Agent] Replacing existing skill '{skill.name}'")
+        self._skills[skill.name] = skill
+        logger.info(f"[Agent] Registered skill: {skill.name}")
+        return skill
+
+    def new_skill(self, source: str, name: str = None, description: str = None) -> Skill:
+        """Build a :class:`~baf.reasoning.skill.Skill` and register it.
+
+        ``source`` is either a path to an existing ``.md`` file (loaded via
+        :meth:`Skill.from_file`) or a literal markdown string. The path
+        detection is automatic.
+
+        Args:
+            source (str): path to a ``.md`` file or the markdown content as a string.
+            name (str): override the skill name (otherwise taken from frontmatter,
+                a leading H1, or the filename stem).
+            description (str): override the description (otherwise taken from
+                frontmatter).
+
+        Returns:
+            Skill: the registered skill.
+        """
+        candidate = Path(source) if isinstance(source, str) else None
+        if candidate is not None and candidate.is_file() and candidate.suffix.lower() == ".md":
+            skill = Skill.from_file(str(candidate))
+            if name:
+                skill.name = name
+            if description:
+                skill.description = description
+        else:
+            skill = Skill(source, name=name, description=description)
+        return self.add_skill(skill)
+
+    def load_skills(self, folder: str) -> list[Skill]:
+        """Register every ``*.md`` file in ``folder`` (non-recursive) as a skill.
+
+        Args:
+            folder (str): path to a folder containing markdown files.
+
+        Returns:
+            list[Skill]: the skills that were registered.
+        """
+        return [self.add_skill(s) for s in Skill.from_folder(folder)]
+
+    def add_workspace(self, workspace: Workspace) -> Workspace:
+        """Add an already-constructed :class:`~baf.reasoning.workspace.Workspace` to the agent.
+
+        The first call also registers the universal ``list_directory`` /
+        ``read_file`` tools, and — if at least one registered workspace has
+        ``writable=True`` — the ``write_file`` / ``create_file`` /
+        ``delete_file`` tools.
+
+        Mirrors :meth:`add_intent`. Use :meth:`new_workspace` to skip the
+        explicit ``Workspace(...)`` construction.
+
+        Args:
+            workspace (Workspace): the workspace to register.
+
+        Returns:
+            Workspace: the registered workspace.
+
+        Raises:
+            ValueError: if a workspace with the same name is already registered.
+        """
+        if workspace.name in self._workspaces:
+            raise ValueError(f"Workspace '{workspace.name}' is already registered")
+        self._workspaces[workspace.name] = workspace
+        self._ensure_workspace_tools_registered()
+        logger.info(f"[Agent] Registered workspace: {workspace.name} "
+                    f"(root={workspace.root}, writable={workspace.writable})")
+        return workspace
+
+    def new_workspace(self, path: str, name: str = "workspace",
+                      description: str = None,
+                      writable: bool = True,
+                      max_read_bytes: int = 200_000) -> Workspace:
+        """Build a :class:`~baf.reasoning.workspace.Workspace` and register it.
+
+        Args:
+            path (str): the workspace root path.
+            name (str): the workspace identifier the LLM passes as the
+                ``workspace`` tool argument. Must be unique within the agent.
+            description (str): a short human-readable explanation of *what* the
+                workspace contains. Strongly recommended — without it the LLM
+                only sees the name and root path and may not realise it should
+                browse the workspace.
+            writable (bool): whether mutating operations are allowed on this
+                workspace (``write_file`` / ``create_file`` / ``delete_file``).
+                Defaults to True.
+            max_read_bytes (int): cap on ``read_file`` output, in bytes.
+
+        Returns:
+            Workspace: the registered workspace.
+        """
+        return self.add_workspace(Workspace(
+            path, name=name, description=description,
+            writable=writable, max_read_bytes=max_read_bytes,
+        ))
+
+    def _resolve_workspace(self, name: str = None) -> 'Workspace':
+        """Look up a workspace by name, or pick the only one when ``name`` is None.
+
+        Raises a ``ValueError`` (which the Tool wrapper turns into an LLM-readable
+        ERROR string) on missing or ambiguous lookups.
+        """
+        if name is None:
+            if len(self._workspaces) == 1:
+                return next(iter(self._workspaces.values()))
+            if not self._workspaces:
+                raise ValueError("No workspaces are registered")
+            raise ValueError(
+                f"Multiple workspaces are registered, please specify one of: "
+                f"{list(self._workspaces.keys())}"
+            )
+        if name not in self._workspaces:
+            raise ValueError(
+                f"Workspace '{name}' not found. Available: {list(self._workspaces.keys())}"
+            )
+        return self._workspaces[name]
+
+    def _ensure_workspace_tools_registered(self) -> None:
+        """Register the universal workspace tools.
+
+        Read tools (``list_directory``, ``read_file``) are registered as soon
+        as any workspace exists. Write tools (``write_file``, ``create_file``,
+        ``delete_file``) are registered only once at least one workspace has
+        ``writable=True`` — read-only-only setups never expose them to the LLM.
+
+        The tool callables themselves live in
+        :mod:`baf.library.tool.workspace_tools`. This method only owns the
+        gating policy (which family to expose, when) plus the dedup check.
+        Idempotent — already-registered tools are skipped.
+        """
+        # Imported lazily to avoid pulling baf.library.tool at module load time.
+        from baf.library.tool.workspace_tools import (
+            build_workspace_read_tools,
+            build_workspace_write_tools,
+        )
+
+        for fn in build_workspace_read_tools(self):
+            if fn.__name__ not in self._tools:
+                self.new_tool(fn)
+
+        if any(ws.writable for ws in self._workspaces.values()):
+            for fn in build_workspace_write_tools(self):
+                if fn.__name__ not in self._tools:
+                    self.new_tool(fn)
+
     def add_intent(self, intent: Intent) -> Intent:
         """Add an intent to the agent.
 
@@ -859,6 +1141,38 @@ class Agent:
             thread = threading.Thread(target=self._monitoring_db.insert_chat, args=(session, message))
             thread.start()
 
+    def _monitoring_db_insert_reasoning_event(
+        self,
+        session: Session,
+        kind: str,
+        payload: Any,
+    ) -> None:
+        """Insert a reasoning-state event (step or task-list snapshot) into the
+        dedicated ``reasoning_step`` table. Synchronous on purpose so a
+        subsequent ``link_pending_reasoning_events`` call sees the row.
+        """
+        if self.get_property(DB_MONITORING) and self._monitoring_db.connected:
+            self._monitoring_db.insert_reasoning_event(session, kind, payload)
+
+    def _monitoring_db_select_reasoning_events(
+        self,
+        session: Session,
+        until_timestamp=None,
+    ):
+        """Fetch all reasoning events for a session, in chronological order."""
+        if self.get_property(DB_MONITORING) and self._monitoring_db.connected:
+            return self._monitoring_db.select_reasoning_events(
+                session, until_timestamp=until_timestamp,
+            )
+        return None
+
+    def _monitoring_db_link_pending_reasoning_events(self, session: Session) -> None:
+        """Attach reasoning events with chat_id IS NULL to the most recent
+        chat row for ``session``. Best-effort, called at the end of every
+        reasoning loop."""
+        if self.get_property(DB_MONITORING) and self._monitoring_db.connected:
+            self._monitoring_db.link_pending_reasoning_events(session)
+
     def _monitoring_db_insert_event(self, event: Event) -> None:
         """Insert an event record into the monitoring database.
 

{besser_agentic_framework-4.3.3 → besser_agentic_framework-4.4.0}/baf/core/message.py

@@ -21,6 +21,7 @@ class MessageType(Enum):
     AUDIO = 'audio'
     RAG_ANSWER = 'rag_answer'
     UI = 'ui'
+    REASONING_TRACE = 'reasoning_trace'  # UI-internal synthetic type aggregating streamed reasoning_step / task_list_update events
 
 
 def get_message_type(value: str):

{besser_agentic_framework-4.3.3 → besser_agentic_framework-4.4.0}/baf/core/session.py

@@ -196,6 +196,61 @@ class Session:
         """
         self._agent._monitoring_db_insert_chat(self, message)
 
+    def save_reasoning_event(self, kind: str, payload: Any) -> None:
+        """Persist a reasoning-state event in the dedicated ``reasoning_step``
+        table.
+
+        Reasoning events (LLM tool calls, tool results, task list mutations,
+        push-backs, max_steps, reasoning_started/finished brackets) are NOT
+        stored in the chat table because they would mismatch the chat
+        message-type schema. This method routes them to their own table.
+
+        Args:
+            kind (str): ``'reasoning_step'`` for a single
+                :class:`~baf.library.state.reasoning_state_library.ReasoningStep`
+                event, or ``'task_list_update'`` for a full task list snapshot.
+            payload (Any): the structured event payload — a step dict or a
+                list of task dicts.
+        """
+        self._agent._monitoring_db_insert_reasoning_event(self, kind, payload)
+
+    def get_reasoning_events(self, until_timestamp: datetime = None) -> list[dict]:
+        """Get the reasoning-state events for this session.
+
+        Includes both step events and task-list snapshots, ordered by their
+        emission timestamp.
+
+        Args:
+            until_timestamp (datetime): if provided, only events at or before
+                this timestamp are returned.
+
+        Returns:
+            list[dict]: each entry has ``kind``, ``step_kind``, ``step``,
+            ``summary``, ``payload``, ``timestamp``, ``chat_id`` keys (some
+            may be None depending on ``kind``).
+        """
+        if not (self._agent.get_property(DB_MONITORING) and self._agent._monitoring_db.connected):
+            return []
+        df = self._agent._monitoring_db_select_reasoning_events(
+            self, until_timestamp=until_timestamp,
+        )
+        if df is None or df.empty:
+            return []
+        return df.to_dict(orient="records")
+
+    def link_pending_reasoning_events(self) -> None:
+        """Link reasoning events with chat_id IS NULL to the most recent chat
+        row for this session. Called once at the end of each reasoning loop
+        so the events emitted during that loop are tied to the chat reply
+        that closed it."""
+        try:
+            self._agent._monitoring_db_link_pending_reasoning_events(self)
+        except Exception as e:
+            logger.warning(
+                f"[Session] link_pending_reasoning_events failed for "
+                f"session {self.id}: {e}"
+            )
+
     def set(self, key: str, value: Any) -> None:
         """Set an entry to the session private data storage.
 

{besser_agentic_framework-4.3.3 → besser_agentic_framework-4.4.0}/baf/db/monitoring_db.py

@@ -44,6 +44,19 @@ TABLE_CHAT = 'chat'
 TABLE_EVENT = 'event'
 """The name of the database table that contains the event records"""
 
+TABLE_REASONING_STEP = 'reasoning_step'
+"""The name of the database table that contains reasoning-state step events
+and task-list snapshots (a single per-session timeline of everything that
+happens inside the reasoning loop)."""
+
+# Two values stored in TableReasoningStep.kind
+REASONING_KIND_STEP = 'reasoning_step'
+"""kind value for a reasoning step event (LLM tool call, tool result, push-back,
+task add/complete/skip, max_steps, reasoning_started/finished)."""
+
+REASONING_KIND_TASK_LIST_UPDATE = 'task_list_update'
+"""kind value for a task list snapshot."""
+
 
 class MonitoringDB:
     """This class is an interface to connect to a database where user interactions with the agent are stored to monitor
@@ -144,6 +157,35 @@ class MonitoringDB:
             info = Column(String, nullable=True)
             timestamp = Column(DateTime, nullable=False)
 
+        class TableReasoningStep(Base):
+            """All reasoning-state events for a session — both per-step events
+            (LLM tool calls, tool results, task add/complete/skip, push-back,
+            max_steps, reasoning_started/finished brackets) and task-list
+            snapshots. ``chat_id`` is optional: each event may be linked to
+            the chat row that closed the reasoning loop, but events emitted
+            during the loop start unlinked and are attached afterwards."""
+            __tablename__ = TABLE_REASONING_STEP
+            id = Column(Integer, primary_key=True, autoincrement=True)
+            session_id = Column(Integer, ForeignKey(f'{TABLE_SESSION}.id', ondelete='CASCADE'), nullable=False)
+            # Optional FK to the chat row that finalised the reasoning loop.
+            # Nullable on insert; populated by link_pending_reasoning_events.
+            chat_id = Column(Integer, ForeignKey(f'{TABLE_CHAT}.id', ondelete='SET NULL'), nullable=True)
+            # 'reasoning_step' or 'task_list_update'.
+            kind = Column(String, nullable=False)
+            # For kind='reasoning_step', the ReasoningStepKind value (e.g. 'llm_tool_calls').
+            # NULL for task_list_update rows.
+            step_kind = Column(String, nullable=True)
+            # For kind='reasoning_step', the loop iteration number.
+            # NULL for task_list_update rows.
+            step = Column(Integer, nullable=True)
+            # For kind='reasoning_step', the short human-readable summary.
+            # NULL for task_list_update rows.
+            summary = Column(String, nullable=True)
+            # Full structured payload: the ReasoningStep dict for step rows,
+            # or the list of task dicts for task_list_update rows.
+            payload = Column(JSONB, nullable=False)
+            timestamp = Column(DateTime, nullable=False)
+
         Base.metadata.create_all(self.conn)
         self.conn.commit()
 
@@ -387,6 +429,17 @@ class MonitoringDB:
             return
         session_db_id = result_session_id[0]
 
+        # Delete reasoning events first — chat rows referenced by chat_id
+        # would otherwise have to be SET NULL by CASCADE, costing an extra
+        # write. (FK CASCADE on session_id would also wipe these, but being
+        # explicit keeps deletion order predictable.)
+        try:
+            table_rs = Table(TABLE_REASONING_STEP, MetaData(), autoload_with=self.conn)
+            stmt_delete_rs = table_rs.delete().where(table_rs.c.session_id == session_db_id)
+            self.run_statement(stmt_delete_rs)
+        except Exception as e:
+            logger.debug(f"[MonitoringDB] delete_session: skipping reasoning_step ({e})")
+
         # Delete chat messages
         table_chat = Table(TABLE_CHAT, MetaData(), autoload_with=self.conn)
         stmt_delete_chat = table_chat.delete().where(table_chat.c.session_id == session_db_id)
@@ -477,6 +530,158 @@ class MonitoringDB:
 
         return pd.read_sql_query(stmt, self.conn)
 
+    # ─── Reasoning step / task-list-update events ──────────────────────────── #
+
+    def insert_reasoning_event(
+        self,
+        session: Session,
+        kind: str,
+        payload: Any,
+    ) -> Optional[int]:
+        """Insert a row into the reasoning_step table.
+
+        Args:
+            session (Session): the session that produced the event.
+            kind (str): one of ``REASONING_KIND_STEP`` /
+                ``REASONING_KIND_TASK_LIST_UPDATE``.
+            payload (Any): for ``REASONING_KIND_STEP`` the ``ReasoningStep``
+                dict (``{"kind", "step", "summary", "details"}``); for
+                ``REASONING_KIND_TASK_LIST_UPDATE`` the list of task dicts
+                (``[{"id", "description", "status", "result"}, ...]``).
+
+        Returns:
+            int | None: the inserted row id, or None on failure.
+        """
+        table = Table(TABLE_REASONING_STEP, MetaData(), autoload_with=self.conn)
+        session_entry = self.select_session(session)
+        if session_entry.empty:
+            logger.warning(
+                "[MonitoringDB] insert_reasoning_event: no session row found, skipping"
+            )
+            return None
+
+        # Pull the per-step columns out of the payload so they're queryable
+        # without unwrapping the JSONB blob. None for task_list_update rows.
+        step_kind: Optional[str] = None
+        step_num: Optional[int] = None
+        summary: Optional[str] = None
+        if kind == REASONING_KIND_STEP and isinstance(payload, dict):
+            step_kind = payload.get("kind")
+            step_num = payload.get("step")
+            summary = payload.get("summary")
+
+        stmt = insert(table).values(
+            session_id=int(session_entry["id"][0]),
+            chat_id=None,
+            kind=kind,
+            step_kind=step_kind,
+            step=step_num,
+            summary=summary,
+            payload=payload,
+            timestamp=datetime.now(),
+        ).returning(table.c.id)
+        try:
+            result = self.conn.execute(stmt)
+            self.conn.commit()
+            row = result.fetchone()
+            return int(row[0]) if row else None
+        except Exception as e:
+            logger.error(f"[MonitoringDB] insert_reasoning_event failed: {e}")
+            self.conn.rollback()
+            return None
+
+    def select_reasoning_events(
+        self,
+        session: Session,
+        until_timestamp: Optional[datetime] = None,
+    ) -> pd.DataFrame:
+        """Retrieve all reasoning-state events for a session, in chronological order.
+
+        Args:
+            session (Session): the session whose events to fetch.
+            until_timestamp (Optional[datetime]): if provided, only events at
+                or before this timestamp are returned.
+
+        Returns:
+            pandas.DataFrame: rows with columns
+            ``id``, ``session_id``, ``chat_id``, ``kind``, ``step_kind``,
+            ``step``, ``summary``, ``payload``, ``timestamp``. Empty if the
+            table doesn't exist (e.g. older DB without the migration applied).
+        """
+        try:
+            table = Table(TABLE_REASONING_STEP, MetaData(), autoload_with=self.conn)
+        except Exception as e:
+            logger.warning(
+                f"[MonitoringDB] select_reasoning_events: reasoning_step table "
+                f"not available — returning empty: {e}"
+            )
+            return pd.DataFrame()
+
+        session_entry = self.select_session(session)
+        if session_entry.empty:
+            return pd.DataFrame()
+
+        stmt = select(table).where(table.c.session_id == int(session_entry["id"][0]))
+        if until_timestamp is not None:
+            stmt = stmt.where(table.c.timestamp <= until_timestamp)
+        stmt = stmt.order_by(table.c.timestamp, table.c.id)
+        return pd.read_sql_query(stmt, self.conn)
+
+    def link_pending_reasoning_events(self, session: Session) -> int:
+        """Attach all reasoning events with chat_id IS NULL to the most recent
+        chat row for the session.
+
+        Best-effort: if the reasoning_step or chat tables don't exist yet, or
+        no chat row exists for the session, the method does nothing and
+        returns 0. Called once per reasoning loop after the final
+        ``session.reply()``.
+
+        Returns:
+            int: number of rows linked.
+        """
+        try:
+            rs_table = Table(TABLE_REASONING_STEP, MetaData(), autoload_with=self.conn)
+            chat_table = Table(TABLE_CHAT, MetaData(), autoload_with=self.conn)
+        except Exception as e:
+            logger.debug(
+                f"[MonitoringDB] link_pending_reasoning_events: skipping ({e})"
+            )
+            return 0
+
+        session_entry = self.select_session(session)
+        if session_entry.empty:
+            return 0
+        session_db_id = int(session_entry["id"][0])
+
+        # Find the latest chat row for the session (highest id wins on ties).
+        latest_stmt = (
+            select(chat_table.c.id)
+            .where(chat_table.c.session_id == session_db_id)
+            .order_by(desc(chat_table.c.timestamp), desc(chat_table.c.id))
+            .limit(1)
+        )
+        result = self.conn.execute(latest_stmt).first()
+        if result is None:
+            return 0
+        latest_chat_id = int(result[0])
+
+        update_stmt = (
+            rs_table.update()
+            .where(
+                rs_table.c.session_id == session_db_id,
+                rs_table.c.chat_id.is_(None),
+            )
+            .values(chat_id=latest_chat_id)
+        )
+        try:
+            res = self.conn.execute(update_stmt)
+            self.conn.commit()
+            return res.rowcount or 0
+        except Exception as e:
+            logger.error(f"[MonitoringDB] link_pending_reasoning_events failed: {e}")
+            self.conn.rollback()
+            return 0
+
     def run_statement(self, stmt: Executable) -> CursorResult[Any] | None:
         """Executes a SQL statement.