oef package¶

Submodules¶

oef.agents module¶

oef.agents¶

This module contains the base class for implementing agents.

class oef.agents.Agent(oef_proxy: oef.core.OEFProxy)¶

Bases: oef.core.AgentInterface, abc.ABC

The base class for OEF Agents.

Extend this class to implement the callback methods defined in DialogueInterface and ConnectionInterface.

In this way you can program the behaviour of the agent when it’s running.

async_connect() → bool¶

The asynchronous counterpart of connect().

Returns:	True if the connection has been established successfully, False otherwise.

async_disconnect() → None¶

The asynchronous counterpart of disconnect().

Returns:	`None`

async_run() → None¶

Run the agent asynchronously.

Returns:	`None`

connect() → bool¶

Connect to the OEF Node.

Returns:	True if the connection has been established successfully, False otherwise.

disconnect() → None¶

Disconnect from the OEF Node.

Returns:	`None`

on_accept(msg_id: int, dialogue_id: int, origin: str, target: int)¶

Handler for Accept messages.

Parameters:	msg_id – the message identifier for the dialogue. dialogue_id – the identifier of the dialogue in which the message is sent. origin – the identifier of the agent who sent the message. target – the identifier of the message to whom this message is answering.
Returns:	`None`

on_cfp(msg_id: int, dialogue_id: int, origin: str, target: int, query: Union[oef.query.Query, bytes, None])¶

Handler for CFP messages.

Parameters:	msg_id – the message identifier for the dialogue. dialogue_id – the identifier of the dialogue in which the message is sent. origin – the identifier of the agent who sent the message. target – the identifier of the message to whom this message is answering. query – the query associated with the Call For Proposals.
Returns:	`None`

on_decline(msg_id: int, dialogue_id: int, origin: str, target: int)¶

Handler for Decline messages.

Parameters:	msg_id – the message identifier for the dialogue. dialogue_id – the identifier of the dialogue in which the message is sent. origin – the identifier of the agent who sent the message. target – the identifier of the message to whom this message is answering.
Returns:	`None`

on_dialogue_error(answer_id: int, dialogue_id: int, origin: str)¶

Handler for error messages concerning dialogues between agents.

Parameters:	answer_id – the id of the message that generated the error. dialogue_id – the identifier of the dialogue in which the message is sent. origin – the identifier of the agent that generated the error.
Returns:	`None`

on_message(msg_id: int, dialogue_id: int, origin: str, content: bytes)¶

Handler for simple messages.

Parameters:	msg_id – the message identifier for the dialogue. origin – the identifier of the agent who sent the message. dialogue_id – the identifier of the dialogue in which the message is sent. content – the content of the message (in bytes).
Returns:	`None`

on_oef_error(answer_id: int, operation: oef.messages.OEFErrorOperation)¶

Handler for error messages from the OEF node.

Parameters:	answer_id – the id of the message that generated the error. operation – the operation that caused the error.
Returns:	`None`

on_propose(msg_id: int, dialogue_id: int, origin: str, target: int, proposals: Union[bytes, List[oef.schema.Description]])¶

Handler for Propose messages.

Parameters:	msg_id – the message identifier for the dialogue. dialogue_id – the identifier of the dialogue in which the message is sent. origin – the identifier of the agent who sent the message. target – the identifier of the message to whom this message is answering. proposals – the proposal associated with the message.
Returns:	`None`

on_search_result(search_id: int, agents: List[str])¶

Handler for Search Result messages.

Parameters:	search_id – the identifier of the search to whom the result is answering. agents – the list of identifiers of the agents compliant with the search constraints.
Returns:	`None`

public_key¶

The public key that identifies the agent in the OEF.

Returns:	the public key.

register_agent(msg_id: int, agent_description: oef.schema.Description) → None¶: Register an agent. See register_agent().

register_service(msg_id: int, service_description: oef.schema.Description) → None¶: Unregister a service. See register_service().

run() → None¶

Run the agent synchronously. That is, until stop() is not called.

Returns:	`None`

search_agents(search_id: int, query: oef.query.Query) → None¶: Search agents. See search_agents().

search_services(search_id: int, query: oef.query.Query) → None¶: Search services. See search_services().

send_accept(msg_id: int, dialogue_id: int, destination: str, target: int) → None¶: Send an Accept. See send_accept().

send_cfp(msg_id: int, dialogue_id: int, destination: str, target: int, query: Union[oef.query.Query, bytes, None]) → None¶: Send a CFP. See send_cfp().

send_decline(msg_id: int, dialogue_id: int, destination: str, target: int) → None¶: Send a Decline. See send_decline().

send_message(msg_id: int, dialogue_id: int, destination: str, msg: bytes) → None¶: Send a simple message. See send_message().

send_propose(msg_id: int, dialogue_id: int, destination: str, target: int, proposals: Union[bytes, List[oef.schema.Description]]) → None¶: Send a Propose. See send_propose().

stop() → None¶

Stop the agent. Specifically, if run() or async_run() have been called, then this method will cancel the previously instantiated task. The task that manages the agent-loop is hence scheduled for cancellation.

Returns:	`None`

unregister_agent(msg_id: int) → None¶: Unregister an agent. See unregister_agent().

unregister_service(msg_id: int, service_description: oef.schema.Description) → None¶: Unregister a service. See unregister_service().

class oef.agents.LocalAgent(public_key: str, local_node: oef.proxy.OEFLocalProxy.LocalNode)¶

Bases: oef.agents.Agent

Agent that interacts with a local implementation of an OEF Node.

It provides a nicer constructor that does not require to instantiate OEFLocalProxy explicitly.

Notice: other agents need to be constructed with the same LocalNode instance.

class oef.agents.OEFAgent(public_key: str, oef_addr: str, oef_port: int = 3333)¶

Bases: oef.agents.Agent

Agent that interacts with an OEFNode on the network.

It provides a nicer constructor that does not require to instantiate OEFLocalProxy explicitly.

oef.core module¶

oef.core¶

The core module that contains the main abstraction of the SDK.

class oef.core.AgentInterface¶

Bases: oef.core.DialogueInterface, oef.core.ConnectionInterface, abc.ABC

Interface to be implemented by agents. It contains methods from:

DialogueInterface, that contains handlers for the incoming messages from other agents
ConnectionInterface, that contains handlers for error and search result messages from the OEF.

class oef.core.ConnectionInterface¶

Bases: abc.ABC

Methods to handle error and search result messages from the OEF Node.

on_dialogue_error(answer_id: int, dialogue_id: int, origin: str) → None¶

Handler for error messages concerning dialogues between agents.

Parameters:	answer_id – the id of the message that generated the error. dialogue_id – the identifier of the dialogue in which the message is sent. origin – the identifier of the agent that generated the error.
Returns:	`None`

on_oef_error(answer_id: int, operation: oef.messages.OEFErrorOperation) → None¶

Handler for error messages from the OEF node.

Parameters:	answer_id – the id of the message that generated the error. operation – the operation that caused the error.
Returns:	`None`

on_search_result(search_id: int, agents: List[str]) → None¶

Handler for Search Result messages.

Parameters:	search_id – the identifier of the search to whom the result is answering. agents – the list of identifiers of the agents compliant with the search constraints.
Returns:	`None`

class oef.core.DialogueInterface¶

Bases: abc.ABC

The methods of this interface are the callbacks that are called from the OEFProxy when a certain message has to be delivered to an agent. The names of the method match the pattern ‘on’ followed by the name of the message.

on_accept(msg_id: int, dialogue_id: int, origin: str, target: int) → None¶

Handler for Accept messages.

Parameters:	msg_id – the message identifier for the dialogue. dialogue_id – the identifier of the dialogue in which the message is sent. origin – the identifier of the agent who sent the message. target – the identifier of the message to whom this message is answering.
Returns:	`None`

on_cfp(msg_id: int, dialogue_id: int, origin: str, target: int, query: Union[oef.query.Query, bytes, None]) → None¶

Handler for CFP messages.

Parameters:	msg_id – the message identifier for the dialogue. dialogue_id – the identifier of the dialogue in which the message is sent. origin – the identifier of the agent who sent the message. target – the identifier of the message to whom this message is answering. query – the query associated with the Call For Proposals.
Returns:	`None`

on_decline(msg_id: int, dialogue_id: int, origin: str, target: int) → None¶

Handler for Decline messages.

