feat(experimental): add basic subscribable protocol

[jrriehl]

Proposed Changes

Adds a basic version of a subscribable protocol that checks the subscription tier of an agent before fulfilling the request. It is tightly based on the existing QuotaProtocol which establishes a free tier that is bypassed for agents on a paid tier.

Usage examples

This Protocol class provides a basic example to support subscriptions.

If a requesting agent is on the free tier, it will be rate-limited according
to the specification given for the QuotaProtocol. If the agent is on a paid
tier (PLUS or PRO), it will not be rate-limited and can make requests
without restrictions.

Usage examples:

```python
from uagents.experimental.subscription import SubscribableProtocol

protocol_spec = ProtocolSpecification(...) # Import or create any protocol specification

# Initialize the SubscribableProtocol instance
subs_protocol = SubscribableProtocol(
    storage_reference=agent.storage,
    identity=agent.identity,
    agentverse=agent.agentverse,
    spec=protocol_spec,
    # default_rate_limit=RateLimit(window_size_minutes=1, max_requests=3), # Optional
)

# Subscription and rate limiting does not apply to this message handler
@subs_protocol.on_message(ExampleMessage1)
async def handle(ctx: Context, sender: str, msg: ExampleMessage1):
    ...

# This message handler is rate limited with custom window size and request limit
# that will be bypassed if the agent is on a paid tier
@subs_protocol.on_message(
    ExampleMessage2,
    rate_limit=RateLimit(window_size_minutes=1, max_requests=3),
)
async def handle(ctx: Context, sender: str, msg: ExampleMessage2):
    ...

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)

[Dacksus]

I wonder if it would make sense to merge it with the general Subscription protocol?

[jrriehl]

I wonder if it would make sense to merge it with the general Subscription protocol?

The tricky thing and the reason I decided to rename this to SubscribableProtocol is that this is meant to wrap any protocol belonging to an agent who has already enabled subscriptions via the SubscriptionProtocol, which is more about managing the user subscriptions to agents themselves. But let me know if you thought about this differently.

[Dacksus]

I wonder if it would make sense to merge it with the general Subscription protocol?

The tricky thing and the reason I decided to rename this to SubscribableProtocol is that this is meant to wrap any protocol belonging to an agent who has already enabled subscriptions via the SubscriptionProtocol, which is more about managing the user subscriptions to agents themselves. But let me know if you thought about this differently.

Yes, I agree that technically they're separate protocols. Conceptually, I feel it would be more convenient for users to only have a single import for everything subscription related, because ultimately you would always need both aspects to make subscriptions work.

Probably at this point the effort is not worth it, but it feels like the right point to integrate would be e.g., at the ChatProtocol level? I.e., make the generic ChatProtocol everyone is using a SubscribableProtocol so that one simply could annotate the message handler for ChatMessages if it's a subscription agent?