Agent model¶

class besser.BUML.metamodel.state_machine.agent.Agent(name: str)[source]¶

Bases: StateMachine

A agent model.

Parameters:: name (str) – the agent name

name¶

Inherited from StateMachine, represents the name of the agent.

Type:: str

visibility¶

Inherited from StateMachine, determines the kind of visibility of the agent (public as default).

Type:: str

states¶

Inherited from StateMachine, the states of the agent

Type:: list[state_machine.State]

properties¶

Inherited from StateMachine, the configuration properties of the agent.

Type:: list[ConfigProperty]

platforms¶

The agent platforms.

Type:: list[Platform]

default_ic_config¶

the intent classifier configuration used by default for the agent states.

Type:: IntentClassifierConfiguration

intents¶

The agent intents.

Type:: list[Intent]

entities¶

The agent entities.

Type:: list[Entity]

global_initial_states¶

List of tuples of initial global states and their triggering intent

Type:: list[state_machine.State, Intent]

_LLM_PROVIDERS: dict[str, type] = {'huggingface': <class 'besser.BUML.metamodel.state_machine.agent.LLMHuggingFace'>, 'huggingface_api': <class 'besser.BUML.metamodel.state_machine.agent.LLMHuggingFaceAPI'>, 'openai': <class 'besser.BUML.metamodel.state_machine.agent.LLMOpenAI'>, 'replicate': <class 'besser.BUML.metamodel.state_machine.agent.LLMReplicate'>}¶

_abc_impl = <_abc._abc_data object>¶

_validate_llm_references(errors: list[str], warnings: list[str]) → None[source]¶: Validate that every llm_name reference resolves to a registered LLM.

_validate_reasoning_primitives(errors: list[str], warnings: list[str]) → None[source]¶: Validate the reasoning extension’s metamodel constraints.

_validate_state_intent_name_collisions(errors: list[str])[source]¶: Ensure state names and intent names do not overlap in the same agent.

_validate_transition_intent_references(errors: list[str])[source]¶: Ensure intent-matching transitions only reference intents defined in the agent.

add_entity(entity: Entity) → Entity[source]¶

Add an entity to the agent.

Parameters:: entity (Entity) – the entity to add
Returns:: the added entity
Return type:: Entity

add_intent(intent: Intent) → Intent[source]¶

Add an intent to the agent.

Parameters:: intent (Intent) – the intent to add
Returns:: the added intent
Return type:: Intent

add_reasoning_state(state: ReasoningState) → ReasoningState[source]¶: Add a pre-built ReasoningState to the agent’s state list.

add_skill(skill: Skill) → Skill[source]¶: Add a pre-built Skill to the agent.

add_tool(tool: Tool) → Tool[source]¶

Add a pre-built Tool to the agent.

Mirrors add_intent() — the caller constructs the wrapper, this method registers it. Use new_tool() to skip the explicit Tool(...) construction.

Parameters:: tool (Tool) – the tool to register.
Returns:: the registered tool.
Return type:: Tool

add_workspace(workspace: Workspace) → Workspace[source]¶: Add a pre-built Workspace to the agent.

new_entity(name: BaseEntityImpl, base_entity: bool = False, entries: dict[str, list[str]] = None, description: str = None) → Entity[source]¶

Create a new entity in the agent.

Parameters:

name (str) – the entity name. It must be unique in the agent
base_entity (bool) – whether the entity is a base entity or not (i.e. a custom entity)
entries (dict[str, list[str]] or None) – the entity entries
description (str or None) – a description of the entity, optional

Returns:

the entity

Return type:

Entity

new_intent(name: str, training_sentences: list[str] = None, parameters: list[IntentParameter] = None, description: str = None) → Intent[source]¶

Create a new intent in the agent.

Parameters:

name (str) – the intent name. It must be unique in the agent
training_sentences (list[str] or None) – the intent’s training sentences
parameters (list[IntentParameter] or None) – the intent parameters, optional
description (str or None) – a description of the intent, optional

Returns:

the intent

Return type:

Intent

new_llm(name: str, provider: str = 'openai', parameters: dict | None = None, num_previous_messages: int = 1, global_context: str | None = None) → LLMWrapper[source]¶

provider selects the concrete subclass: openai → LLMOpenAI, huggingface → LLMHuggingFace, huggingface_api → LLMHuggingFaceAPI, replicate → LLMReplicate. Names must be unique on the agent so other elements (reasoning states, RAG, replies, intent classifiers) can reference the LLM by llm_name.

new_rag(name: str, vector_store: RAGVectorStore, splitter: RAGTextSplitter, llm_name: str, llm_prompt: str | None = None, k: int = 4, num_previous_messages: int = 0) → RAG[source]¶: Register a Retrieval-Augmented Generation configuration on the agent.

new_reasoning_state(name: str, llm: str | None = None, initial: bool = False, max_steps: int = 8, enable_task_planning: bool = True, stream_steps: bool = True, system_prompt: str | None = None, fallback_message: str | None = None) → ReasoningState[source]¶

Create a new ReasoningState on the agent.

Mirrors new_state() for non-reasoning states. The llm argument may be omitted during incremental model construction (e.g. while the diagram is being built); it must be set before code generation.

new_skill(name: str, content: str = '', description: str | None = None) → Skill[source]¶: Build a Skill and register it on the agent.

new_state(name: str, initial: bool = False, ic_config: IntentClassifierConfiguration = None) → AgentState[source]¶

Create a new state in the agent.

Parameters:

name (str) – the state name. It must be unique in the agent.
initial (bool) – whether the state is initial or not. A agent must have 1 initial state.
ic_config (IntentClassifierConfiguration or None) – the intent classifier configuration for the state. If None is provided, the agent’s default one will be assigned to the state.

Returns:

the state

Return type:

AgentState

new_tool(name: str, description: str = '', code: str = '') → Tool[source]¶: Build a Tool and register it on the agent.

new_workspace(name: str, path: str = '', description: str | None = None, writable: bool = True, max_read_bytes: int = 200000) → Workspace[source]¶: Build a Workspace and register it on the agent.

set_default_llm(name: str) → None[source]¶

Mark the LLM with the given name as the agent’s default.

The default LLM is the one used by every consumer (LLMReply, DBReply, RAG, intent classifier) that does not specify its own llm_name. The named LLM must already be registered on the agent via new_llm().

use_telegram_platform() → TelegramPlatform[source]¶

Use the TelegramPlatform on this agent.

Returns:: the telegram platform
Return type:: TelegramPlatform

use_websocket_platform() → WebSocketPlatform[source]¶

Use the WebSocketPlatform on this agent.

Returns:: the websocket platform
Return type:: WebSocketPlatform

validate(raise_exception: bool = True) → dict[source]¶

Validate the agent model according to agent constraints.

Parameters:: raise_exception (bool) – If True, raise ValueError when validation fails.
Returns:: Validation result with success flag, errors, and warnings.
Return type:: dict

class besser.BUML.metamodel.state_machine.agent.AgentReply(message: str)[source]¶

Bases: Action

Primitive action that represents sending a reply message.

Parameters:: message (Expression) – The message to send (can be Literal, VariableRef, ParameterRef, or any Expression)

message¶

The message expression

Type:: Expression