Parameters:	msg_id – the message identifier for the dialogue. dialogue_id – the identifier of the dialogue in which the message is sent. origin – the identifier of the agent who sent the message. target – the identifier of the message to whom this message is answering.
Returns:	`None`

on_message(msg_id: int, dialogue_id: int, origin: str, content: bytes) → None¶

Handler for simple messages.

Parameters:	msg_id – the message identifier for the dialogue. origin – the identifier of the agent who sent the message. dialogue_id – the identifier of the dialogue in which the message is sent. content – the content of the message (in bytes).
Returns:	`None`

on_propose(msg_id: int, dialogue_id: int, origin: str, target: int, proposals: Union[bytes, List[oef.schema.Description]]) → None¶

Handler for Propose messages.

Parameters:	msg_id – the message identifier for the dialogue. dialogue_id – the identifier of the dialogue in which the message is sent. origin – the identifier of the agent who sent the message. target – the identifier of the message to whom this message is answering. proposals – the proposal associated with the message.
Returns:	`None`

class oef.core.OEFCoreInterface¶

Bases: abc.ABC

Methods to interact with an OEF node.

connect() → bool¶

Connect to the OEF Node

Returns:	True if the connection has been established, False otherwise.

register_agent(msg_id: int, agent_description: oef.schema.Description) → None¶

Adds a description of an agent to the OEF so that it can be understood/ queried by other agents in the OEF.

Parameters:	msg_id – the identifier of the message. agent_description – description of the agent to add
Returns:	`None`

register_service(msg_id: int, service_description: oef.schema.Description) → None¶

Adds a description of the respective service so that it can be understood/queried by other agents in the OEF.

Parameters:	msg_id – the identifier of the message. service_description – description of the services to add
Returns:	`None`

search_agents(msg_id: int, query: oef.query.Query) → None¶

Search for other agents it is interested in communicating with. This can be useful when an agent wishes to directly proposition the provision of a service that it thinks another agent may wish to be able to offer it. All matching agents are returned (potentially including ourselves).

Parameters:	msg_id – the identifier of the message. query – specifications of the constraints on the agents that are matched
Returns:	`None`.

search_services(msg_id: int, query: oef.query.Query) → None¶

Search for a particular service. This allows constrained search of all services that have been registered with the OEF. All matching services will be returned (potentially including services offered by ourselves).

Parameters:	msg_id – the identifier of the message. query – the constraint on the matching services
Returns:	`None`.

send_accept(msg_id: int, dialogue_id: int, destination: str, target: int) → None¶

Send an Accept.

Parameters:	msg_id – the message identifier for the dialogue. dialogue_id – the identifier of the dialogue in which the message is sent. destination – the agent identifier to whom the message is sent. target – the identifier of the message to whom this message is answering.
Returns:	`None`

send_cfp(msg_id: int, dialogue_id: int, destination: str, target: int, query: Union[oef.query.Query, bytes, None]) → None¶

Send a Call-For-Proposals.

Parameters:	msg_id – the message identifier for the dialogue. dialogue_id – the identifier of the dialogue in which the message is sent. destination – the agent identifier to whom the message is sent. target – the identifier of the message to whom this message is answering. query – the query associated with the Call For Proposals.
Returns:	`None`

send_decline(msg_id: int, dialogue_id: int, destination: str, target: int) → None¶

Send a Decline.

Parameters:	msg_id – the message identifier for the dialogue. dialogue_id – the identifier of the dialogue in which the message is sent. destination – the agent identifier to whom the message is sent. target – the identifier of the message to whom this message is answering.
Returns:	`None`

send_message(msg_id: int, dialogue_id: int, destination: str, msg: bytes) → None¶

Send a simple message.

Parameters:	msg_id – the identifier of the message. dialogue_id – the identifier of the dialogue in which the message is sent. destination – the agent identifier to whom the message is sent. msg – the message (in bytes).
Returns:	`None`

send_propose(msg_id: int, dialogue_id: int, destination: str, target: int, proposals: Union[bytes, List[oef.schema.Description]]) → None¶

Send a Propose.

Parameters:	msg_id – the message identifier for the dialogue. dialogue_id – the identifier of the dialogue in which the message is sent. destination – the agent identifier to whom the message is sent. target – the identifier of the message to whom this message is answering. proposals – either a list of `Description` or `bytes`.
Returns:	`None`

stop()¶: Stop the proxy.

unregister_agent(msg_id: int) → None¶

Remove the description of an agent from the OEF. This agent will no longer be queryable by other agents in the OEF. A conversation handler must be provided that allows the agent to receive and manage conversations from other agents wishing to communicate with it.

Parameters:	msg_id – the identifier of the message.
Returns:	`None`

unregister_service(msg_id: int, service_description: oef.schema.Description) → None¶

Add a description of the respective service so that it can be understood/queried by other agents in the OEF.

Parameters:	msg_id – the identifier of the message. service_description – description of the services to add
Returns:	`None`

class oef.core.OEFProxy(public_key)¶

Bases: oef.core.OEFCoreInterface, abc.ABC

Abstract definition of an OEF Proxy.

is_connected() → bool¶

Check if the proxy is currently connected to the OEF Node.

Returns:	`True` if the proxy is connected, `False` otherwise.

loop(agent: oef.core.AgentInterface) → None¶

Event loop to wait for messages and to dispatch the arrived messages to the proper handler.

Parameters:	agent – the implementation of the message handlers specified in AgentInterface.
Returns:	`None`

public_key¶: The public key used by the proxy to communicate with the OEF Node.

oef.dialogue module¶

oef.dialogue¶

This module contains classes to implement more complex dialogues.

class oef.dialogue.DialogueAgent(oef_proxy: oef.core.OEFProxy)¶

Bases: oef.agents.Agent, abc.ABC

This class implements a special agent that uses the dialogue to make complex interactions with other agents.

on_accept(msg_id: int, dialogue_id: int, origin: str, target: int)¶

Handler for Accept messages.

Parameters:	msg_id – the message identifier for the dialogue. dialogue_id – the identifier of the dialogue in which the message is sent. origin – the identifier of the agent who sent the message. target – the identifier of the message to whom this message is answering.
Returns:	`None`

on_cfp(msg_id: int, dialogue_id: int, origin: str, target: int, query: Union[oef.query.Query, bytes, None])¶

Handler for CFP messages.

Parameters:	msg_id – the message identifier for the dialogue. dialogue_id – the identifier of the dialogue in which the message is sent. origin – the identifier of the agent who sent the message. target – the identifier of the message to whom this message is answering. query – the query associated with the Call For Proposals.
Returns:	`None`

on_connection_error(operation: oef.messages.OEFErrorOperation) → None¶

Handle a connection error.

Parameters:	operation – the OEF error
Returns:	`None`

on_decline(msg_id: int, dialogue_id: int, origin: str, target: int)¶

Handler for Decline messages.

Parameters:	msg_id – the message identifier for the dialogue. dialogue_id – the identifier of the dialogue in which the message is sent. origin – the identifier of the agent who sent the message. target – the identifier of the message to whom this message is answering.
Returns:	`None`

on_message(msg_id: int, dialogue_id: int, origin: str, content: bytes)¶

Handler for simple messages.

Parameters:	msg_id – the message identifier for the dialogue. origin – the identifier of the agent who sent the message. dialogue_id – the identifier of the dialogue in which the message is sent. content – the content of the message (in bytes).
Returns:	`None`

on_new_cfp(msg_id: int, dialogue_id: int, from_: str, target: int, query: Union[oef.query.Query, bytes, None]) → None¶

Handle a new CFP message.

Parameters:	msg_id – the message identifier dialogue_id – the dialogue identifier that the CFP refers to from – the id of the agent who sent the CFP. target – the identifier of the target message query – the query associated with the CFP.
Returns:	`None`

on_new_message(msg_id: int, dialogue_id: int, from_: str, content: bytes) → None¶

Handle a new Message message.

Parameters:	msg_id – the message identifier dialogue_id – the dialogue id. from – the agent id of the source. content – the content of the message.
Returns:	`None`

on_propose(msg_id: int, dialogue_id: int, origin: str, target: int, proposals: Union[bytes, List[oef.schema.Description]])¶

Handler for Propose messages.

Parameters:	msg_id – the message identifier for the dialogue. dialogue_id – the identifier of the dialogue in which the message is sent. origin – the identifier of the agent who sent the message. target – the identifier of the message to whom this message is answering. proposals – the proposal associated with the message.
Returns:	`None`

