Dependencies

Developing complex projects with multiple themes, dictionaries, and script extensions can become unwieldy and inefficient if the project code is stored in one script. Instead, JAICP supports separating the script code into isolated components and importing them into the main script as dependencies. This approach has several advantages:

• Modular architecture makes it easier to develop and support the project.
• A single dependency can be imported into several projects at once.

There are two ways to add dependencies:

• As local modules. The code of local modules is stored in the same project as the main script.
• As external dependencies from remote repositories.

tip

You can also use system modules as dependencies. They contain a number of ready-made named patterns, functions, etc., which can be imported into JAICP projects without any extra setup.

Local modules

Local modules are useful when one large script within one project should be split into multiple smaller scripts.

Configuration

Dependencies are declared in the dependencies section of the chatbot.yaml configuration file. For local modules, specify the following properties:

Property	Description	Value
name	The name by which the dependency is imported into the script	The dependency directory name
type	Dependency type	module

Project structure

Suppose there is a project consisting of two files:

• main.sc — the main script.
• offtopic.sc — the “chitchat”: answers to random frequently asked questions.

offtopic.sc may look like this:

patterns:
    $you = (you/your)

theme: /

    state: WhatCanYouDo
        q!: * what * {can $you do} *
        q!: * what * $you * (able/capable) [of] *
        q!: * (what/which) * {$you * (*abilit*/function*/service*)} *
        a: I can answer your questions.

The project directory structure is as follows:

├── chatbot.yaml
├── src
│   ├── main.sc
│   └── offtopic.sc
└── test
    └── test.xml

If the “chitchat” is expected to be later expanded with new functionality, such as a theme specifically covering the imaginary bot biography or functions used nowhere else in the script, it is recommended to split it into a separate module, independent from the main one.

In this case, two nested directories must be created in the root directory: one for the main script, e. g. main, and one for the dependency. All files relating to the dependency should be transferred into its directory, resulting in the following directory tree:

├── main
│   ├── chatbot.yaml
│   ├── src
│   │   └── main.sc
│   └── test
│       └── test.xml
└── offtopic
    └── src
        └── offtopic.sc

tip

Dependencies do not require the presence of chatbot.yaml or XML tests.

Dependency import

1. Go to the project editing menu. On the Location tab, change the Folder to the name of the new project root directory: main.

   caution

   If you cannot see the Folder setting on this tab, contact your account manager.

2. Create the dependencies section in chatbot.yaml if it doesn’t exist yet. Add a new dependency with the module type and a name matching the new directory name:

   dependencies:
     - name: offtopic
       type: module

3. Using the require tag, import the required file from this dependency into main.sc:

   require: offtopic.sc
       module = offtopic
   
   theme: /
   
       state: You
           q!: * $you *
           a: I see that you are referring to me, but I understand little else.
   
       state: CatchAll
           q!: *
           a: I’m sorry, I didn’t get it.

The content of the imported file will now become accessible from the main script: in this case, it includes the WhatCanYouDo state and the $you named pattern.

External dependencies

If a project module contains some standard functionality which may come in handy in many different projects, it is recommended to move it to a separate Git repository. This module can then be reused in other projects as an external dependency. Such dependencies may contain things like ready-made script fragments, frequently used functions, or dictionaries.

Configuration

Dependencies are declared in the dependencies section of the chatbot.yaml configuration file. For external dependencies, specify the following properties:

Property	Description	Value
name	The name by which the dependency is imported into the script	An arbitrary string
type	Dependency type	git
url	The external repository URL	A string beginning with https://, git://, or file://
version	The name of the necessary branch in the repository	<branch> or heads/<branch>
loginSecretKey	The login to an account with access to the repository	The name of the secret containing the loginSecretKey value
tokenSecretKey	A personal access token allowing access to the repository	The name of the secret containing the tokenSecretKey value

danger

You only need to provide loginSecretKey and tokenSecretKey if the dependency is stored in a private repository. Also be aware of the following requirements:

1. You cannot use your account password as the tokenSecretKey value. Instead, you need to issue a personal access token which allows read access to the necessary repository. Learn more about obtaining a token for Bitbucket, GitHub, and GitLab.
2. To protect your data, you cannot specify the login or the token directly in chatbot.yaml. Instead, they need to be stored in the JAICP secrets storage. Use the names of secrets where the necessary values are stored as the values for loginSecretKey and tokenSecretKey.

Project structure

Consider the example of offtopic.sc illustrated above.

1. Create a directory for a new repository.

2. Create the src subdirectory and move offtopic.sc inside it:

   └── src
       └── offtopic.sc

3. Initialize a Git repository in the project root directory and commit the changes into version control.

4. Publish the repository on any external hosting service, such as Bitbucket, GitLab, or GitHub.

Dependency import

1. If the repository with the dependency code is private, go to Secrets and variables and create two secrets for the login and the personal access token: for example, GITHUB_LOGIN_SECRET and GITHUB_TOKEN_SECRET.

2. Create the dependencies section in chatbot.yaml if it doesn’t exist yet. Add a new dependency with the git type and the repository connection properties:

   dependencies:
     - name: offtopic
       type: git
       url: https://github.com/example/offtopic
       version: master
       # If the repository is private:
       loginSecretKey: GITHUB_LOGIN_SECRET
       tokenSecretKey: GITHUB_TOKEN_SECRET

3. Using the require tag, import the required file from this dependency into main.sc:

   require: offtopic.sc
       module = offtopic

The content of the imported file will now become accessible from the main script.

tip

You can view the contents of all external dependencies connected to the project in the code editor.