{
  "name": "forge.comm",
  "language": "python",
  "version": "0.1.0",
  "description": "Python comm package; imports are explicit from this package.",
  "manifest": "forge-py/pyproject.toml",
  "manifestSha256": "7f96957378b21995bf2e583af2afd1b9e6fb3b0089ff3559d62c7e012a034696",
  "status": "source-reference",
  "registryPublicationVerified": false,
  "route": "/libraries/python/comm",
  "features": {},
  "files": [
    {
      "path": "forge-py/src/forge/comm/__init__.py",
      "sha256": "2fdca6da76c24368cb3f4baa3f0ccf435d1031b59aabfa8827294cb84b06e3f6",
      "artifactSha256": "d975dd34a530df503f7633beeab41ac523f17290af96c25a8cc53c367f50d0e9",
      "url": "/reference/source/forge-py/src/forge/comm/__init__.py.txt",
      "declarations": []
    },
    {
      "path": "forge-py/src/forge/comm/channel.py",
      "sha256": "2d25831e013ea36b74f374405e2dc820a74ea1de5549d7beb7213793e9a30475",
      "artifactSha256": "803d5dd4bf1e467d202a3a87a8042eab04552802f1eb8315d5241ce20f9e5055",
      "url": "/reference/source/forge-py/src/forge/comm/channel.py.txt",
      "declarations": [
        {
          "name": "ChannelTransport",
          "line": 17,
          "signature": "class ChannelTransport()",
          "documentation": "In-memory async channel transport.\n\nCreated in pairs via the ``create_pair`` class method. Each side\nsends messages to the other's receive queue.\n\nANVIL Spec section 10.3 -- Transport Contract.\n\nExample:\n    >>> import asyncio\n    >>> async def demo():\n    ...     a, b = ChannelTransport.create_pair(capacity=16)\n    ...     msg = AgentMessage.new(\n    ...         \"did:oas:l1fe:agent:a\",\n    ...         \"did:oas:l1fe:agent:b\",\n    ...         \"anvil.task.v1\",\n    ...         \"request\",\n    ...         {\"data\": 42},\n    ...     )\n    ...     await a.send(msg)\n    ...     received = await b.receive()\n    ...     return received.sender\n    >>> asyncio.run(demo())\n    'did:oas:l1fe:agent:a'"
        },
        {
          "name": "ChannelTransport.__init__",
          "line": 43,
          "signature": "def __init__(self, send_queue: asyncio.Queue[AgentMessage], recv_queue: asyncio.Queue[AgentMessage]) -> None",
          "documentation": ""
        },
        {
          "name": "ChannelTransport.create_pair",
          "line": 53,
          "signature": "def create_pair(cls, capacity: int=32) -> tuple[ChannelTransport, ChannelTransport]",
          "documentation": "Create a bidirectional pair of channel transports.\n\nMessages sent on one side are received on the other.\n\nArgs:\n    capacity: The maximum number of messages buffered per direction.\n\nReturns:\n    A tuple of two ChannelTransport instances."
        },
        {
          "name": "ChannelTransport.send",
          "line": 70,
          "signature": "async def send(self, message: AgentMessage) -> None",
          "documentation": "Send a message to the other side of the channel.\n\nArgs:\n    message: The message to send.\n\nRaises:\n    CommChannelClosedError: If the channel has been closed."
        },
        {
          "name": "ChannelTransport.receive",
          "line": 83,
          "signature": "async def receive(self) -> AgentMessage",
          "documentation": "Receive the next message from the channel.\n\nBlocks until a message is available.\n\nReturns:\n    The next AgentMessage.\n\nRaises:\n    CommChannelClosedError: If the channel has been closed."
        },
        {
          "name": "ChannelTransport.close",
          "line": 98,
          "signature": "def close(self) -> None",
          "documentation": "Close this side of the channel.\n\nAfter closing, send and receive will raise CommChannelClosedError."
        }
      ]
    },
    {
      "path": "forge-py/src/forge/comm/errors.py",
      "sha256": "3280a385b03a55f37d49f6427c9eb5939177fc58e209526b367fc38b76d8c12b",
      "artifactSha256": "549955bce214abc256d1a0a4c04ef31e9fd05f24904889ce1cbf7b31d3d58d88",
      "url": "/reference/source/forge-py/src/forge/comm/errors.py.txt",
      "declarations": [
        {
          "name": "CommError",
          "line": 14,
          "signature": "class CommError(ForgeError)",
          "documentation": "Base error for communication operations."
        },
        {
          "name": "CommSerializationError",
          "line": 18,
          "signature": "class CommSerializationError(CommError)",
          "documentation": "Message serialization failed.\n\nArgs:\n    reason: What went wrong during serialization."
        },
        {
          "name": "CommSerializationError.__init__",
          "line": 25,
          "signature": "def __init__(self, reason: str) -> None",
          "documentation": ""
        },
        {
          "name": "CommDeserializationError",
          "line": 30,
          "signature": "class CommDeserializationError(CommError)",
          "documentation": "Message deserialization failed.\n\nArgs:\n    reason: What went wrong during deserialization."
        },
        {
          "name": "CommDeserializationError.__init__",
          "line": 37,
          "signature": "def __init__(self, reason: str) -> None",
          "documentation": ""
        },
        {
          "name": "CommTransportError",
          "line": 42,
          "signature": "class CommTransportError(CommError)",
          "documentation": "Transport-level communication failed.\n\nArgs:\n    reason: What went wrong with the transport."
        },
        {
          "name": "CommTransportError.__init__",
          "line": 49,
          "signature": "def __init__(self, reason: str) -> None",
          "documentation": ""
        },
        {
          "name": "CommNotConnectedError",
          "line": 54,
          "signature": "class CommNotConnectedError(CommError)",
          "documentation": "The transport is not connected.\n\nANVIL Spec section 10.3 -- Transport Contract."
        },
        {
          "name": "CommNotConnectedError.__init__",
          "line": 60,
          "signature": "def __init__(self) -> None",
          "documentation": ""
        },
        {
          "name": "CommChannelClosedError",
          "line": 67,
          "signature": "class CommChannelClosedError(CommError)",
          "documentation": "The communication channel has been closed.\n\nArgs:\n    reason: Why the channel was closed."
        },
        {
          "name": "CommChannelClosedError.__init__",
          "line": 74,
          "signature": "def __init__(self, reason: str='channel closed') -> None",
          "documentation": ""
        },
        {
          "name": "CommSignatureInvalidError",
          "line": 79,
          "signature": "class CommSignatureInvalidError(CommError)",
          "documentation": "Message signature verification failed.\n\nANVIL Spec section 10.4 -- Message Integrity.\n\nArgs:\n    message_id: The ID of the message with the invalid signature."
        },
        {
          "name": "CommSignatureInvalidError.__init__",
          "line": 88,
          "signature": "def __init__(self, message_id: str) -> None",
          "documentation": ""
        },
        {
          "name": "CommProtocolNegotiationError",
          "line": 96,
          "signature": "class CommProtocolNegotiationError(CommError)",
          "documentation": "Protocol negotiation failed.\n\nANVIL Spec section 10.5 -- Protocol Negotiation.\n\nArgs:\n    reason: Why negotiation failed."
        },
        {
          "name": "CommProtocolNegotiationError.__init__",
          "line": 105,
          "signature": "def __init__(self, reason: str) -> None",
          "documentation": ""
        },
        {
          "name": "CommMessageTooLargeError",
          "line": 113,
          "signature": "class CommMessageTooLargeError(CommError)",
          "documentation": "Message exceeds the maximum permitted size.\n\nArgs:\n    size: The actual message size in bytes.\n    max_size: The maximum permitted size in bytes."
        },
        {
          "name": "CommMessageTooLargeError.__init__",
          "line": 121,
          "signature": "def __init__(self, size: int, max_size: int) -> None",
          "documentation": ""
        },
        {
          "name": "CommTimeoutError",
          "line": 129,
          "signature": "class CommTimeoutError(CommError)",
          "documentation": "A communication operation timed out.\n\nArgs:\n    operation: The operation that timed out.\n    timeout_seconds: The timeout duration in seconds."
        },
        {
          "name": "CommTimeoutError.__init__",
          "line": 137,
          "signature": "def __init__(self, operation: str, timeout_seconds: float) -> None",
          "documentation": ""
        }
      ]
    },
    {
      "path": "forge-py/src/forge/comm/message.py",
      "sha256": "52be33fb24fe57790d06f4a306c09e7a04b29976e51362df5f28888499535590",
      "artifactSha256": "9fdace0b49b4dc1b45d3fd49c5741f98efa020c7e2099d978298af504df2bc0a",
      "url": "/reference/source/forge-py/src/forge/comm/message.py.txt",
      "declarations": [
        {
          "name": "AgentMessage",
          "line": 23,
          "signature": "class AgentMessage()",
          "documentation": "An agent message envelope per ANVIL Spec section 10.2.\n\nThe AgentMessage is the fundamental unit of inter-agent communication.\nIt wraps a JSON payload with routing metadata (sender/recipient DIDs),\nprotocol identification, correlation tracking, and an optional\ncryptographic signature for integrity verification.\n\nANVIL Spec section 10.2 -- Agent Message Envelope.\n\nArgs:\n    sender: Sender's OAS DID.\n    recipient: Recipient's OAS DID.\n    protocol: Protocol identifier (e.g., \"anvil.task.v1\").\n    message_type: Message type within the protocol (e.g., \"request\").\n    payload: Arbitrary JSON-serializable payload.\n\nExample:\n    >>> msg = AgentMessage.new(\n    ...     \"did:oas:l1fe:agent:sender\",\n    ...     \"did:oas:l1fe:agent:receiver\",\n    ...     \"anvil.task.v1\",\n    ...     \"request\",\n    ...     {\"task\": \"analyze\"},\n    ... )\n    >>> msg.sender\n    'did:oas:l1fe:agent:sender'\n    >>> msg.is_signed()\n    False"
        },
        {
          "name": "AgentMessage.new",
          "line": 66,
          "signature": "def new(sender: str, recipient: str, protocol: str, message_type: str, payload: Any) -> AgentMessage",
          "documentation": "Create a new AgentMessage with a generated UUID and current timestamp.\n\nANVIL Spec section 10.2 -- Agent Message Envelope.\n\nArgs:\n    sender: The sender's OAS DID string.\n    recipient: The recipient's OAS DID string.\n    protocol: The protocol identifier (e.g., \"anvil.task.v1\").\n    message_type: The message type within the protocol.\n    payload: The JSON payload body.\n\nReturns:\n    A new AgentMessage with a UUID v4 id and the current UTC timestamp."
        },
        {
          "name": "AgentMessage.kind",
          "line": 97,
          "signature": "def kind(self) -> str",
          "documentation": "Return the message type.\n\nReturns:\n    The message type string."
        },
        {
          "name": "AgentMessage.is_signed",
          "line": 105,
          "signature": "def is_signed(self) -> bool",
          "documentation": "Return whether this message has an Ed25519 signature.\n\nANVIL Spec section 10.4 -- Message Integrity.\n\nReturns:\n    True if the signature field is set, False otherwise."
        },
        {
          "name": "AgentMessage.with_correlation_id",
          "line": 115,
          "signature": "def with_correlation_id(self, correlation_id: str) -> AgentMessage",
          "documentation": "Set the correlation ID.\n\nArgs:\n    correlation_id: The correlation ID string.\n\nReturns:\n    Self for chaining."
        },
        {
          "name": "AgentMessage.with_reply_to",
          "line": 127,
          "signature": "def with_reply_to(self, reply_to: str) -> AgentMessage",
          "documentation": "Set the reply-to message ID.\n\nArgs:\n    reply_to: The ID of the message this is a reply to.\n\nReturns:\n    Self for chaining."
        },
        {
          "name": "AgentMessage.to_dict",
          "line": 139,
          "signature": "def to_dict(self) -> dict[str, Any]",
          "documentation": "Serialize to a dictionary.\n\nReturns:\n    Dictionary representation."
        },
        {
          "name": "AgentMessage.from_dict",
          "line": 163,
          "signature": "def from_dict(data: dict[str, Any]) -> AgentMessage",
          "documentation": "Deserialize from a dictionary.\n\nArgs:\n    data: Dictionary representation.\n\nReturns:\n    The deserialized AgentMessage."
        },
        {
          "name": "AgentMessage.to_json",
          "line": 185,
          "signature": "def to_json(self) -> str",
          "documentation": "Serialize to JSON string."
        },
        {
          "name": "AgentMessage.from_json",
          "line": 190,
          "signature": "def from_json(data: str) -> AgentMessage",
          "documentation": "Deserialize from JSON string."
        }
      ]
    },
    {
      "path": "forge-py/src/forge/comm/noop.py",
      "sha256": "ce09540eff2d669ae7f22de05cf6390804620333f2233c397a8b1027e076d970",
      "artifactSha256": "2a5a27b50995c24b6b514ca7280b322520a9685fc9c4a54515c9a853c0a6d2a0",
      "url": "/reference/source/forge-py/src/forge/comm/noop.py.txt",
      "declarations": [
        {
          "name": "NoopTransport",
          "line": 15,
          "signature": "class NoopTransport()",
          "documentation": "No-op transport that discards all sent messages.\n\nSending always succeeds silently; receiving always raises\nCommNotConnectedError because there is no underlying connection.\n\nANVIL Spec section 10.3 -- Transport Contract (default implementation).\n\nExample:\n    >>> import asyncio\n    >>> transport = NoopTransport()\n    >>> msg = AgentMessage.new(\n    ...     \"did:oas:l1fe:agent:a\",\n    ...     \"did:oas:l1fe:agent:b\",\n    ...     \"anvil.task.v1\",\n    ...     \"request\",\n    ...     {},\n    ... )\n    >>> asyncio.run(transport.send(msg))  # Silently succeeds"
        },
        {
          "name": "NoopTransport.send",
          "line": 36,
          "signature": "async def send(self, message: AgentMessage) -> None",
          "documentation": "Discard the message silently.\n\nArgs:\n    message: The message to discard."
        },
        {
          "name": "NoopTransport.receive",
          "line": 43,
          "signature": "async def receive(self) -> AgentMessage",
          "documentation": "Always raises CommNotConnectedError.\n\nReturns:\n    Never returns; always raises.\n\nRaises:\n    CommNotConnectedError: Always raised because noop transport\n        has no underlying connection."
        }
      ]
    },
    {
      "path": "forge-py/src/forge/comm/protocol.py",
      "sha256": "16c866ebd6ff3a0e2050d88576f43a95e40e580a7712bdf6ff861170a7ff4550",
      "artifactSha256": "1bbad76b53108dd58cfaa1df9def897acee039cddfadd29d1dad9829563dd2a2",
      "url": "/reference/source/forge-py/src/forge/comm/protocol.py.txt",
      "declarations": [
        {
          "name": "ProtocolOffer",
          "line": 18,
          "signature": "class ProtocolOffer()",
          "documentation": "A protocol negotiation offer.\n\nSent by the initiating agent to propose a set of protocols and versions\nit supports.\n\nANVIL Spec section 10.5 -- Protocol Negotiation.\n\nArgs:\n    protocol: The protocol name (e.g., \"anvil.task\").\n    versions: Supported versions, sorted ascending.\n\nExample:\n    >>> offer = ProtocolOffer(protocol=\"anvil.task\", versions=[1, 2, 3])\n    >>> offer.protocol\n    'anvil.task'"
        },
        {
          "name": "ProtocolAccept",
          "line": 41,
          "signature": "class ProtocolAccept()",
          "documentation": "A protocol negotiation acceptance.\n\nSent by the responding agent to confirm the selected protocol and version.\n\nANVIL Spec section 10.5 -- Protocol Negotiation.\n\nArgs:\n    protocol: The agreed-upon protocol name.\n    version: The selected version.\n\nExample:\n    >>> accept = ProtocolAccept(protocol=\"anvil.task\", version=2)\n    >>> accept.version\n    2"
        },
        {
          "name": "negotiate_protocol",
          "line": 62,
          "signature": "def negotiate_protocol(offer: ProtocolOffer, supported_versions: list[int]) -> ProtocolAccept",
          "documentation": "Negotiate a protocol version from an offer and supported versions.\n\nSelects the highest version that both sides support.\n\nANVIL Spec section 10.5 -- Protocol Negotiation.\n\nArgs:\n    offer: The protocol offer from the initiating agent.\n    supported_versions: The versions supported by the responding agent.\n\nReturns:\n    A ProtocolAccept with the highest common version.\n\nRaises:\n    CommProtocolNegotiationError: If no common version exists.\n\nExample:\n    >>> offer = ProtocolOffer(protocol=\"anvil.task\", versions=[1, 2, 3])\n    >>> accept = negotiate_protocol(offer, [2, 3, 4])\n    >>> accept.version\n    3"
        }
      ]
    },
    {
      "path": "forge-py/src/forge/comm/transport.py",
      "sha256": "aa30ccae8e5e7dc5495ca50fd136bd8dd6630a095abbd8bf537b87a5facab874",
      "artifactSha256": "5f2922f948642c1fb2b62e6088845beeeac5bb51fb88984a08a71179d945e90d",
      "url": "/reference/source/forge-py/src/forge/comm/transport.py.txt",
      "declarations": [
        {
          "name": "MessageTransport",
          "line": 16,
          "signature": "class MessageTransport(Protocol)",
          "documentation": "Async message transport contract.\n\nImplementations provide the send/receive mechanism for inter-agent\ncommunication. The transport is agnostic to the message content and\nprotocol -- it only moves AgentMessage envelopes between endpoints.\n\nANVIL Spec section 10.3 -- Transport Contract."
        },
        {
          "name": "MessageTransport.send",
          "line": 26,
          "signature": "async def send(self, message: AgentMessage) -> None",
          "documentation": "Send a message to the recipient.\n\nANVIL Spec section 10.3 -- Transport Contract: send.\n\nArgs:\n    message: The message to send.\n\nRaises:\n    CommTransportError: If the send operation fails.\n    CommNotConnectedError: If the transport is not connected."
        },
        {
          "name": "MessageTransport.receive",
          "line": 40,
          "signature": "async def receive(self) -> AgentMessage",
          "documentation": "Receive the next message.\n\nBlocks until a message is available or an error occurs.\n\nANVIL Spec section 10.3 -- Transport Contract: receive.\n\nReturns:\n    The next AgentMessage in the receive queue.\n\nRaises:\n    CommNotConnectedError: If the transport is not connected.\n    CommChannelClosedError: If the channel has been closed."
        }
      ]
    }
  ]
}