register_dialogue(dialogue: oef.dialogue.SingleDialogue) → None¶

Register a dialogue with another agent.

Parameters:	dialogue – the dialogue to register in the state of the agent.
Returns:	`None`
Raises:	ValueError – if the dialogue key is already present.

unregister_dialogue(dialogue: oef.dialogue.SingleDialogue) → None¶

Unregister a dialogue from the state of the agent.

Parameters:	dialogue – the dialogue to unregister.
Returns:	`None`
Raises:	ValueError – if the key of the dialogue to be unregistered cannot be found.

class oef.dialogue.GroupDialogues(agent: oef.dialogue.DialogueAgent)¶

Bases: object

Class to handle a set of dialogues and take decisions taking into accounts all the dialogues.

add_agents(agents: List[oef.dialogue.SingleDialogue]) → None¶

Add a list of dialogues to the group.

Parameters:	agents – a list of dialogues.
Returns:	`None`

better(price1: int, price2: int) → bool¶

Determine whether a price is better than another one.

Parameters:	price1 – the first price to compare. price2 – the second price to compare
Returns:	`True` if the first price is better than the second, `False` otherwise.

finished() → None¶

Handle the end of all the dialogues.

Returns:	`None`

update(agent: str, price: int) → None¶

Update the price value received from another agent, e.g. during a negotiation.

Parameters:	agent – the agent who sent us the price. price – the price sent by the other agent.
Returns:	`None`

class oef.dialogue.SingleDialogue(agent: None, destination: str, id_: Optional[int] = None)¶

Bases: abc.ABC

This class is used to hold information about a dialogue with another agent.

It implements the DialogueInterface, so it is needed to implement all the message handlers (i.e. on_message(), on_cfp()…)

key¶: The identifier for this dialogue.

on_accept(msg_id: int, target: int) → None¶

Handler for Accept messages. Analogous to the:func:~oef.core.DialogueInterface.on_accept method.

Parameters:	msg_id – the message identifier for the dialogue. target – the identifier of the message to whom this message is answering.
Returns:	`None`

on_cfp(msg_id: int, target: int, query: Union[oef.query.Query, bytes, None]) → None¶

Handler for CFP messages. Analogous to the:func:~oef.core.DialogueInterface.on_cfp method.

Parameters:	msg_id – the message identifier for the dialogue. target – the identifier of the message to whom this message is answering. query – the query associated with the Call For Proposals.

on_decline(msg_id: int, target: int) → None¶

Handler for Decline messages. Analogous to the:func:~oef.core.DialogueInterface.on_decline method.

Parameters:	msg_id – the message identifier for the dialogue. target – the identifier of the message to whom this message is answering.
Returns:	`None`

on_dialogue_error(answer_id: int, dialogue_id: int, origin: str) → None¶

Handler for error messages concerning dialogues between agents. Analogous to the:func:~oef.core.ConnectionInterface.on_dialogue_error method.

Parameters:	answer_id – the id of the message that generated the error. dialogue_id – the identifier of the dialogue in which the message is sent. origin – the identifier of the agent that generated the error.
Returns:	`None`

on_message(msg_id: int, content: bytes) → None¶

Handler for simple messages. Analogous to the on_message() method.

Parameters:	msg_id – the message identifier for the dialogue. content – the content of the message (in bytes).
Returns:	`None`

on_propose(msg_id: int, target: int, proposal: Union[bytes, List[oef.schema.Description]]) → None¶

Handler for Propose messages. Analogous to the:func:~oef.core.DialogueInterface.on_propose method.

Parameters:	msg_id – the message identifier for the dialogue. target – the identifier of the message to whom this message is answering. proposal – the proposal associated with the message.
Returns:	`None`

send_accept(msg_id: int, target: int) → None¶

Send an Accept. Analogous to the send_accept() method.

Parameters:	msg_id – the message identifier for the dialogue. target – the identifier of the message to whom this message is answering.
Returns:	`None`

send_cfp(msg_id: int, target: int, query: Union[oef.query.Query, bytes, None]) → None¶

Send a Call-For-Proposals. Analogous to the send_cfp() method.

Parameters:	msg_id – the message identifier for the dialogue. target – the identifier of the message to whom this message is answering. query – the query associated with the Call For Proposals.
Returns:	`None`

send_decline(msg_id: int, target: int) → None¶

Send a Decline. Analogous to the send_decline() method.

Parameters:	msg_id – the message identifier for the dialogue. target – the identifier of the message to whom this message is answering.
Returns:	`None`

send_message(msg_id: int, msg: bytes) → None¶

Send a simple message. Analogous to the send_message() method.

Parameters:	msg_id – the identifier of the message. msg – the message (in bytes).
Returns:	`None`

send_propose(msg_id: int, target: int, proposals: Union[bytes, List[oef.schema.Description]]) → None¶

Send a Propose. Analogous to the send_propose() method.

Parameters:	msg_id – the message identifier for the dialogue. target – the identifier of the message to whom this message is answering. proposals – either a list of `Description` or `bytes`.
Returns:	`None`

oef.helpers module¶

oef.helpers¶

This module contains helper functions.

oef.helpers.haversine(lat1: float, lon1: float, lat2: float, lon2: float) → float¶

Compute the Haversine distance between two locations (i.e. two pairs of latitude and longitude).

Parameters:	lat1 – the latitude of the first location. lon1 – the longitude of the first location. lat2 – the latitude of the second location. lon2 – the longitude of the second location.
Returns:	the Haversine distance.

oef.logger module¶

oef.logger.set_logger(name, level=20, handlers: List[logging.Handler] = None)¶

Utility to set up a logger, for a given module.

>>> logger = set_logger("oef", logging.DEBUG)

Parameters:	name – the name of the module to audit. This can be the name of the package (e.g. `"oef"`) \| or any child module (e.g. `"oef.agents"`). level – the logging level handlers – a list of logging handlers. If None, then a default StreamHandler is provided, \| printing to standard error.
Returns:	the logger.

oef.messages module¶

oef.messages¶

This module contains classes to manage serialization of data in Protobuf messages.

class oef.messages.Accept(msg_id: int, dialogue_id: int, destination: str, target: int)¶

Bases: oef.messages.AgentMessage

This message is used to send an Accept. It contains:

the message id, that is an unique identifier for a message, given dialogue.
a dialogue id, that identifies the dialogue in which the message is sent.
a destination, that is the public key of the recipient of the message.
target, that is, the identifier of the message to whom this message is targeting.

If everything works correctly, eventually, the recipient will receive the content of the message and the recipient’s on_accept() is executed.

It is used in the method send_accept().

to_envelope() → agent_pb2.Message¶

Pack the message into a protobuf message.

Returns:	the envelope.

class oef.messages.AgentMessage(msg_id)¶

Bases: oef.messages.BaseMessage, abc.ABC

This type of message is used for interacting with other agents, via an OEF Node. There are five different type of agent messages:

Message, to convey a generic message (that is, a sequence of bytes).
CFP, to make a Call For Proposals for some resources.
Propose, to make a Proposal about a specific resource.
Accept, to accept a previous Proposal.
Decline, to decline the negotiation.

Using message 1 is the most generic way to interact with other OEF agent. It is flexible, but requires extra development efforts to come up with a working protocol.

Messages 2-5 are used in the negotiation protocol, where some agents are buyers and other are sellers. The protocol is compliant with FIPA specifications.

class oef.messages.BaseMessage(msg_id)¶

Bases: abc.ABC

An abstract class to represent the messages exchanged with the OEF. Every subclass must implement the to_envelope() method that serialize the data into a protobuf message.

to_envelope() → agent_pb2.Envelope¶

Pack the message into a protobuf message.

Returns:	the envelope.

class oef.messages.CFP(msg_id: int, dialogue_id: int, destination: str, target: int, query: Union[oef.query.Query, bytes, None])¶

Bases: oef.messages.AgentMessage

This message is used to send a Call For Proposals. It contains:

a message id, that is an unique identifier for a message, given the dialogue.
a dialogue id, that identifies the dialogue in which the message is sent.
a destination, that is the public key of the recipient of the message.
a target id, that is, the identifier of the message to whom this message is targeting, in a given dialogue.
a query, that describes the resources the sender is interested in.

If everything works correctly, eventually, the recipient will receive the content of the message and the recipient’s on_cfp() is executed.

It is used in the method send_cfp().