_abc_impl = <_abc._abc_data object>¶

message: str¶

class besser.BUML.metamodel.state_machine.agent.AgentSession[source]¶

Bases: Session

A user session in a agent execution.

When a user starts interacting with a state machine, a session is assigned to him/her to store user related information, such as the current state of the agent or any custom variable. A session can be accessed from the body of the states to read/write user information. If a state machine does not have the concept of ‘users’ (i.e., there are no concurrent executions of the state machine, but a single one) then it could simply have 1 unique session.

id¶

Inherited from Session, the session id, which must unique among all state machine sessions

Type:: str

current_state¶

Inherited from Session, the current state in the state machine for this session

Type:: str

message¶

The last message sent to the agent by this session

Type:: str

predicted_intent¶

The last predicted intent for this session

Type:: IntentClassifierPrediction

file¶

The last file sent to the agent.

Type:: File

chat_history¶

The session chat history

Type:: list[tuple[str, int]]

chat_history: list[tuple[str, int]]¶

file: File¶

message: str¶

predicted_intent: IntentClassifierPrediction¶

reply(message: str) → None[source]¶

A agent message (usually a reply to a user message) is sent to the session platform to show it to the user.

Parameters:: message (str) – the agent reply

class besser.BUML.metamodel.state_machine.agent.AgentState(agent: Agent, name: str, initial: bool = False, ic_config: IntentClassifierConfiguration = None)[source]¶

Bases: State

A agent state.

Parameters:

agent (Agent) – the agent the state belongs to
name (str) – the state name
initial (bool) – whether the state is initial or not

name¶

Inherited from State, the state name

Type:: str

visibility¶

Inherited from State, determines the kind of visibility of the state (public as default).

Type:: str

sm¶

Inherited from State, the state machine the state belongs to

Type:: StateMachine

initial¶

Inherited from State, whether the state is initial or not

Type:: bool

transitions¶

Inherited from State, the state’s transitions to other states

Type:: list[Transition]

body¶

Inherited from State, the body of the state

Type:: Body

fallback_body¶

Inherited from State, the fallback body of the state

Type:: Body

_transition_counter¶

Inherited from State, count the number of transitions of this state. Used to name the transitions.

Type:: int

_abc_impl = <_abc._abc_data object>¶

agent: Agent¶

go_to(dest: AgentState) → None[source]¶

Create a new auto transition on this state.

This transition needs no event to be triggered, which means that when the agent moves to a state that has an auto transition, the agent will move to the transition’s destination state unconditionally without waiting for user input. This transition cannot be combined with other transitions.

Parameters:: dest (AgentState) – the destination state

ic_config: IntentClassifierConfiguration¶

intents: list[Intent]¶

set_global(intent: Intent)[source]¶

Set state as globally accessible state.

Parameters:: intent (Intent) – the intent that should trigger the jump to the global state

when_condition(condition: Condition) → TransitionBuilder[source]¶

Start the definition of a transition triggered by a custom condition.

Parameters:: condition (Condition) – Condition instance evaluated by the transition.
Returns:: the transition builder
Return type:: TransitionBuilder

when_event(event: Event) → TransitionBuilder[source]¶

Start the definition of a transition triggered by a custom event.

Parameters:: event (Event) – Event instance used to trigger the transition.
Returns:: the transition builder
Return type:: TransitionBuilder

when_file_received(allowed_types: list[str] = None) → TransitionBuilder[source]¶

Start the definition of a “file received” transition on this state.

Parameters:: allowed_types (list[str] or str) – the file types to consider for this transition. List of strings or just 1 string are valid values
Returns:: the transition builder
Return type:: TransitionBuilder

when_intent_matched(intent: Intent) → TransitionBuilder[source]¶

Start the definition of an “intent matching” transition on this state.

Parameters:: intent (Intent) – the target intent for the transition to be triggered
Returns:: the transition builder
Return type:: TransitionBuilder

when_no_intent_matched() → TransitionBuilder[source]¶

when_variable_matches_operation(var_name: str, operation: Callable[[Any, Any], bool], target: Any) → TransitionBuilder[source]¶

Start the definition of a “variable matching operator” transition on this state.

This transition evaluates if (variable operator target_value) is satisfied. For instance, “age > 18”.

Parameters:

var_name (str) – the name of the variable to evaluate. The variable must exist in the user session
operation (Callable[[Any, Any], bool]) – the operation to apply to the variable and the target value. It gets as arguments the variable and the target value, and returns a boolean value
target (Any) – the target value to compare with the variable

Returns:

the transition builder

Return type:

TransitionBuilder

class besser.BUML.metamodel.state_machine.agent.Auto[source]¶

Bases: Condition

This condition always returns True.

name¶

Inherited from Event, represents the name of the event.

Type:: str

visibility¶

Inherited from Event, represents the visibility of the event.

Type:: str

type¶

Inherited from Event, represents the type of the event.

Type:: Type

is_abstract¶

Inherited from Event, indicates if the event is abstract.

Type:: bool

parameters¶

Inherited from Event, the set of parameters for the event.

Type:: set[structural.Parameter]

owner¶

Inherited from Event, the type that owns the property.

Type:: Type

code¶

Inherited from Event, code of the event.

Type:: str

_abc_impl = <_abc._abc_data object>¶

class besser.BUML.metamodel.state_machine.agent.BaseEntity(name: BaseEntityImpl)[source]¶

Bases: Entity

Predefined entities, which are provided by the agent framework and do not need the user to define them.

Parameters:: name (BaseEntityImpl) – the entity’s name

name¶

Inherited from Entity, represents the name of the entity.

Type:: str

visibility¶

Inherited from NamedElement, represents the visibility of the entity.

Type:: str

_abc_impl = <_abc._abc_data object>¶

class besser.BUML.metamodel.state_machine.agent.BaseEntityImpl(*values)[source]¶

Bases: Enum

All the available base entities.

any = 'any_entity'¶

datetime = 'datetime_entity'¶

number = 'number_entity'¶

class besser.BUML.metamodel.state_machine.agent.CustomEntity(name: str, description: str, entries: list[EntityEntry])[source]¶

Bases: Entity

An entity with custom values.

Parameters:

name (str) – the entity’s name
entries (list[EntityEntry]) – the entity entries. If base_entity, there are no entries (i.e. None)
description (str) – a description of the entity, optional

name¶

Inherited from Entity, represents the name of the entity.

Type:: str

visibility¶

Inherited from NamedElement, represents the visibility of the entity.

Type:: str

description¶

a description of the entity, optional

Type:: str

entries¶

the entity entries

Type:: list[EntityEntry]

_abc_impl = <_abc._abc_data object>¶

description: str¶

entries: list[EntityEntry]¶

class besser.BUML.metamodel.state_machine.agent.DBReply(db_selection_type: str = 'default', db_custom_name: str | None = None, db_query_mode: str = 'llm_query', db_operation: str = 'any', db_sql_query: str | None = None, llm_name: str | None = None)[source]¶

Bases: Action

Primitive action that represents fetching information from a database.

Parameters:

db_selection_type (str) – Database selection mode. Supported values are default and custom.
db_custom_name (str, optional) – Custom database identifier used when db_selection_type is custom.
db_query_mode (str) – Query execution mode. Supported values are llm_query and sql.
db_operation (str) – SQL operation restriction. Supported values are any, select, insert, update and delete.
db_sql_query (str, optional) – SQL query to run when db_query_mode is sql.

