feat: api docs automation

python/docs/api/uagents/context.md

@@ -0,0 +1,292 @@
+<a id="src.uagents.context"></a>
+
+# src.uagents.context
+
+Agent Context and Message Handling
+
+<a id="src.uagents.context.MsgDigest"></a>
+
+## MsgDigest Objects
+
+```python
+@dataclass
+class MsgDigest()
+```
+
+Represents a message digest containing a message and its schema digest.
+
+**Attributes**:
+
+- `message` _Any_ - The message content.
+- `schema_digest` _str_ - The schema digest of the message.
+
+<a id="src.uagents.context.Context"></a>
+
+## Context Objects
+
+```python
+class Context()
+```
+
+Represents the context in which messages are handled and processed.
+
+**Attributes**:
+
+- `storage` _KeyValueStore_ - The key-value store for storage operations.
+- `wallet` _LocalWallet_ - The local wallet instance for managing identities.
+- `ledger` _LedgerClient_ - The ledger client for interacting with distributed ledgers.
+- `_name` _Optional[str]_ - The optional name associated with the context.
+- `_address` _str_ - The address of the context.
+- `_resolver` _Resolver_ - The resolver for name-to-address resolution.
+- `_identity` _Identity_ - The identity associated with the context.
+- `_queries` _Dict[str, asyncio.Future]_ - Dictionary of query names and their asyncio Futures.
+- `_session` _Optional[uuid.UUID]_ - The optional session UUID.
+- `_replies` _Optional[Dict[str, Set[Type[Model]]]]_ - The optional dictionary of reply models.
+- `_interval_messages` _Optional[Set[str]]_ - The optional set of interval messages.
+- `_message_received` _Optional[MsgDigest]_ - The optional message digest received.
+- `_protocols` _Optional[Dict[str, Protocol]]_ - The optional dictionary of protocols.
+- `_logger` _Optional[logging.Logger]_ - The optional logger instance.
+
+  Properties:
+- `name` _str_ - The name associated with the context, or a truncated address if name is None.
+- `address` _str_ - The address of the context.
+- `logger` _logging.Logger_ - The logger instance.
+- `protocols` _Optional[Dict[str, Protocol]]_ - The dictionary of protocols.
+
+
+**Methods**:
+
+- `get_message_protocol(message_schema_digest)` - Get the protocol associated
+  with a message schema digest.
+  send(destination, message, timeout): Send a message to a destination.
+
+<a id="src.uagents.context.Context.__init__"></a>
+
+#### `__`init`__`
+
+```python
+def __init__(address: str,
+             name: Optional[str],
+             storage: KeyValueStore,
+             resolve: Resolver,
+             identity: Identity,
+             wallet: LocalWallet,
+             ledger: LedgerClient,
+             queries: Dict[str, asyncio.Future],
+             session: Optional[uuid.UUID] = None,
+             replies: Optional[Dict[str, Set[Type[Model]]]] = None,
+             interval_messages: Optional[Set[str]] = None,
+             message_received: Optional[MsgDigest] = None,
+             protocols: Optional[Dict[str, Protocol]] = None,
+             logger: Optional[logging.Logger] = None)
+```
+
+Initialize the Context instance.
+
+**Arguments**:
+
+- `address` _str_ - The address of the context.
+- `name` _Optional[str]_ - The optional name associated with the context.
+- `storage` _KeyValueStore_ - The key-value store for storage operations.
+- `resolve` _Resolver_ - The resolver for name-to-address resolution.
+- `identity` _Identity_ - The identity associated with the context.
+- `wallet` _LocalWallet_ - The local wallet instance for managing identities.
+- `ledger` _LedgerClient_ - The ledger client for interacting with distributed ledgers.
+- `queries` _Dict[str, asyncio.Future]_ - Dictionary of query names and their Futures.
+- `session` _Optional[uuid.UUID]_ - The optional session UUID.
+- `replies` _Optional[Dict[str, Set[Type[Model]]]]_ - Optional dictionary of reply models.
+- `interval_messages` _Optional[Set[str]]_ - The optional set of interval messages.
+- `message_received` _Optional[MsgDigest]_ - The optional message digest received.
+- `protocols` _Optional[Dict[str, Protocol]]_ - The optional dictionary of protocols.
+- `logger` _Optional[logging.Logger]_ - The optional logger instance.
+
+<a id="src.uagents.context.Context.name"></a>
+
+#### name
+
+```python
+@property
+def name() -> str
+```
+
+Get the name associated with the context or a truncated address if name is None.
+
+**Returns**:
+
+- `str` - The name or truncated address.
+
+<a id="src.uagents.context.Context.address"></a>
+
+#### address
+
+```python
+@property
+def address() -> str
+```
+
+Get the address of the context.
+
+**Returns**:
+
+- `str` - The address of the context.
+
+<a id="src.uagents.context.Context.logger"></a>
+
+#### logger
+
+```python
+@property
+def logger() -> logging.Logger
+```
+
+Get the logger instance associated with the context.
+
+**Returns**:
+
+- `logging.Logger` - The logger instance.
+
+<a id="src.uagents.context.Context.protocols"></a>
+
+#### protocols
+
+```python
+@property
+def protocols() -> Optional[Dict[str, Protocol]]
+```
+
+Get the dictionary of protocols associated with the context.
+
+**Returns**:
+
+  Optional[Dict[str, Protocol]]: The dictionary of protocols.
+
+<a id="src.uagents.context.Context.session"></a>
+
+#### session
+
+```python
+@property
+def session() -> uuid.UUID
+```
+
+Get the session UUID associated with the context.
+
+**Returns**:
+
+- `uuid.UUID` - The session UUID.
+
+<a id="src.uagents.context.Context.get_message_protocol"></a>
+
+#### get`_`message`_`protocol
+
+```python
+def get_message_protocol(message_schema_digest) -> Optional[str]
+```
+
+Get the protocol associated with a given message schema digest.
+
+**Arguments**:
+
+- `message_schema_digest` _str_ - The schema digest of the message.
+
+
+**Returns**:
+
+- `Optional[str]` - The protocol digest associated with the message schema digest,
+  or None if not found.
+
+<a id="src.uagents.context.Context.get_agents_by_protocol"></a>
+
+#### get`_`agents`_`by`_`protocol
+
+```python
+def get_agents_by_protocol(protocol_digest: str,
+                           limit: Optional[int] = None) -> List[str]
+```
+
+Retrieve a list of agent addresses using a specific protocol digest.
+
+This method queries the Almanac API to retrieve a list of agent addresses
+that are associated with a given protocol digest. The list can be optionally
+limited to a specified number of addresses.
+
+**Arguments**:
+
+- `protocol_digest` _str_ - The protocol digest to search for, starting with "proto:".
+- `limit` _int, optional_ - The maximum number of agent addresses to return.
+
+
+**Returns**:
+
+- `List[str]` - A list of agent addresses using the specified protocol digest.
+
+<a id="src.uagents.context.Context.send"></a>
+
+#### send
+
+```python
+async def send(destination: str,
+               message: Model,
+               timeout: Optional[int] = DEFAULT_ENVELOPE_TIMEOUT_SECONDS)
+```
+
+Send a message to the specified destination.
+
+**Arguments**:
+
+- `destination` _str_ - The destination address to send the message to.
+- `message` _Model_ - The message to be sent.
+- `timeout` _Optional[int]_ - The optional timeout for sending the message, in seconds.
+
+<a id="src.uagents.context.Context.experimental_broadcast"></a>
+
+#### experimental`_`broadcast
+
+```python
+async def experimental_broadcast(
+        destination_protocol: str,
+        message: Model,
+        limit: Optional[int] = DEFAULT_SEARCH_LIMIT,
+        timeout: Optional[int] = DEFAULT_ENVELOPE_TIMEOUT_SECONDS)
+```
+
+Broadcast a message to agents with a specific protocol.
+
+This asynchronous method broadcasts a given message to agents associated
+with a specific protocol. The message is sent to multiple agents concurrently.
+The schema digest of the message is used for verification.
+
+**Arguments**:
+
+- `destination_protocol` _str_ - The protocol to filter agents by.
+- `message` _Model_ - The message to broadcast.
+- `limit` _int, optional_ - The maximum number of agents to send the message to.
+- `timeout` _int, optional_ - The timeout for sending each message.
+
+
+**Returns**:
+
+  None
+
+<a id="src.uagents.context.Context.send_raw"></a>
+
+#### send`_`raw
+
+```python
+async def send_raw(destination: str,
+                   json_message: JsonStr,
+                   schema_digest: str,
+                   message_type: Optional[Type[Model]] = None,
+                   timeout: Optional[int] = DEFAULT_ENVELOPE_TIMEOUT_SECONDS)
+```
+
+Send a raw message to the specified destination.
+
+**Arguments**:
+
+- `destination` _str_ - The destination address to send the message to.
+- `json_message` _JsonStr_ - The JSON-encoded message to be sent.
+- `schema_digest` _str_ - The schema digest of the message.
+- `message_type` _Optional[Type[Model]]_ - The optional type of the message being sent.
+- `timeout` _Optional[int]_ - The optional timeout for sending the message, in seconds.
+