to_envelope() → agent_pb2.Message¶

Pack the message into a protobuf message.

Returns:	the envelope.

class oef.messages.Decline(msg_id: int, dialogue_id: int, destination: str, target: int)¶

Bases: oef.messages.AgentMessage

This message is used to send an Decline. It contains:

the message id, that is an unique identifier for a message, given dialogue.
a dialogue id, that identifies the dialogue in which the message is sent.
a destination, that is the public key of the recipient of the message.
target, that is, the identifier of the message to whom this message is targeting.

If everything works correctly, eventually, the recipient will receive the content of the message and the recipient’s on_decline() is executed.

It is used in the method send_decline().

to_envelope()¶

Pack the message into a protobuf message.

Returns:	the envelope.

class oef.messages.Message(msg_id: int, dialogue_id: int, destination: str, msg: bytes)¶

Bases: oef.messages.AgentMessage

This message is used to send a generic message to other agents. It contains:

a dialogue id, that identifies the dialogue in which the message is sent.
a destination, that is the public key of the recipient of the message.
a sequence of bytes, that is the content of the message.

If everything works correctly, eventually, the recipient will receive the content of the message: and the recipient’s on_message() is executed.

It is used in the method send_message().

to_envelope() → agent_pb2.Envelope¶

Pack the message into a protobuf message.

Returns:	the envelope.

class oef.messages.OEFErrorOperation¶

Bases: enum.Enum

Operation code for the OEF. It is returned in the OEF Error messages.

REGISTER_DESCRIPTION = 2¶

REGISTER_SERVICE = 0¶

UNREGISTER_DESCRIPTION = 3¶

UNREGISTER_SERVICE = 1¶

class oef.messages.Propose(msg_id: int, dialogue_id: int, destination: str, target: int, proposals: Union[bytes, List[oef.schema.Description]])¶

Bases: oef.messages.AgentMessage

This message is used to send a Propose. It contains:

the message id, that is an unique identifier for a message, given dialogue.
a dialogue id, that identifies the dialogue in which the message is sent.
a destination, that is the public key of the recipient of the message.
target, that is, the identifier of the message to whom this message is targeting.
a list of proposals describing the resources that the seller proposes.

If everything works correctly, eventually, the recipient will receive the content of the message and the recipient’s on_propose() is executed.

It is used in the method send_propose().

to_envelope() → agent_pb2.Message¶

Pack the message into a protobuf message.

Returns:	the envelope.

class oef.messages.RegisterDescription(msg_id: int, agent_description: oef.schema.Description)¶

Bases: oef.messages.BaseMessage

This message is used for registering a new agent in the Agent Directory of an OEF Node. The agent is described by a Description object.

It is used in the method register_agent().

to_envelope() → agent_pb2.Envelope¶

Pack the message into a protobuf message.

Returns:	the envelope.

class oef.messages.RegisterService(msg_id: int, service_description: oef.schema.Description)¶

Bases: oef.messages.BaseMessage

This message is used for registering a new agent in the Service Directory of an OEF Node. The service agent is described by a Description object.

It is used in the method register_service().

to_envelope() → agent_pb2.Envelope¶

Pack the message into a protobuf message.

Returns:	the envelope.

class oef.messages.SearchAgents(msg_id: int, query: oef.query.Query)¶

Bases: oef.messages.BaseMessage

This message is used for searching agents in the Agent Directory of an OEF Node. It contains:

a search id, that identifies the search query. This id will be used by the sender in order to distinguish different incoming search results.
a query, i.e. a list of constraints defined over a data model.

If everything works correctly, eventually, the sender of the message will receive a search result message and the agent’s on_search_result() will be executed.

It is used in the method search_agents().

to_envelope()¶

Pack the message into a protobuf message.

Returns:	the envelope.

class oef.messages.SearchServices(msg_id: int, query: oef.query.Query)¶

Bases: oef.messages.BaseMessage

This message is used for searching services in the Service Directory of an OEF Node. It contains:

a search id, that identifies the search query. This id will be used by the sender in order to distinguish different incoming search results.
a query, i.e. a list of constraints defined over a data model.

If everything works correctly, eventually, the sender of the message will receive a search result message and the agent’s on_search_result() is executed.

It is used in the method search_services().

to_envelope() → agent_pb2.Envelope¶

Pack the message into a protobuf message.

Returns:	the envelope.

class oef.messages.UnregisterDescription(msg_id: int)¶

Bases: oef.messages.BaseMessage

This message is used for unregistering an agent in the Agent Directory of an OEF Node.

It is used in the method unregister_agent().

to_envelope() → agent_pb2.Envelope¶

Pack the message into a protobuf message.

Returns:	the envelope.

class oef.messages.UnregisterService(msg_id: int, service_description)¶

Bases: oef.messages.BaseMessage

This message is used for unregistering a (service agent, description) in the Service Directory of an OEF Node. The service agent is described by a Description object.

It is used in the method unregister_service().

to_envelope() → agent_pb2.Envelope¶

Pack the message into a protobuf message.

Returns:	the envelope.

oef.proxy module¶

oef.proxy¶

This module defines the proxies classes used by agents to interact with an OEF Node.

exception oef.proxy.OEFConnectionError¶

Bases: ConnectionError

This exception is used whenever an error occurs during the connection to the OEF Node.

class oef.proxy.OEFLocalProxy(public_key: str, local_node: oef.proxy.OEFLocalProxy.LocalNode)¶

Bases: oef.core.OEFProxy

Proxy to the functionality of the OEF. It allows the interaction between agents, but not the search functionality. It is useful for local testing.

class LocalNode¶

Bases: object

A light-weight local implementation of a OEF Node.

connect(public_key: str) → Optional[Tuple[asyncio.queues.Queue, asyncio.queues.Queue]]¶

Connect a public key to the node.

Parameters:	public_key – the public key of the agent.
Returns:	an asynchronous queue, that constitutes the communication channel.

register_agent(public_key: str, agent_description: oef.schema.Description) → None¶

Register an agent in the agent directory of the node.

Parameters:	public_key – the public key of the agent to be registered. agent_description – the description of the agent to be registered.
Returns:	`None`

register_service(public_key: str, service_description: oef.schema.Description)¶

Register a service agent in the service directory of the node.

Parameters:	public_key – the public key of the service agent to be registered. service_description – the description of the service agent to be registered.
Returns:	`None`

run() → None¶

Run the node, i.e. start processing the messages.

Returns:	`None`

search_agents(public_key: str, search_id: int, query: oef.query.Query) → None¶

Search the agents in the local Agent Directory, and send back the result. The provided query will be checked with every instance of the Agent Directory.

Parameters:	public_key – the source of the search request. search_id – the search identifier associated with the search request. query – the query that constitutes the search.
Returns:	`None`

search_services(public_key: str, search_id: int, query: oef.query.Query) → None¶

Search the agents in the local Service Directory, and send back the result. The provided query will be checked with every instance of the Agent Directory.

Parameters:	public_key – the source of the search request. search_id – the search identifier associated with the search request. query – the query that constitutes the search.
Returns:	`None`

stop() → None¶

Stop the execution of the node.

Returns:	`None`

unregister_agent(public_key: str) → None¶

Unregister an agent.

Parameters:	public_key – the public key of the agent to be unregistered.
Returns:	`None`

unregister_service(public_key: str, service_description: oef.schema.Description) → None¶

Unregister a service agent.

Parameters:	public_key – the public key of the service agent to be unregistered. service_description – the description of the service agent to be unregistered.
Returns:	`None`

connect() → bool¶

Connect to the OEF Node

Returns:	True if the connection has been established, False otherwise.

is_connected() → bool¶

Check if the proxy is currently connected to the OEF Node.

Returns:	`True` if the proxy is connected, `False` otherwise.

register_agent(msg_id: int, agent_description: oef.schema.Description) → None¶

Adds a description of an agent to the OEF so that it can be understood/ queried by other agents in the OEF.

Parameters:	msg_id – the identifier of the message. agent_description – description of the agent to add
Returns:	`None`

register_service(msg_id: int, service_description: oef.schema.Description) → None¶

Adds a description of the respective service so that it can be understood/queried by other agents in the OEF.

Parameters:	msg_id – the identifier of the message. service_description – description of the services to add
Returns:	`None`

search_agents(search_id: int, query: oef.query.Query) → None¶