db_selection_type¶

Whether the default application database or a named custom database is used.

Type:: str

db_custom_name¶

Name of the custom database when applicable.

Type:: str | None

db_query_mode¶

How the query will be produced at runtime.

Type:: str

db_operation¶

Which DB handler method must be used when executing the query.

Type:: str

db_sql_query¶

Raw SQL query when SQL mode is selected.

Type:: str | None

VALID_OPERATIONS = {'any', 'delete', 'insert', 'select', 'update'}¶

VALID_QUERY_MODES = {'llm_query', 'sql'}¶

VALID_SELECTION_TYPES = {'custom', 'default'}¶

_abc_impl = <_abc._abc_data object>¶

db_custom_name: str | None¶

db_operation: str¶

db_query_mode: str¶

db_selection_type: str¶

db_sql_query: str | None¶

llm_name: str | None¶

class besser.BUML.metamodel.state_machine.agent.DummyEvent[source]¶

Bases: Event

Represents a placeholder event.

_abc_impl = <_abc._abc_data object>¶

class besser.BUML.metamodel.state_machine.agent.Entity(name: str)[source]¶

Bases: NamedElement

Entities are used to specify the type of information to extract from user inputs. These entities are embedded in intent parameters.

Parameters:: name (str) – Inherited from NamedElement, the entity’s name

name¶

Inherited from NamedElement, represents the name of the entity.

Type:: str

visibility¶

Inherited from NamedElement, represents the visibility of the entity.

Type:: str

_abc_impl = <_abc._abc_data object>¶

class besser.BUML.metamodel.state_machine.agent.EntityEntry(value: str, synonyms: list[str])[source]¶

Bases: object

Each one of the entries an entity consists of.

Parameters:

value (str) – the entry value
synonyms (list[str] or None) – the value synonyms

value¶

the entry value

Type:: str

synonyms¶

The value synonyms

Type:: list[str]

synonyms: list[str]¶

value: str¶

class besser.BUML.metamodel.state_machine.agent.File(file_name: str = None, file_type: str = None, file_base64: str = None, file_path: str = None, file_data: bytes = None)[source]¶

Bases: object

A representation of files sent and received by a agent.

Files are used to encapsulate information about the files exchanged in a agent conversation. They include attributes such as the file’s name, type, and base64 representation. Note that at least one of path, data or base64 need to be set.

Parameters:

file_name (str) – The name of the file.
file_type (str) – The type of the file.
file_base64 (str, optional) – The base64 representation of the file.
file_path (str, optional) – Path to the file.
file_data (bytes, optional) – Raw file data.

name¶

The name of the file.

Type:: str

type¶

The type of the file.

Type:: str

base64¶

The base64 representation of the file.

Type:: str

base64: str¶

name: str¶

type: str¶

class besser.BUML.metamodel.state_machine.agent.FileTypeMatcher(allowed_types: list[str] = None)[source]¶

Bases: Condition

This event only returns True if a user just sent a file.

Parameters:: allowed_types (list[str]) – The file types that will be considered in the event

name¶

Inherited from Event, represents the name of the event.

Type:: str

visibility¶

Inherited from Event, represents the visibility of the event.

Type:: str

type¶

Inherited from Event, represents the type of the event.

Type:: Type

is_abstract¶

Inherited from Event, indicates if the event is abstract.

Type:: bool

parameters¶

Inherited from Event, the set of parameters for the event.

Type:: set[structural.Parameter]

owner¶

Inherited from Event, the type that owns the property.

Type:: Type

code¶

Inherited from Event, code of the event.

Type:: str

allowed_types¶

The file types that will be considered in the event

Type:: list[str]

_abc_impl = <_abc._abc_data object>¶

allowed_types: list[str] or str¶

class besser.BUML.metamodel.state_machine.agent.Intent(name: str, training_sentences: list[str] = None, parameters: list[IntentParameter] = None, description: str = None)[source]¶

Bases: NamedElement

Intents define the intentions or goals the user can express to a agent.

An intent is defined by a set of training sentences representing the different ways a user could express an intention (e.g. “Hi”, “Hello” for a Greetings intent) and/or with a description.

Intents can also define parameters that are filled with information extracted from the user input using entities.

Parameters:

name (str) – the intent’s name
training_sentences (list[str] or None) – the intent’s training sentences
parameters (list[IntentParameter] or None) – the intent’s parameters
description (str or None) – a description of the intent, optional

name¶

Inherited from NamedElement, represents the name of the intent

Type:: str

visibility¶

Inherited from NamedElement, represents the visibility of the intent

Type:: str

description¶

a description of the intent, optional

Type:: str or None

training_sentences¶

The intent’s training sentences

Type:: list[str]

parameters¶

The intent’s parameters

Type:: list[IntentParameter]

_abc_impl = <_abc._abc_data object>¶

description: str¶

parameter(name: str, fragment: str, entity: Entity)[source]¶

Add a parameter to the list of intent parameters.

Parameters:

name (str) – The name of the parameter.
fragment (str) – A description or fragment associated with the parameter.
entity (Entity) – The entity that this parameter is related to.

Returns:

Returns the instance of Intent it was called on (i.e., self).

Return type:

Intent

parameters: list[IntentParameter]¶

training_sentences: list[str]¶

class besser.BUML.metamodel.state_machine.agent.IntentClassifierConfiguration[source]¶

Bases: ABC

The Intent Classifier Configuration abstract class.

This configuration is assigned to a state, allowing the customization of its intent classifier.

This class serves as a template to implement intent classifier configurations for the different Intent Classifiers.

_abc_impl = <_abc._abc_data object>¶

class besser.BUML.metamodel.state_machine.agent.IntentClassifierPrediction(intent: Intent, score: float = None, matched_sentence: str = None, matched_parameters: list[MatchedParameter] = None)[source]¶

Bases: object

The prediction result of an Intent Classifier for a specific intent.

The intent classifier tries to determine the intent of a user message. For each possible intent, it will return an IntentClassifierPrediction containing the results, that include the probability itself and other information.

Parameters:

intent (Intent) – the target intent of the prediction
score (float) – the probability that this is the actual intent of the user message
matched_sentence (str) – the sentence used in the intent classifier (the original user message is previously processed, is modified by the NER, etc.)
matched_parameters (list[MatchedParameter]) – the list of parameters (i.e. entities) found in the user message

intent¶

The target intent of the prediction

Type:: Intent

score¶

The probability that this is the message intent

Type:: float

matched_sentence¶

The sentence used in the intent classifier (the original user message is previously processed, is modified by the NER, etc.)

Type:: str

matched_parameters¶

The list of parameters (i.e. entities) found in the user message

Type:: list[MatchedParameter]

get_parameter(name: str) → MatchedParameter[source]¶

Get a parameter from the intent classifier prediction.

Parameters:: name (str) – the name of the parameter to get
Returns:: the parameter if it exists, None otherwise
Return type:: MatchedParameter or None

intent: Intent¶

matched_parameters: list[MatchedParameter]¶

matched_sentence: str¶

score: float¶