python/docs/api/uagents/envelope.md

@@ -0,0 +1,85 @@
+<a id="src.uagents.envelope"></a>
+
+# src.uagents.envelope
+
+Agent Envelope.
+
+<a id="src.uagents.envelope.Envelope"></a>
+
+## Envelope Objects
+
+```python
+class Envelope(BaseModel)
+```
+
+Represents an envelope for message communication between agents.
+
+**Attributes**:
+
+- `version` _int_ - The envelope version.
+- `sender` _str_ - The sender's address.
+- `target` _str_ - The target's address.
+- `session` _UUID4_ - The session UUID.
+- `schema_digest` _str_ - The schema digest (alias for protocol).
+- `protocol_digest` _Optional[str]_ - The protocol digest (optional).
+- `payload` _Optional[str]_ - The payload data (optional).
+- `expires` _Optional[int]_ - The expiration timestamp (optional).
+- `nonce` _Optional[int]_ - The nonce value (optional).
+- `signature` _Optional[str]_ - The envelope signature (optional).
+
+<a id="src.uagents.envelope.Envelope.encode_payload"></a>
+
+#### encode`_`payload
+
+```python
+def encode_payload(value: JsonStr)
+```
+
+Encode the payload value and store it in the envelope.
+
+**Arguments**:
+
+- `value` _JsonStr_ - The payload value to be encoded.
+
+<a id="src.uagents.envelope.Envelope.decode_payload"></a>
+
+#### decode`_`payload
+
+```python
+def decode_payload() -> Optional[Any]
+```
+
+Decode and retrieve the payload value from the envelope.
+
+**Returns**:
+
+- `Optional[Any]` - The decoded payload value, or None if payload is not present.
+
+<a id="src.uagents.envelope.Envelope.sign"></a>
+
+#### sign
+
+```python
+def sign(identity: Identity)
+```
+
+Sign the envelope using the provided identity.
+
+**Arguments**:
+
+- `identity` _Identity_ - The identity used for signing.
+
+<a id="src.uagents.envelope.Envelope.verify"></a>
+
+#### verify
+
+```python
+def verify() -> bool
+```
+
+Verify the envelope's signature.
+
+**Returns**:
+
+- `bool` - True if the signature is valid, False otherwise.
+