Search for other agents it is interested in communicating with. This can be useful when an agent wishes to directly proposition the provision of a service that it thinks another agent may wish to be able to offer it. All matching agents are returned (potentially including ourselves).

Parameters:	msg_id – the identifier of the message. query – specifications of the constraints on the agents that are matched
Returns:	`None`.

search_services(search_id: int, query: oef.query.Query) → None¶

Search for a particular service. This allows constrained search of all services that have been registered with the OEF. All matching services will be returned (potentially including services offered by ourselves).

Parameters:	msg_id – the identifier of the message. query – the constraint on the matching services
Returns:	`None`.

send_accept(msg_id: int, dialogue_id: int, destination: str, target: int) → None¶

Send an Accept.

Parameters:	msg_id – the message identifier for the dialogue. dialogue_id – the identifier of the dialogue in which the message is sent. destination – the agent identifier to whom the message is sent. target – the identifier of the message to whom this message is answering.
Returns:	`None`

send_cfp(msg_id: int, dialogue_id: int, destination: str, target: int, query: Union[oef.query.Query, bytes, None]) → None¶

Send a Call-For-Proposals.

Parameters:	msg_id – the message identifier for the dialogue. dialogue_id – the identifier of the dialogue in which the message is sent. destination – the agent identifier to whom the message is sent. target – the identifier of the message to whom this message is answering. query – the query associated with the Call For Proposals.
Returns:	`None`

send_decline(msg_id: int, dialogue_id: int, destination: str, target: int) → None¶

Send a Decline.

Parameters:	msg_id – the message identifier for the dialogue. dialogue_id – the identifier of the dialogue in which the message is sent. destination – the agent identifier to whom the message is sent. target – the identifier of the message to whom this message is answering.
Returns:	`None`

send_message(msg_id: int, dialogue_id: int, destination: str, msg: bytes)¶

Send a simple message.

Parameters:	msg_id – the identifier of the message. dialogue_id – the identifier of the dialogue in which the message is sent. destination – the agent identifier to whom the message is sent. msg – the message (in bytes).
Returns:	`None`

send_propose(msg_id: int, dialogue_id: int, destination: str, target: int, proposals: Union[bytes, List[oef.schema.Description]]) → None¶

Send a Propose.

Parameters:	msg_id – the message identifier for the dialogue. dialogue_id – the identifier of the dialogue in which the message is sent. destination – the agent identifier to whom the message is sent. target – the identifier of the message to whom this message is answering. proposals – either a list of `Description` or `bytes`.
Returns:	`None`

stop()¶: Stop the proxy.

unregister_agent(msg_id: int) → None¶

Remove the description of an agent from the OEF. This agent will no longer be queryable by other agents in the OEF. A conversation handler must be provided that allows the agent to receive and manage conversations from other agents wishing to communicate with it.

Parameters:	msg_id – the identifier of the message.
Returns:	`None`

unregister_service(msg_id: int, service_description: oef.schema.Description) → None¶

Add a description of the respective service so that it can be understood/queried by other agents in the OEF.

Parameters:	msg_id – the identifier of the message. service_description – description of the services to add
Returns:	`None`

class oef.proxy.OEFNetworkProxy(public_key: str, oef_addr: str, port: int = 3333)¶

Bases: oef.core.OEFProxy

Proxy to the functionality of the OEF. Provides functionality for an agent to:

Register a description of itself

Register its services

Locate other agents

Locate other services

Establish a connection with another agent

connect() → bool¶

Connect to the OEF Node

Returns:	True if the connection has been established, False otherwise.

is_connected() → bool¶

Check if the proxy is currently connected to the OEF Node.

Returns:	`True` if the proxy is connected, `False` otherwise.

register_agent(msg_id: int, agent_description: oef.schema.Description)¶

Adds a description of an agent to the OEF so that it can be understood/ queried by other agents in the OEF.

Parameters:	msg_id – the identifier of the message. agent_description – description of the agent to add
Returns:	`None`

register_service(msg_id: int, service_description: oef.schema.Description)¶

Adds a description of the respective service so that it can be understood/queried by other agents in the OEF.

Parameters:	msg_id – the identifier of the message. service_description – description of the services to add
Returns:	`None`

search_agents(search_id: int, query: oef.query.Query) → None¶

Search for other agents it is interested in communicating with. This can be useful when an agent wishes to directly proposition the provision of a service that it thinks another agent may wish to be able to offer it. All matching agents are returned (potentially including ourselves).

Parameters:	msg_id – the identifier of the message. query – specifications of the constraints on the agents that are matched
Returns:	`None`.

search_services(search_id: int, query: oef.query.Query) → None¶

Search for a particular service. This allows constrained search of all services that have been registered with the OEF. All matching services will be returned (potentially including services offered by ourselves).

Parameters:	msg_id – the identifier of the message. query – the constraint on the matching services
Returns:	`None`.

send_accept(msg_id: int, dialogue_id: int, destination: str, target: int)¶

Send an Accept.

Parameters:	msg_id – the message identifier for the dialogue. dialogue_id – the identifier of the dialogue in which the message is sent. destination – the agent identifier to whom the message is sent. target – the identifier of the message to whom this message is answering.
Returns:	`None`

send_cfp(msg_id: int, dialogue_id: int, destination: str, target: int, query: Union[oef.query.Query, bytes, None])¶

Send a Call-For-Proposals.

Parameters:	msg_id – the message identifier for the dialogue. dialogue_id – the identifier of the dialogue in which the message is sent. destination – the agent identifier to whom the message is sent. target – the identifier of the message to whom this message is answering. query – the query associated with the Call For Proposals.
Returns:	`None`

send_decline(msg_id: int, dialogue_id: int, destination: str, target: int)¶

Send a Decline.

Parameters:	msg_id – the message identifier for the dialogue. dialogue_id – the identifier of the dialogue in which the message is sent. destination – the agent identifier to whom the message is sent. target – the identifier of the message to whom this message is answering.
Returns:	`None`

send_message(msg_id: int, dialogue_id: int, destination: str, msg: bytes) → None¶

Send a simple message.

Parameters:	msg_id – the identifier of the message. dialogue_id – the identifier of the dialogue in which the message is sent. destination – the agent identifier to whom the message is sent. msg – the message (in bytes).
Returns:	`None`

send_propose(msg_id: int, dialogue_id: int, destination: str, target: int, proposals: Union[bytes, List[oef.schema.Description]])¶

Send a Propose.

Parameters:	msg_id – the message identifier for the dialogue. dialogue_id – the identifier of the dialogue in which the message is sent. destination – the agent identifier to whom the message is sent. target – the identifier of the message to whom this message is answering. proposals – either a list of `Description` or `bytes`.
Returns:	`None`

stop() → None¶: Tear down resources associated with this Proxy, i.e. the writing connection with the server.

unregister_agent(msg_id: int)¶

Remove the description of an agent from the OEF. This agent will no longer be queryable by other agents in the OEF. A conversation handler must be provided that allows the agent to receive and manage conversations from other agents wishing to communicate with it.

Parameters:	msg_id – the identifier of the message.
Returns:	`None`

unregister_service(msg_id: int, service_description: oef.schema.Description)¶

Add a description of the respective service so that it can be understood/queried by other agents in the OEF.

Parameters:	msg_id – the identifier of the message. service_description – description of the services to add
Returns:	`None`

oef.query module¶

class oef.query.And(constraints: List[oef.query.ConstraintExpr])¶

Bases: oef.query.ConstraintExpr

A constraint type that allows you to specify a conjunction of constraints. That is, the And constraint is satisfied whenever all the constraints that constitute the and are satisfied.

Examples:

All the books whose title is between ‘I’ and ‘J’ (alphanumeric order) but not equal to ‘It’

>>> c = And([Constraint("title", Range(("I", "J"))), Constraint("title", NotEq("It"))])
>>> c.check(Description({"title": "I, Robot"}))
True
>>> c.check(Description({"title": "It"}))
False
>>> c.check(Description({"title": "1984"}))
False

check(description: oef.schema.Description) → bool¶

Check if a value satisfies the And constraint expression.

Parameters:	description – the description to check.
Returns:	`True` if the description satisfy the constraint expression, `False` otherwise.

classmethod from_pb(constraint_pb: query_pb2.And)¶

From the And Protobuf object to the associated instance of And.

Parameters:	constraint_pb – the Protobuf object that represents the `And` constraint.
Returns:	an instance of `And` equivalent to the Protobuf object.

