From 9c8877ed664e3ec7bb3896030f4cf0dfbf38558e Mon Sep 17 00:00:00 2001 From: peterychang <49209570+peterychang@users.noreply.github.com> Date: Mon, 23 Dec 2024 17:06:56 -0500 Subject: [PATCH] Add API documentation (#4798) * Add API documentation * Update python/packages/autogen-core/src/autogen_core/_cancellation_token.py Co-authored-by: Eric Zhu --------- Co-authored-by: Eric Zhu --- .../agent-identity-and-lifecycle.md | 1 + .../core-concepts/topic-and-subscription.md | 1 + .../autogen-core/src/autogen_core/_agent_id.py | 17 +++++++++++++++++ .../src/autogen_core/_agent_proxy.py | 2 ++ .../src/autogen_core/_cancellation_token.py | 6 ++++++ .../autogen-core/src/autogen_core/_topic.py | 7 +++++++ 6 files changed, 34 insertions(+) diff --git a/python/packages/autogen-core/docs/src/user-guide/core-user-guide/core-concepts/agent-identity-and-lifecycle.md b/python/packages/autogen-core/docs/src/user-guide/core-user-guide/core-concepts/agent-identity-and-lifecycle.md index 4a4439500..0dae41e78 100644 --- a/python/packages/autogen-core/docs/src/user-guide/core-user-guide/core-concepts/agent-identity-and-lifecycle.md +++ b/python/packages/autogen-core/docs/src/user-guide/core-user-guide/core-concepts/agent-identity-and-lifecycle.md @@ -1,3 +1,4 @@ +(agentid_and_lifecycle)= # Agent Identity and Lifecycle The agent runtime manages agents' identities diff --git a/python/packages/autogen-core/docs/src/user-guide/core-user-guide/core-concepts/topic-and-subscription.md b/python/packages/autogen-core/docs/src/user-guide/core-user-guide/core-concepts/topic-and-subscription.md index 340ad96b8..7af198f00 100644 --- a/python/packages/autogen-core/docs/src/user-guide/core-user-guide/core-concepts/topic-and-subscription.md +++ b/python/packages/autogen-core/docs/src/user-guide/core-user-guide/core-concepts/topic-and-subscription.md @@ -12,6 +12,7 @@ will handle their messages, and a workflow can be composed of agents with no inter-dependencies. This section focuses on the core concepts in broadcast: topic and subscription. +(topic_and_subscription_topic)= ## Topic A topic defines the scope of a broadcast message. diff --git a/python/packages/autogen-core/src/autogen_core/_agent_id.py b/python/packages/autogen-core/src/autogen_core/_agent_id.py index 9aae843eb..de046592c 100644 --- a/python/packages/autogen-core/src/autogen_core/_agent_id.py +++ b/python/packages/autogen-core/src/autogen_core/_agent_id.py @@ -10,6 +10,12 @@ def is_valid_agent_type(value: str) -> bool: class AgentId: + """ + Agent ID uniquely identifies an agent instance within an agent runtime - including distributed runtime. It is the 'address' of the agent instance for receiving messages. + + See here for more information: :ref:`agentid_and_lifecycle` + """ + def __init__(self, type: str | AgentType, key: str) -> None: if isinstance(type, AgentType): type = type.type @@ -36,6 +42,7 @@ class AgentId: @classmethod def from_str(cls, agent_id: str) -> Self: + """Convert a string of the format ``type/key`` into an AgentId""" items = agent_id.split("/", maxsplit=1) if len(items) != 2: raise ValueError(f"Invalid agent id: {agent_id}") @@ -44,8 +51,18 @@ class AgentId: @property def type(self) -> str: + """ + An identifier that associates an agent with a specific factory function. + + Strings may only be composed of alphanumeric letters (a-z) and (0-9), or underscores (_). + """ return self._type @property def key(self) -> str: + """ + Agent instance identifier. + + Strings may only be composed of alphanumeric letters (a-z) and (0-9), or underscores (_). + """ return self._key diff --git a/python/packages/autogen-core/src/autogen_core/_agent_proxy.py b/python/packages/autogen-core/src/autogen_core/_agent_proxy.py index f3eb70f28..09cf3c1de 100644 --- a/python/packages/autogen-core/src/autogen_core/_agent_proxy.py +++ b/python/packages/autogen-core/src/autogen_core/_agent_proxy.py @@ -11,6 +11,8 @@ if TYPE_CHECKING: class AgentProxy: + """A helper class that allows you to use an :class:`~autogen_core.AgentId` in place of its associated :class:`~autogen_core.Agent`""" + def __init__(self, agent: AgentId, runtime: AgentRuntime): self._agent = agent self._runtime = runtime diff --git a/python/packages/autogen-core/src/autogen_core/_cancellation_token.py b/python/packages/autogen-core/src/autogen_core/_cancellation_token.py index 5aa449039..06e037e53 100644 --- a/python/packages/autogen-core/src/autogen_core/_cancellation_token.py +++ b/python/packages/autogen-core/src/autogen_core/_cancellation_token.py @@ -4,12 +4,15 @@ from typing import Any, Callable, List class CancellationToken: + """A token used to cancel pending async calls""" + def __init__(self) -> None: self._cancelled: bool = False self._lock: threading.Lock = threading.Lock() self._callbacks: List[Callable[[], None]] = [] def cancel(self) -> None: + """Cancel pending async calls linked to this cancellation token.""" with self._lock: if not self._cancelled: self._cancelled = True @@ -17,10 +20,12 @@ class CancellationToken: callback() def is_cancelled(self) -> bool: + """Check if the CancellationToken has been used""" with self._lock: return self._cancelled def add_callback(self, callback: Callable[[], None]) -> None: + """Attach a callback that will be called when cancel is invoked""" with self._lock: if self._cancelled: callback() @@ -28,6 +33,7 @@ class CancellationToken: self._callbacks.append(callback) def link_future(self, future: Future[Any]) -> Future[Any]: + """Link a pending async call to a token to allow its cancellation""" with self._lock: if self._cancelled: future.cancel() diff --git a/python/packages/autogen-core/src/autogen_core/_topic.py b/python/packages/autogen-core/src/autogen_core/_topic.py index c8965a7da..67d4a246f 100644 --- a/python/packages/autogen-core/src/autogen_core/_topic.py +++ b/python/packages/autogen-core/src/autogen_core/_topic.py @@ -10,6 +10,12 @@ def is_valid_topic_type(value: str) -> bool: @dataclass(eq=True, frozen=True) class TopicId: + """ + TopicId defines the scope of a broadcast message. In essence, agent runtime implements a publish-subscribe model through its broadcast API: when publishing a message, the topic must be specified. + + See here for more information: :ref:`topic_and_subscription_topic` + """ + type: str """Type of the event that this topic_id contains. Adhere's to the cloud event spec. @@ -33,6 +39,7 @@ class TopicId: @classmethod def from_str(cls, topic_id: str) -> Self: + """Convert a string of the format ``type/source`` into a TopicId""" items = topic_id.split("/", maxsplit=1) if len(items) != 2: raise ValueError(f"Invalid topic id: {topic_id}")