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:
Pure-Python DSL for dialog scripting.
Under Apache 2.0 license. (GitHub)
Supports custom state management, transitions, conditions, and response templates.
Suitable for websites, call-centres, social networks, and personal assistants. (GitHub)
This article provides: background, architecture breakdown, step-by-step walkthrough, code snippets, use-cases, limitations, fixes, FAQs, and a publishing checklist.
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:
A script data structure (Python dict) defines flows, nodes, and transitions.
A pipeline object (Pipeline) manages execution of the script.
Condition functions (e.g., ExactMatch, RegexMatch) determine transition eligibility.
Global and flow-scoped sections support modular dialog definition.
State is managed internally via a simple dictionary.
The framework is pure Python, so customizable and extensible. (GitHub)
Why use Chatsky?
You get a scripting language (DSL) built into Python: less boilerplate code.
For developers familiar with Python, this is more accessible.
Because it’s open source, you can extend conditions, responses, transitions, and integrate your own logic.
Active maintenance: the repo shows recent commits and release (v0.10.0 as of Feb 18, 2025). (GitHub)
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:
We import key classes and constants.
script has a GLOBAL section defining transitions that apply from the global state.
Two transitions: one if the user input exactly matches “Hi” leads to ("flow","node_hi"), otherwise default to ("flow","node_ok").
In the “flow” section, we define two nodes: node_hi responds “Hi!” and node_ok responds “OK”.
We initialise the Pipeline with the script and a start label.
run() executes (simplified).
(GitHub)
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
Customer-service chatbots: define flows like greeting, FAQs, escalation, using Chatsky DSL.
Call-centre automation: embed in voice or text channels, integrate with CRM via backend logic.
Social-network chatbots: Messenger, Telegram bots using chatsky[telegram] extra.
Internal assistant: an enterprise tool that guides employees via chat.
On-device or edge scenarios: because it's pure Python, potential use in local/edge deployments (though scale must be evaluated).
Limitations / Considerations
Chatsky uses a rule/graph-based dialog model; it is not a large-language-model (LLM) style generative agent. For open-ended conversation, you may need to integrate external LLMs.
State management: while it supports dictionary-based state, complex multi-turn contexts (with memory, embeddings) may require custom extensions.
Scalability: For very high-volume production deployments, you’ll need proper infrastructure (Redis/back-end, horizontal scaling).
Learning curve: While easier than building from scratch, you still need to design dialog graphs, transitions,and conditions.
Channel integrations: You may need custom wrappers for new channels beyond built-ins.
Version & community size: Relatively smaller star-count (65 stars) and forks (12) at time of writing — implies smaller community ecosystem. (GitHub)
Fixes (common pitfalls with solutions)
Pitfall: Transition conditions never trigger.
Fix: Check that your condition function (e.g., cnd.ExactMatch("Hi")) matches the user input exactly, including casing. Consider adding cnd.LowerExactMatch or normalizing.
Pitfall: State variables not persisting across turns.
Fix: Ensure you pass the correct state dict or use the persistence layer (Redis/Mongo) if you need it across sessions.
Pitfall: Complex flows become hard to manage.
Fix: Modularise scripts into multiple flows, use naming conventions, and document transitions. Use code comments to clarify nodes.
Pitfall: Response callback functions cause exceptions.
Fix: Wrap backend logic with try-catch, ensure returned value is compatible (string or appropriate type).
Pitfall: Integration channel drops messages.
Fix: Validate your adapter (e.g., Telegram) is passing messages to pipeline correctly; log input & output.
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.