Feature/refresh docs (#459)

* rollback cli changes

* refresh docs

* refresh docs

docs/agent/agent.rst

@@ -1,25 +1,89 @@
--  The ``Agent`` class is typically used as a base for creating
-   autonomous agents that interact with different APIs or data sources.
-   These agents can be used for a variety of tasks including but not
-   limited to text generation, translation, summarization or any task
-   that involves natural language processing.
-
--  The ``OpenAIAutomataAgent`` is one specific implementation of the
-   ``Agent`` class. Depending on the library, there might be other
-   concrete implementations to interact with different APIs.
-
--  A custom database provider for the ``set_database_provider`` method
-   could be any class that implements a common interface for database
-   operations. For instance, this could be a provider that interacts
-   with a SQL database, a NoSQL database like MongoDB, or a simple
-   in-memory database for testing purposes.
-
--  The ``LLMConversation`` typically represents a series of exchanges or
-   “turns” between the agent and user, where each “turn” includes a user
-   message and an assistant message. The ``LLMIterationResult``
-   typically contains the result of a single iteration of processing,
-   which includes the assistant’s message for the current turn and when
-   implemented, could include other metadata such as response time,
-   temperature for generation, use of p, etc. Kindly note that the
-   actual implementation might differ based on specific implementation
-   of ``Agent`` and the context it is being used in.
+Agent Class
+===========
+
+Overview
+--------
+
+The ``Agent`` is an abstract class for creating autonomous agents. These
+agents can perform actions and communicate with other providers. During
+instantiation, an agent is initialized with a set of instructions and
+can optionally be linked with a database provider.
+
+An ``Agent`` works by advancing through a sequence of tasks. It
+implements iterator methods (``__iter__`` and ``__next__``) for this
+purpose. Each iteration corresponds to a step of the task that the
+``Agent`` has been designed to accomplish. This step could be a
+conversation turn, which involves generating a new message from the
+‘assistant’ and then parsing the reply from the ‘user’. The ``run``
+method can be used to execute these tasks until completion, with the
+task being deemed complete when the ``__next__`` method returns
+``None``.
+
+It has abstract properties for fetching its responses, associated
+conversation, and tools, whose concrete implementation is instantiated
+by subclasses. It also has an abstract method for setting a database
+provider, essential for managing conversations with the user.
+
+Usage Example:
+--------------
+
+The following example shows a basic creation of a subclass of ``Agent``:
+
+.. code:: python
+
+   class SimpleAgent(Agent):
+       """Implements the abstract Agent class for a simple specific agent."""
+
+       def __init__(self, instructions: str) -> None:
+           super().__init__(instructions)
+
+       def __iter__(self):
+           ...
+
+       def __next__(self) -> str:
+           ...
+
+       @property
+       def conversation(self) -> LLMConversation:
+           ...
+
+       @property
+       def agent_responses(self) -> List[LLMChatMessage]:
+           ...
+
+       @property
+       def tools(self) -> Sequence[Tool]:
+           ...
+
+       def run(self) -> str:
+           ...
+
+This example shows a simple implementation of the ``Agent`` abstract
+class. The ``...`` represents sections of code that must be implemented
+to define the specific behaviour of the ``SimpleAgent``.
+
+Related Symbols
+---------------
+
+-  ``LLMChatMessage``, ``LLMConversation``: Models for handling and
+   representing chat messages and conversations.
+-  ``Tool``: An abstraction for different types of tools associated with
+   the agent.
+-  ``LLMConversationDatabaseProvider``: Abstract base class for database
+   providers.
+
+Limitations
+-----------
+
+The ``Agent`` abstract class doesn’t provide an easy method to modify or
+control the flow of execution. It assumes that all tasks are to be
+performed in a cyclical manner and that they complete after a specific
+number of steps.
+
+Follow-up Questions:
+--------------------
+
+-  How to handle more complex workflows that require non-linear
+   execution paths?
+-  Is it possible to dynamically adjust the maximum number of iterations
+   based on the task complexity?

docs/agent/agent/index.rst

@@ -17,6 +17,8 @@ how to :ref:`installation` the project.
 Summary of content
 
 
+
+
 ..  AUTO-GENERATED CONTENT START
 ..
 

docs/agent/agent_database_error.rst

@@ -1,17 +1,2 @@
--  Given that ``AgentDatabaseError`` will be raised in cases of various
-   database-related issues, it would be beneficial to include specific
-   error messages or codes. This would make it easier for users to
-   determine the source of the problem and know how to fix it, rather
-   than needing to manually inspect the code and database setup.
--  Whether ``AgentDatabaseError`` is being used in test coverage would
-   depend on the specific practices of the developers or team using it.
-   As a best practice, it is usually a good idea to include error
-   handling and exception throwing in testing to ensure that your code
-   can gracefully handle any runtime issues. If ``AgentDatabaseError``
-   is used in testing, it should be documented in the test cases to make
-   it clear to other developers and future users exactly when and why
-   it’s being raised.
--  The documentation for ``AgentDatabaseError`` should also ideally
-   include examples of situations where it could be raised, to provide a
-   better understanding for users who aren’t intimately familiar with
-   the database provider setup.
+class AgentDatabaseError(AutomataError): ‘An exception raised when the
+agent fails to set the database provider.’ pass

docs/agent/agent_general_error.rst

@@ -1,16 +1,2 @@
--  ``AgentGeneralError`` could potentially have subclasses for further
-   granulation of errors. However, whether such subclasses exist or not
-   depends on the specifics of the error handling design in the package.
-   Subclasses could be helpful in distinguishing between different types
-   of errors, providing more detailed information to the users and
-   developers.
-
--  More specific errors can indeed be beneficial in certain cases. If
-   the system has known points of potential failure, then having more
-   specific exceptions allows for more precise error handling and easier
-   debugging. However, the ``AgentGeneralError`` should still be present
-   to catch all the unexpected errors that do not fit into any of the
-   specific cases.
-
-Thus, a balance between general and specific errors should be maintained
-for a robust error handling system.
+class AgentGeneralError(AutomataError): ‘An exception raised when there
+is a general error arises with the agent.’ pass

docs/agent/agent_max_iter_error.rst

@@ -1,27 +1,2 @@
-As an AI developed by OpenAI, I do not have direct access to the
-``automata`` module, a third-party package. I cannot retrieve its
-concrete implementation details, making it challenging to answer the
-follow-up questions concretely. Furthermore, my training doesn’t include
-specific knowledge of this package. Nonetheless, I can offer a general
-perspective based on common programming principles and practices:
-
-1. **Default iteration count**: With most libraries that include a
-   maximum iteration count, a default value is often defined. The actual
-   default value can vary according to the specific parameters of the
-   agent.
-
-2. **Modifying iteration count**: Depending on how the library is
-   implemented, the maximum iteration count could potentially be
-   modified during an agent’s lifecycle. However, typically, such
-   settings are defined during initialization and might remain constant.
-
-3. **Recovery from AgentMaxIterError**: Typically, when a maximum
-   iteration count is exceeded, the task that the agent was trying to
-   fulfill is considered unsuccessful. However, the way this case is
-   handled can vary. In some cases, it might be designed to attempt the
-   task again with adjusted parameters; in others, it could fail
-   outright and require manual intervention.
-
-To obtain the most accurate answers, consulting the specific
-implementation details of the ``automata`` library or reaching out to
-its developers would be recommended.
+class AgentMaxIterError(AutomataError): ‘An exception raised when the
+agent exceeds the maximum number of iterations.’ pass

docs/agent/agent_result_error.rst

@@ -1,17 +1,2 @@
-``AgentResultError`` is typically thrown when an agent in the Automata
-project fails to deliver an expected outcome after performing its task.
-This could be due to an internal error, a communication failure with
-other interfaces, or reaching the maximum number of iterations without a
-result.
-
-How the system recovers from this error greatly depends on the context
-and the system design. In general, raising an ``AgentResultError`` would
-be followed by diagnostic logging that provides useful information for
-troubleshooting. The system might also catch this exception and attempt
-a retry cycle, switch to a different agent, or notify the user about the
-incident if the error persists.
-
-For a specific recovery process, developers should consider the
-trade-off between system complexity and resilience. It’s crucial to
-strike a balance to avoid overcomplicating the system or making it
-excessively prone to errors.
+class AgentResultError(AutomataError): ‘An exception raised when the
+agent fails to produce a result.’ pass

docs/agent/agent_stop_iteration_error.rst

@@ -0,0 +1,2 @@
+class AgentStopIterationError(AutomataError): ‘An exception raised when
+the agent iteration process terminates.’ pass

docs/agent/agent_toolkit_builder.rst

@@ -1,94 +1,13 @@
-AgentToolkitBuilder
-===================
+class AgentToolkitBuilder(ABC): ‘:raw-latex:`\n    `AgentToolkitBuilder
+is an abstract class for building tools for
+providers.:raw-latex:`\n    `Each builder builds the tools associated
+with a specific AgentToolkitNames.:raw-latex:`\n    `’ TOOL_NAME:
+Optional[AgentToolkitNames] = None LLM_PROVIDER: Optional[LLMProvider] =
+None
 
-``AgentToolkitBuilder`` is an abstract class used for building tools for
-various providers. These tools, once built, are associated with the
-respective ``AgentToolkitNames``.
-
-Overview
---------
-
-The fundamental purpose of ``AgentToolkitBuilder`` is to offer a
-standardized way to create a collection of tools that can be used with
-different types of agents, as defined by the ``AgentToolkitNames``.
-
-Given the abstract nature of this class, it doesn’t instantiate any
-object on its own, but outlines the requirements for
-sub-classes/offspring of the ``AgentToolkitBuilder``.
-
-Related Symbols
----------------
-
-Here are some related classes that build upon or interact with
-``AgentToolkitBuilder``:
-
--  ``ContextOracleOpenAIToolkitBuilder``
--  ``SymbolSearchOpenAIToolkitBuilder``
--  ``PythonAgentToolkit``
--  ``OpenAIAgentToolkitBuilder``
--  ``PyWriterOpenAIToolkitBuilder``
-
-Mandatory Methods
------------------
-
-The ``AgentToolkitBuilder`` possesses an abstract method named
-``build``:
-
-.. code:: python
+::
 
    @abstractmethod
-   def build(self) -> List[Tool]:
+   def build(self) -> List['Tool']:
+       'Builds the tools associated with the `AgentToolkitBuilder`.'
        pass
-
-This method, once implemented in the subclasses, is expected to return a
-list of ``Tool`` objects.
-
-Example
--------
-
-Let’s provide an example of a class ``PythonAgentToolkit`` which
-inherits from ``AgentToolkitBuilder``.
-
-.. code:: python
-
-   from automata.tools.base import Tool
-
-   class PythonAgentToolkit:
-       def __init__(self, python_agent: PythonAgent):
-           self.python_agent = python_agent
-
-       def build(self) -> List[Tool]:
-           def python_agent_python_task():
-               pass
-
-           tools = [
-               Tool(
-                   "automata-task",
-                   python_agent_python_task,  
-                   "Execute a Python task using the PythonAgent. Provide the task description in plain English.",
-               )
-           ]
-           return tools
-
-In this example, the subclass ``PythonAgentToolkit`` implements the
-``build`` method to generate a list of ``Tool`` items.
-
-Limitations and Considerations
-------------------------------
-
-Since ``AgentToolkitBuilder`` is an abstract class, it should not be
-instantiated directly. Instead, create a subclass that implements the
-``build`` method. The usage and appropriateness of this class and its
-subclasses will depend on the corresponding agent context where this
-toolkit would be used.
-
-Follow-up Questions:
---------------------
-
--  Are there existing subclasses of ``AgentToolkitBuilder`` apart from
-   the ones identified?
--  Are there any additional methods that could be part of the
-   ``AgentToolkitBuilder``, to be implemented by subclasses?
--  Any specific structures to be maintained in the ``Tool`` objects
-   built by the subclasses? How are these ``Tool`` objects expected to
-   interact with agents?