class besser.BUML.metamodel.state_machine.agent.IntentMatcher(intent: Intent)[source]¶

Bases: Condition

This event checks if 2 intents are the same (returning True, and False otherwise), used for intent matching checking.

Parameters:: intent (Intent) – The reference intent to compare with the target intent

name¶

Inherited from Event, represents the name of the event.

Type:: str

visibility¶

Inherited from Event, represents the visibility of the event.

Type:: str

type¶

Inherited from Event, represents the type of the event.

Type:: Type

is_abstract¶

Inherited from Event, indicates if the event is abstract.

Type:: bool

parameters¶

Inherited from Event, the set of parameters for the event.

Type:: set[structural.Parameter]

owner¶

Inherited from Event, the type that owns the property.

Type:: Type

code¶

Inherited from Event, code of the event.

Type:: str

intent¶

The reference intent to compare with the target intent

Type:: Intent

_abc_impl = <_abc._abc_data object>¶

intent: Intent¶

class besser.BUML.metamodel.state_machine.agent.IntentParameter(name: str, fragment: str, entity: Entity)[source]¶

Bases: NamedElement

The intent parameter.

An intent parameter is composed by a name, a fragment and an entity. The fragment is the intent’s training sentence substring where an entity should be matched. E.g. in an intent with the training sentence “What is the weather in CITY?” we could define a parameter named “city” in the fragment “CITY” that should match with any value in the entity “city_entity” (previously defined)

Parameters:

name (str) – the intent parameter name
fragment (str) – the fragment the intent’s training sentences that is expected to match with the entity
entity (Entity) – the entity to be matched in this parameter

name¶

Inherited from NamedElement, represents the name of the intent parameter.

Type:: str

visibility¶

Inherited from NamedElement, represents the visibility of the intent parameter.

Type:: str

fragment¶

The fragment the intent’s training sentences that is expected to match with the entity

Type:: str

entity¶

The entity to be matched in this parameter

Type:: Entity

_abc_impl = <_abc._abc_data object>¶

entity: Entity¶

fragment: str¶

class besser.BUML.metamodel.state_machine.agent.LLMChatReply(prompt: str | None = None, llm_name: str | None = None)[source]¶

Bases: Action

Primitive action that represents sending a chat-style reply using an LLM.

Parameters:

prompt (str, optional) – Additional system prompt injected in the chat call.
llm_name (str, optional) – Name of the LLM (registered on the agent via Agent.new_llm()) that should serve this reply. None lets the generator fall back to the agent’s default LLM.

prompt¶

Optional system prompt used by llm.chat(...).

Type:: str | None

llm_name¶

Name of the LLM used for this reply.

Type:: str | None

_abc_impl = <_abc._abc_data object>¶

llm_name: str | None¶

prompt: str | None¶

class besser.BUML.metamodel.state_machine.agent.LLMHuggingFace(agent: Agent, name: str, parameters: dict, num_previous_messages: int = 1, global_context: str = None)[source]¶

Bases: LLMWrapper

A HuggingFace LLM wrapper.

Normally, we consider an LLM in HuggingFace those models under the tasks text-generation or text2text-generation tasks (more info), but there could be exceptions for other tasks (which have not been tested in this class).

Parameters:

agent (Agent) – the agent the LLM belongs to
name (str) – the LLM name
parameters (dict) – the LLM parameters
num_previous_messages (int) – for the chat functionality, the number of previous messages of the conversation to add to the prompt context (must be > 0).
global_context (str) – the global context to be provided to the LLM for each request

name¶

the LLM name

Type:: str

parameters¶

the LLM parameters

Type:: dict

num_previous_messages¶

for the chat functionality, the number of previous messages of the conversation to add to the prompt context (must be > 0).

Type:: int

_global_context¶

the global context to be provided to the LLM for each request

Type:: str

_abc_impl = <_abc._abc_data object>¶

agent: Agent¶

num_previous_messages: int¶

set_model(name: str) → None[source]¶

Set the LLM model name.

Parameters:: name (str) – the new LLM name

set_num_previous_messages(num_previous_messages: int) → None[source]¶

Set the number of previous messages to use in the chat functionality

Parameters:: num_previous_messages (int) – the new number of previous messages

class besser.BUML.metamodel.state_machine.agent.LLMHuggingFaceAPI(agent: Agent, name: str, parameters: dict, num_previous_messages: int = 1, global_context: str = None)[source]¶

Bases: LLMWrapper

A HuggingFace LLM wrapper for HuggingFace’s Inference API.

Parameters:

agent (Agent) – the agent the LLM belongs to
name (str) – the LLM name
parameters (dict) – the LLM parameters
num_previous_messages (int) – for the chat functionality, the number of previous messages of the conversation to add to the prompt context (must be > 0).
global_context (str) – the global context to be provided to the LLM for each request

name¶

the LLM name

Type:: str

parameters¶

the LLM parameters

Type:: dict

num_previous_messages¶

for the chat functionality, the number of previous messages of the conversation to add to the prompt context (must be > 0).

Type:: int

_global_context¶

the global context to be provided to the LLM for each request

Type:: str

_abc_impl = <_abc._abc_data object>¶

agent: Agent¶

num_previous_messages: int¶

set_model(name: str) → None[source]¶

Set the LLM model name.

Parameters:: name (str) – the new LLM name

set_num_previous_messages(num_previous_messages: int) → None[source]¶

Set the number of previous messages to use in the chat functionality

Parameters:: num_previous_messages (int) – the new number of previous messages

class besser.BUML.metamodel.state_machine.agent.LLMIntentClassifierConfiguration(llm_suite: LLMSuite | None = None, parameters: dict = None, use_intent_descriptions: bool = False, use_training_sentences: bool = False, use_entity_descriptions: bool = False, use_entity_synonyms: bool = False, llm_name: str | None = None)[source]¶

Bases: IntentClassifierConfiguration

The LLM Intent Classifier Configuration class.

Parameters:

llm_suite (LLMSuite | None) – the service provider from which we will load/access the LLM. Optional when llm_name is provided — in that case the suite is resolved from the named LLM’s class.
parameters (dict) – the LLM parameters (this will vary depending on the suite and the LLM)
use_intent_descriptions (bool) – whether to include the intent descriptions in the LLM prompt
use_training_sentences (bool) – whether to include the intent training sentences in the LLM prompt
use_entity_descriptions (bool) – whether to include the entity descriptions in the LLM prompt
use_entity_synonyms (bool) – whether to include the entity value’s synonyms in the LLM prompt
llm_name (str, optional) – Name of an LLM registered on the agent (via Agent.new_llm()) that this classifier should use.

llm_suite¶

the service provider from which we will load/access the LLM

Type:: str | None

parameters¶

the LLM parameters (this will vary depending on the suite and the LLM)

Type:: dict

use_intent_descriptions¶

whether to include the intent descriptions in the LLM prompt

Type:: bool

use_training_sentences¶

whether to include the intent training sentences in the LLM prompt

Type:: bool

use_entity_descriptions¶

whether to include the entity descriptions in the LLM prompt

Type:: bool

use_entity_synonyms¶

whether to include the entity value’s synonyms in the LLM prompt

Type:: bool

llm_name¶

Name of the registered LLM that this classifier should use.

