<commit_before>Get Started
===========

This part of the doc will guide you through understanding the basics of how
Bernard works. There is of course more to add but this should cover the
fundamentals.

A good starting point is the [demobot](../demobot). In this documentation,
we'll go through the code of the bot and then we'll dig into the more
theoretical concepts.

It is a Facebook Messenger bot, which means that you'll only be able to talk
to it through Facebook and you'll need to setup a bot on their platform.

**TLDR**: I'm sorry, this page is as short as I can imagine it, you'll have to
read it all. No one-liner to start, that's a framework built for the real
world.

## Base code

The core of the bot is in two files:

- [`states.py`](../demobot/states.py) has the code of the bot for each state,
  that's basically the code that drives what the bot does
- [`transitions.py`](../demobot/transitions.py) lists the transitions between
  states. That's how you describe the user flow.

Other files are present for technical reasons:

- [`settings.py`](../demobot/settings.py) are simply the settings, which
  covers pretty much everything from the API tokens to any single timeout. To
  start a project, you only need to fill a few variables.
- [`__init__.py`](../demobot/__init__.py) makes the folder into a Python
  module, it's ok if it's empty.
- Language files. Those are subject to serious changes in the future, as
  currently the translation system is fare from being feature-complete.
    - [`i18n/fr/intents.csv`](../demobot/i18n/fr/intents.csv) are the intents,
      or rather the list of sentences the user might say to trigger a specific
      intent. More on that later.
    - [`i18n/fr/responses.csv`](../demobot/i18n/responses.csv) are the
      response strings we'll send to the user.

### Specs

This bot can be specified with the following diagram:

![demobot flow](./fsm-hello.svg)

Read it this way:

- The user can type the text "Hello" at any time. This will trigger the "Hello"
  state.
- The "Hello" state provides two quick replies (_"QR"_) to the user: "Yes" and
  "No". The user can click either of them.
- If the user chooses "Yes", the bot transitions to "Good".
- if the user chooses "No", the bot transitions to "TooBad".

Basically, it would look like:

- **User**: Hello
- **Bot**: Hello, are you all right?
- **User**: No
- **Bot**: That's your problem

As you can understand, you can trigger the "Hello" state from anywhere but you
can't go to "Good" if you're not on "Hello".

### Core files

As those files are the core of the bot, let's start with them.

#### `states.py`

Your bot needs a _base state_. This states defines the default behaviour of
your bot: what will it say when it does not understand user input or when
there is an internal error?<commit_msg>Fix SVG link<commit_after>Get Started
===========

This part of the doc will guide you through understanding the basics of how
Bernard works. There is of course more to add but this should cover the
fundamentals.

A good starting point is the [demobot](../demobot). In this documentation,
we'll go through the code of the bot and then we'll dig into the more
theoretical concepts.

It is a Facebook Messenger bot, which means that you'll only be able to talk
to it through Facebook and you'll need to setup a bot on their platform.

**TLDR**: I'm sorry, this page is as short as I can imagine it, you'll have to
read it all. No one-liner to start, that's a framework built for the real
world.

## Base code

The core of the bot is in two files:

- [`states.py`](../demobot/states.py) has the code of the bot for each state,
  that's basically the code that drives what the bot does
- [`transitions.py`](../demobot/transitions.py) lists the transitions between
  states. That's how you describe the user flow.

Other files are present for technical reasons:

- [`settings.py`](../demobot/settings.py) are simply the settings, which
  covers pretty much everything from the API tokens to any single timeout. To
  start a project, you only need to fill a few variables.
- [`__init__.py`](../demobot/__init__.py) makes the folder into a Python
  module, it's ok if it's empty.
- Language files. Those are subject to serious changes in the future, as
  currently the translation system is fare from being feature-complete.
    - [`i18n/fr/intents.csv`](../demobot/i18n/fr/intents.csv) are the intents,
      or rather the list of sentences the user might say to trigger a specific
      intent. More on that later.
    - [`i18n/fr/responses.csv`](../demobot/i18n/responses.csv) are the
      response strings we'll send to the user.

### Specs

This bot can be specified with the following diagram:

![demobot flow](https://raw.githubusercontent.com/BernardFW/bernard/develop/doc/fsm-hello.svg)

Read it this way:

- The user can type the text "Hello" at any time. This will trigger the "Hello"
  state.
- The "Hello" state provides two quick replies (_"QR"_) to the user: "Yes" and
  "No". The user can click either of them.
- If the user chooses "Yes", the bot transitions to "Good".
- if the user chooses "No", the bot transitions to "TooBad".

Basically, it would look like:

- **User**: Hello
- **Bot**: Hello, are you all right?
- **User**: No
- **Bot**: That's your problem

As you can understand, you can trigger the "Hello" state from anywhere but you
can't go to "Good" if you're not on "Hello".

### Core files

As those files are the core of the bot, let's start with them.

#### `states.py`

Your bot needs a _base state_. This states defines the default behaviour of
your bot: what will it say when it does not understand user input or when
there is an internal error?
{'fraction_non_alphanumeric': 0.0934480941507114, 'fraction_numerical': 0.002810468997013877, 'mean_word_length': 3.6595744680851063, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 1, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 4, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4496036', 'n_tokens_mistral': 1684, 'n_tokens_neox': 1622, 'n_words': 861}