Abstract / Overview

Chatsky is a free open-source software stack developed by DeepPavlov for building conversational agents (chatbots) using Python. (GitHub)
It supports a domain-specific language (DSL) for defining dialogs as a graph of states and transitions.
Key features:

Conceptual Background

chatsky-hero

What problem does Chatsky address?

In a typical chatbot project, you must handle: message receiving, parsing user intent, dialog state management, selecting response, integrating backend logic, and maintaining flow. Chatsky abstracts many of these via a DSL that defines flows (nodes), transitions, state dictionaries, and responses.

Architecture at a glance

At its core:

Why use Chatsky?

Step-by-Step Walkthrough

1. Installation

Install via pip:

pip install chatsky

If using database back-ends or telegram integration, you install extras, e.g.:

pip install chatsky[postgresql,mysql,telegram]

(GitHub)

2. Define a simple dialog script

Below is a minimal example (adapted):

from chatsky import GLOBAL, TRANSITIONS, RESPONSE, Pipeline, conditions as cnd, Transition as Tr

script = {
    GLOBAL: {
        TRANSITIONS: [
            Tr(dst=("flow", "node_hi"),
               cnd=cnd.ExactMatch("Hi")),
            Tr(dst=("flow", "node_ok"))
        ]
    },
    "flow": {
        "node_hi": {RESPONSE: "Hi!"},
        "node_ok": {RESPONSE: "OK"}
    },
}

pipeline = Pipeline(script, start_label=("flow","node_hi"))
pipeline.run()

Explanation:

3. Expand the dialog graph

You can define multiple flows (e.g., “greeting_flow”, “faq_flow”), nodes with actions besides static responses (e.g., calls to backend services), add context/state conditions, and transition priorities.

4. Integrate with messaging channel/deployment

After your dialog logic is defined, you can hook the pipeline into an interface: e.g., Telegram bot, web service endpoint, or chat widget. Chatsky supports back-end integrations (Redis, MongoDB, MySQL, PostgreSQL) via optional extras. (GitHub)

5. Monitor and test

You should implement unit tests for dialog flows (there is a tests/ directory in the repo). Use logging to track state transitions. Use benchmarking extras if needed (chatsky[benchmark]). (GitHub)

Code / JSON Snippets

JSON snippet for workflow (if storing a script externally)

{
  "GLOBAL": {
    "TRANSITIONS": [
      {
        "dst": ["flow", "node_hi"],
        "cnd": {
          "type": "ExactMatch",
          "value": "Hi"
        }
      },
      {
        "dst": ["flow", "node_ok"]
      }
    ]
  },
  "flow": {
    "node_hi": {
      "RESPONSE": "Hi!"
    },
    "node_ok": {
      "RESPONSE": "OK"
    }
  }
}

Assumption: You loaded this JSON and passed it to Pipeline after converting conditions appropriately.

Inline Python code snippet for a more advanced condition and response

from chatsky import Pipeline, GLOBAL, TRANSITIONS, RESPONSE, Transition as Tr, conditions as cnd

def custom_backend_action(ctx):
    # ctx is the state dict
    user_age = ctx.get('user_age', None)
    if user_age and user_age > 18:
        return "You are an adult user."
    return "You are a minor or unknown age."

script = {
    GLOBAL: {
        TRANSITIONS: [
            Tr(dst=("flow", "ask_age"),
               cnd=cnd.ExactMatch("Start")),
        ]
    },
    "flow": {
        "ask_age": {
            RESPONSE: "Please tell me your age.",
            TRANSITIONS: [
                Tr(dst=("flow","age_response"),
                   cnd=cnd.HasNumber())
            ]
        },
        "age_response": {
            RESPONSE: custom_backend_action
        }
    }
}

pipeline = Pipeline(script, start_label=("flow","ask_age"))
pipeline.run()

This snippet shows a callback function as RESPONSE allowing backend logic.

Use Cases / Scenarios

Limitations / Considerations

Fixes (common pitfalls with solutions)

FAQs

Q: Is Chatsky free for commercial use?
Yes. It is licensed under Apache 2.0. (GitHub)

Q: Does it require a specific backend database?
No. The core works with an in-memory state. Extras allow Redis, MongoDB, MySQL, PostgreSQL, and Yandex DB. (GitHub)

Q: Can I use it with LLMs like GPT-4?
Yes, but you must integrate calls to LLMs yourself (e.g., in a response callback) since Chatsky provides the flow/DSL, not the generative model.

Q: What Python versions are supported?
The repo indicates Python 3.9 or higher. (GitHub)

Q: How do I test a chatbot built with Chatsky?
You can write unit tests for the pipeline by simulating inputs and checking responses. Also use the tests/ directory for sample patterns.

References

Conclusion

Chatsky is a robust, Python-native framework for building conversational agents using a dialog graph DSL. It suits developers who prefer explicit flow control rather than purely generative models. It offers extensibility, various backend integrations, and production-orientation. Users should be aware of its rule-based nature and plan for scalability and complexity management. For many chatbot use-cases — especially defined dialog flows and domain-specific tasks — Chatsky offers a sound foundation.