-
Notifications
You must be signed in to change notification settings - Fork 215
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Co-authored-by: James Riehl <[email protected]>
- Loading branch information
1 parent
3c41113
commit 846a1e9
Showing
20 changed files
with
3,280 additions
and
8 deletions.
There are no files selected for viewing
Large diffs are not rendered by default.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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. | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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. | ||
|
Oops, something went wrong.