Type:: str | None

_abc_impl = <_abc._abc_data object>¶

llm_name: str | None¶

llm_suite: str | None¶

parameters: dict¶

use_entity_descriptions: bool¶

use_entity_synonyms: bool¶

use_intent_descriptions: bool¶

use_training_sentences: bool¶

class besser.BUML.metamodel.state_machine.agent.LLMOpenAI(agent: Agent, name: str, parameters: dict, num_previous_messages: int = 1, global_context: str = None)[source]¶

Bases: LLMWrapper

An LLM wrapper for OpenAI’s LLMs through its API.

Parameters:

agent (Agent) – the agent the LLM belongs to
name (str) – the LLM name
parameters (dict) – the LLM parameters
num_previous_messages (int) – for the chat functionality, the number of previous messages of the conversation to add to the prompt context (must be > 0).
global_context (str) – the global context to be provided to the LLM for each request

_nlp_engine¶

the NLPEngine that handles the NLP processes of the agent the LLM belongs to

Type:: NLPEngine

name¶

the LLM name

Type:: str

parameters¶

the LLM parameters

Type:: dict

num_previous_messages¶

for the chat functionality, the number of previous messages of the conversation to add to the prompt context (must be > 0).

Type:: int

_global_context¶

the global context to be provided to the LLM for each request

Type:: str

_user_context¶

user specific context to be provided to the LLM for each request

Type:: dict

_abc_impl = <_abc._abc_data object>¶

agent: Agent¶

num_previous_messages: int¶

set_model(name: str) → None[source]¶

Set the LLM model name.

Parameters:: name (str) – the new LLM name

set_num_previous_messages(num_previous_messages: int) → None[source]¶

Set the number of previous messages to use in the chat functionality

Parameters:: num_previous_messages (int) – the new number of previous messages

class besser.BUML.metamodel.state_machine.agent.LLMReplicate(agent: Agent, name: str, parameters: dict, num_previous_messages: int = 1, global_context: str = None)[source]¶

Bases: LLMWrapper

An LLM wrapper for Replicate’s LLMs through its API.

Parameters:

agent (Agent) – the agent the LLM belongs to
name (str) – the LLM name
parameters (dict) – the LLM parameters
num_previous_messages (int) – for the chat functionality, the number of previous messages of the conversation to add to the prompt context (must be > 0)
global_context (str) – the global context to be provided to the LLM for each request

_nlp_engine¶

the NLPEngine that handles the NLP processes of the agent the LLM belongs to

Type:: NLPEngine

name¶

the LLM name

Type:: str

parameters¶

the LLM parameters

Type:: dict

num_previous_messages¶

for the chat functionality, the number of previous messages of the conversation to add to the prompt context (must be > 0)

Type:: int

_global_context¶

the global context to be provided to the LLM for each request

Type:: str

_user_context¶

user specific context to be provided to the LLM for each request

Type:: dict

_abc_impl = <_abc._abc_data object>¶

agent: Agent¶

num_previous_messages: int¶

set_model(name: str) → None[source]¶

Set the LLM model name.

Parameters:: name (str) – the new LLM name

set_num_previous_messages(num_previous_messages: int) → None[source]¶

Set the number of previous messages to use in the chat functionality

Parameters:: num_previous_messages (int) – the new number of previous messages

class besser.BUML.metamodel.state_machine.agent.LLMReply(prompt: str | None = None, llm_name: str | None = None)[source]¶

Bases: Action

Primitive action that represents sending a reply using an LLM.

Parameters:

prompt (str, optional) – Additional system prompt injected when calling the LLM.
llm_name (str, optional) – Name of the LLM (registered on the agent via Agent.new_llm()) that should serve this reply. None lets the generator fall back to the agent’s default LLM.

prompt¶

Optional system prompt that augments the user message.

Type:: str | None

llm_name¶

Name of the LLM used for this reply.

Type:: str | None

_abc_impl = <_abc._abc_data object>¶

llm_name: str | None¶

prompt: str | None¶

class besser.BUML.metamodel.state_machine.agent.LLMSuite(*values)[source]¶

Bases: Enum

Enumeration of the available LLM suites.

huggingface = 'huggingface'¶

huggingface_inference_api = 'huggingface-inference-api'¶

openai = 'openai'¶

replicate = 'replicate'¶

class besser.BUML.metamodel.state_machine.agent.LLMWrapper(name: str, agent: Agent, parameters: dict, global_context: str = None)[source]¶

Bases: ABC

The LLM Wrapper class.

Parameters:

name (str) – the LLM name
parameters (dict) – the LLM parameters (this will vary depending on the LLM)
global_context (str) – the global context to be used in the LLM prompt

name¶

the LLM name

Type:: str

parameters¶

the LLM parameters (this will vary depending on the LLM)

Type:: dict

global_context¶

the global context to be used in the LLM prompt

Type:: str

_abc_impl = <_abc._abc_data object>¶

_user_context: dict¶

_user_contexts: dict¶

add_user_context(context: str, context_name: str) → None[source]¶

Add user-specific context.

Parameters:

session (Session) – the ongoing session
context (str) – the user-specific context
context_name (str) – the key given to the specific user context

chat(parameters: dict = None, system_message: str = None) → str[source]¶

Make a prediction, i.e., generate an output.

This function can provide the chat history to the LLM for the output generation, simulating a conversation or remembering previous messages.

Parameters:

session (Session) – the user session
parameters (dict) – the LLM parameters. If none is provided, the RAG’s default value will be used
system_message (str) – system message to give high priority context to the LLM

Returns:

the LLM output

Return type:

str

global_context: str¶

name: str¶

parameters: dict¶

predict(message: str, parameters: dict = None, system_message: str = None) → str[source]¶

Make a prediction, i.e., generate an output.

Parameters:

message (Any) – the LLM input text
session (Session) – the ongoing session, can be None if no context needs to be applied
parameters (dict) – the LLM parameters to use in the prediction. If none is provided, the default LLM parameters will be used
system_message (str) – system message to give high priority context to the LLM

Returns:

the LLM output

Return type:

str

remove_user_context(context_name: str) → None[source]¶

Remove user-specific context.

Parameters:

session (Session) – the ongoing session
context_name (str) – the key given to the specific user context

class besser.BUML.metamodel.state_machine.agent.MatchedParameter(name: str, value: object = None, info: dict = None)[source]¶

Bases: object

A matched parameter in a user input (i.e. an entity that is found in a user message, which is an intent parameter).

Parameters:

name (str) – the parameter name
value (object or None) – the parameter value
info (dict or None) – extra parameter information

name¶

The parameter name

Type:: str

value¶

The parameter value

Type:: object or None

info¶

Extra parameter information

Type:: dict

info: dict¶

name: str¶

value: object¶

class besser.BUML.metamodel.state_machine.agent.Platform[source]¶

Bases: ABC

The platform abstract class.

A platform defines the methods the agent can use to interact with a particular communication channel (e.g. Telegram, Slack…) for instance, sending and receiving messages.

This class serves as a template to implement platforms.

_abc_impl = <_abc._abc_data object>¶

reply(session: AgentSession, message: str) → None[source]¶

Send a agent reply, i.e. a text message, to a specific user.

Parameters:

session (Session) – the user session
message (str) – the message to send to the user

class besser.BUML.metamodel.state_machine.agent.RAG(name: str, agent: Agent, vector_store: RAGVectorStore, splitter: RAGTextSplitter, llm_name: str, llm_prompt: str | None = None, k: int = 4, num_previous_messages: int = 0)[source]¶

Bases: NamedElement

Retrieval-Augmented Generation configuration bound to an agent.

This models the minimal information required to generate code similar to:

vector_store = Chroma(...)
splitter = RecursiveCharacterTextSplitter(...)
rag = RAG(
    agent=agent,
    vector_store=vector_store,
    splitter=splitter,
    llm_name='gpt-4o-mini',
    llm_prompt='Use only trusted corpus facts.',
    k=4,
    num_previous_messages=0,
)

Parameters:

name (str) – Logical name of the RAG resource.
agent (Agent) – Agent that owns the configuration.
vector_store (RAGVectorStore) – Vector store definition.
splitter (RAGTextSplitter) – Chunking strategy definition.
llm_name (str) – Identifier of the LLM used to synthesize answers.
llm_prompt (str | None) – Optional prefix instructions injected before each RAG prompt.
k (int) – Number of chunks retrieved per question.
num_previous_messages (int) – Conversation context depth forwarded to the LLM.

_abc_impl = <_abc._abc_data object>¶

agent: Agent¶

k: int¶

llm_name: str¶

llm_prompt: str | None¶

num_previous_messages: int¶

splitter: RAGTextSplitter¶

vector_store: RAGVectorStore¶

class besser.BUML.metamodel.state_machine.agent.RAGReply(rag_db_name: str, prompt: str | None = None)[source]¶

Bases: Action

Primitive action that represents sending a reply using a configured RAG pipeline.

Parameters:

rag_db_name (str) – The logical name of the RAG database to query.
prompt (str, optional) – Optional instructions passed to the LLM phase of the RAG answer.

rag_db_name¶

Identifier of the RAG database that should handle the reply.

Type:: str

prompt¶

Additional instructions for the downstream LLM.

Type:: str | None

_abc_impl = <_abc._abc_data object>¶

prompt: str | None¶

rag_db_name: str¶

class besser.BUML.metamodel.state_machine.agent.RAGTextSplitter(splitter_type: str, chunk_size: int, chunk_overlap: int)[source]¶

Bases: object

Declarative description of the chunking strategy used before indexing content.

chunk_overlap: int¶

chunk_size: int¶

splitter_type: str¶

class besser.BUML.metamodel.state_machine.agent.RAGVectorStore(embedding_provider: str, embedding_parameters: dict | None = None, persist_directory: str | None = None)[source]¶

Bases: object

Declarative description of a vector store used by a RAG pipeline.

Parameters:

embedding_provider (str) – Identifier of the embedding backend (e.g., “openai”, “huggingface”).
embedding_parameters (dict or None) – Backend-specific parameters (API key placeholder, model name, etc.).
persist_directory (str or None) – Directory where the embedding index is stored.

embedding_provider¶

Provider used to build embeddings.

Type:: str

embedding_parameters¶

Provider specific parameters.

Type:: dict

persist_directory¶

Optional path used to persist vectors.

Type:: str or None

embedding_parameters: dict¶

embedding_provider: str¶

persist_directory: str | None¶

class besser.BUML.metamodel.state_machine.agent.ReasoningState(agent: Agent, name: str, llm: str | None = None, initial: bool = False, max_steps: int = 8, enable_task_planning: bool = True, stream_steps: bool = True, system_prompt: str | None = None, fallback_message: str | None = None)[source]¶

Bases: AgentState

A predefined state whose body runs an LLM-driven plan→act→observe loop.

The body is supplied automatically at code-generation time (via the BAF new_reasoning_state(...) factory) — this metamodel class only captures the configuration knobs that flow into that factory plus the LLM driving the loop.

Parameters:

agent (Agent) – the agent the state belongs to.
name (str) – the state name.
llm (str | None) – the name of the LLM that drives the reasoning loop. This is a free-form identifier — the state does not require the LLM to be registered on the agent’s llms list; code generation will instantiate an LLM with this name. May be None during incremental model construction (e.g. while the diagram is being built).
initial (bool) – whether this is the agent’s initial state.
max_steps (int) – maximum LLM turns per user message.
enable_task_planning (bool) – when True, expose the built-in add_tasks / complete_task / skip_task tools and require all tasks to be resolved before a final answer is accepted.
stream_steps (bool) – forward intermediate step events to the session’s platform (if it supports reply_reasoning_step).
system_prompt (str | None) – optional override for the base system prompt. None keeps the BAF default.
fallback_message (str | None) – optional override for the message sent when max_steps is exhausted. None keeps the BAF default.

llm¶

name of the LLM driving the loop.

Type:: str | None

max_steps¶

maximum LLM turns per user message.

Type:: int

enable_task_planning¶

whether to expose the planning tools.

Type:: bool

stream_steps¶

whether to stream intermediate events.

Type:: bool

system_prompt¶

optional system prompt override.

Type:: str | None

fallback_message¶

optional fallback override.

Type:: str | None

_abc_impl = <_abc._abc_data object>¶

enable_task_planning: bool¶

fallback_message: str | None¶

llm: str | None¶

max_steps: int¶

set_body(body)[source]¶: Reasoning states use the predefined new_reasoning_state() body — a hand-written body would be ignored at generation time.

set_fallback_body(body)[source]¶: ReasoningState does not accept a fallback body either — the reasoning loop has its own fallback_message knob.

stream_steps: bool¶

system_prompt: str | None¶

class besser.BUML.metamodel.state_machine.agent.ReceiveFileEvent(file: File = None)[source]¶

Bases: Event

Event for receiving files.

Parameters:

file (File) – the received file
session_id (str) – the id of the session the event was sent to (can be none)
human (bool) – indicates if the sender is human. Defaults to True

file¶

the received file

Type:: File

human¶

indicates if the sender is human. Defaults to True

Type:: bool

_abc_impl = <_abc._abc_data object>¶

file: File¶

class besser.BUML.metamodel.state_machine.agent.ReceiveJSONEvent(payload: dict = None)[source]¶

Bases: ReceiveMessageEvent

Event for receiving JSON messages.

Parameters:

payload (dict) – the received message content
session_id (str) – the id of the session the event was sent to (can be none)
human (bool) – indicates if the sender is human. Defaults to False

_name¶

the name of the event

Type:: str

_abc_impl = <_abc._abc_data object>¶

class besser.BUML.metamodel.state_machine.agent.ReceiveMessageEvent(message: str)[source]¶

Bases: Event

This event checks if a message is received from the user.

Parameters:: message (str) – The message to be checked

name¶

Inherited from Event, represents the name of the event.

Type:: str

visibility¶

Inherited from Event, represents the visibility of the event.

Type:: str

type¶

Inherited from Event, represents the type of the event.

Type:: Type

is_abstract¶

Inherited from Event, indicates if the event is abstract.

Type:: bool

parameters¶

Inherited from Event, the set of parameters for the event.

Type:: set[structural.Parameter]

owner¶

Inherited from Event, the type that owns the property.

Type:: Type

code¶

Inherited from Event, code of the event.