is_valid(data_model: oef.schema.DataModel) → bool¶

Check whether a constraint expression is valid wrt a data model. Specifically, check the following conditions:

If all the attributes referenced by the constraints are correctly associated with the Data Model attributes.

Parameters:	data_model – the data model used to check the validity of the constraint expression.
Returns:	`True` if the constraint expression is valid wrt the data model, `False` otherwise.

to_pb()¶

From an instance of And to its associated Protobuf object.

Returns:	the ConstraintExpr Protobuf object that contains the `And` constraint.

class oef.query.Constraint(attribute_name: str, constraint: oef.query.ConstraintType)¶

Bases: oef.query.ConstraintExpr

A class that represent a constraint over an attribute.

check(description: oef.schema.Description) → bool¶

Check if a description satisfies the constraint. The implementation depends on the type of the constraint.

Parameters:	description – the description to check.
Returns:	`True` if the description satisfies the constraint, `False` otherwise.

Examples:

>>> attr_author = AttributeSchema("author" , str, True, "The author of the book.")
>>> attr_year   = AttributeSchema("year",    int, True, "The year of publication of the book.")
>>> c1 = Constraint("author", Eq("Stephen King"))
>>> c2 = Constraint("year", Gt(1990))
>>> book_1 = Description({"author": "Stephen King",  "year": 1991})
>>> book_2 = Description({"author": "George Orwell", "year": 1948})

The "author" attribute instantiation satisfies the constraint, so the result is True.

>>> c1.check(book_1)
True

Here, the "author" does not satisfy the constraints. Hence, the result is False.

>>> c1.check(book_2)
False

In this case, there is a missing field specified by the query, that is "year" So the result is False, even in the case it is not required by the schema:

>>> c2.check(Description({"author": "Stephen King"}))
False

If the type of some attribute of the description is not correct, the result is False. In this case, the field "year" has a string instead of an integer:

>>> c2.check(Description({"author": "Stephen King", "year": "1991"}))
False
>>> Constraint("position", Distance(Location(0.0, 0.0), 1.0)).check(Description({"position": "1.0,1.0"}))
False

classmethod from_pb(constraint_pb: query_pb2.Constraint)¶

From the Constraint Protobuf object to the associated instance of Constraint.

Parameters:	constraint_pb – the Protobuf object that represents the `Constraint` object.
Returns:	an instance of `Constraint` equivalent to the Protobuf object provided in input.

is_valid(data_model: oef.schema.DataModel) → bool¶

Check whether a constraint expression is valid wrt a data model. Specifically, check the following conditions:

If all the attributes referenced by the constraints are correctly associated with the Data Model attributes.

Parameters:	data_model – the data model used to check the validity of the constraint expression.
Returns:	`True` if the constraint expression is valid wrt the data model, `False` otherwise.

to_pb()¶

Return the associated Protobuf object.

Returns:	a Protobuf object equivalent to the caller object.

class oef.query.ConstraintExpr¶

Bases: oef.schema.ProtobufSerializable, abc.ABC

This class is used to represent a constraint expression.

check(description: oef.schema.Description) → bool¶

Check if a description satisfies the constraint expression.

Parameters:	description – the description to check.
Returns:	`True` if the description satisfy the constraint expression, `False` otherwise.

is_valid(data_model: oef.schema.DataModel) → bool¶

Check whether a constraint expression is valid wrt a data model. Specifically, check the following conditions:

If all the attributes referenced by the constraints are correctly associated with the Data Model attributes.

Parameters:	data_model – the data model used to check the validity of the constraint expression.
Returns:	`True` if the constraint expression is valid wrt the data model, `False` otherwise.

class oef.query.ConstraintType¶

Bases: oef.schema.ProtobufSerializable, abc.ABC

This class is used to represent a constraint type.

check(value: Union[float, str, bool, int, oef.schema.Location]) → bool¶

Check if an attribute value satisfies the constraint. The implementation depends on the constraint type.

Parameters:	value – the value to check.
Returns:	`True` if the value satisfy the constraint, `False` otherwise.

is_valid(attribute: oef.schema.AttributeSchema) → bool¶

Check if the constraint type is valid wrt a given attribute.

Parameters:	attribute – the data model used to check the validity of the constraint type.
Returns:	`True` if the constraint type is valid wrt the attribute, `False` otherwise.

class oef.query.Distance(center: oef.schema.Location, distance: float)¶

Bases: oef.query.ConstraintType

Class that implements the ‘distance’ constraint type. That is, the locations we are looking for must be within a given distance from a given location. The distance is interpreted as a radius from a center.

Examples:

Define a location of interest, e.g. the Tour Eiffel >>> tour_eiffel = Location(48.8581064, 2.29447)

Find all the locations close to the Tour Eiffel within 1 km >>> close_to_tour_eiffel = Distance(tour_eiffel, 1.0)

Le Jules Verne, a famous restaurant close to the Tour Eiffel, satisfies the constraint. >>> le_jules_verne_restaurant = Location(48.8579675, 2.2951849) >>> close_to_tour_eiffel.check(le_jules_verne_restaurant) True

The Colosseum does not satisfy the constraint (farther than 1 km from the Tour Eiffel). >>> colosseum = Location(41.8902102, 12.4922309) >>> close_to_tour_eiffel.check(colosseum) False

check(value: oef.schema.Location) → bool¶

Check if an attribute value satisfies the constraint. The implementation depends on the constraint type.

Parameters:	value – the value to check.
Returns:	`True` if the value satisfy the constraint, `False` otherwise.

classmethod from_pb(distance_pb: query_pb2.Distance)¶

From the Distance Protobuf object to the associated instance of Distance.

Parameters:	distance_pb – the Protobuf object that represents the `~oef.query.Distance` constraint.
Returns:	an instance of `~oef.query.Distance`.

to_pb() → query_pb2.Distance¶

From an instance Distance to its associated Protobuf object.

Returns:	the Protobuf object that contains the `Distance` constraint.

class oef.query.Eq(value: Union[float, str, bool, int, oef.schema.Location])¶

Bases: oef.query.Relation

The equality relation. That is, if the value of an attribute is equal to the value specified then the Constraint with this constraint type is satisfied.

Examples:

All the books whose author is Stephen King

>>> c = Constraint("author",  Eq("Stephen King"))
>>> c.check(Description({"author": "Stephen King"}))
True
>>> c.check(Description({"author": "George Orwell"}))
False

check(value: Union[float, str, bool, int, oef.schema.Location]) → bool¶

Check if a value is equal to the value of the constraint.

Parameters:	value – the value to check.
Returns:	`True` if the value satisfy the constraint, `False` otherwise.

class oef.query.Gt(value: Union[int, str, float])¶

Bases: oef.query.OrderingRelation

Greater-than relation. That is, if the value of an attribute is greater than the value specified then the Constraint with this constraint type is satisfied.

Examples:

All the books with rating greater than 4.0

>>> c = Constraint("average_rating", Gt(4.0))
>>> c.check(Description({"average_rating": 4.5}))
True
>>> c.check(Description({"average_rating": 3.0}))
False

check(value: Union[int, str, float]) → bool¶

Check if a value is greater than the value of the constraint.

Parameters:	value – the value to check.
Returns:	`True` if the value satisfy the constraint, `False` otherwise.

class oef.query.GtEq(value: Union[int, str, float])¶

Bases: oef.query.OrderingRelation

Greater-than-equal relation. That is, if the value of an attribute is greater than or equal to the value specified then the Constraint with this constraint type is satisfied.

Examples:

All the books published after 2000, included

>>> c = Constraint("year", GtEq(2000))
>>> c.check(Description({"year": 2000}))
True
>>> c.check(Description({"year": 1990}))
False

check(value: Union[int, str, float]) → bool¶

Check if a value greater than or equal to the value of the constraint.

Parameters:	value – the value to check.
Returns:	`True` if the value satisfy the constraint, `False` otherwise.

class oef.query.In(values: Union[List[float], List[str], List[bool], List[int], List[oef.schema.Location]])¶

Bases: oef.query.Set

Class that implements the ‘in set’ constraint type. That is, the value of attribute over which the constraint is defined must be in the set of values provided.

Examples:

All the books whose genre is one of the following: Horror, Science fiction, Non-fiction

>>> c = Constraint("genre", In(["horror", "science fiction", "non-fiction"]))
>>> c.check(Description({"genre": "horror"}))
True
>>> c.check(Description({"genre": "thriller"}))
False

