A programming framework for agentic AI
fix some docstring issues affecting rendering (#1739)
Jack Gerritsd8a204a9a3a3
diff --git a/autogen/agentchat/contrib/compressible_agent.py b/autogen/agentchat/contrib/compressible_agent.pyindex f9ea6bd26..e196773ef 100644--- a/autogen/agentchat/contrib/compressible_agent.py+++ b/autogen/agentchat/contrib/compressible_agent.py@@ -84,10 +84,9 @@ Reply "TERMINATE" in the end when everything is done.compress_config (dict or True/False): config for compression before oai_reply. Default to False.You should contain the following keys:- "mode" (Optional, str, default to "TERMINATE"): Choose from ["COMPRESS", "TERMINATE", "CUSTOMIZED"].- "TERMINATE": terminate the conversation ONLY when token count exceeds the max limit of current model.- `trigger_count` is NOT used in this mode.- "COMPRESS": compress the messages when the token count exceeds the limit.- "CUSTOMIZED": pass in a customized function to compress the messages.+ 1. `TERMINATE`: terminate the conversation ONLY when token count exceeds the max limit of current model. `trigger_count` is NOT used in this mode.+ 2. `COMPRESS`: compress the messages when the token count exceeds the limit.+ 3. `CUSTOMIZED`: pass in a customized function to compress the messages.- "compress_function" (Optional, callable, default to None): Must be provided when mode is "CUSTOMIZED".The function should takes a list of messages and returns a tuple of (is_compress_success: bool, compressed_messages: List[Dict]).- "trigger_count" (Optional, float, int, default to 0.7): the threshold to trigger compression.diff --git a/autogen/agentchat/contrib/qdrant_retrieve_user_proxy_agent.py b/autogen/agentchat/contrib/qdrant_retrieve_user_proxy_agent.pyindex 1efeb3c19..01b513623 100644--- a/autogen/agentchat/contrib/qdrant_retrieve_user_proxy_agent.py+++ b/autogen/agentchat/contrib/qdrant_retrieve_user_proxy_agent.py@@ -29,12 +29,12 @@ class QdrantRetrieveUserProxyAgent(RetrieveUserProxyAgent):name (str): name of the agent.human_input_mode (str): whether to ask for human inputs every time a message is received.Possible values are "ALWAYS", "TERMINATE", "NEVER".- (1) When "ALWAYS", the agent prompts for human input every time a message is received.+ 1. When "ALWAYS", the agent prompts for human input every time a message is received.Under this mode, the conversation stops when the human input is "exit",or when is_termination_msg is True and there is no human input.- (2) When "TERMINATE", the agent only prompts for human input only when a termination message is received or+ 2. When "TERMINATE", the agent only prompts for human input only when a termination message is received orthe number of auto reply reaches the max_consecutive_auto_reply.- (3) When "NEVER", the agent will never prompt for human input. Under this mode, the conversation stops+ 3. When "NEVER", the agent will never prompt for human input. Under this mode, the conversation stopswhen the number of auto reply reaches the max_consecutive_auto_reply or when is_termination_msg is True.is_termination_msg (function): a function that takes a message in the form of a dictionaryand returns a boolean value indicating if this received message is a termination message.diff --git a/autogen/agentchat/contrib/retrieve_user_proxy_agent.py b/autogen/agentchat/contrib/retrieve_user_proxy_agent.pyindex 949afcc96..facb64d07 100644--- a/autogen/agentchat/contrib/retrieve_user_proxy_agent.py+++ b/autogen/agentchat/contrib/retrieve_user_proxy_agent.py@@ -77,17 +77,17 @@ class RetrieveUserProxyAgent(UserProxyAgent):retrieve_config: Optional[Dict] = None, # config for the retrieve agent**kwargs,):- """+ r"""Args:name (str): name of the agent.human_input_mode (str): whether to ask for human inputs every time a message is received.Possible values are "ALWAYS", "TERMINATE", "NEVER".- (1) When "ALWAYS", the agent prompts for human input every time a message is received.+ 1. When "ALWAYS", the agent prompts for human input every time a message is received.Under this mode, the conversation stops when the human input is "exit",or when is_termination_msg is True and there is no human input.- (2) When "TERMINATE", the agent only prompts for human input only when a termination message is received or+ 2. When "TERMINATE", the agent only prompts for human input only when a termination message is received orthe number of auto reply reaches the max_consecutive_auto_reply.- (3) When "NEVER", the agent will never prompt for human input. Under this mode, the conversation stops+ 3. When "NEVER", the agent will never prompt for human input. Under this mode, the conversation stopswhen the number of auto reply reaches the max_consecutive_auto_reply or when is_termination_msg is True.is_termination_msg (function): a function that takes a message in the form of a dictionaryand returns a boolean value indicating if this received message is a termination message.@@ -136,10 +136,11 @@ class RetrieveUserProxyAgent(UserProxyAgent):- custom_text_types (Optional, List[str]): a list of file types to be processed. Default is `autogen.retrieve_utils.TEXT_FORMATS`.This only applies to files under the directories in `docs_path`. Explicitly included files and urls will be chunked regardless of their types.- recursive (Optional, bool): whether to search documents recursively in the docs_path. Default is True.- **kwargs (dict): other kwargs in [UserProxyAgent](../user_proxy_agent#__init__).+ `**kwargs` (dict): other kwargs in [UserProxyAgent](../user_proxy_agent#__init__).++ Example:- Example of overriding retrieve_docs:- If you have set up a customized vector db, and it's not compatible with chromadb, you can easily plug in it with below code.+ Example of overriding retrieve_docs - If you have set up a customized vector db, and it's not compatible with chromadb, you can easily plug in it with below code.```pythonclass MyRetrieveUserProxyAgent(RetrieveUserProxyAgent):def query_vector_db(diff --git a/autogen/agentchat/utils.py b/autogen/agentchat/utils.pyindex 27c550739..07982d037 100644--- a/autogen/agentchat/utils.py+++ b/autogen/agentchat/utils.py@@ -25,7 +25,7 @@ def consolidate_chat_info(chat_info, uniform_sender=None) -> None:def gather_usage_summary(agents: List[Agent]) -> Tuple[Dict[str, any], Dict[str, any]]:- """Gather usage summary from all agents.+ r"""Gather usage summary from all agents.Args:agents: (list): List of agents.@@ -33,19 +33,24 @@ def gather_usage_summary(agents: List[Agent]) -> Tuple[Dict[str, any], Dict[str,Returns:tuple: (total_usage_summary, actual_usage_summary)- Example return:- total_usage_summary = {- 'total_cost': 0.0006090000000000001,- 'gpt-35-turbo':- {- 'cost': 0.0006090000000000001,- 'prompt_tokens': 242,- 'completion_tokens': 123,- 'total_tokens': 365- }+ Example:++ ```python+ total_usage_summary = {+ "total_cost": 0.0006090000000000001,+ "gpt-35-turbo": {+ "cost": 0.0006090000000000001,+ "prompt_tokens": 242,+ "completion_tokens": 123,+ "total_tokens": 365}- `actual_usage_summary` follows the same format.- If none of the agents incurred any cost (not having a client), then the total_usage_summary and actual_usage_summary will be {'total_cost': 0}.+ }+ ```++ Note:++ `actual_usage_summary` follows the same format.+ If none of the agents incurred any cost (not having a client), then the total_usage_summary and actual_usage_summary will be `{'total_cost': 0}`."""def aggregate_summary(usage_summary: Dict[str, any], agent_summary: Dict[str, any]) -> None:diff --git a/autogen/cache/cache.py b/autogen/cache/cache.pyindex d20aadef9..9fd7f7fbe 100644--- a/autogen/cache/cache.py+++ b/autogen/cache/cache.py@@ -14,16 +14,6 @@ class Cache:Attributes:config (Dict[str, Any]): A dictionary containing cache configuration.cache: The cache instance created based on the provided configuration.-- Methods:- redis(cache_seed=42, redis_url="redis://localhost:6379/0"): Static method to create a Redis cache instance.- disk(cache_seed=42, cache_path_root=".cache"): Static method to create a Disk cache instance.- __init__(self, config): Initializes the Cache with the given configuration.- __enter__(self): Context management entry, returning the cache instance.- __exit__(self, exc_type, exc_value, traceback): Context management exit.- get(self, key, default=None): Retrieves an item from the cache.- set(self, key, value): Sets an item in the cache.- close(self): Closes the cache."""ALLOWED_CONFIG_KEYS = ["cache_seed", "redis_url", "cache_path_root"]diff --git a/autogen/cache/cache_factory.py b/autogen/cache/cache_factory.pyindex 3917fa2da..6f386abdb 100644--- a/autogen/cache/cache_factory.py+++ b/autogen/cache/cache_factory.py@@ -28,11 +28,17 @@ class CacheFactory:and the provided redis_url.Examples:- Creating a Redis cache- > redis_cache = cache_factory("myseed", "redis://localhost:6379/0")- Creating a Disk cache- > disk_cache = cache_factory("myseed", None)+ Creating a Redis cache++ ```python+ redis_cache = cache_factory("myseed", "redis://localhost:6379/0")+ ```+ Creating a Disk cache++ ```python+ disk_cache = cache_factory("myseed", None)+ ```"""if RedisCache is not None and redis_url is not None:return RedisCache(seed, redis_url)diff --git a/autogen/function_utils.py b/autogen/function_utils.pyindex efb50060b..0189836a4 100644--- a/autogen/function_utils.py+++ b/autogen/function_utils.py@@ -225,21 +225,22 @@ def get_function_schema(f: Callable[..., Any], *, name: Optional[str] = None, deTypeError: If the function is not annotatedExamples:- ```- def f(a: Annotated[str, "Parameter a"], b: int = 2, c: Annotated[float, "Parameter c"] = 0.1) -> None:- pass-- get_function_schema(f, description="function f")-- # {'type': 'function',- # 'function': {'description': 'function f',- # 'name': 'f',- # 'parameters': {'type': 'object',- # 'properties': {'a': {'type': 'str', 'description': 'Parameter a'},- # 'b': {'type': 'int', 'description': 'b'},- # 'c': {'type': 'float', 'description': 'Parameter c'}},- # 'required': ['a']}}}- ```++ ```python+ def f(a: Annotated[str, "Parameter a"], b: int = 2, c: Annotated[float, "Parameter c"] = 0.1) -> None:+ pass++ get_function_schema(f, description="function f")++ # {'type': 'function',+ # 'function': {'description': 'function f',+ # 'name': 'f',+ # 'parameters': {'type': 'object',+ # 'properties': {'a': {'type': 'str', 'description': 'Parameter a'},+ # 'b': {'type': 'int', 'description': 'b'},+ # 'c': {'type': 'float', 'description': 'Parameter c'}},+ # 'required': ['a']}}}+ ```"""typed_signature = get_typed_signature(f)diff --git a/autogen/oai/openai_utils.py b/autogen/oai/openai_utils.pyindex 70ae22812..e1f0c15a5 100644--- a/autogen/oai/openai_utils.py+++ b/autogen/oai/openai_utils.py@@ -103,7 +103,7 @@ def get_config_list(list: A list of configs for OepnAI API calls.Example:- ```+ ```python# Define a list of API keysapi_keys = ['key1', 'key2', 'key3']@@ -292,32 +292,32 @@ def config_list_from_models(list: A list of configs for OpenAI API calls, each including model information.Example:- ```- # Define the path where the API key files are located- key_file_path = '/path/to/key/files'-- # Define the file names for the OpenAI and Azure OpenAI API keys and bases- openai_api_key_file = 'key_openai.txt'- aoai_api_key_file = 'key_aoai.txt'- aoai_api_base_file = 'base_aoai.txt'-- # Define the list of models for which to create configurations- model_list = ['gpt-4', 'gpt-3.5-turbo']-- # Call the function to get a list of configuration dictionaries- config_list = config_list_from_models(- key_file_path=key_file_path,- openai_api_key_file=openai_api_key_file,- aoai_api_key_file=aoai_api_key_file,- aoai_api_base_file=aoai_api_base_file,- model_list=model_list- )+ ```python+ # Define the path where the API key files are located+ key_file_path = '/path/to/key/files'++ # Define the file names for the OpenAI and Azure OpenAI API keys and bases+ openai_api_key_file = 'key_openai.txt'+ aoai_api_key_file = 'key_aoai.txt'+ aoai_api_base_file = 'base_aoai.txt'++ # Define the list of models for which to create configurations+ model_list = ['gpt-4', 'gpt-3.5-turbo']++ # Call the function to get a list of configuration dictionaries+ config_list = config_list_from_models(+ key_file_path=key_file_path,+ openai_api_key_file=openai_api_key_file,+ aoai_api_key_file=aoai_api_key_file,+ aoai_api_base_file=aoai_api_base_file,+ model_list=model_list+ )- # The `config_list` will contain configurations for the specified models, for example:- # [- # {'api_key': '...', 'base_url': 'https://api.openai.com', 'model': 'gpt-4'},- # {'api_key': '...', 'base_url': 'https://api.openai.com', 'model': 'gpt-3.5-turbo'}- # ]+ # The `config_list` will contain configurations for the specified models, for example:+ # [+ # {'api_key': '...', 'base_url': 'https://api.openai.com', 'model': 'gpt-4'},+ # {'api_key': '...', 'base_url': 'https://api.openai.com', 'model': 'gpt-3.5-turbo'}+ # ]```"""config_list = config_list_openai_aoai(@@ -383,40 +383,39 @@ def filter_config(config_list, filter_dict):in `filter_dict`.Example:- ```- # Example configuration list with various models and API types- configs = [- {'model': 'gpt-3.5-turbo'},- {'model': 'gpt-4'},- {'model': 'gpt-3.5-turbo', 'api_type': 'azure'},- {'model': 'gpt-3.5-turbo', 'tags': ['gpt35_turbo', 'gpt-35-turbo']},- ]-- # Define filter criteria to select configurations for the 'gpt-3.5-turbo' model- # that are also using the 'azure' API type- filter_criteria = {- 'model': ['gpt-3.5-turbo'], # Only accept configurations for 'gpt-3.5-turbo'- 'api_type': ['azure'] # Only accept configurations for 'azure' API type- }-- # Apply the filter to the configuration list- filtered_configs = filter_config(configs, filter_criteria)-- # The resulting `filtered_configs` will be:- # [{'model': 'gpt-3.5-turbo', 'api_type': 'azure', ...}]--- # Define a filter to select a given tag- filter_criteria = {- 'tags': ['gpt35_turbo'],- }-- # Apply the filter to the configuration list- filtered_configs = filter_config(configs, filter_criteria)-- # The resulting `filtered_configs` will be:- # [{'model': 'gpt-3.5-turbo', 'tags': ['gpt35_turbo', 'gpt-35-turbo']}]-+ ```python+ # Example configuration list with various models and API types+ configs = [+ {'model': 'gpt-3.5-turbo'},+ {'model': 'gpt-4'},+ {'model': 'gpt-3.5-turbo', 'api_type': 'azure'},+ {'model': 'gpt-3.5-turbo', 'tags': ['gpt35_turbo', 'gpt-35-turbo']},+ ]++ # Define filter criteria to select configurations for the 'gpt-3.5-turbo' model+ # that are also using the 'azure' API type+ filter_criteria = {+ 'model': ['gpt-3.5-turbo'], # Only accept configurations for 'gpt-3.5-turbo'+ 'api_type': ['azure'] # Only accept configurations for 'azure' API type+ }++ # Apply the filter to the configuration list+ filtered_configs = filter_config(configs, filter_criteria)++ # The resulting `filtered_configs` will be:+ # [{'model': 'gpt-3.5-turbo', 'api_type': 'azure', ...}]+++ # Define a filter to select a given tag+ filter_criteria = {+ 'tags': ['gpt35_turbo'],+ }++ # Apply the filter to the configuration list+ filtered_configs = filter_config(configs, filter_criteria)++ # The resulting `filtered_configs` will be:+ # [{'model': 'gpt-3.5-turbo', 'tags': ['gpt35_turbo', 'gpt-35-turbo']}]```Note:@@ -467,7 +466,7 @@ def config_list_from_json(keys representing field names and values being lists or sets of acceptable values for those fields.Example:- ```+ ```python# Suppose we have an environment variable 'CONFIG_JSON' with the following content:# '[{"model": "gpt-3.5-turbo", "api_type": "azure"}, {"model": "gpt-4"}]'@@ -511,7 +510,7 @@ def get_config(Constructs a configuration dictionary for a single model with the provided API configurations.Example:- ```+ ```pythonconfig = get_config(api_key="sk-abcdef1234567890",base_url="https://api.openai.com",diff --git a/autogen/retrieve_utils.py b/autogen/retrieve_utils.pyindex 31467b07c..c3e50c7a9 100644--- a/autogen/retrieve_utils.py+++ b/autogen/retrieve_utils.py@@ -276,8 +276,10 @@ def create_vector_db_from_dir(custom_text_types (Optional, List[str]): a list of file types to be processed. Default is TEXT_FORMATS.recursive (Optional, bool): whether to search documents recursively in the dir_path. Default is True.extra_docs (Optional, bool): whether to add more documents in the collection. Default is False+Returns:- API: the chromadb client.++ The chromadb client."""if client is None:client = chromadb.PersistentClient(path=db_path)@@ -353,13 +355,17 @@ def query_vector_db(functions, you can pass it here, follow the examples in `https://docs.trychroma.com/embeddings`.Returns:- QueryResult: the query result. The format is:- class QueryResult(TypedDict):- ids: List[IDs]- embeddings: Optional[List[List[Embedding]]]- documents: Optional[List[List[Document]]]- metadatas: Optional[List[List[Metadata]]]- distances: Optional[List[List[float]]]++ The query result. The format is:++ ```python+ class QueryResult(TypedDict):+ ids: List[IDs]+ embeddings: Optional[List[List[Embedding]]]+ documents: Optional[List[List[Document]]]+ metadatas: Optional[List[List[Metadata]]]+ distances: Optional[List[List[float]]]+ ```"""if client is None:client = chromadb.PersistentClient(path=db_path)diff --git a/website/pydoc-markdown.yml b/website/pydoc-markdown.ymlindex 6f854d9ad..d943b9ef4 100644--- a/website/pydoc-markdown.yml+++ b/website/pydoc-markdown.yml@@ -4,8 +4,7 @@ loaders:processors:- type: filterskip_empty_modules: true- - type: smart- - type: crossref+ - type: googlerenderer:type: docusaurusdocs_base_path: docs@@ -13,4 +12,11 @@ renderer:relative_sidebar_path: sidebar.jsonsidebar_top_level_label: Referencemarkdown:- escape_html_in_docstring: true+ escape_html_in_docstring: false+ descriptive_class_title: false+ header_level_by_type:+ Module: 1+ Class: 2+ Method: 3+ Function: 3+ Variable: 4