#chatbot #programming-language #csml

csml_engine

The CSML Engine is a conversational engine designed to make it extremely easy to create rich and powerful chatbots

28 releases (16 stable)

new 1.7.0-beta3 Sep 18, 2021
1.7.0-beta2 Sep 14, 2021
1.6.4 Jul 9, 2021
1.6.3 Jun 4, 2021
1.3.5 Oct 30, 2020

#38 in Text processing

Download history 30/week @ 2021-06-01 24/week @ 2021-06-08 8/week @ 2021-06-22 1/week @ 2021-06-29 18/week @ 2021-07-06 1/week @ 2021-07-13 52/week @ 2021-07-20 51/week @ 2021-07-27 28/week @ 2021-08-03 42/week @ 2021-08-10 1/week @ 2021-08-17 1/week @ 2021-08-24 61/week @ 2021-09-14

81 downloads per month

Apache-2.0

1MB
24K SLoC


CSML

First programming language dedicated to building chatbots.

Rust GitHub release (latest by date) Docker Image Version (latest semver) Slack

Key FeaturesExampleGetting startedAdditional Information

Try CSML online

CSML-demo

CSML (Conversational Standard Meta Language) is both a domain-specific programming language and chatbot engine, designed to make it easy to develop complex chatbots.

With a very expressive and text-only syntax, CSML flows are easy to understand, making it easy to deploy and maintain conversational agents. CSML handles short and long-term memory slots, metadata injection, and connecting to any third party API or injecting arbitrary code in any programming language thanks to its powerful runtime APIs.

Key Features

  • Text-only, expressive syntax, easy to learn and develop complex chatbot scenarios with
  • Rich and extensible conversational components such as Carousel, Image, Video, Button, Card, Input, Calendar...
  • Built-in short-term and long-term memory slots: no more complex state machine boilerplate
  • Portable, fast, and easy to deploy: it only requires a MongoDB database (or AWS account for serverless version)
  • Vibrant community of over 5000 active CSML developers

Example

start:
  say "Hi, nice to meet you, I'm a demo bot 👋"
  if (name) {
    say "I already know you 😉"
    goto known
  }
  else 
    goto name

name:
  say Question(
    "I'd like to know you better, what's your name?",
    buttons=[
      Button("I'm anonymous 😎", accepts=["No", "Nope"]) as anonBtn
    ],
  )
  hold
  if (event.match(anonBtn)) {
    remember name = "anon"
  } else {
    remember name = event
  }
  goto known

known:
  if (name == "anon")
    say "...but I know you don't want to say too much about yourself!"
  else 
    say "You are {{name}}!"
  goto end

The full documentation is available on https://docs.csml.dev/language.

Getting Started

The simplest way to get started with CSML is to use CSML Studio, a free online development environment with everything already setup to start creating bots right away, directly in your browser.

To get started with CSML Studio: https://studio.csml.dev

CSML Studio gives you a free playground to experiment with the language as well as options to deploy your chatbots at scale in one-click.

Self-hosted / cloud / local installation

CSML is available as a self-hostable web server that you can easily install with one of the options below.

Note that you will need a database. The default choice is MongoDB, but Amazon DynamoDB and *PostgreSQL are also available by choosing the dynamodb or postgresql engine DB type with a slightly different set of environment variables.

Before you start, make sure that you have the environment set with following options:

ENGINE_DB_TYPE=mongodb # must be one of mongodb|dynamodb|postgresql

# for mongodb
MONGODB_HOST=localhost
MONGODB_PORT=27017
MONGODB_DATABASE=csml
MONGODB_USERNAME=root
MONGODB_PASSWORD=root

# for dynamodb
AWS_ACCESS_KEY_ID= # or use an IAM role
AWS_SECRET_ACCESS_KEY= # or use an IAM role
AWS_REGION=
AWS_DYNAMODB_ENDPOINT= # optional, defaults to the default dynamodb endpoint for the given region.
AWS_DYNAMODB_TABLE=
AWS_S3_ENDPOINT= # optional, defaults to the default S3 endpoint for the given region
AWS_S3_BUCKET=

# for postgresql
POSTGRESQL_URL=postgres://user:password@hostname:port/database

# CSML Server configuration
ENGINE_SERVER_PORT=5000
ENGINE_SERVER_API_KEYS=someAuthKey4CsmlServer,someOtherAuthKey

# Other optional engine configuration
ENGINE_ENCRYPTION_SECRET=some-secret-string # if not set, data will not be stored encrypted
TTL_DURATION=30 # auto-remove chatbot user data after X days
LOW_DATA_MODE=true # do not store contents of sent/received messages
DISABLE_SSL_VERIFY=false # reach trusted endpoints with known invalid certificates
DEBUG=true # print debug output in console

Deploy to Heroku

Deploy to Heroku

Using a ready-to-use binary (Linux and MacOS only)

The easiest way to launch a CSML Engine on your own machine is to use one of our pre-built, optimized binaries (available for both MongoDB and Amazon DynamoDB). These binaries are available as executables on each of CSML's releases since v1.3.0.

Follow the installation guide (for ubuntu, but the process will be similar on other operating systems) along on this blog post: https://blog.csml.dev/how-to-install-a-self-hosted-csml-engine-on-ubuntu-18-04/

To download the latest CSML Server binaries, head over to the latest release and make sure to download the right version for your architecture.

Mac users: upon first execution of this binary, Mac will probably open a warning about the application not being signed (more info from Apple). As this is not intended as a widely-distributed application, we decided to not go through the notarization process for now, but you can safely ignore that warning! However, if you prefer, you can always build this package from source.

With Docker

We provide a docker image for easy self-hosted usage.

docker pull clevy/csml-engine

To get started with CSML Engine on Docker: https://github.com/CSML-by-Clevy/csml-engine-docker

With Rust, from source

CSML is built in Rust. You don't need to know any Rust to run it though! Make sure you are running Rust v1.46+ and that you have openssl installed on your machine (or an equivalent for your linux distribution, such as libssl), then run:

cd csml_server

# for use with MongoDB
cargo build --release --features csml_engine/mongo

# for use with Amazon DynamoDB
cargo build --release --features csml_engine/dynamo

After that, execute your build (by default under ./targets/release/csml_server) and visit http://localhost:5000 for some request examples.

With Node.js

This repository provides Node.js bindings of this rust library. To use this library in a Node.js project, you will need to build it from source. There are a few requirements:

  • Rust v1.46
  • Node.js LTS or above
  • Neon CLI v0.4.0 (make sure that all required dependencies are installed)
  • libssl-dev (or equivalent for your architecture: openssl-dev, libssl-devel...)

To compile CSML Engine into a native node module, run:

git clone https://github.com/CSML-by-Clevy/csml-engine csml
neon build -p csml/bindings/node --release

If you are not familiar with Rust build times, please know that the neon build step can take up to 10 minutes. Be patient!

This method will output this native file: csml/bindings/node/native/index.node that you can simply require() (or import) in your project. For more details about how to use this module in your own projects, you can have a look at our implementation for Docker version.

Please note that if you plan to deploy your project on a different architecture, you will need to recompile the project on that architecture. We recommend using git submodules if you need to integrate CSML Engine in your own Node.js projects.

REST API documentation

CSML Server's HTTP REST API documentation is available in OpenAPIv3 format: swagger.yaml. To read this file easily, you can open it in Swagger Editor.

Additional Information

Play with the language

  • Studio - Create and deploy your chatbot in a matter of minutes.
  • Playground - Test and learn CSML in your browser.

Getting Help

Information

Dependencies

~37MB
~765K SLoC