API docs and cleanup (#64)

* WIP Docs & cleanup

* Lots of API docs

* update tests data

docs/source/_templates/autosummary/base.rst

@@ -1,5 +1,6 @@
-{{ fullname | escape | underline}}
+{{ fullname | escape | underline }}
 
 .. currentmodule:: {{ module }}
 
+
 .. auto{{ objtype }}:: {{ objname }}

docs/source/_templates/autosummary/module.rst

@@ -1,65 +1,61 @@
 {{ fullname | escape | underline}}
 
-.. automodule:: {{ fullname }}
-
-   {% block attributes %}
-   {% if attributes %}
-   .. rubric:: {{ _('Module Attributes') }}
-
-   .. autosummary::
-   {% for item in attributes %}
-      {{ item }}
-   {%- endfor %}
-   {% endif %}
-   {% endblock %}
-
-   {% block functions %}
-   {% if functions %}
-   .. rubric:: {{ _('Functions') }}
-
-   .. autosummary::
-   {% for item in functions %}
-   .. autofunction:: {{ item }}
-   {%- endfor %}
-   {% endif %}
-   {% endblock %}
 
-   {% block classes %}
-   {% if classes %}
-   .. rubric:: {{ _('Classes') }}
-
-   .. autosummary::
-     :toctree:
-   {% for item in classes %}
-     {{item}}
-   {%- endfor %}
-   {% for item in classes %}
-   .. autoclass:: {{item}}
-     :members:
-   {%- endfor %}
-   {% endif %}
-   {% endblock %}
-
-   {% block exceptions %}
-   {% if exceptions %}
-   .. rubric:: {{ _('Exceptions') }}
-
-   .. autosummary::
-   {% for item in exceptions %}
-      {{ item }}
-   {%- endfor %}
-   {% endif %}
-   {% endblock %}
-
-{% block modules %}
-{% if modules %}
-.. rubric:: Modules
+.. automodule:: {{ fullname }}
 
-.. autosummary::
-   :toctree:
-   :recursive:
-{% for item in modules %}
-   {{ item }}
-{%- endfor %}
-{% endif %}
-{% endblock %}
+ {% block attributes %}
+ {% if attributes %}
+ .. rubric:: {{ _('Module Attributes') }}
+
+ .. autosummary::
+ {% for item in attributes %}
+    {{ item }}
+ {%- endfor %}
+ {% endif %}
+ {% endblock %}
+
+ {% block functions %}
+ {% if functions %}
+ .. rubric:: {{ _('Functions') }}
+
+ .. autosummary::
+ {% for item in functions %}
+    {{ item }}
+ {%- endfor %}
+ {% endif %}
+ {% endblock %}
+
+ {% block classes %}
+ {% if classes %}
+ .. rubric:: {{ _('Classes') }}
+
+ .. autosummary::
+ {% for item in classes %}
+    {{ item }}
+ {%- endfor %}
+ {% endif %}
+ {% endblock %}
+
+ {% block exceptions %}
+ {% if exceptions %}
+ .. rubric:: {{ _('Exceptions') }}
+
+ .. autosummary::
+ {% for item in exceptions %}
+    {{ item }}
+ {%- endfor %}
+ {% endif %}
+ {% endblock %}
+
+ {% block modules %}
+ {% if modules %}
+ .. rubric:: Modules
+
+ .. autosummary::
+    :toctree:
+    :recursive:
+ {% for item in modules %}
+    {{ item }}
+ {%- endfor %}
+ {% endif %}
+ {% endblock %}

docs/source/api.rst

@@ -5,4 +5,4 @@ API
    :toctree: _autosummary
    :recursive:
 
-   motleycrew
+   motleycrew

docs/source/conf.py

@@ -11,7 +11,6 @@
 
 sys.path.append(os.path.abspath("../.."))
 
-
 project = "motleycrew"
 copyright = "2024, motleycrew"
 author = "motleycrew"
@@ -29,12 +28,22 @@
     "nbsphinx_link",
 ]
 
+
 templates_path = ["_templates", "_templates/autosummary"]
 exclude_patterns = []
-autosummary_generate = True
+
+# autodoc_default_options = {
+#     "member-order": "bysource",
+#     "special-members": "__init__",
+# }
+
 autodoc_default_options = {
+    "members": True,
     "member-order": "bysource",
     "special-members": "__init__",
+    "show-inheritance": True,
+    "inherited-members": False,
+    "undoc-members": True,
 }
 
 napoleon_google_docstring = True
@@ -50,7 +59,11 @@
 nbsphinx_allow_errors = True
 nbsphinx_execute = "never"
 
-html_theme_options = {
-    "display_github": True,
-    "github_url": "https://github.com/ShoggothAI/motleycrew",
-}
+# Additional configuration for better auto-generated documentation
+autosummary_generate = True  # Turn on autosummary
+
+# Create separate .rst files for each module
+autosummary_generate_overwrite = False
+
+# Make sure that the generated files are included in the toctree
+autosummary_generate_include_files = True

docs/source/index.rst

@@ -16,7 +16,6 @@ Welcome to motleycrew's documentation!
    :caption: Contents:
 
 
-
 Indices and tables
 ==================
 

docs/source/key_concepts.rst

@@ -11,7 +11,7 @@ For a basic introduction, you can check out the `quickstart <quickstart.html>`_.
 Crew and knowledge graph
 ------------------------
 
