feat(core): add protocol specification

[jrriehl]

Proposed Changes

Add protocol specification for easier definition of protocols based on interactions and roles. The original way of defining protocols still works exactly the same, but now if you provide a protocol specification object, for example:

from uagents import Model


class ProposeChat(Model):
    pass


class AcceptChat(Model):
    pass


class RejectChat(Model):
    pass


class Chat(Model):
    text: str


class EndChat(Model):
    pass


spec = ProtocolSpecification(
    interactions={
        ProposeChat: {AcceptChat, RejectChat},
        AcceptChat: {Chat, EndChat},
        RejectChat: set(),
        Chat: {Chat, EndChat},
        EndChat: set(),
    },
    roles={
        "user": {ProposeChat, Chat, EndChat},
        "agent": {AcceptChat, RejectChat, Chat, EndChat},
    },
)

Then you can generate the protocols for both roles:

user_proto = Protocol(name="ChatProtocol", version="0.1", spec=spec, role="user")
agent_proto = Protocol(name="ChatProtocol", version="0.1", spec=spec, role="agent")

Creating the protocol this way locks the protocol so that you cannot add handlers for messages that are not already included int he interactions, ensuring that the protocol manifest and digest do not change. Also, when an agent includes a protocol, it calls the protocol.verify() function, which checks that all the required handlers for the role have been implemented.

Linked Issues

[if applicable, add links to issues resolved by this PR]

Types of changes

What type of change does this pull request make (put an x in the boxes that apply)?

• Bug fix (non-breaking change that fixes an issue).
• New feature added (non-breaking change that adds functionality).
• Breaking change (fix or feature that would cause existing functionality to stop working as expected).
• Documentation update.
• Something else (e.g., tests, scripts, example, deployment, infrastructure).

Checklist

Put an x in the boxes that apply:

• I have read the CONTRIBUTING guide
• Checks and tests pass locally

If applicable

• I have added tests that prove my fix is effective or that my feature works
• I have added/updated the documentation (executed the script in python/scripts/generate_api_docs.py)

[Archento]

I really like this comprehensive approach of defining a protocol. Ultimately we'd benefit a lot from separating the syntax of the protocol from its implementation.
Great work! 👍🏻

[Archento]

Looks good to me now!