check(value: Union[float, str, bool, int, oef.schema.Location]) → bool¶

Check if a value is in the set of values specified by the constraint.

Parameters:	value – the value to check.
Returns:	`True` if the value satisfy the constraint, `False` otherwise.

class oef.query.Lt(value: Union[int, str, float])¶

Bases: oef.query.OrderingRelation

The Less-than relation. That is, if the value of an attribute is less than the value specified then the Constraint with this constraint type is satisfied.

Examples:

All the books published before 1990

>>> c = Constraint("year", Lt(1990))
>>> c.check(Description({"year": 1985}))
True
>>> c.check(Description({"year": 2000}))
False

check(value: Union[int, str, float]) → bool¶

Check if a value is less than the value of the constraint.

Parameters:	value – the value to check.
Returns:	`True` if the value satisfy the constraint, `False` otherwise.

class oef.query.LtEq(value: Union[int, str, float])¶

Bases: oef.query.OrderingRelation

Less-than-equal relation. That is, if the value of an attribute is less than or equal to the value specified then the Constraint with this constraint type is satisfied.

Examples:

All the books published before 1990, 1990 included

>>> c = Constraint("year", LtEq(1990))
>>> c.check(Description({"year": 1990}))
True
>>> c.check(Description({"year": 1991}))
False

check(value: Union[int, str, float]) → bool¶

Check if a value is less than or equal to the value of the constraint.

Parameters:	value – the value to check.
Returns:	`True` if the value satisfy the constraint, `False` otherwise.

class oef.query.Not(constraint: oef.query.ConstraintExpr)¶

Bases: oef.query.ConstraintExpr

A constraint type that allows you to specify a negation of a constraint. That is, the Not constraint is satisfied whenever the constraint that constitutes the Not expression is not satisfied.

Examples:

All the books whose genre is science fiction, but the year is not between 1990 and 2000

>>> c = And([Constraint("genre", Eq("science-fiction")), Not(Constraint("year", Range((1990, 2000))))])
>>> c.check(Description({"genre": "science-fiction", "year": 1995}))
False
>>> c.check(Description({"genre": "science-fiction", "year": 2001}))
True

check(description: oef.schema.Description) → bool¶

Check if a value satisfies the Not constraint expression.

Parameters:	description – the description to check.
Returns:	`True` if the description satisfy the constraint expression, `False` otherwise.

classmethod from_pb(constraint_pb: query_pb2.Not)¶

From the Not Protobuf object to the associated instance of Not.

Parameters:	constraint_pb – the Protobuf object that represents the `Not` constraint.
Returns:	an instance of `Not` equivalent to the Protobuf object.

is_valid(data_model: oef.schema.DataModel) → bool¶

Check whether a constraint expression is valid wrt a data model. Specifically, check the following conditions:

If all the attributes referenced by the constraints are correctly associated with the Data Model attributes.

Parameters:	data_model – the data model used to check the validity of the constraint expression.
Returns:	`True` if the constraint expression is valid wrt the data model, `False` otherwise.

to_pb()¶

From an instance of Not to its associated Protobuf object.

Returns:	the Protobuf object that contains the `Not` constraint.

class oef.query.NotEq(value: Union[float, str, bool, int, oef.schema.Location])¶

Bases: oef.query.Relation

The non-equality relation. That is, if the value of an attribute is not equal to the value specified then the Constraint with this constraint type is satisfied.

Examples:

All the books that are not of the genre Horror

>>> c = Constraint("genre", NotEq("horror"))
>>> c.check(Description({"genre": "non-fiction"}))
True
>>> c.check(Description({"author": "horror"}))
False

check(value: Union[float, str, bool, int, oef.schema.Location]) → bool¶

Check if a value is not equal to the value of the constraint.

Parameters:	value – the value to check.
Returns:	`True` if the value satisfy the constraint, `False` otherwise.

class oef.query.NotIn(values: Union[List[float], List[str], List[bool], List[int], List[oef.schema.Location]])¶

Bases: oef.query.Set

Class that implements the ‘not in set’ constraint type. That is, the value of attribute over which the constraint is defined must be not in the set of values provided.

Examples:

All the books that have not been published neither in 1990, nor in 1995, nor in 2000

>>> c = Constraint("year", NotIn([1990, 1995, 2000]))
>>> c.check(Description({"year": 1991}))
True
>>> c.check(Description({"year": 2000}))
False

check(value: Union[float, str, bool, int, oef.schema.Location]) → bool¶

Check if a value is not in the set of values specified by the constraint.

Parameters:	value – the value to check.
Returns:	`True` if the value satisfy the constraint, `False` otherwise.

class oef.query.Or(constraints: List[oef.query.ConstraintExpr])¶

Bases: oef.query.ConstraintExpr

A constraint type that allows you to specify a disjunction of constraints. That is, the Or constraint is satisfied whenever at least one of the constraints that constitute the or is satisfied.

Examples:

All the books that have been published either before the year 1960 or after the year 1970

>>> c = Or([Constraint("year", Lt(1960)), Constraint("year", Gt(1970))])
>>> c.check(Description({"year": 1950}))
True
>>> c.check(Description({"year": 1975}))
True
>>> c.check(Description({"year": 1960}))
False
>>> c.check(Description({"year": 1970}))
False

check(description: oef.schema.Description) → bool¶

Check if a value satisfies the Or constraint expression.

Parameters:	description – the description to check.
Returns:	`True` if the description satisfy the constraint expression, `False` otherwise.

classmethod from_pb(constraint_pb: query_pb2.Or)¶

From the Or Protobuf object to the associated instance of Or.

Parameters:	constraint_pb – the Protobuf object that represents the `Or` constraint.
Returns:	an instance of `Or` equivalent to the Protobuf object.

is_valid(data_model: oef.schema.DataModel) → bool¶

Check whether a constraint expression is valid wrt a data model. Specifically, check the following conditions:

If all the attributes referenced by the constraints are correctly associated with the Data Model attributes.

Parameters:	data_model – the data model used to check the validity of the constraint expression.
Returns:	`True` if the constraint expression is valid wrt the data model, `False` otherwise.

to_pb()¶

From an instance of Or to its associated Protobuf object.

Returns:	the Protobuf object that contains the `Or` constraint.

class oef.query.OrderingRelation(value: Union[int, str, float])¶

Bases: oef.query.Relation, abc.ABC

A specialization of the Relation class to represent ordering relation (e.g. greater-than).

class oef.query.Query(constraints: List[oef.query.ConstraintExpr], model: Optional[oef.schema.DataModel] = None)¶

Bases: oef.schema.ProtobufSerializable

Representation of a search that is to be performed. Currently a search is represented as a set of key value pairs that must be contained in the description of the service/ agent.

Examples:

Return all the books written by Stephen King published after 1990, and available as an e-book:

>>> attr_author   = AttributeSchema("author" ,         str,   True,  "The author of the book.")
>>> attr_year     = AttributeSchema("year",            int,   True,  "The year of publication of the book.")
>>> attr_ebook    = AttributeSchema("ebook_available", bool,  False, "If the book can be sold as an e-book.")
>>> q = Query([
...     Constraint("author", Eq("Stephen King")),
...     Constraint("year", Gt(1990)),
...     Constraint("ebook_available", Eq(True))
... ])

With a query, you can check that a ~oef.schema.Description object satisfies the constraints.

>>> q.check(Description({"author": "Stephen King", "year": 1991, "ebook_available": True}))
True
>>> q.check(Description({"author": "George Orwell", "year": 1948, "ebook_available": False}))
False

check(description: oef.schema.Description) → bool¶

Check if a description satisfies the constraints of the query. The constraints are interpreted as conjunction.

Parameters:	description – the description to check.
Returns:	`True` if the description satisfies all the constraints, `False` otherwise.

classmethod from_pb(query: query_pb2.Model)¶

From the Query Protobuf object to the associated instance of Query.

Parameters:	query – the Protobuf object that represents the `Query` object.
Returns:	an instance of `Query` equivalent to the Protobuf object provided in input.

is_valid(data_model: oef.schema.DataModel) → bool¶

Given a data model, check whether the query is valid for that data model.

Returns:	`True` if the query is compliant with the data model, `False` otherwise.

to_pb() → query_pb2.Model¶

Return the associated Protobuf object.

Returns:	a Protobuf object equivalent to the caller object.

