Update docs

automata/cli/options.py

@@ -64,6 +64,12 @@ def agent_options(command: click.Command, *args, **kwargs) -> click.Command:
             default="gpt-4-0613",
             help="Which model to use?",
         ),
+        click.option(
+            "--max_iterations",
+            default=None,
+            help="How many iterations can we use?",
+            type=int,
+        ),
         click.option(
             "--config-to-load",
             default="automata-main",

automata/cli/scripts/run_agent.py

@@ -61,14 +61,17 @@ def main(*args, **kwargs):
     tools = AgentToolFactory.build_tools(toolkit_list, **tool_dependencies)
     logger.info("Done building tools...")
     config_name = AgentConfigName(kwargs.get("agent_name", "automata-main"))
-    agent_config = (
+    agent_config_builder = (
         OpenAIAutomataAgentConfigBuilder.from_name(config_name)
         .with_tools(tools)
         .with_model(kwargs.get("model", "gpt-4-0613"))
-        .build()
     )
 
-    agent = OpenAIAutomataAgent(instructions, config=agent_config)
+    max_iterations = kwargs.get("max_iterations", None)
+    if max_iterations is not None:
+        agent_config_builder = agent_config_builder.with_max_iterations(max_iterations)
+
+    agent = OpenAIAutomataAgent(instructions, config=agent_config_builder.build())
     result = agent.run()
     print("Final result:\n\n", result)
     return result

automata/docs/config/agent_config.rst

@@ -1,117 +1,102 @@
-``AgentConfig`` Class
-=====================
+AgentConfig
+===========
 
-The ``AgentConfig`` class is a base abstraction for creating specific
-configurations to be used by agent instances. It includes necessary
-parameters such as instructions to be executed by the agent, a list of
-tools used, a model name, and various boolean flags for stream and
-verbose logging status.
+``AgentConfig`` class is a configuration base class used for setting up
+agent instances in ``automata``. It is an abstract class (as it is
+derived from the ``ABC`` class) that outlines the structure and basic
+functionality for agent configurations in the package. This class
+provides a basis for creating and loading custom agent configurations.
 
-In addition, it holds the max iterations and temperature settings for
-the agent’s operation. It also has an optional session id attribute.
+Overview
+--------
 
-This class is an abstract base class (ABC), and it includes abstract
-methods, requiring subclasses to provide concrete implementations of
-these methods.
+The ``AgentConfig`` class includes several attributes, such as
+``config_name``, ``tools``, ``instructions``, ``description``,
+``model``, ``stream``, ``verbose``, ``max_iterations``, ``temperature``,
+``session_id``. These attributes hold various information needed to
+configure and run an agent.
 
-Attributes
-----------
-
--  ``config_name``: Defines the name of the configuration.
--  ``tools``: Sets a list of Tools to be used by the agent.
--  ``instructions``: A string set by the user to handle instructions for
-   the agent.
--  ``description``: A string to hold any necessary description.
--  ``model``: Defines the model to be used by the agent.
--  ``stream``: Boolean variable to define whether to use stream
-   functionality.
--  ``verbose``: Boolean variable to define whether verbose logging
-   should be used.
--  ``max_iterations``: Sets the maximum iterations count for the agent
-   operations.
--  ``temperature``: Sets the temperature scalar for the agent
-   operations.
--  ``session_id``: (Optional) Defines the session id for the agent.
-
-Methods
--------
-
-setup
-~~~~~
-
-A method that subclasses must implement. Its purpose is to be defined by
-the subclasses.
-
-load
-~~~~
-
-A method that subclasses must implement. It should load the agent
-configuration based on the provided name.
-
-get_llm_provider
-~~~~~~~~~~~~~~~~
+Additionally, it has methods that must be implemented in subclasses -
+``setup()``, ``load()``, and ``get_llm_provider()``. These methods are
+crucial for setting up the agent and loading the needed configuration.
 
-A static method that subclasses must implement. The method should return
-the provider for the agent.
+A nested ``Config`` class is also included, allowing for further
+configuration settings. Using arbitrary types and specifying the
+provider for low-level machine (LLM) operations are available within
+this nested class.
 
-\_load_automata_yaml_config
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Attributes
+----------
 
-This method is responsible for loading YAML configuration for the agent.
-It opens a YAML file, processes its content, and loads them into an
-agent configuration instance. If ``config_name`` appears in the loaded
-YAML, it raises an Exception. Once the loading completes, it adds
-``config_name`` to the loaded YAML and returns it.
+-  ``config_name``: Indicates the name of the agent configuration
+   (default is ``AgentConfigName.DEFAULT``).
+-  ``tools``: A list of ``Tool`` instances used by the agent.
+-  ``instructions``: A string containing instructions for the agent.
+-  ``description``: A descriptive string for the agent.
+-  ``model``: The model used by the agent.
+-  ``stream``: Boolean indicating whether streaming functionality is
+   enabled.
+-  ``verbose``: Boolean controlling the verbosity of the agent.
+-  ``max_iterations``: The maximum number of iterations the agent will
+   attempt.
+-  ``temperature``: A float controlling the random behaviour of the
+   agent.
+-  ``session_id``: An optional string describing the current session.
+
+Related Symbols
+---------------
+
+-  ``automata.config.base.AgentConfigName``
+-  ``automata.tests.unit.test_automata_agent_builder.test_builder_default_config``
+-  ``automata.core.agent.agent.AgentInstance.Config``
+-  ``automata.tests.unit.test_task_environment.TestURL``
+-  ``automata.core.agent.instances.OpenAIAutomataAgentInstance.Config``
+-  ``automata.tests.unit.test_automata_agent_builder.test_builder_creates_proper_instance``
+
+Example Usage
+-------------
+
+The following example shows how to create a subclass of ``AgentConfig``.
+In the subclass, abstract methods are implemented and additional
+configurations are set.
 
-Inherited Classes
------------------
+.. code:: python
 
-The ``OpenAIAutomataAgentConfig`` is a concrete class that inherits from
-``AgentConfig``. This class specifies ``OPENAI`` as the ``LLMProvider``
-and allows the use of different models. It further enriches the
-configuration by defining the system template, system template
-variables, system template formatter, instruction version, and system
-instruction.
+   from automata.config.base import AgentConfig, ConfigCategory
+   from automata.config.base import AgentConfigName, LLMProvider
 
-Example
--------
+   class CustomAgentConfig(AgentConfig):
+       def __init__(self, **data: Any):
+           super().__init__(**data)
+           self.custom_attribute = ''
 
-Creating a derived class ``OpenAIAutomataAgentConfig`` and using the
-``load`` method:
+       def setup(self) -> None:
+           pass
+
+       @classmethod
+       def load(cls, config_name: AgentConfigName) -> "CustomAgentConfig":
+           loaded_yaml = cls._load_automata_yaml_config(config_name)
+           return CustomAgentConfig(**loaded_yaml)
 
-.. code:: python
+       @staticmethod
+       def get_llm_provider() -> LLMProvider:
+           return LLMProvider.OPENAI
 
-       from automata.config.openai_agent import OpenAIAutomataAgentConfig
-       from automata.config.base import AgentConfigName
-
-       config = OpenAIAutomataAgentConfig.load(AgentConfigName.DEFAULT)
-       assert isinstance(config, OpenAIAutomataAgentConfig)
+   custom_config = CustomAgentConfig.load(AgentConfigName.AUTOMATA_MAIN)
 
 Limitations
 -----------
 
-The class ``AgentConfig`` is an abstract base class and cannot be
-directly used to create an object. It must be subclassed, and each
-subclass must provide implementations for the abstract methods.
-
-A derived class can load YAML configurations from a specific file
-location, and this could raise file operation related exceptions. For
-instance, if the configuration file is not found or if the YAML file is
-not in the correct format, corresponding exceptions will be raised.
-
-When a ``config_name`` is found in the loaded_yaml, the
-``_load_automata_yaml_config`` method throws an error stating:
-“config_name already specified in YAML. Please remove this from the YAML
-file.” This could be a limitation when the user does not have much
-control over the yaml content or if the yaml modification would conflict
-with other requirements.
+As ``AgentConfig`` is an abstract base class, it can’t be instantiated
+directly. All abstract methods ``setup()``, ``load()``, and
+``get_llm_provider()`` must be implemented in any subclass. It also
+assumes a specific file structure for loading YAML configurations and
+will raise errors if it can’t locate the necessary files.
 
 Follow-up Questions:
 --------------------
 
--  How to manage the file operation exceptions when loading yaml
-   configuration?
--  Can we modify ``_load_automata_yaml_config`` to allow ``config_name``
-   in yaml or provide a mechanism to overwrite it?
--  What to do when we need to set up an ``AgentConfig`` with varying
-   attributes not defined in existing classes?
+-  How can we handle custom YAML file structures in subclasses of
+   ``AgentConfig``?
+-  Can we add a method to validate the content of the loaded YAML
+   configuration file?

automata/docs/config/agent_config_builder.rst

@@ -1,71 +1,73 @@
 AgentConfigBuilder
 ==================
 
-``AgentConfigBuilder`` is a base class that defines a builder for
-constructing instances of ``Agent``. It offers a flexible and
-easy-to-use interface for setting various properties of the agent before
-instantiation. The config builder is a builder pattern implementation
-that helps organize the processing of agent specific configurations.
+``AgentConfigBuilder`` is a builder class that helps in the creation of
+Agent configurations. It extends the generic type ``T`` and requires the
+implementor to implement methods for creating the specific configuration
+object and associating the correct model with the agent.
 
 Overview
 --------
 
-The ``AgentConfigBuilder`` is an abstract class defining the base
-methods needed to create a configuration for providers. The class
-implements a generic structure with methods for configuration building.
-It also provides a private attribute for storing the configuration data
-and uses abstract methods to enforce the implementation of builder
-methods in the related symbols.
+``AgentConfigBuilder`` primarily functions by taking an optional
+``config`` object, upon instantiation which defaults to the result of
+the ``create_config`` function if not provided. The configuration object
+can be constructed from scratch or from existing configurations by using
+the ``from_config`` or ``from_name`` methods, respectively.
 
-This builder class supports setting multiple properties like ``model``,
-``tools``, ``stream``, ``verbose``, ``max_iterations``, ``temperature``,
-and ``session_id``. It also provides class methods for easily creating
-an ``AgentConfigBuilder`` instance using the provided configuration
-object or the configuration object name.
+This configuration builder also has the capability to set specific
+parameters related to the Agent including the tools it will use, the
+model it should run, whether it will stream output, verbosity of
+logging, maximum iterations the agent should run, and others. The
+validity of all parameter types is thoroughly checked before being
+updated in the builder configuration.
 
 Related Symbols
 ---------------
 
--  ``automata.config.openai_agent.OpenAIAutomataAgentConfigBuilder``
 -  ``automata.tests.unit.test_automata_agent_builder.test_builder_default_config``
+-  ``automata.config.openai_agent.OpenAIAutomataAgentConfigBuilder``
 -  ``automata.tests.unit.test_automata_agent_builder.test_builder_creates_proper_instance``
+-  ``automata.tests.unit.test_automata_agent_builder.test_builder_provided_parameters_override_defaults``
+-  ``automata.core.agent.agent.AgentInstance.Config``
+-  ``automata.tests.unit.test_automata_agent_builder.test_builder_accepts_all_fields``
+-  ``automata.core.agent.instances.OpenAIAutomataAgentInstance.Config``
+-  ``automata.config.base.AgentConfigName``
+-  ``automata.core.tools.base.Tool``
 
-Example
--------
-
-The following example demonstrates how to create an instance of
-``OpenAIAutomataAgentConfigBuilder``, a subclass of
-``AgentConfigBuilder``, and configure its properties.
+Usage Example
+-------------
 
 .. code:: python
 
    from automata.config.openai_agent import OpenAIAutomataAgentConfigBuilder
-   from automata.tools.registries import Tool
+   from automata.config.base import AgentConfigName
+
+   # Using builder to construct with default config
+   builder_default_config = OpenAIAutomataAgentConfigBuilder()
+   config_default = builder_default_config.build()
 
-   builder = OpenAIAutomataAgentConfigBuilder()
-   builder = builder.with_model("gpt-3.5-turbo")
-   builder = builder.with_stream(True)
-   builder = builder.with_verbose(True)
-   builder = builder.with_max_iterations(500)
-   builder = builder.with_temperature(0.5)
-   builder = builder.with_session_id("test-session-id")
-   builder = builder.with_tools([Tool("tool_name", "tool_function")])
+   # Using builder to construct with existing config
+   builder_from_config = OpenAIAutomataAgentConfigBuilder.from_config(config_default)
+   config_from_config = builder_from_config.build()
 
-   config = builder.build()
+   # Using builder to construct from named config
+   builder_from_name = OpenAIAutomataAgentConfigBuilder.from_name(AgentConfigName.TEST)
+   config_from_name = builder_from_name.build()
 
 Limitations
 -----------
 
-The main limitation of ``AgentConfigBuilder`` is that it’s an abstract
-class and can’t be used directly. Subclasses (like
-``OpenAIAutomataAgentConfigBuilder``) should be used, which implement
-the necessary methods, and can be built efficiently with specific
-configurations.
+The builder pattern, while providing a clean API, can lead to over
+complicated code since each attribute is set individually. Be careful of
+overusing builders and consider passing a single object with many
+parameters. This can also make it more difficult to understand as the
+logical groups of parameters can be broken up.
 
 Follow-up Questions:
 --------------------
 
--  How can we extend the builder pattern to add support for new
-   configurations and other providers?
--  Are there any common naming conventions or practices to better
-   understand the builder pattern in Python?
+-  Is there a way to populate the builder with a group of related
+   parameters at once?
+-  How can we ensure each attribute is being updated in a consistent
+   manner?