diff --git a/README.md b/README.md index 9a7159609..4f7466d0f 100644 --- a/README.md +++ b/README.md @@ -26,6 +26,7 @@ pip install dff The above command will set the minimum dependencies to start working with DFF. The installation process allows the user to choose from different packages based on their dependencies, which are: ```bash +pip install dff[core] # minimal dependencies (by default) pip install dff[redis] # dependencies for using Redis pip install dff[mongodb] # dependencies for using MongoDB pip install dff[mysql] # dependencies for using MySQL diff --git a/dff/context_storages/database.py b/dff/context_storages/database.py index ca2f23b3a..32bd86d6e 100644 --- a/dff/context_storages/database.py +++ b/dff/context_storages/database.py @@ -1,8 +1,11 @@ """ Database -------- -Base module. Provided classes: - - Abstract context storage interface :py:class:`.DBContextStorage`. +The `Database` module provides classes for managing the context storage of a dialog system. +The module can be used to store information such as the current state of the conversation +and other data. This module includes the intermediate class (:py:class:`.DBContextStorage`) is a class +that developers can inherit from in order to create their own context storage solutions. +This class implements the basic functionality and can be extended to add additional features as needed. """ import asyncio import importlib diff --git a/dff/context_storages/json.py b/dff/context_storages/json.py index 93e22c73e..2c642af49 100644 --- a/dff/context_storages/json.py +++ b/dff/context_storages/json.py @@ -1,7 +1,9 @@ """ JSON ----- -Provides the json-based version of the :py:class:`.DBContextStorage`. +----- +The JSON module provides a json-based version of the :py:class:`.DBContextStorage` class. +This class is used to store and retrieve context data in a JSON. It allows the `DFF` to easily +store and retrieve context data. """ import asyncio from typing import Hashable diff --git a/dff/context_storages/mongo.py b/dff/context_storages/mongo.py index 63fbec731..850d99840 100644 --- a/dff/context_storages/mongo.py +++ b/dff/context_storages/mongo.py @@ -1,7 +1,15 @@ """ Mongo ----- -Provides the mongo-based version of the :py:class:`.DBContextStorage`. +The Mongo module provides a MongoDB-based version of the :py:class:`.DBContextStorage` class. +This class is used to store and retrieve context data in a MongoDB. +It allows the `DFF` to easily store and retrieve context data in a format that is highly scalable +and easy to work with. + +MongoDB is a widely-used, open-source NoSQL database that is known for its scalability and performance. +It stores data in a format similar to JSON, making it easy to work with the data in a variety of programming languages +and environments. Additionally, MongoDB is highly scalable and can handle large amounts of data +and high levels of read and write traffic. """ from typing import Hashable, Dict diff --git a/dff/context_storages/pickle.py b/dff/context_storages/pickle.py index 004a4a984..fb903f80a 100644 --- a/dff/context_storages/pickle.py +++ b/dff/context_storages/pickle.py @@ -1,7 +1,14 @@ """ Pickle ------ -Provides the pickle-based version of the :py:class:`.DBContextStorage`. +The Pickle module provides a pickle-based version of the :py:class:`.DBContextStorage` class. +This class is used to store and retrieve context data in a pickle format. +It allows the `DFF` to easily store and retrieve context data in a format that is efficient +for serialization and deserialization and can be easily used in python. + +Pickle is a python library that allows to serialize and deserialize python objects. +It is efficient and fast, but it is not recommended to use it to transfer data across +different languages or platforms because it's not cross-language compatible. """ import asyncio import pickle diff --git a/dff/context_storages/protocol.py b/dff/context_storages/protocol.py index f92aae034..531bfa061 100644 --- a/dff/context_storages/protocol.py +++ b/dff/context_storages/protocol.py @@ -1,8 +1,16 @@ """ Protocol -------- -Base protocol code. Protocols :py:data:`.PROTOCOLS`. -A func is used for suggestion of installation: :py:func:`.get_protocol_install_suggestion`. +The Protocol module contains the base code for the different communication protocols used in the `DFF`. +It defines the :py:data:`.PROTOCOLS` constant, which lists all the supported protocols in the `DFF`. + +The module also includes a function :py:func:`.get_protocol_install_suggestion()` that is used to provide +suggestions for installing the necessary dependencies for a specific protocol. +This function takes the name of the desired protocol as an argument and returns +a string containing the necessary installation commands for that protocol. + +The `DFF` supports a variety of communication protocols, +which allows it to communicate with different types of databases. """ import json import pathlib diff --git a/dff/context_storages/redis.py b/dff/context_storages/redis.py index fb361f08c..d69b3fa80 100644 --- a/dff/context_storages/redis.py +++ b/dff/context_storages/redis.py @@ -1,7 +1,16 @@ """ Redis ----- -Provides the redis-based version of the :py:class:`.DBContextStorage`. +The Redis module provides a Redis-based version of the :py:class:`.DBContextStorage` class. +This class is used to store and retrieve context data in a Redis. +It allows the `DFF` to easily store and retrieve context data in a format that is highly scalable +and easy to work with. + +Redis is an open-source, in-memory data structure store that is known for its +high performance and scalability. It stores data in key-value pairs and supports a variety of data +structures such as strings, hashes, lists, sets, and more. +Additionally, Redis can be used as a cache, message broker, and database, making it a versatile +and powerful choice for data storage and management. """ import json from typing import Hashable diff --git a/dff/context_storages/shelve.py b/dff/context_storages/shelve.py index d8b8c8767..316504c67 100644 --- a/dff/context_storages/shelve.py +++ b/dff/context_storages/shelve.py @@ -1,7 +1,16 @@ """ Shelve ------ -Provides the shelve-based version of the :py:class:`.DBContextStorage`. +The Shelve module provides a shelve-based version of the :py:class:`.DBContextStorage` class. +This class is used to store and retrieve context data in a shelve format. +It allows the `DFF` to easily store and retrieve context data in a format that is efficient +for serialization and deserialization and can be easily used in python. + +Shelve is a python library that allows to store and retrieve python objects. +It is efficient and fast, but it is not recommended to use it to transfer data across different languages +or platforms because it's not cross-language compatible. +It stores data in a dbm-style format in the file system, which is not as fast as the other serialization +libraries like pickle or JSON. """ import pickle from shelve import DbfilenameShelf diff --git a/dff/context_storages/sql.py b/dff/context_storages/sql.py index a3813ac81..0e8048b69 100644 --- a/dff/context_storages/sql.py +++ b/dff/context_storages/sql.py @@ -1,8 +1,16 @@ """ SQL --- -Provides the SQL-based version of the :py:class:`.DBContextStorage`. -You can choose the backend option of your liking from MySQL, PostgreSQL, or SQLite. +The SQL module provides a SQL-based version of the :py:class:`.DBContextStorage` class. +This class is used to store and retrieve context data from SQL databases. +It allows the `DFF` to easily store and retrieve context data in a format that is highly scalable +and easy to work with. + +The SQL module provides the ability to choose the backend of your choice from +MySQL, PostgreSQL, or SQLite. You can choose the one that is most suitable for your use case and environment. +MySQL and PostgreSQL are widely used open-source relational databases that are known for their +reliability and scalability. SQLite is a self-contained, high-reliability, embedded, full-featured, +public-domain, SQL database engine. """ import asyncio import importlib diff --git a/dff/context_storages/ydb.py b/dff/context_storages/ydb.py index c446becb9..16a9710a0 100644 --- a/dff/context_storages/ydb.py +++ b/dff/context_storages/ydb.py @@ -1,7 +1,13 @@ """ Yandex DB --------- -Provides the version of the :py:class:`.DBContextStorage` for Yandex DataBase. +The Yandex DB module provides a version of the :py:class:`.DBContextStorage` class that designed to work with +Yandex and other databases. Yandex DataBase is a fully-managed cloud-native SQL service that makes it easy to set up, +operate, and scale high-performance and high-availability databases for your applications. + +The Yandex DB module uses the Yandex Cloud SDK, which is a python library that allows you to work +with Yandex Cloud services using python. This allows the DFF to easily integrate with the Yandex DataBase and +take advantage of the scalability and high-availability features provided by the service. """ import asyncio import os diff --git a/dff/messengers/common/interface.py b/dff/messengers/common/interface.py index 232703cc2..9d0eb4892 100644 --- a/dff/messengers/common/interface.py +++ b/dff/messengers/common/interface.py @@ -1,7 +1,8 @@ """ Message Interfaces ------------------ -This module contains several basic classes of message interfaces. +The Message Interfaces module contains several basic classes that define the message interfaces. +These classes provide a way to define the structure of the messengers that are used to communicate with the `DFF`. """ import abc import asyncio diff --git a/dff/messengers/common/types.py b/dff/messengers/common/types.py index 1fc477685..7c9275a93 100644 --- a/dff/messengers/common/types.py +++ b/dff/messengers/common/types.py @@ -1,8 +1,9 @@ """ Types ----- -This module contains two special types. -One is used for the messenger interface to client interaction, the other to the polling loop control. +The Types module contains two special types that are used throughout the `DFF Messengers`. +The first type is used for the messenger interface to client interaction and the second one +to control the polling loop. """ from typing import Callable, Any, Hashable, Awaitable from typing_extensions import TypeAlias @@ -13,7 +14,7 @@ PipelineRunnerFunction: TypeAlias = Callable[[Any, Hashable], Awaitable[Context]] """ A function type for messenger_interface-to-client interaction. -Accepts anything (user input) and hashable vaklue (current dialog id), returns string (answer from pipeline). +Accepts anything (user input) and hashable value (current context id), returns string (answer from pipeline). """ diff --git a/dff/pipeline/conditions.py b/dff/pipeline/conditions.py index 00f5d6fd9..c042f90cb 100644 --- a/dff/pipeline/conditions.py +++ b/dff/pipeline/conditions.py @@ -1,6 +1,9 @@ """ Conditions ---------- +The conditions module contains functions that can be used to determine whether the pipeline component to which they +are attached should be executed or not. +The standard set of them allows user to setup dependencies between pipeline components. """ from typing import Optional diff --git a/dff/pipeline/pipeline/component.py b/dff/pipeline/pipeline/component.py index 2f199b1a3..5a1207543 100644 --- a/dff/pipeline/pipeline/component.py +++ b/dff/pipeline/pipeline/component.py @@ -1,7 +1,12 @@ """ Component --------- -The PipelineComponent class is defined in this module. +The Component module defines a :py:class:`.PipelineComponent` class, +which is a fundamental building block of the framework. A PipelineComponent represents a single +step in a processing pipeline, and is responsible for performing a specific task or set of tasks. + +The PipelineComponent class can be a group or a service. It is designed to be reusable and composable, +allowing developers to create complex processing pipelines by combining multiple components. """ import logging import abc diff --git a/dff/pipeline/pipeline/pipeline.py b/dff/pipeline/pipeline/pipeline.py index 382961178..25d041b65 100644 --- a/dff/pipeline/pipeline/pipeline.py +++ b/dff/pipeline/pipeline/pipeline.py @@ -1,7 +1,17 @@ """ Pipeline -------- -This module contains the Pipeline class. +The Pipeline module contains the :py:class:`.Pipeline` class, +which is a fundamental element of the `DFF`. The Pipeline class is responsible +for managing and executing the various components (:py:class:`.PipelineComponent`)which make up +the processing of messages from and to users. +It provides a way to organize and structure the messages processing flow. +The Pipeline class is designed to be highly customizable and configurable, +allowing developers to add, remove, or modify the components that make up the messages processing flow. + +The Pipeline class is designed to be used in conjunction with the :py:class:`.PipelineComponent` +class, which is defined in the Component module. Together, these classes provide a powerful and flexible way +to structure and manage the messages processing flow. """ import asyncio import logging diff --git a/dff/pipeline/pipeline/utils.py b/dff/pipeline/pipeline/utils.py index e5a85ff6f..6e735bf7d 100644 --- a/dff/pipeline/pipeline/utils.py +++ b/dff/pipeline/pipeline/utils.py @@ -1,7 +1,8 @@ """ Utils ----- -This module contains several service functions. +The Utils module contains several service functions that are commonly used throughout the framework. +These functions provide a variety of utility functionality. """ import collections from typing import Union, List, Callable diff --git a/dff/pipeline/service/extra.py b/dff/pipeline/service/extra.py index e3faed789..fc7f4796d 100644 --- a/dff/pipeline/service/extra.py +++ b/dff/pipeline/service/extra.py @@ -1,6 +1,9 @@ """ Extra Handler ------------- +The Extra Handler module contains additional functionality that extends the capabilities of the system +beyond the core functionality. Extra handlers is an input converting addition to :py:class:`.PipelineComponent`. +For examples, it is used to grep statistics from components, timeing, logging, etc. """ import asyncio import logging diff --git a/dff/pipeline/service/group.py b/dff/pipeline/service/group.py index 48259c4e9..a00a6b8f3 100644 --- a/dff/pipeline/service/group.py +++ b/dff/pipeline/service/group.py @@ -1,7 +1,11 @@ """ Service Group ------------- -This module contatins `ServiceGroup` class. This class represents a service group. +The Service Group module contains the +:py:class:`~.ServiceGroup` class, which is used to represent a group of related services. +This class provides a way to organize and manage multiple services as a single unit, +allowing for easier management and organization of the services within the pipeline. +The :py:class:`~.ServiceGroup` serves the important function of grouping services to work together in parallel. """ import asyncio import logging diff --git a/dff/pipeline/service/service.py b/dff/pipeline/service/service.py index 3215d8cc8..d75a93cc8 100644 --- a/dff/pipeline/service/service.py +++ b/dff/pipeline/service/service.py @@ -1,8 +1,16 @@ """ -Service Class -------------- -This module contains `Service` class. A description of the class is given below. +Service +------- +The Service module contains the :py:class:`.Service` class, +which can be included into pipeline as object or a dictionary. +Pipeline consists of services and service groups. +Service group can be synchronous or asynchronous. +Service is an atomic part of a pipeline. +Service can be asynchronous only if its handler is a coroutine. +Actor wrapping service can be synchronous only. """ +# TODO: change last sentence, when actor will be asynchronous + import logging import asyncio import inspect diff --git a/dff/pipeline/service/utils.py b/dff/pipeline/service/utils.py index a7fe54086..d76769319 100644 --- a/dff/pipeline/service/utils.py +++ b/dff/pipeline/service/utils.py @@ -1,7 +1,8 @@ """ Utility Functions ----------------- -These module contains several utility functions. +The Utility Functions module contains several utility functions that are commonly used throughout the `DFF`. +These functions provide a variety of utility functionality. """ import asyncio from typing import Callable, Any, Optional, Tuple, Mapping diff --git a/dff/pipeline/types.py b/dff/pipeline/types.py index 6d8ac72e7..06c32e2cb 100644 --- a/dff/pipeline/types.py +++ b/dff/pipeline/types.py @@ -1,7 +1,9 @@ """ Types ----- -This module contains several classes and special types (see below). +The Types module contains several classes and special types that are used throughout the `DFF Pipeline`. +The classes and special types in this module can include data models, +data structures, and other types that are defined for type hinting. """ from abc import ABC from enum import unique, Enum, auto diff --git a/dff/script/conditions/std_conditions.py b/dff/script/conditions/std_conditions.py index 7a9252c8b..44aa035d5 100644 --- a/dff/script/conditions/std_conditions.py +++ b/dff/script/conditions/std_conditions.py @@ -1,9 +1,12 @@ """ Conditions ---------------------------- -Conditions are one of the most important components of the dialog graph, -which determine the possibility of transition from one node of the graph to another. -This is a standard set of scripting conditions. +---------- +Conditions are one of the most important components of the dialog graph. +They determine the possibility of transition from one node of the graph to another. +The conditions are used to specify when a particular transition should occur, based on certain criteria. +This module contains a standard set of scripting conditions that can be used to control the flow of a conversation. +These conditions can be used to check the current context, the user's input, +or other factors that may affect the conversation flow. """ from typing import Callable, Pattern, Union, Any, List, Optional import logging @@ -21,10 +24,10 @@ def exact_match(match: Message, skip_none: bool = True, *args, **kwargs) -> Call """ Returns function handler. This handler returns `True` only if the last user phrase is the same Message as the :py:const:`match`. - If :py:const:`skip_none` the handler will not compare None fields of :py:const:`match`. + If :py:const:`skip_none` the handler will not compare `None` fields of :py:const:`match`. :param match: A Message variable to compare user request with. - :param skip_none: Whether fields should be compared if they are None in :py:const:`match`. + :param skip_none: Whether fields should be compared if they are `None` in :py:const:`match`. """ def exact_match_condition_handler(ctx: Context, actor: Actor, *args, **kwargs) -> bool: diff --git a/dff/script/core/actor.py b/dff/script/core/actor.py index c1d17ca94..2efe074d3 100644 --- a/dff/script/core/actor.py +++ b/dff/script/core/actor.py @@ -1,9 +1,21 @@ """ Actor ---------------------------- -Actor is one of the main abstractions that processes incoming requests -(:py:class:`~dff.script.Context`) -from the user in accordance with the dialog graph (:py:class:`~dff.script.Script`). +----- +Actor is a component of :py:class:`.Pipeline`, that contains the :py:class:`.Script` and handles it. +It is responsible for processing user input and determining the appropriate response based +on the current state of the conversation and the script. +The actor receives requests in the form of a :py:class:`.Context` class, which contains +information about the user's input, the current state of the conversation, and other relevant data. + +The actor uses the dialog graph, represented by the :py:class:`.Script` class, +to determine the appropriate response. The script contains the structure of the conversation, +including the different `nodes` and `transitions`. +It defines the possible paths that the conversation can take, and the conditions that must be met +for a transition to occur. The actor uses this information to navigate the graph +and determine the next step in the conversation. + +Overall, the actor acts as a bridge between the user's input and the dialog graph, +making sure that the conversation follows the expected flow and providing a personalized experience to the user. """ import logging from typing import Union, Callable, Optional, Dict, List, Any diff --git a/dff/script/core/context.py b/dff/script/core/context.py index 3714c8b0f..51a332b8f 100644 --- a/dff/script/core/context.py +++ b/dff/script/core/context.py @@ -1,9 +1,20 @@ """ Context ---------------------------- -Data structure that is used for the context storage. -It provides a convenient interface for working with data: -adding data, data serialization, type checking etc. +------- +A Context is a data structure that is used to store information about the current state of a conversation. +It is used to keep track of the user's input, the current stage of the conversation, and any other +information that is relevant to the current context of a dialog. +The Context provides a convenient interface for working with data, allowing developers to easily add, +retrieve, and manipulate data as the conversation progresses. + +The Context data structure provides several key features to make working with data easier. +Developers can use the context to store any information that is relevant to the current conversation, +such as user data, session data, conversation history, or etc. +This allows developers to easily access and use this data throughout the conversation flow. + +Another important feature of the context is data serialization. +The context can be easily serialized to a format that can be stored or transmitted, such as JSON. +This allows developers to save the context data and resume the conversation later. """ import logging from uuid import UUID, uuid4 @@ -226,7 +237,8 @@ def last_response(self) -> Optional[Message]: return self.responses.get(last_index) def set_last_response(self, response: Optional[Message]): - """Sets the last `response` of the current :py:class:`~dff.core.engine.core.context.Context`. + """ + Sets the last `response` of the current :py:class:`~dff.core.engine.core.context.Context`. Required for use with various response wrappers. """ last_index = get_last_index(self.responses) @@ -236,13 +248,14 @@ def set_last_response(self, response: Optional[Message]): def last_request(self) -> Optional[Message]: """ Returns the last `request` of the current :py:class:`~dff.script.Context`. - Returns `None if `requests` is empty. + Returns `None` if `requests` is empty. """ last_index = get_last_index(self.requests) return self.requests.get(last_index) def set_last_request(self, request: Optional[Message]): - """Sets the last `request` of the current :py:class:`~dff.core.engine.core.context.Context`. + """ + Sets the last `request` of the current :py:class:`~dff.core.engine.core.context.Context`. Required for use with various request wrappers. """ last_index = get_last_index(self.requests) diff --git a/dff/script/core/keywords.py b/dff/script/core/keywords.py index 78b023869..471d5834b 100644 --- a/dff/script/core/keywords.py +++ b/dff/script/core/keywords.py @@ -1,7 +1,9 @@ """ Keywords ---------------------------- -Keywords are used to define the dialog graph. +-------- +Keywords are used to define the dialog graph, which is the structure of a conversation. +They are used to determine all nodes in the script and to assign python objects and python functions for nodes. + """ from enum import Enum, auto diff --git a/dff/script/core/message.py b/dff/script/core/message.py index e211fe1f7..dcee94756 100644 --- a/dff/script/core/message.py +++ b/dff/script/core/message.py @@ -1,10 +1,8 @@ """ -Dialog Flow Generics --------------------- - -This module contains a universal response model that should be supported in all `dff` add-ons. -It only contains types and properties that are compatible with most messaging services. -On the other hand, it can support service-specific ui models. +Message +------- +The :py:class:`.Message` class is a universal data model for representing a message that should be supported by +`DFF`. It only contains types and properties that are compatible with most messaging services. """ from typing import Any, Optional, List, Union from enum import Enum, auto @@ -91,6 +89,10 @@ class Keyboard(DataModel): class Message(DataModel): + """ + Class representing a message and contains several class level variables to store message information. + """ + text: Optional[str] = None commands: Optional[List[Command]] = None attachments: Optional[Attachments] = None diff --git a/dff/script/core/normalization.py b/dff/script/core/normalization.py index 848b6780f..4329768ce 100644 --- a/dff/script/core/normalization.py +++ b/dff/script/core/normalization.py @@ -1,7 +1,9 @@ """ Normalization ---------------------------- -A basic set of functions for normalizing data in a dialog script is placed here. +------------- +Normalization module is used to normalize all python objects and functions to a format +that is suitable for script and actor execution process. +This module contains a basic set of functions for normalizing data in a dialog script. """ import logging diff --git a/dff/script/core/script.py b/dff/script/core/script.py index 6a3dac89f..65eecf7ec 100644 --- a/dff/script/core/script.py +++ b/dff/script/core/script.py @@ -1,7 +1,9 @@ """ Script ---------------------------- -Here is a set of `pydantic` models for the dialog graph. +------ +The Script module provides a set of `pydantic` models for representing the dialog graph. +These models are used to define the conversation flow, and to determine the appropriate response based on +the user's input and the current state of the conversation. """ # %% diff --git a/dff/script/core/types.py b/dff/script/core/types.py index 234429b42..75f9a2285 100644 --- a/dff/script/core/types.py +++ b/dff/script/core/types.py @@ -1,7 +1,10 @@ """ Types ---------------------------- -Basic types are defined here. +----- +The Types module contains a set of basic data types that +are used to define the expected input and output of various components of the framework. +The types defined in this module include basic data types such as strings +and lists, as well as more complex types that are specific to the framework. """ from typing import Union, Callable, Tuple from enum import Enum, auto diff --git a/dff/script/labels/std_labels.py b/dff/script/labels/std_labels.py index 7bcdbbd75..0c2c99d9a 100644 --- a/dff/script/labels/std_labels.py +++ b/dff/script/labels/std_labels.py @@ -1,11 +1,14 @@ """ Labels ---------------------------- -:py:const:`Labels ` are one of -the most important components of the dialog graph, -which determine targeted node name of transition. -This is a standard set of scripting -:py:const:`labels `. +------ +:py:const:`Labels ` are one of the important components of the dialog graph, +which determine the targeted node name of the transition. +They are used to identify the next step in the conversation. +Labels can also be used in combination with other conditions, +such as the current context or user data, to create more complex and dynamic conversations. + +This module contains a standard set of scripting :py:const:`labels ` that +can be used by developers to define the conversation flow. """ from typing import Optional, Callable from dff.script import Actor, Context, NodeLabel3Type @@ -13,9 +16,9 @@ def repeat(priority: Optional[float] = None, *args, **kwargs) -> Callable: """ - Returns transition handler that takes :py:class:`~dff.script.Context`, - :py:class:`~dff.script.Actor` and :py:const:`priority `. - This handler returns a :py:const:`label ` + Returns transition handler that takes :py:class:`.Context`, + :py:class:`.Actor` and :py:const:`priority `. + This handler returns a :py:const:`label ` to the last node with a given :py:const:`priority `. If the priority is not given, `Actor.label_priority` is used as default. diff --git a/dff/script/responses/std_responses.py b/dff/script/responses/std_responses.py index 7132f1604..ae9119fbd 100644 --- a/dff/script/responses/std_responses.py +++ b/dff/script/responses/std_responses.py @@ -1,9 +1,12 @@ """ Responses ---------------------------- -Responses are one of the most important components of the dialog graph, -which determine response for each node of a dialog graph. -This is a standard set of responses. +--------- +Responses determine the response that will be sent to the user for each node of the dialog graph. +Responses are used to provide the user with information, ask questions, +or guide the conversation in a particular direction. + +This module provides only one predefined response function that can be used to quickly +respond to the user and keep the conversation flowing. """ import random from typing import List diff --git a/dff/utils/testing/response_comparers.py b/dff/utils/testing/response_comparers.py index 0e4317229..1dd3d453d 100644 --- a/dff/utils/testing/response_comparers.py +++ b/dff/utils/testing/response_comparers.py @@ -7,9 +7,9 @@ def default_comparer(candidate: Message, reference: Message, _: Context) -> Opti """ The default response comparer. Literally compares two response objects. - :param candidate: the received (candidate) response - :param reference: the true (reference) response - :param _: current Context (unused) - :return: None if two responses are equal or candidate response otherwise + :param candidate: The received (candidate) response. + :param reference: The true (reference) response. + :param _: Current Context (unused). + :return: `None` if two responses are equal or candidate response otherwise. """ return None if candidate == reference else candidate diff --git a/docs/source/about_us.rst b/docs/source/about_us.rst index 15c2f9452..c71742d47 100644 --- a/docs/source/about_us.rst +++ b/docs/source/about_us.rst @@ -1,6 +1,9 @@ About us -------- -`DFF` is developed by the DeepPavlov development team (aka MIPT Neural Systems and Deep Learning Laboratories): +Dilog Flow Framework is developed by the DFF development department of `DeepPavlov `_ +(aka MIPT Neural Systems and Deep Learning Laboratories). -Denis Kuznetsov, etc. \ No newline at end of file +Founder and leader of the project -- Denis Kuznetsov. + +Developers -- Roman Zlobin, Aleksandr Sergeev, Daniil Ignatiev, Aleksandr Sakharov. \ No newline at end of file diff --git a/docs/source/conf.py b/docs/source/conf.py index 09ec8b26c..00908fcf7 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -130,10 +130,10 @@ def setup(_): generate_example_links_for_notebook_creation( [ - "examples/script/*.py", - "examples/pipeline/*.py", "examples/context_storages/*.py", - "examples/messengers/*.py", + "examples/pipeline/*.py", + "examples/script/*.py", + "examples/utils/*.py", ] ) regenerate_apiref( diff --git a/docs/source/documentation.rst b/docs/source/documentation.rst index 467f28bfa..9fe686bab 100644 --- a/docs/source/documentation.rst +++ b/docs/source/documentation.rst @@ -6,4 +6,110 @@ Documentation :glob: :maxdepth: 1 - apiref/index_* \ No newline at end of file + apiref/index_* + + + +Context Storages +~~~~~~~~~~~~~~~~ + +Context Storages allow you to save and retrieve user dialogue states +(in the form of a `Context` object) using various database backends. +The following backends are currently supported: + +- **Redis:** Provides a Redis-based version of the :py:class:`.DBContextStorage` class. + +- | **Protocol:** This module contains base protocol code. Supported protocols fot db: + shelve, json, pickle, sqlite, redis, mongodb, mysql, postgresql, grpc, grpcs. + +- | **SQL:** Provides a SQL-based version of the DBContextStorage class. + It allows the user to choose the backend option of his liking from MySQL, PostgreSQL, or SQLite. + +- **Mongo:** Provides a MongoDB-based version of the DBContextStorage class. + +- **JSON:** Provides a JSON-based version of the DBContextStorage class. + +- **Pickle:** Provides a pickle-based version of the DBContextStorage class. + +- **Database:** This module contains the Database class which is used to store and retrieve context data. + +- **Shelve:** Provides a shelve-based version of the DBContextStorage class. + +- | **Yandex DB:** Provides a version of the DBContextStorage class that is specifically designed + to work with Yandex DataBase. + + +Messenger Interfaces +~~~~~~~~~~~~~~~~~~~~ + +- | **Message Interfaces:** This module contains several basic classes of message interfaces. + These classes provide a standardized way of interacting with different messaging services, + allowing the application to work with multiple messaging platforms seamlessly. + +- | **Telegram interface:** This package contains classes and functions specific + to the Telegram messenger service. It provides an interface for the application to interact with Telegram, + allowing it to send and receive messages, handle callbacks, and perform other actions. + +- | **Types:** This module contains special types that are used for the messenger interface to client interaction. + These types are used to define the format of messages and other data that is exchanged between the + application and the messaging service. + + +Pipeline +~~~~~~~~ + +- | **Conditions:** The conditions module contains functions that can be used to determine whether the pipeline + component to which they are attached should be executed or not. + +- | **Service Group:** This module contains the :py:class:`.ServiceGroup` class. This class represents a group + of services that can be executed together in a specific order. + +- **Component:** This module contains the :py:class:`.PipelineComponent` class, which can be group or a service. + +- | **Pipeline:** This module contains the :py:class:`.Pipeline` class. This class represents the main pipeline of + the DFF and is responsible for managing the execution of services. + +- | **Service:** This module contains the :py:class:`.Service` class, + which can be included into pipeline as object or a dictionary. + +Script +~~~~~~ + +- | **dff.script.extras.slots package:** This package contains classes and functions specific to the use of slots + in a dialog script. + +- | **Conditions:** This module contains a standard set of scripting conditions that + can be used to control the flow of a conversation. + +- | **Message:** This module contains a universal response model that is supported in `DFF`. + It only contains types and properties that are compatible with most messaging services and + can support service-specific UI models. + +- | **dff.script.extras.conditions package:** This package contains additional classes and functions that can be used + to define and check conditions in a dialog script. + +- | **Types:** This module contains basic types that are used throughout the `DFF`. + These types include classes and special types that are used to define the structure of data and the behavior + of different components in the pipeline. + +- | **Script:** This module contains a set of pydantic models for the dialog graph. These models define the structure + of a dialog script. + +- | **Keywords:** This module contains a set of keywords that are used to define the dialog graph. + These keywords are used to specify the structure and behavior of a script, + such as the nodes and edges of the graph, and can be used to create custom scripts. + +- | **Responses:** This module contains a set of standard responses that can be used in a dialog script. + These responses can be used to specify the text, commands, attachments, and other properties + of a message that will be sent to the user. + +- | **Context:** This module contains the :py:class:`.Context` class, which is used for the context storage. + It provides a convenient interface for working with data, adding data, data serialization, type checking ,etc. + +- | **Labels:** This module contains labels that define the target name of the transition node. + +- | **Actor:** This module contains the :py:class:`.Actor` class. + It is one of the main abstractions that processes incoming requests + from the user in accordance with the dialog graph. + +- **Normalization:** This module contains a basic set of functions for normalizing data in a dialog script. diff --git a/docs/source/get_started.rst b/docs/source/get_started.rst index e0eb06363..0b4b4b8ce 100644 --- a/docs/source/get_started.rst +++ b/docs/source/get_started.rst @@ -4,39 +4,75 @@ Getting started Installation ~~~~~~~~~~~~ -`DFF` can be installed via ``pip``: +`DFF` can be easily installed on your system using the ``pip`` package manager: .. code-block:: console - + pip install dff -and supports Python 3.7 and newer. You can also download the library from `Github `_: +This framework is compatible with Python 3.7 and newer versions. + +The above command will set the minimum dependencies to start working with DFF. +The installation process allows the user to choose from different packages based on their dependencies, which are: + +.. code-block:: console + + pip install dff[core] # minimal dependencies (by default) + pip install dff[redis] # dependencies for using Redis + pip install dff[mongodb] # dependencies for using MongoDB + pip install dff[mysql] # dependencies for using MySQL + pip install dff[postgresql] # dependencies for using PostgreSQL + pip install dff[sqlite] # dependencies for using SQLite + pip install dff[ydb] # dependencies for using Yandex Database + pip install dff[full] # full dependencies including all options above + pip install dff[tests] # dependencies for running tests + pip install dff[test_full] # full dependencies for running all tests (all options above) + pip install dff[examples] # dependencies for running examples (all options above) + pip install dff[devel] # dependencies for development + pip install dff[doc] # dependencies for documentation + pip install dff[devel_full] # full dependencies for development (all options above) + +For example, if you are going to use one of the database backends, +you can specify the corresponding requirements yourself. + +Additionally, you also have the option to download the source code directly from the +`GitHub `_ repository using the commands: .. code-block:: console git clone https://github.com/deeppavlov/dialog_flow_framework.git cd dialog_flow_framework - make venv -The last command will set up all requirements. If requirements need to be updated, use the command ``make clean`` before ``make venv``. +Once you are in the directory, you can run the command ``make venv`` to set up all the necessary requirements for the library. +If you need to update the requirements, use the command ``make clean`` to remove `venv` first. Key concepts ~~~~~~~~~~~~ -`DFF` allows you to write conversational services. The service is written by defining a special dialog graph -that describes the behavior of the dialog service. `DFF` offers a Specialized Language (`DSL`) for quickly writing dialog graphs. -You can use it to write chatbots for social networks, call centers, websites, writing skills for Amazon Alexa, etc. +DFF is a powerful tool for creating conversational services. +It allows developers to easily write and manage dialog systems by defining a special +dialog graph that describes the behavior of the service. +DFF offers a specialized language (DSL) for quickly writing dialog graphs, +making it easy for developers to create chatbots for a wide +range of applications such as social networks, call centers, websites, skills for Amazon Alexa, etc. -`DFF` has the following important concepts: +DFF has several important concepts: -**Script**: First of all, to create a dialog agent it is necessary to create a dialog (:py:class:`~dff.script.core.script.Script`). -A dialog `script` is a dictionary, where keys correspond to different `flows`. A script can contain multiple `scripts`, what is needed in order to divide +**Script**: First of all, to create a dialog agent it is necessary +to create a dialog :py:class:`~dff.script.core.script.Script`. +A dialog `script` is a dictionary, where keys correspond to different `flows`. +A script can contain multiple scripts, which are flows too, what is needed in order to divide a dialog into sub-dialogs and process them separately. -**Flow**: As mentioned above, the dialog is divided into `flows`. -Each `flow` represent a sub-dialog corresponding to the discussion of a particular topic. -Each `flow` is also a dictionary, where the keys are the `nodes`. +**Flow**: As mentioned above, the dialog is divided into flows. +Each flow represent a sub-dialog corresponding to the discussion of a particular topic. +Each flow is also a dictionary, where the keys are the `nodes`. + +**Node**: A `node` is the smallest unit of a dialog flow, and it contains the bot's response +to a user's input as well as a `condition` that determines +the `transition` to another node, whether it's within the current or another flow. -**Node**: Each `node` necessarily contains a `response` of the bot and -the `condition` of `transition` to another `node` -in this or another `flow`. +**Keywords**: DFF uses several special `keywords`. These keywords are the keys in the dictionaries inside the script. +The most important for using the framework are `RESPONSE` and `TRANSITIONS` keywords. +The first one corresponds to the response that the bot will send to the user from the current node. +The second corresponds to the transition conditions from the current node to other nodes. \ No newline at end of file diff --git a/docs/source/index.rst b/docs/source/index.rst index 0684be89c..8542fc10f 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -7,12 +7,12 @@ Dialog Flow Framework *Date*: |today| *Version*: |version| -The Dialog Flow Framework (`DFF`) is an open-source, `Apache 2.0 `_-licensed library -that was developed specifically for creating dialog systems. `DFF` provides a comprehensive set of tools and resources for building conversational systems +The Dialog Flow Framework (DFF) is an open-source, `Apache 2.0 `_-licensed library +that was developed specifically for creating dialog systems. DFF provides a comprehensive set of tools and resources for building conversational systems for a wide range of applications, including chatbots, virtual assistants, and other interactive systems. It allows developers to easily create and manage complex dialog flows, integrate with natural language processing (NLP) tools, and handle user input in a flexible and efficient manner. Additionally, the framework is highly customizable, -allowing developers to easily adapt it to their specific needs and requirements. +allowing developers to easily adapt it to their specific needs and requirements. .. toctree:: :maxdepth: 1