-The crew is a central concept in motleycrew. It is the orchestrator that knows what tasks sould be done in which order,
+The crew (:class:`motleycrew.crew.crew.MotleyCrew`) is a central concept in motleycrew. It is the orchestrator that knows what tasks sould be done in which order,
 and manages the execution of those tasks.
 
 The crew has an underlying knowledge graph, in which it stores all information relevant to the execution of the tasks.
@@ -79,8 +79,8 @@ that you can override to customize the task's behavior.
 
 #. ``get_next_unit()`` should return the next task unit to be processed. If there are no units to do at the moment, it should return `None`.
 #. ``get_worker()`` should return the worker (typically an agent) that will process the task's units.
-#. `optional` ``register_started_unit(unit)`` is called by the crew when a task unit is dispatched.
-#. `optional` ``register_completed_unit(unit)`` is called by the crew when a task unit is completed.
+#. `optional` ``on_unit_dispatch(unit)`` is called by the crew when a task unit is dispatched.
+#. `optional` ``on_unit_completion(unit)`` is called by the crew when a task unit is completed.
 
 
 Task hierarchy
@@ -106,15 +106,15 @@ The crew queries the tasks for task units and dispatches them in a loop. The cre
 tasks are completed or available tasks stop providing task units.
 
 A task is considered completed when it has ``done`` attribute set to ``True``. For example, in the case of `SimpleTask`,
-this happens when its only task unit is completed and the crew calls the task's ``register_completed_unit`` method.
+this happens when its only task unit is completed and the crew calls the task's ``on_unit_completion`` method.
 In case of a custom task, this behavior is up to the task's implementation.
 
 Available tasks are defined as tasks that have not been completed and have no incomplete
 upstream tasks. On each iteration, available tasks are queried for task units one by one,
 and the crew will dispatch the task unit to the worker that the task provides.
 
-When a task unit is dispatched, the crew adds it to the knowledge graph and calls the task's ``register_started_unit``
-method. When the worker finishes processing the task unit, the crew calls the task's ``register_completed_unit`` method.
+When a task unit is dispatched, the crew adds it to the knowledge graph and calls the task's ``on_unit_dispatch``
+method. When the worker finishes processing the task unit, the crew calls the task's ``on_unit_completion`` method.
 
 .. image:: images/crew_diagram.png
     :alt: Crew main loop

examples/old/image_generation_crewai.py

@@ -2,8 +2,9 @@
 
 from motleycrew import MotleyCrew
 from motleycrew.agents.crewai import CrewAIMotleyAgent
-from motleycrew.tools.image.dall_e import DallEImageGeneratorTool
 from motleycrew.common import configure_logging
+from motleycrew.tasks import SimpleTask
+from motleycrew.tools.image.dall_e import DallEImageGeneratorTool
 
 
 def main():
@@ -35,7 +36,8 @@ def main():
 
     # Create tasks for your agents
     crew = MotleyCrew()
-    write_task = crew.create_simple_task(
+    write_task = SimpleTask(
+        crew=crew,
         name="write a short story about a cat",
         description="Creatively write a short story of about 4 paragraphs "
         "about a house cat that was smarter than its owners. \n"

examples/old/math_crewai.py

@@ -2,8 +2,9 @@
 
 from motleycrew import MotleyCrew
 from motleycrew.agents.crewai import CrewAIMotleyAgent
-from motleycrew.tools import PythonREPLTool
 from motleycrew.common import configure_logging
+from motleycrew.tasks import SimpleTask
+from motleycrew.tools import PythonREPLTool
 
 
 def main():
@@ -36,7 +37,8 @@ def main():
 
     # Create tasks for your agents
     crew = MotleyCrew()
-    task = crew.create_simple_task(
+    task = SimpleTask(
+        crew=crew,
         name="solve math problem",
         description=f"""Create a nice human-readable solution to the following problem:
         {problems[1]}

motleycrew/agents/abstract_parent.py

@@ -1,39 +1,32 @@
-""" Module description"""
 from abc import ABC, abstractmethod
 from typing import Optional, Any, TYPE_CHECKING
 
-from langchain_core.runnables import RunnableConfig
+from langchain_core.runnables import Runnable, RunnableConfig
 
 if TYPE_CHECKING:
     from motleycrew.tools import MotleyTool
 
 
-class MotleyAgentAbstractParent(ABC):
+class MotleyAgentAbstractParent(Runnable, ABC):
+    """Abstract class for describing agents.
+
+    Agents in motleycrew implement the Langchain Runnable interface.
+    """
+
     @abstractmethod
     def invoke(
         self,
         input: dict,
         config: Optional[RunnableConfig] = None,
         **kwargs: Any,
     ) -> Any:
-        """ Description
-
-            Args:
-                input (dict):
-                config (:obj:`RunnableConfig`, optional):
-                **kwargs:
-
-            Returns:
-                Any:
-        """
         pass
 
     @abstractmethod
     def as_tool(self) -> "MotleyTool":
-        """ Description
+        """Convert the agent to a MotleyTool to be used by other agents via delegation.
 
         Returns:
-            MotleyTool
-
+            The tool representation of the agent.
         """
         pass

motleycrew/agents/crewai/agent_with_config.py

@@ -1,9 +1,7 @@
-""" Module description """
-
 from typing import Any, Optional, List
 
-from langchain_core.runnables import RunnableConfig
 from langchain.tools.render import render_text_description
+from langchain_core.runnables import RunnableConfig
 
 from motleycrew.common.utils import ensure_module_is_installed