besser-agentic-framework 4.4.2__tar.gz → 4.5.0__tar.gz

{besser_agentic_framework-4.4.2/besser_agentic_framework.egg-info → besser_agentic_framework-4.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: besser-agentic-framework
-Version: 4.4.2
+Version: 4.5.0
 Summary: BESSER Agentic Framework (BAF)
 Author: Luxembourg Institute of Science and Technology
 License: MIT
@@ -61,7 +61,7 @@ Provides-Extra: tensorflow
 Requires-Dist: keras==3.12.0; extra == "tensorflow"
 Requires-Dist: tensorflow-cpu==2.20.0; extra == "tensorflow"
 Provides-Extra: torch
-Requires-Dist: torch==2.6.0+cpu; extra == "torch"
+Requires-Dist: torch==2.6.0; extra == "torch"
 Requires-Dist: scikit-learn>=1.7.0; extra == "torch"
 Provides-Extra: docs
 Requires-Dist: sphinx==7.2.3; extra == "docs"
@@ -91,7 +91,7 @@ Requires-Dist: replicate==0.23.1; extra == "all"
 Requires-Dist: transformers==4.53.0; extra == "all"
 Requires-Dist: keras==3.12.0; extra == "all"
 Requires-Dist: tensorflow-cpu==2.20.0; extra == "all"
-Requires-Dist: torch==2.6.0+cpu; extra == "all"
+Requires-Dist: torch==2.6.0; extra == "all"
 Requires-Dist: scikit-learn>=1.7.0; extra == "all"
 Dynamic: license-file
 Dynamic: provides-extra

{besser_agentic_framework-4.4.2 → besser_agentic_framework-4.5.0}/baf/core/agent.py

@@ -9,7 +9,7 @@ from pathlib import Path
 from typing import Any, Callable, get_type_hints
 
 import yaml
-
+from baf.core.gui.agent_gui import AgentGUI
 from baf.core.transition.event import Event
 from baf.core.message import Message, MessageType
 from baf.core.entity.entity import Entity
@@ -26,7 +26,7 @@ from baf.db.monitoring_db import MonitoringDB
 from baf.exceptions.exceptions import AgentNotTrainedError, DuplicatedEntityError, DuplicatedInitialStateError, \
     DuplicatedIntentError, DuplicatedStateError, InitialStateNotFound
 from baf.exceptions.logger import logger
-from baf.library.transition.events.base_events import ReceiveMessageEvent, ReceiveJSONEvent, ReceiveFileEvent
+from baf.library.transition.events.base_events import ReceiveMessageEvent, ReceiveJSONEvent, ReceiveFileEvent, GUIEvent
 from baf.nlp.intent_classifier.intent_classifier_configuration import IntentClassifierConfiguration, \
     SimpleIntentClassifierConfiguration
 from baf.nlp.intent_classifier.intent_classifier_prediction import IntentClassifierPrediction
@@ -138,6 +138,7 @@ class Agent:
         """dict[str, Any]: The agent configuration parameters."""
         return self._config
 
+
     def load_properties(self, path: str) -> None:
         """Read a properties file and store its properties in the agent configuration.
 
@@ -818,6 +819,18 @@ class Agent:
             session.save_message(Message(t=t, content=event.message, is_user=True, timestamp=datetime.now()))
         if isinstance(event, ReceiveFileEvent):
             session.save_message(Message(t=MessageType.FILE, content=event.file.get_json_string(), is_user=True, timestamp=datetime.now()))
+        if isinstance(event, GUIEvent) and not event.is_broadcasted():
+            message_id = event.message_id
+            if message_id and message_id in session.gui_inputs:
+                action = event.event_data.get('action')
+                value = event.event_data.get('value')
+                if action == 'onChange':
+                    field_name = event.event_data.get('name')
+                    if field_name is not None:
+                        session.gui_inputs[message_id][field_name] = value
+                elif action == 'onSubmit':
+                    if isinstance(value, dict):
+                        session.gui_inputs[message_id].update(value)
 
         logger.info(f'Received event: {event.log()}')
 

besser_agentic_framework-4.5.0/baf/core/gui/agent_gui.py

@@ -0,0 +1,291 @@
+"""AgentGUI: BAF's interface to besser's GUIModel, with optional-dependency handling."""
+from __future__ import annotations
+
+import copy
+import uuid
+
+from baf.exceptions.logger import logger
+
+try:
+    from besser.BUML.metamodel.gui.graphical_ui import GUIModel, ViewContainer
+    _BESSER_AVAILABLE = True
+except ImportError:
+    logger.warning(
+        "besser GUI dependencies could not be imported. GUI features will be unavailable. "
+        "Install with 'pip install --no-deps besser'."
+    )
+    GUIModel = None
+    ViewContainer = None
+    _BESSER_AVAILABLE = False
+
+
+class AgentGUI:
+    """BAF's interface to besser's :class:`GUIModel`, with helper methods for common GUI operations.
+
+    Handles the case where besser is not installed: all methods log a warning and return
+    ``None``/``False`` instead of raising an error. When besser *is* installed, attribute
+    access is transparently delegated to the inner model so that existing code that uses
+    ``gui.modules``, ``gui.name``, etc. continues to work unchanged.
+
+    Args:
+        model: the :class:`GUIModel` instance to wrap, or ``None``.
+        gui_id: identifier for the AgentGUI.
+        persist: whether to store GUI updates in the session or not. Defaults to true
+
+    Attributes:
+        _model: the inner :class:`GUIModel`, or ``None`` when besser is not installed or
+            no model has been set.
+        _id: identifier for the AgentGUI.
+        _persist: whether to store GUI updates in the session or not. Defaults to true
+    """
+
+    def __init__(self, model: GUIModel, gui_id: str | None = None, persist: bool = True, width: str | None = None):
+        self._model: GUIModel = model
+        if gui_id is None:
+            gui_id = str(uuid.uuid4())
+        self._id: str = gui_id
+        self._persist: bool = persist
+        self._width: str | None = width
+
+    # ------------------------------------------------------------------
+    # Core proxy behaviour
+    # ------------------------------------------------------------------
+
+    @property
+    def model(self):
+        """The underlying GUIModel instance, or None."""
+        return self._model
+
+    @property
+    def id(self) -> str:
+        """Unique identifier for this GUI reply message."""
+        return self._id
+
+    @property
+    def persist(self) -> bool:
+        """bool: If True, input values from GUI events for this component are persisted in the session's gui_inputs."""
+        return self._persist
+
+    @persist.setter
+    def persist(self, value: bool) -> None:
+        self._persist = value
+
+    @property
+    def width(self) -> str | None:
+        """str | None: CSS width applied to the GUI bubble in chat mode (e.g. '600px', '80%').
+        Overrides the default 78% max-width cap. None means use the default."""
+        return self._width
+
+    @width.setter
+    def width(self, value: str | None) -> None:
+        self._width = value
+
+    def __getattr__(self, name: str):
+        """Delegate attribute access to the inner GUIModel."""
+        model = self._model
+        if model is None:
+            if not _BESSER_AVAILABLE:
+                logger.warning(
+                    f"Cannot access attribute '{name}': besser is not installed. "
+                    "Install with 'pip install --no-deps besser'."
+                )
+            else:
+                logger.warning(f"Cannot access attribute '{name}': no GUI model set.")
+            return None
+        return getattr(model, name)
+
+    def __setattr__(self, name: str, value):
+        """Delegate attribute assignment to the inner GUIModel for non-private names."""
+        if name.startswith('_'):
+            super().__setattr__(name, value)
+            return
+        model = self._model
+        if model is None:
+            logger.warning(f"Cannot set attribute '{name}': no GUI model set.")
+            return
+        setattr(model, name, value)
+
+    def __bool__(self) -> bool:
+        return self._model is not None
+
+    # ------------------------------------------------------------------
+    # Helper: deep copy
+    # ------------------------------------------------------------------
+
+    def deep_copy(self) -> 'AgentGUI':
+        """Return a deep copy of this :class:`AgentGUI` and its inner model.
+
+        Returns:
+            AgentGUI: a new instance wrapping a deep-copied model.
+        """
+        model = self._model
+        if model is None:
+            return AgentGUI(None)
+        try:
+            return AgentGUI(copy.deepcopy(model))
+        except Exception as e:
+            logger.warning(f"Could not deep-copy GUI model: {e}. Returning a shallow reference.")
+            return AgentGUI(model)
+
+    # ------------------------------------------------------------------
+    # Helper: find
+    # ------------------------------------------------------------------
+
+    def find_components(self, field: str, value) -> list:
+        """Find all components in the model where ``getattr(component, field) == value``.
+
+        Recursively searches through all modules → screens → containers.
+
+        Args:
+            field (str): the attribute name to match (e.g. ``'component_id'``,
+                ``'name'``, ``'content'``).
+            value: the value to look for.
+
+        Returns:
+            list: all matching :class:`ViewElement` instances (empty list if none found).
+        """
+        model: GUIModel = self._model
+        if model is None:
+            logger.warning("Cannot find components: no GUI model set.")
+            return []
+        results = []
+        for module in model.modules:
+            for screen in module.screens:
+                self._collect_matching(screen.view_elements, field, value, results)
+        return results
+
+    def find_component(self, field: str, value):
+        """Find the first component in the model where ``getattr(component, field) == value``.
+
+        Recursively searches through all modules → screens → containers.
+
+        Args:
+            field (str): the attribute name to match (e.g. ``'component_id'``,
+                ``'name'``, ``'content'``).
+            value: the value to look for.
+
+        Returns:
+            The first matching :class:`ViewElement`, or ``None`` if not found.
+        """
+        results = self.find_components(field, value)
+        return results[0] if results else None
+
+    def _collect_matching(self, elements, field: str, value, results: list) -> None:
+        """Recursively collect into *results* every element where ``getattr(el, field) == value``."""
+        for el in elements:
+            if getattr(el, field, None) == value:
+                results.append(el)
+            child_elements = getattr(el, 'view_elements', None)
+            if child_elements:
+                self._collect_matching(child_elements, field, value, results)
+
+    # ------------------------------------------------------------------
+    # Helper: update
+    # ------------------------------------------------------------------
+
+    def update_component_by_id(self, component_id: str, **kwargs):
+        """Update attributes of a component located by its ``component_id``.
+
+        Args:
+            component_id (str): identifies the component to update.
+            **kwargs: attribute names and their new values.
+
+        Returns:
+            The updated component if found, or ``None``.
+        """
+        model = self._model
+        if model is None:
+            logger.warning("Cannot update component: no GUI model set.")
+            return None
+        component = self.find_component('component_id', component_id)
+        if component is None:
+            logger.warning(f"Component with id '{component_id}' not found in GUI model.")
+            return None
+        for attr, value in kwargs.items():
+            setattr(component, attr, value)
+        return component
+
+    # ------------------------------------------------------------------
+    # Helper: add
+    # ------------------------------------------------------------------
+
+    def add_component(self, component, parent_id: str = None, screen_name: str = None) -> bool:
+        """Add a component to the GUI model.
+
+        Resolution order:
+
+        1. If *parent_id* is given, the component is added to the container that has
+           that ``component_id`` (must be a container with ``view_elements``).
+        2. If *screen_name* is given, the component is added to the top-level
+           ``view_elements`` of the named screen.
+        3. Otherwise the component is added to the main screen (``is_main_page=True``),
+           or to the first screen when no main screen exists.
+
+        Args:
+            component: the :class:`ViewElement` to add.
+            parent_id (str | None): ``component_id`` of the target container.
+            screen_name (str | None): name of the target screen (used when *parent_id* is
+                not given).
+
+        Returns:
+            bool: ``True`` if the component was added, ``False`` otherwise.
+        """
+        model = self._model
+        if model is None:
+            logger.warning("Cannot add component: no GUI model set.")
+            return False
+
+        if parent_id is not None:
+            parent = self.find_component('component_id', parent_id)
+            if parent is None:
+                logger.warning(f"Parent container with id '{parent_id}' not found.")
+                return False
+            if not hasattr(parent, 'view_elements'):
+                logger.warning(f"Component '{parent_id}' is not a container (no view_elements).")
+                return False
+            parent.view_elements = parent.view_elements | {component}
+            return True
+
+        target = self.get_screen(screen_name)
+        if target is None:
+            logger.warning("No screen found to add the component to.")
+            return False
+        target.view_elements = target.view_elements | {component}
+        return True
+
+    # ------------------------------------------------------------------
+    # Helper: screens
+    # ------------------------------------------------------------------
+
+    def get_screen(self, screen_name: str = None):
+        """Retrieve a screen by name, or the main screen when no name is given.
+
+        Falls back to the first screen when there is no screen marked as main.
+
+        Args:
+            screen_name (str | None): the screen name to look for, or ``None`` to get
+                the main/first screen.
+
+        Returns:
+            The :class:`Screen`, or ``None`` if not found.
+        """
+        model = self._model
+        if model is None:
+            logger.warning("Cannot get screen: no GUI model set.")
+            return None
+
+        first = None
+        for module in model.modules:
+            for screen in module.screens:
+                if first is None:
+                    first = screen
+                if screen_name is not None:
+                    if screen.name == screen_name:
+                        return screen
+                elif getattr(screen, 'is_main_page', False):
+                    return screen
+
+        # Fallbacks
+        if screen_name is None:
+            return first
+        return None

{besser_agentic_framework-4.4.2 → besser_agentic_framework-4.5.0}/baf/core/gui/gui_deserializer.py

@@ -1,7 +1,8 @@
-"""Deserialization helpers: JSON string → GUIModel."""
+"""Deserialization helpers: JSON string → AgentGUI."""
 import json
 from types import SimpleNamespace
 
+from baf.core.gui.agent_gui import AgentGUI
 from baf.exceptions.logger import logger
 
 try:
@@ -10,6 +11,7 @@ try:
         ViewElement, ViewContainer, ViewComponent,
         Button, Text, Image, InputField, Form, Menu, MenuItem,
         DataList, EmbeddedContent, Link,
+        Alert, AlertSeverity, SelectOption,
     )
     from besser.BUML.metamodel.gui.style import Styling, Size, Position, Color, Layout
     from besser.BUML.metamodel.gui.dashboard import (
@@ -302,8 +304,22 @@ def _deserialize_view_element(d: dict) -> ViewElement:
         )
 
     if t == "InputField":
