Update userguides (#60)

* Update userguides

* Change graph view to image

* Extend evaluation and extender userguides

* Update example info in README

Author: anna-a-m

README.md

@@ -41,7 +41,7 @@ cd dialog2graph
 poetry install
 ```
 
-If you are planning to visualize your graphs consider installing **PyGraphviz** from [here](https://pygraphviz.github.io/) and also add it to the poetry environment.
+Consider installing **PyGraphviz** from [here](https://pygraphviz.github.io/), if you are planning to visualize your graphs. Then add it to the poetry environment.
 
 ```bash
 poetry add pygraphviz
@@ -59,48 +59,21 @@ Create `.env` file to store credentials
 
 ## How to Use
 
-### Generate synthetic graph on certain topic
+See `dialog2graph` usage examples:
 
-Choose LLMs for generating and validating dialog graph and invoke graph generation
+1. [Learn base classes usage](https://github.com/deeppavlov/dialog2graph/blob/dev/examples/basics/base_classes_usage.ipynb)
 
-```python
-from dialog2graph.datasets.complex_dialogs.generation import LoopedGraphGenerator
-from langchain_community.chat_models import ChatOpenAI
+2. [Learn dialog2graph pipelines and model configuration](https://github.com/deeppavlov/dialog2graph/blob/dev/examples/pipeline_usage/pipeline_example.ipynb)
 
+3. [Generate dialog graph using LLMs](https://github.com/deeppavlov/dialog2graph/blob/dev/examples/data_generation/LoopedGraphGenerator_example.ipynb)
 
-gen_model = ChatOpenAI(
-    model='gpt-4o',
-    api_key=os.getenv("OPENAI_API_KEY"),
-    base_url=os.getenv("OPENAI_BASE_URL"),
-)
-val_model = ChatOpenAI(
-    model='gpt-3.5-turbo',
-    api_key=os.getenv("OPENAI_API_KEY"),
-    base_url=os.getenv("OPENAI_BASE_URL"),
-    temperature=0,
-)
+4. [Evaluate graph and dialogs](https://github.com/deeppavlov/dialog2graph/blob/dev/examples/evaluation/examples_of_metrics_usage.ipynb)
 
-pipeline = LoopedGraphGenerator(
-    generation_model=gen_model,
-    validation_model=val_model,
-)
+5. [Learn CLI interface](https://github.com/deeppavlov/dialog2graph/blob/dev/examples/cli_usage/main.ipynb)
 
-generated_graph = pipeline.invoke(topic="restaurant reservation")
-```
-
-### Sample dialogs from existing dialog graph
-
-Create graph instance and invoke sampler to get dialog list
+6. [Augment dialogs on dialog graph](https://github.com/deeppavlov/dialog2graph/blob/dev/examples/dialog_augmentation/dialogue_augmentation_example.ipynb)
 
-```python
-from dialog2graph.pipelines.core.dialog_sampling import RecursiveDialogSampler
-from dialog2graph.pipelines.core.graph import Graph
-
-G = Graph(graph_dict={...})
-
-sampler = RecursiveDialogSampler()
-sampler.invoke(graph=G) #-> list of Dialog objects
-```
+7. [Extend a dialog graph](https://github.com/deeppavlov/dialog2graph/blob/dev/examples/dialog_extension/dialog_extender_example.ipynb)
 
 ## How to Contribute
 

dialog2graph/pipelines/helpers/__init__.py

@@ -1,14 +1,13 @@
 About us
 =========
 
-Dialog2Graph is developed by `DeepPavlov <https://deeppavlov.ai>`_.
 .. |deeppavlov| image:: _static/images/logo-deeppavlov.svg
     :align: middle
-    :width: 40 
+    :width: 40
 
 Developed by
 """"""""""""
- |deeppavlov| `DeepPavlov <https://deeppavlov.ai>`_, an open source conversational AI framework   
+ |deeppavlov| `DeepPavlov <https://deeppavlov.ai>`_, an open source conversational AI framework 
 
 Project founders
 """"""""""""""""

docs/source/_static/images/graph-example.png

@@ -43,8 +43,7 @@
     "sphinx.ext.viewcode",
     "sphinx.ext.napoleon",
     "sphinx.ext.extlinks",
-    "sphinx_autodoc_typehints",
-    "sphinx.ext.graphviz",
+    "sphinx_autodoc_typehints"
 ]
 
 autodoc_default_options = {

docs/source/about_us.rst

@@ -7,13 +7,11 @@ Key Concepts
 A **dialog graph** is a structured, graph-based representation of conversational data, where **nodes** represent key elements such 
 as utterances, intents, or states, and **edges** define the transitions between these elements.
 
-.. graphviz::
+.. figure:: _static/images/graph-example.png
+   :width: 400
    :align: center
-   :caption: Simple example of dialog graph
 
-   digraph graphexample {
-      "['Hello! How can I assist you today?']" -> "['Great! What product are you interested in?']" [ label="['I want to place an order.']" ];
-   }
+   Simple example of dialog graph
 
 :doc:`Data collections <./research/data_collections>`
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

docs/source/conf.py

@@ -1,5 +1,5 @@
-Datasets
-========
+Data collections
+================
 
 We provide several datasets that can be utilized for your experiments.
 
@@ -11,22 +11,22 @@ Task oriented dialog datasets
 -------------------------------
 
 +---------------+-------------------------------------------------------------------------------------------------------------------+
-|d2g_real_dialogs                                                                                                                 |
+|d2g_real_dialogs                                                                                                                   |
 +===============+===================================================================================================================+
 |**Description**| Reformatted task oriented dialog datasets                                                                         |
 +---------------+-------------------------------------------------------------------------------------------------------------------+
-|**Datasets**   | 1. WOZ, 2. MULTIWOZ2_2, 3. MetaLWOz, 4. Microsoft Dialog Challenge, 5. schema_guided_dialog, 6. Stanford        |
+|**Datasets**   | 1. WOZ, 2. MULTIWOZ2_2, 3. MetaLWOz, 4. Microsoft Dialog Challenge, 5. schema_guided_dialog, 6. Stanford          |
 |               | Multi-Domain, 7. TaskMaster3, 8. Frames                                                                           |
 +---------------+-------------------------------------------------------------------------------------------------------------------+
-|**Format**     |``['domain', 'dialog_id', 'dialog']``                                                                          |
+|**Format**     |``['domain', 'dialog_id', 'dialog']``                                                                              |
 +---------------+-------------------------------------------------------------------------------------------------------------------+
-|**Link**       | |huggingface| `d2g_real_dialogs on HuggingFace <https://huggingface.co/datasets/DeepPavlov/d2g_real_dialogs>`_|
+|**Link**       | |huggingface| `d2g_real_dialogs on HuggingFace <https://huggingface.co/datasets/DeepPavlov/d2g_real_dialogs>`_    |
 +---------------+-------------------------------------------------------------------------------------------------------------------+
 |**Usage**      |.. code-block:: python                                                                                             |
 |               |                                                                                                                   |
 |               |    from datasets import load_dataset                                                                              |
 |               |                                                                                                                   |
-|               |    dataset = load_dataset("DeepPavlov/d2g_real_dialogs",                                                        |
+|               |    dataset = load_dataset("DeepPavlov/d2g_real_dialogs",                                                          |
 |               |                           "MULTIWOZ2_2", token=True)                                                              |
 +---------------+-------------------------------------------------------------------------------------------------------------------+
 
@@ -38,7 +38,7 @@ Synthetic dialog graph dataset
 +===============+=========================================================================================================+
 |**Description**| LLM generated dialog graphs                                                                             |
 +---------------+---------------------------------------------------------------------------------------------------------+
-|**Format**     |``['graph', 'topic', 'dialogs']``                                                                      |
+|**Format**     |``['graph', 'topic', 'dialogs']``                                                                        |
 +---------------+---------------------------------------------------------------------------------------------------------+
 |**Link**       | |huggingface| `d2g_generated on HuggingFace <https://huggingface.co/datasets/DeepPavlov/d2g_generated>`_|
 +---------------+---------------------------------------------------------------------------------------------------------+

docs/source/research.rst

@@ -16,21 +16,33 @@ This guide demonstrates usage of ``ModelStorage`` class and generating the dialo
 
 This generation guide demonstrates how we can generate a dialog graph to a certain topic.
 
+:doc:`Evaluate graph and dialogs <./userguides/evaluate_userguide>`
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This guide demonstrates how to evaluate single dialog graphs and dialog sets, how to compare graphs on various metrics.
+
 :doc:`Learn how to use dialog2graph CLI <./userguides/cli_usage>`
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-This guide demonstrates how to use CLI interface of dialog2graph.
+This guide demonstrates how to use ``dialog2graph`` CLI interface.
 
 :doc:`Augment dialogs <./userguides/augment_dialogs>`
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 This guide demonstrates how to augment existing dialogs using LLMs.
 
+:doc:`Extend graphs <./userguides/extend_graphs>`
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This guide demonstrates how to extend existing dialog graph using LLMs.
+
 .. toctree::
    :hidden:
 
    userguides/basic_usage
    userguides/generate_graphs
    userguides/generate_synthetic
+   userguides/evaluate_userguide
    userguides/cli_usage
-   userguides/augment_dialogs
+   userguides/augment_dialogs
+   userguides/extend_graphs

docs/source/research/data_collections.rst

@@ -1,10 +1,10 @@
-:tutorial_name: dialog_augmentation/dialog_augmentation_example.ipynb
+:tutorial_name: dialog_augmentation/dialogue_augmentation_example.ipynb
 
 Generate augmented dialogs on one given dialog
 ==================================================
 
-Use :py:class:`~dialog2graph.datasets.augment_dialogs.augmentation.DialogAugmenter` to augment an original dialog by paraphrasing 
-its lines while maintaining the structure and flow of the conversation.
+:py:class:`~dialog2graph.datasets.augment_dialogs.augmentation.DialogAugmenter` is a class used to augment an original dialog by paraphrasing 
+dialog turns while maintaining dialog structure and flow of the conversation.
 
 .. code-block:: python
 
@@ -14,8 +14,9 @@ its lines while maintaining the structure and flow of the conversation.
     from dialog2graph.pipelines.model_storage import ModelStorage
 
 
-1. Create :py:class:`~dialog2graph.pipelines.model_storage.ModelStorage` instance and add choosen LLMs for dialog generation (i.e. dialog augmentation) 
-and formatting LLM's output.
+First, LLM models should be configured for further use. So, :py:class:`~dialog2graph.pipelines.model_storage.ModelStorage` instance 
+is created to which choosen LLMs are added for dialog generation (i.e. dialog augmentation) 
+and formatting LLM's output. More information on ModelStorage usage may be found :doc:`in this userguide <./generate_graphs>`. 
 
 .. code-block:: python
 
@@ -31,8 +32,11 @@ and formatting LLM's output.
             model_type=ChatOpenAI
         )
 
-2. Create :py:class:`~dialog2graph.datasets.augment_dialogs.augmentation.DialogAugmenter` instance and use 
-:py:class:`~dialog2graph.datasets.augment_dialogs.augmentation.DialogAugmenter.invoke` method to get augmented dialogs.
+Then, :py:class:`~dialog2graph.datasets.augment_dialogs.augmentation.DialogAugmenter` instance is created to use 
+:py:class:`~dialog2graph.datasets.augment_dialogs.augmentation.DialogAugmenter.invoke` method for getting augmented dialogs. 
+:py:class:`~dialog2graph.datasets.augment_dialogs.augmentation.DialogAugmenter` takes previously created 
+:py:class:`~dialog2graph.pipelines.model_storage.ModelStorage` instance and the names given to models should be leveraged
+for new dialog generation and dialog formatting.
 
 .. code-block:: python
 

docs/source/userguides.rst

@@ -4,7 +4,8 @@ Learn base dialog2graph classes
 =========================================
 
 :py:class:`~dialog2graph.pipelines.core.graph.Graph` and :py:class:`~dialog2graph.pipelines.core.dialog.Dialog` are the base structures used in the 
-``dialog2graph`` project. They are perfect to store information about your graphs and dialogs in a clear format.
+``dialog2graph`` project. They are perfect to store information about your graphs and dialogs in a clear format. This tutorial demonstrates these classes
+functional.
 
 Create dialog2graph.Graph
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~