class oef.query.Range(values: Union[Tuple[str, str], Tuple[int, int], Tuple[float, float], Tuple[oef.schema.Location, oef.schema.Location]])¶

Bases: oef.query.ConstraintType

A constraint type that allows you to restrict the values of the attribute in a given range.

Examples:

All the books published after 2000, included

>>> c = Constraint("year", Range((2000, 2005)))
>>> c.check(Description({"year": 2000}))
True
>>> c.check(Description({"year": 2005}))
True
>>> c.check(Description({"year": 1990}))
False
>>> c.check(Description({"year": 2010}))
False

check(value: Union[Tuple[str, str], Tuple[int, int], Tuple[float, float], Tuple[oef.schema.Location, oef.schema.Location]]) → bool¶

Check if a value is in the range specified by the constraint.

Parameters:	value – the value to check.
Returns:	`True` if the value satisfy the constraint, `False` otherwise.

classmethod from_pb(range_pb: query_pb2.Range)¶

From the Range Protobuf object to the associated instance of Range.

Parameters:	range_pb – the Protobuf object that represents the range.
Returns:	an instance of `Range` equivalent to the Protobuf object provided as input.

to_pb() → query_pb2.Query¶

From an instance of Range to its associated Protobuf object.

Returns:	the Protobuf object that contains the range.

class oef.query.Relation(value: Union[float, str, bool, int, oef.schema.Location])¶

Bases: oef.query.ConstraintType, abc.ABC

A constraint type that allows you to impose specific values for the attributes.

The specific operator of the relation is defined in the subclasses that extend this class.

classmethod from_pb(relation: query_pb2.Relation)¶

From the Relation Protobuf object to the associated instance of a subclass of Relation.

Parameters:	relation – the Protobuf object that represents the relation constraint.
Returns:	an instance of one of the subclasses of Relation.

to_pb() → query_pb2.Relation¶

From an instance of Relation to its associated Protobuf object.

Returns:	the Protobuf object that contains the relation.

class oef.query.Set(values: Union[List[float], List[str], List[bool], List[int], List[oef.schema.Location]])¶

Bases: oef.query.ConstraintType, abc.ABC

A constraint type that allows you to restrict the values of the attribute in a specific set.

The specific operator of the relation is defined in the subclasses that extend this class.

classmethod from_pb(set_pb: query_pb2.Set)¶

From the Set Protobuf object to the associated instance of a subclass of Set.

Parameters:	set_pb – the Protobuf object that represents the set constraint.
Returns:	the object of one of the subclasses of `Set`.

to_pb()¶

From an instance of one of the subclasses of Set to its associated Protobuf object.

Returns:	the Protobuf object that contains the set constraint.

oef.schema module¶

oef.schema¶

This module defines classes to deal with data models and their instances.

exception oef.schema.AttributeInconsistencyException¶

Bases: Exception

Raised when the attributes in a Description are inconsistent.

Inconsistency is defined when values do not meet their respective schema, or if the values are not of an allowed type.

class oef.schema.AttributeSchema(attribute_name: str, attribute_type: Type[Union[float, str, bool, int, oef.schema.Location]], is_attribute_required: bool, attribute_description: Optional[str] = None)¶

Bases: oef.schema.ProtobufSerializable

Description of a single element of datum of either a description or a service.

This defines the schema that a single entry in a schema must take.

Examples:

>>> attr_title    = AttributeSchema("title" ,          str,   True,  "The title of the book.")
>>> attr_author   = AttributeSchema("author" ,         str,   True,  "The author of the book.")
>>> attr_genre    = AttributeSchema("genre",           str,   True,  "The genre of the book.")
>>> attr_year     = AttributeSchema("year",            int,   True,  "The year of publication of the book.")
>>> attr_avg_rat  = AttributeSchema("average_rating",  float, False, "The average rating of the book.")
>>> attr_isbn     = AttributeSchema("ISBN",            str,   True,  "The ISBN.")
>>> attr_ebook    = AttributeSchema("ebook_available", bool,  False, "If the book can be sold as an e-book.")

classmethod from_pb(attribute: query_pb2.Attribute)¶

Unpack the attribute Protobuf object.

Parameters:	attribute – the Protobuf object associated with the attribute.
Returns:	the attribute.

to_pb() → query_pb2.Attribute¶

Convert the attribute into a Protobuf object

Returns:	the associated Attribute protobuf object.

class oef.schema.DataModel(name: str, attribute_schemas: List[oef.schema.AttributeSchema], description: Optional[str] = None)¶

Bases: oef.schema.ProtobufSerializable

This class represents a data model (a.k.a. schema) of the OEFCore.

Examples:

>>> book_model = DataModel("book", [
...  AttributeSchema("title" ,          str,   True,  "The title of the book."),
...  AttributeSchema("author" ,         str,   True,  "The author of the book."),
...  AttributeSchema("genre",           str,   True,  "The genre of the book."),
...  AttributeSchema("year",            int,   True,  "The year of publication of the book."),
...  AttributeSchema("average_rating",  float, False, "The average rating of the book."),
...  AttributeSchema("ISBN",            str,   True,  "The ISBN."),
...  AttributeSchema("ebook_available", bool,  False, "If the book can be sold as an e-book."),
... ], "A data model to describe books.")

classmethod from_pb(model: query_pb2.DataModel)¶

Unpack the data model Protobuf object.

Parameters:	model – the Protobuf object associated with the data model.
Returns:	the data model.

to_pb()¶

Convert the data model into a Protobuf object

Returns:	the associated DataModel Protobuf object.

class oef.schema.Description(attribute_values: Dict[str, Union[float, str, bool, int, oef.schema.Location]], data_model: oef.schema.DataModel = None, data_model_name: str = '')¶

Bases: oef.schema.ProtobufSerializable

Description of either a service or an agent so it can be understood by the OEF and other agents.

Contains values of the description, and an optional schema for checking format of values.

Whenever the description is changed (including when it is create), the attribute values will checked to make sure they do not violate the attribute schema.

Examples:

>>> It = Description({
...     "title" :           "It",
...     "author":           "Stephen King",
...     "genre":            "horror",
...     "year":             1986,
...     "average_rating":   4.5,
...     "ISBN":             "0-670-81302-8",
...     "ebook_available":  True
... })

>>> _1984 = Description({
...     "title" :           "1984",
...     "author":           "George Orwell",
...     "genre":            "novel",
...     "year":             1949,
...     "ISBN":             "978-0451524935",
...     "ebook_available":  False
... })

classmethod from_pb(query_instance: query_pb2.Instance)¶

Unpack the data model Protobuf object.

Parameters:	query_instance – the Protobuf object associated with the data model.
Returns:	the data model.

to_agent_description_pb() → agent_pb2.AgentDescription¶

Convert the description into the Protobuf object associated to the AgentDescription message.

Returns:	the associated AgentDescription Protobuf object.

to_pb() → query_pb2.Instance¶

Return the description object as a Protobuf query instance.

Returns:	the Protobuf query instance object associated to the description.

class oef.schema.Location(latitude: float, longitude: float)¶

Bases: oef.schema.ProtobufSerializable

Data structure to represent locations (i.e. a pair of latitude and longitude).

distance(other) → float¶

classmethod from_pb(obj: query_pb2.Location)¶

From the Location Protobuf object to the associated instance of Location.

Parameters:	obj – the Protobuf object that represents the `Location` constraint.
Returns:	an instance of `Location` equivalent to the Protobuf object.

to_pb() → query_pb2.Location¶

From an instance of Location to its associated Protobuf object.

Returns:	the Location Protobuf object that contains the `Location` constraint.

class oef.schema.ProtobufSerializable¶

Bases: abc.ABC

Interface that includes method for packing/unpacking to/from Protobuf objects.

classmethod from_pb(obj)¶

Unpack a Protobuf object.

Parameters:	obj – the Protobuf object to parse.
Returns:	an instance of the class that implements the interface.

to_pb()¶: Convert the object into a Protobuf object

oef.schema.generate_schema(model_name: str, attribute_values: Dict[str, Union[float, str, bool, int, oef.schema.Location]]) → oef.schema.DataModel¶

Generate a schema that matches the values stored in this description. That is, for each attribute (name, value), generate an AttributeSchema. It is assumed that each attribute is required.

Parameters:	model_name – the name of the model. attribute_values – the values of each attribute
Returns:	the schema compliant with the values specified.

Module contents¶

Python SDK for OEF Agent development.