+        options_data = d.get("options") or []
+        options = [SelectOption(label=o.get("label", ""), value=o.get("value", "")) for o in options_data]
         return InputField(
-            field_type=d.get("field_type", "text"),
+            field_type=d.get("field_type", "Text"),
+            label=d.get("label", ""),
+            placeholder=d.get("placeholder", ""),
+            required=d.get("required", False),
+            default_value=d.get("default_value"),
+            options=options if options else None,
+            min_value=d.get("min_value"),
+            max_value=d.get("max_value"),
+            step=d.get("step"),
+            help_text=d.get("help_text"),
+            disabled=d.get("disabled", False),
+            readonly=d.get("readonly", False),
+            multiple=d.get("multiple", False),
             validationRules=d.get("validationRules"),
             **base,
         )
@@ -311,6 +327,11 @@ def _deserialize_view_element(d: dict) -> ViewElement:
     if t == "Form":
         return Form(
             inputFields=set(_deserialize_view_element(f) for f in d.get("inputFields", [])),
+            title=d.get("title"),
+            submit_label=d.get("submit_label", "Submit"),
+            show_cancel=d.get("show_cancel", False),
+            cancel_label=d.get("cancel_label", "Cancel"),
+            columns=d.get("columns", 1),
             **base,
         )
 