Type:: str

_abc_impl = <_abc._abc_data object>¶

message: Any¶

class besser.BUML.metamodel.state_machine.agent.ReceiveTextEvent(text: str = None)[source]¶

Bases: ReceiveMessageEvent

Event for receiving text messages. Supports intent prediction.

Parameters:

text (str) – the received message content
session_id (str) – the id of the session the event was sent to (can be none)
human (bool) – indicates if the sender is human. Defaults to True

_name¶

the name of the event

Type:: str

predicted_intent¶

the predicted intent for the event message

Type:: IntentClassifierPrediction

_abc_impl = <_abc._abc_data object>¶

log()[source]¶

predicted_intent: IntentClassifierPrediction¶

class besser.BUML.metamodel.state_machine.agent.SimpleIntentClassifierConfiguration(num_words: int = 1000, num_epochs: int = 300, embedding_dim: int = 128, input_max_num_tokens: int = 15, discard_oov_sentences: bool = True, check_exact_prediction_match: bool = True, activation_last_layer: str = 'sigmoid', activation_hidden_layers: str = 'tanh', lr: float = 0.001)[source]¶

Bases: IntentClassifierConfiguration

The Simple Intent Classifier Configuration class.

Parameters:

num_words (int) – Max num of words to keep in the index of words
num_epochs (int) – Number of epochs to be run during training
embedding_dim (int) – Number of embedding dimensions to be used when embedding the words
input_max_num_tokens (int) – Max length for the vector representing a sentence
discard_oov_sentences (bool) – whether to automatically assign zero probabilities to sentences with all tokens being oov ones or not
check_exact_prediction_match (bool) – Whether to check for exact match between the sentence to predict and one of the training sentences or not
activation_last_layer (str) – The activation function of the last layer
activation_hidden_layers (str) – The activation function of the hidden layers
lr (float) – Learning rate for the optimizer

num_words¶

Max num of words to keep in the index of words

Type:: int

num_epochs¶

Number of epochs to be run during training

Type:: int

embedding_dim¶

Number of embedding dimensions to be used when embedding the words

Type:: int

input_max_num_tokens¶

Max length for the vector representing a sentence

Type:: int

discard_oov_sentences¶

whether to automatically assign zero probabilities to sentences with all tokens being oov ones or not

Type:: bool

check_exact_prediction_match¶

Whether to check for exact match between the sentence to predict and one of the training sentences or not

Type:: bool

activation_last_layer¶

The activation function of the last layer

Type:: str

activation_hidden_layers¶

The activation function of the hidden layers

Type:: str

lr¶

Learning rate for the optimizer

Type:: float

_abc_impl = <_abc._abc_data object>¶

activation_hidden_layers: str¶

activation_last_layer: str¶

check_exact_prediction_match: bool¶

discard_oov_sentences: bool¶

embedding_dim: int¶

input_max_num_tokens: int¶

lr: float¶

num_epochs: int¶

num_words: int¶

class besser.BUML.metamodel.state_machine.agent.Skill(name: str, content: str = '', description: str | None = None)[source]¶

Bases: NamedElement

A markdown-based playbook the reasoning state injects into the system prompt.

Parameters:

name (str) – the skill name. Surfaced to the LLM as the skill header.
content (str) – the markdown body of the skill.
description (str | None) – optional one-line description.

content¶

the markdown body of the skill.

Type:: str

description¶

optional one-line description.

Type:: str | None

_abc_impl = <_abc._abc_data object>¶

content: str¶

description: str | None¶

class besser.BUML.metamodel.state_machine.agent.TelegramPlatform[source]¶

Bases: Platform

The Telegram Platform allows a agent to interact via Telegram.

_abc_impl = <_abc._abc_data object>¶

reply_file(session: AgentSession, file: File, message: str = None) → None[source]¶

Send a file reply to a specific user

Parameters:

session (AgentSession) – the user session
file (File) – the file to send
message (str, optional) – message to be attached to file, 1024 char limit

reply_image(session: AgentSession, file: File, message: str = None) → None[source]¶

Send an image reply to a specific user

Parameters:

session (AgentSession) – the user session
file (File) – the file to send (the image)
message (str, optional) – message to be attached to file, 1024 char limit

reply_location(session: AgentSession, latitude: float, longitude: float) → None[source]¶

Send a location reply to a specific user.

Parameters:

session (AgentSession) – the user session
latitude (str) – the latitude of the location
longitude (str) – the longitude of the location

class besser.BUML.metamodel.state_machine.agent.Tool(name: str, description: str = '', code: str = '')[source]¶

Bases: NamedElement

A Python callable the agent’s reasoning state can invoke.

The metamodel stores the tool’s source code as a string (similar to how CustomCodeAction stores user-supplied Python). The BAF generator pastes code into the output module verbatim and registers the callable on the agent via agent.new_tool(...).

Parameters:

name (str) – the tool name (defaults to the callable’s own name at runtime, but here we require it explicitly so the generator can produce a stable Python identifier).
description (str) – a short description shown to the LLM.
code (str) – the Python source defining the callable. Must define a top-level def whose name matches name.

description¶

the description shown to the LLM.

Type:: str

code¶

the Python source defining the callable.

Type:: str

_abc_impl = <_abc._abc_data object>¶

code: str¶

description: str¶

class besser.BUML.metamodel.state_machine.agent.VariableOperationMatcher(var_name: str, operation: Callable[[Any, Any], bool], target: Any)[source]¶

Bases: Condition

This event checks if for a specific comparison operation, using a stored session value and a given target value, returns true (e.g., ‘temperature’ > 30, where var_name = ‘temperature’, operation = op.greater and target = 30)

Parameters:

var_name (str) – The variable name (stored in the user session)
operation (Callable[[Any, Any], bool]) – The operation function
target (Any) – The target value

name¶

Inherited from Event, represents the name of the event.

Type:: str

visibility¶

Inherited from Event, represents the visibility of the event.

Type:: str

type¶

Inherited from Event, represents the type of the event.

Type:: Type

is_abstract¶

Inherited from Event, indicates if the event is abstract.

Type:: bool

parameters¶

Inherited from Event, the set of parameters for the event.

Type:: set[structural.Parameter]

owner¶

Inherited from Event, the type that owns the property.

Type:: Type

code¶

Inherited from Event, code of the event.

Type:: str

var_name¶

The variable name (stored in the user session)

Type:: str

operation¶

The operation function

Type:: Callable[[Any, Any], bool]

target¶

The target value

Type:: Any

_abc_impl = <_abc._abc_data object>¶

operation: Callable[[Any, Any], bool]¶

target: Any¶

var_name: str¶

class besser.BUML.metamodel.state_machine.agent.WebCrawlLLMReply(initial_url: str = '', max_depth: int = 2, max_pages: int = 20, crawl_format: str = 'markdown', base_url_prefix: str | None = None, run_crawl: bool = True, no_crawl_error_message: str = 'No web crawl data is available yet.', system_message_prefix: str | None = None, llm_name: str | None = None)[source]¶

Bases: Action

Crawls a website (or reuses a cached result) and queries an LLM with the content.

Parameters:

initial_url (str) – Target URL. Used as BFS start point when run_crawl=True, or as the session-key suffix when run_crawl=False.
max_depth (int) – Maximum link depth to follow. Used only when run_crawl=True.
max_pages (int) – Maximum number of pages to fetch. Used only when run_crawl=True.
crawl_format (str) – Output format for crawled content (“markdown” or “html”).
base_url_prefix (str, optional) – Only URLs starting with this prefix are included. Used only when run_crawl=True.
run_crawl (bool) – When True, the crawl runs and its result is stored in the session under the key f"web_crawl_{initial_url}". When False, reads from that key.
no_crawl_error_message (str) – Reply sent when run_crawl=False and no cached result is found in the session.
system_message_prefix (str, optional) – Prepended to the crawl result when building the LLM system message. Defaults to a generic instruction when None.
llm_name (str, optional) – Name of the LLM to use. Falls back to the agent default.

initial_url¶

Target URL.

Type:: str

max_depth¶

Maximum link depth.

Type:: int

max_pages¶

Maximum number of pages.

Type:: int

crawl_format¶

Output format (“markdown” or “html”).

Type:: str

base_url_prefix¶

Optional URL prefix filter.

Type:: str | None

run_crawl¶

Whether to execute the crawl.

Type:: bool

no_crawl_error_message¶

Error reply when no cached data exists.

Type:: str

system_message_prefix¶

Prefix for the LLM system message.

Type:: str | None

llm_name¶

Name of the LLM to use.

Type:: str | None

_abc_impl = <_abc._abc_data object>¶

base_url_prefix: str | None¶

crawl_format: str¶

initial_url: str¶

llm_name: str | None¶

max_depth: int¶

max_pages: int¶

no_crawl_error_message: str¶

run_crawl: bool¶

system_message_prefix: str | None¶

class besser.BUML.metamodel.state_machine.agent.WebSocketPlatform[source]¶

Bases: Platform

The WebSocket Platform allows a agent to communicate with the users using the WebSocket bidirectional communications protocol.

_abc_impl = <_abc._abc_data object>¶

reply_dataframe(session: AgentSession, df) → None[source]¶

Send a DataFrame agent reply, i.e. a table, to a specific user.

Parameters:

session (AgentSession) – the user session
df (pandas.DataFrame) – the message to send to the user

reply_file(session: AgentSession, file: File) → None[source]¶

Send a file reply to a specific user

Parameters:

session (AgentSession) – the user session
file (File) – the file to send

reply_location(session: AgentSession, latitude: float, longitude: float) → None[source]¶

Send a location reply to a specific user.

Parameters:

session (AgentSession) – the user session
latitude (str) – the latitude of the location
longitude (str) – the longitude of the location

reply_options(session: AgentSession, options: list[str])[source]¶

Send a list of options as a reply. They can be used to let the user choose one of them

Parameters:

session (AgentSession) – the user session
options (list[str]) – the list of options to send to the user

reply_plotly(session: AgentSession, plot) → None[source]¶

Send a Plotly figure as a agent reply, to a specific user.

Parameters:

session (AgentSession) – the user session
plot (plotly.graph_objs.Figure) – the message to send to the user

class besser.BUML.metamodel.state_machine.agent.WebSocketReplyDataframe[source]¶

Bases: Action

Send a DataFrame reply via WebSocketPlatform.reply_dataframe(). Requires a runtime pandas DataFrame.

_abc_impl = <_abc._abc_data object>¶

class besser.BUML.metamodel.state_machine.agent.WebSocketReplyFile[source]¶

Bases: Action

Send a file reply via WebSocketPlatform.reply_file(). Requires a runtime File object.

_abc_impl = <_abc._abc_data object>¶

class besser.BUML.metamodel.state_machine.agent.WebSocketReplyHTML(message: str = '')[source]¶

Bases: Action

Send an HTML-formatted text reply via WebSocketPlatform.reply_html().

_abc_impl = <_abc._abc_data object>¶

message: str¶

class besser.BUML.metamodel.state_machine.agent.WebSocketReplyImage[source]¶

Bases: Action

Send an image reply via WebSocketPlatform.reply_image(). Requires a runtime numpy ndarray.

_abc_impl = <_abc._abc_data object>¶

class besser.BUML.metamodel.state_machine.agent.WebSocketReplyLocation(latitude: float = 0.0, longitude: float = 0.0)[source]¶

Bases: Action

Send a geographic location reply via WebSocketPlatform.reply_location().

_abc_impl = <_abc._abc_data object>¶

latitude: float¶

longitude: float¶

class besser.BUML.metamodel.state_machine.agent.WebSocketReplyMarkdown(message: str = '')[source]¶

Bases: Action

Send a Markdown-formatted text reply via WebSocketPlatform.reply_markdown().

_abc_impl = <_abc._abc_data object>¶

message: str¶

class besser.BUML.metamodel.state_machine.agent.WebSocketReplyOptions(options: list | None = None)[source]¶

Bases: Action

Send a list of selectable options via WebSocketPlatform.reply_options().

_abc_impl = <_abc._abc_data object>¶

options: list¶

class besser.BUML.metamodel.state_machine.agent.WebSocketReplyPlotly[source]¶

Bases: Action

Send a Plotly figure reply via WebSocketPlatform.reply_plotly(). Requires a runtime plotly Figure.

_abc_impl = <_abc._abc_data object>¶

class besser.BUML.metamodel.state_machine.agent.WebSocketReplySpeech(message: str = '', audio_speed: float | None = None)[source]¶

Bases: Action

Convert text to speech and send the audio via WebSocketPlatform.reply_speech().

_abc_impl = <_abc._abc_data object>¶

audio_speed: float | None¶

message: str¶

class besser.BUML.metamodel.state_machine.agent.WildcardEvent[source]¶

Bases: Event

Wildcard event. Can be used to match any event in a transition.

_abc_impl = <_abc._abc_data object>¶

class besser.BUML.metamodel.state_machine.agent.Workspace(name: str, path: str = '', description: str | None = None, writable: bool = True, max_read_bytes: int = 200000)[source]¶

Bases: NamedElement

A filesystem path the reasoning state can browse and (optionally) modify.

The BAF runtime auto-registers list_directory / read_file tools on the agent the first time a workspace is added, plus write_file / create_file / delete_file when at least one workspace has writable=True.

Parameters:

name (str) – the workspace identifier (used by the LLM as the workspace argument when multiple workspaces are present).
path (str) – the workspace root path (absolute or relative to the generated agent’s working directory).
description (str | None) – a short human-readable explanation of what the workspace contains. Strongly recommended.
writable (bool) – when False, mutating operations on this workspace raise WorkspaceError at runtime. Defaults to True.
max_read_bytes (int) – cap on read_file output. Defaults to 200_000 (matches the BAF runtime default).

path¶

the workspace root path.

Type:: str

description¶

optional human-readable description.

Type:: str | None

writable¶

whether mutating operations are allowed.

Type:: bool

max_read_bytes¶

cap on read_file output.

Type:: int

_abc_impl = <_abc._abc_data object>¶

description: str | None¶

max_read_bytes: int¶

path: str¶

writable: bool¶

besser.BUML.metamodel.state_machine.agent.llm_provider_key(llm: LLMWrapper) → str[source]¶: Reverse-lookup the provider keyword for an existing LLM instance.