@@ -329,6 +350,18 @@ def _deserialize_view_element(d: dict) -> ViewElement:
     if t == "DataList":
         return DataList(list_sources=set(), **base)
 
+    if t == "Alert":
+        severity_str = d.get("severity", "info")
+        _severity_map = {s.value: s for s in AlertSeverity}
+        severity = _severity_map.get(severity_str, AlertSeverity.Info)
+        return Alert(
+            content=d.get("content", ""),
+            severity=severity,
+            title=d.get("title"),
+            dismissible=d.get("dismissible", False),
+            **base,
+        )
+
     if t == "EmbeddedContent":
         return EmbeddedContent(
             source=d.get("source", ""),
@@ -367,14 +400,14 @@ def _deserialize_screen(d: dict) -> Screen:
     return Screen(**base)
 
 
-def json_to_gui(json_str: str) -> GUIModel:
-    """Deserialize a JSON string produced by :func:`gui_to_json` back into a :class:`GUIModel`.
+def json_to_gui(json_str: str, gui_id: str | None = None) -> AgentGUI:
+    """Deserialize a JSON string produced by :func:`gui_to_json` back into an :class:`~baf.core.gui.agent_gui.AgentGUI`.
 
     Args:
         json_str: JSON string representing the GUI model.
 
     Returns:
-        A reconstructed :class:`GUIModel` instance.
+        A reconstructed :class:`~baf.core.gui.agent_gui.AgentGUI` instance wrapping the rebuilt model.
     """
     data = json.loads(json_str)
     modules = set()
@@ -392,7 +425,7 @@ def json_to_gui(json_str: str) -> GUIModel:
     style_entries = data.get("style_entries")
     if style_entries is not None:
         try:
-            return GUIModel(**gui_kwargs, style_entries=style_entries)
+            return AgentGUI(GUIModel(**gui_kwargs, style_entries=style_entries))
         except TypeError:
             pass
-    return GUIModel(**gui_kwargs)
+    return AgentGUI(GUIModel(**gui_kwargs), gui_id=gui_id)

besser_agentic_framework-4.5.0/baf/core/gui/gui_llm.py

@@ -0,0 +1,118 @@
+"""LLM-assisted GUI generation utilities."""
+from __future__ import annotations
+
+import json
+import re
+from typing import TYPE_CHECKING
+
+from baf.core.gui.agent_gui import AgentGUI
+from baf.core.gui.gui_deserializer import json_to_gui
+from baf.core.gui.gui_schema import get_json_schema
+from baf.exceptions.logger import logger
+
+if TYPE_CHECKING:
+    from baf.nlp.llm.llm import LLM
+
+_SYSTEM_PROMPT_TEMPLATE = (
+    "You are a GUI model generator. Given a user request, respond with a single valid JSON object "
+    "that conforms to the JSON Schema below. Output raw JSON only — no explanation, no markdown "
+    "code fences, no prose before or after.\n\n"
+    "JSON Schema:\n{schema}\n\n"
+    "Rules:\n"
+    "- The top-level object must contain 'name' and 'modules'.\n"
+    "- Each module must have 'name' and 'screens'.\n"
+    "- Each screen must have 'name' and 'view_elements'.\n"
+    "- Every view element must have a 'type' field discriminating its kind.\n"
+    "- Keep the model minimal but meaningful for the user request.\n"
+    "- Use realistic placeholder content (titles, labels, button labels, etc.)."
+)
+
+_RETRY_PROMPT_TEMPLATE = (
+    "The previous response could not be deserialized. Error: {error}\n\n"
+    "Please fix the JSON and respond again with a single valid JSON object only. "
+    "Original request: {prompt}"
+)
+
+
+def _build_system_prompt() -> str:
+    return _SYSTEM_PROMPT_TEMPLATE.format(schema=json.dumps(get_json_schema(), indent=2))
+
+
+def _extract_json(text: str) -> str:
+    """Strip markdown code fences and return the raw JSON string from LLM output."""
+    match = re.search(r'```(?:json)?\s*([\s\S]*?)\s*```', text)
+    if match:
+        return match.group(1).strip()
+    match = re.search(r'(\{[\s\S]*\})', text)
+    if match:
+        return match.group(1).strip()
+    return text.strip()
+
+
+def create_gui_with_llm(
+    llm: 'LLM',
+    prompt: str,
+    gui_id: str | None = None,
+    max_retries: int = 2,
+) -> AgentGUI:
+    """Generate an :class:`~baf.core.gui.agent_gui.AgentGUI` from a natural-language description.
+
+    The LLM is instructed via a system prompt to produce a JSON object conforming to
+    the AgentGUI JSON Schema. The JSON is then deserialized into a full
+    :class:`~baf.core.gui.agent_gui.AgentGUI` instance. If the first response fails to
+    parse or deserialize, the error is fed back to the LLM and the call is retried up to
+    *max_retries* times.
+
+    Args:
+        llm (LLM): any BAF :class:`~baf.nlp.llm.llm.LLM` instance with a ``predict`` method.
+        prompt (str): natural-language description of the GUI to generate (e.g.
+            ``"A login form with email, password fields and a Submit button."``).
+        gui_id (str | None): optional identifier forwarded to the returned
+            :class:`~baf.core.gui.agent_gui.AgentGUI`. A random UUID is used when
+            ``None`` (default).
+        max_retries (int): number of correction attempts when the LLM returns invalid or
+            non-deserializable JSON. Defaults to ``2``.
+
+    Returns:
+        AgentGUI | None: the generated GUI model, or ``None`` if generation failed after
+        all retries.
+
+    Example::
+
+        from baf.core.gui.gui_llm import create_gui_with_llm
+
+        gui = create_gui_with_llm(
+            llm=gpt,
+            prompt="A dashboard with a line chart and two metric cards.",
+        )
+        if gui is not None:
+            session.set_gui(gui)
+    """
+    system_prompt = _build_system_prompt()
+    current_prompt = prompt
+    last_error: Exception | None = None
+
+    for attempt in range(1 + max_retries):
+        raw = llm.predict(current_prompt, system_message=system_prompt)
+        try:
+            gui = json_to_gui(_extract_json(raw), gui_id=gui_id)
+            if attempt > 0:
+                logger.info(f"create_gui_with_llm: succeeded on attempt {attempt + 1}.")
+            return gui
+        except Exception as exc:
+            last_error = exc
+            if attempt < max_retries:
+                logger.warning(
+                    f"create_gui_with_llm: attempt {attempt + 1} failed — {exc}. Retrying..."
+                )
+                current_prompt = _RETRY_PROMPT_TEMPLATE.format(error=exc, prompt=prompt)
+            else:
+                logger.warning(
+                    f"create_gui_with_llm: attempt {attempt + 1} failed — {exc}. No more retries."
+                )
+
+    logger.error(
+        f"create_gui_with_llm: could not generate a valid GUI after {1 + max_retries} "
+        f"attempt(s). Last error: {last_error}"
+    )
+    return None