Skip to content
This repository was archived by the owner on Sep 22, 2023. It is now read-only.

Commit 016e3dc

Browse files
lyudmil-pelovlyudmil-pelov
committed
- init code publishing
0 parents  commit 016e3dc

File tree

115 files changed

+12950
-0
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

115 files changed

+12950
-0
lines changed

‎.gitignore

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
.idea
2+
node_modules
3+
coverage
4+
dists
5+
pls
6+
dist
7+
.nyc_output
8+
*.tgz
9+
service-*
10+
package/
11+
build
12+
builds

‎.npmignore

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
*.tgz
2+
spec
3+
service-*
4+
package/
5+
.vscode
6+
builds
7+
docs
8+
pls
9+
spec
10+
jasmine*

‎COMPONENTS.md

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
# Custom Component Package
2+
3+
Copyright (c) 2020, Oracle and/or its affiliates.
4+
5+
This example is in format of a Component Package. Component Package is the recommended way to organize Bots Custom Components code. Component Package allows the custom component code to be more portable to different runtime environments.
6+
7+
A Component Package contains the component code of one or more custom components. The package as a unit can be embedded within a Component Service Wrapper to make up a complete Component Service. There are Component Service Wrappers for different runtime environments. The same component package can thus be used for running in different environments.
8+
9+
## Custom Component Package format
10+
11+
A Component Package consists of the following:
12+
13+
- package.json
14+
- main.js
15+
- .npmignore
16+
- component file(s)
17+
18+
### package.json
19+
20+
The package.json file needs to have a "main" entry that is entry point for the consuming wrapper application. The example "main" entry is "main.js".
21+
22+
The package.json file has an optional entry for "@oracle/bots-node-sdk" in devDependencies, as the Bots Node SDK could be used to assist dev/test of the component package. The runtime version of the SDK is specified by the service wrapper project package.json. In some runtime environments, if the service wrapper does not specify the sdk version, the version specified by the component package dev dependency will be inspected. Alternatively, the version spec of the SDK could also be listed in peerDependencies.
23+
24+
```javascript
25+
{
26+
"name": "custom-component-default-pkg",
27+
"version": "1.0.0",
28+
"main": "main.js",
29+
"dependencies": {},
30+
"devDependencies": {
31+
"@oracle/bots-node-sdk": "^2.0.0"
32+
}
33+
}
34+
```
35+
36+
### main.js
37+
38+
main.js exports the settings of the package. It has the following properties:
39+
40+
"components" - this is required property to specify the list of components the package exports. The "components" property can be in one of the 2 formats below:
41+
42+
First, "components" can be an object with property names being component names, and property value being the corresponding component module. For example:
43+
44+
```javascript
45+
module.exports = {
46+
components: {
47+
'hello.world': require('./components/hello.world')
48+
}
49+
};
50+
```
51+
52+
This format is the same format as registry.js for users of prior samples. You could simply rename registry.js to main.js.
53+
54+
Second, "components" can be an array of paths to component file or directory. For example:
55+
56+
```javascript
57+
module.exports = {
58+
components: [
59+
'./components/hello.world'
60+
]
61+
};
62+
```
63+
64+
or
65+
66+
```javascript
67+
module.exports = {
68+
components: [
69+
'./components'
70+
]
71+
};
72+
```
73+
74+
The main.js file will thus export all component modules or file/directory as the component package content.
75+
76+
### .npmignore
77+
78+
The .npmignore file is used when exporting the Component Package (see below). It simply excludes the .tgz file from being included within the package export.
79+
80+
### component file(s)
81+
82+
There could be 1 or more component file(s) in a package. The component files could be in different sub-directories. The component code exports a metadata() method and an invoke() method. See the [example](./components/hello.world.js).
83+
84+
## Export the Component Package
85+
86+
A Component Package can be exported by running `npm pack` into a .tgz file. This .tgz file contains all custom files needed to construct a complete custom component service. The .tgz file can be extracted (tar -xvf name.tgz && mv package cc_package) and used within a Component Service Wrapper.
87+
88+
## Running in Nodejs Express (Component Service Wrapper)
89+
90+
See [starter example](../README.md)
91+
92+

‎CONTRIBUTING.md

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# Contributing to SmallTalk Bot
2+
3+
Copyright (c) 2020, Oracle and/or its affiliates.
4+
5+
Pull requests can be made under
6+
[The Oracle Contributor Agreement](https://www.oracle.com/technetwork/community/oca-486395.html)
7+
(OCA).
8+
9+
Before submitting a code contribution please discuss it with us by creating a
10+
new issue.
11+
12+
For pull requests to be accepted into SmallTalk Bot, the bottom of
13+
your commit message must have the following line using your name and
14+
e-mail address as it appears in the OCA Signatories list.
15+
16+
```text
17+
Signed-off-by: Your Name <you@example.org>
18+
```
19+
20+
This can be automatically added to pull requests by committing with:
21+
22+
```text
23+
git commit --signoff
24+
````
25+
26+
Only pull requests from committers that can be verified as having
27+
signed the OCA can be accepted.

‎LICENSE.txt

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
Copyright (c) 2020, Oracle and/or its affiliates.
2+
3+
The Universal Permissive License (UPL), Version 1.0
4+
5+
Subject to the condition set forth below, permission is hereby granted to any person obtaining a copy of this software, associated documentation and/or data (collectively the "Software"), free of charge and under any and all copyright rights in the Software, and any and all patent rights owned or freely licensable by each licensor hereunder covering either (i) the unmodified Software as contributed to or provided by such licensor, or (ii) the Larger Works (as defined below), to deal in both
6+
7+
(a) the Software, and
8+
9+
(b) any piece of software and/or hardware listed in the lrgrwrks.txt file if one is included with the Software (each a “Larger Work” to which the Software is contributed by such licensors),
10+
11+
without restriction, including without limitation the rights to copy, create derivative works of, display, perform, and distribute the Software and make, use, sell, offer for sale, import, export, have made, and have sold the Software and the Larger Work(s), and to sublicense the foregoing rights on either these or other terms.
12+
13+
This license is subject to the following condition:
14+
15+
The above copyright notice and either this complete permission notice or at a minimum a reference to the UPL must be included in all copies or substantial portions of the Software.
16+
17+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

‎README.md

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
# Digital Assistant Smalltalk Skill and Custom Component
2+
3+
Copyright (c) 2020, Oracle and/or its affiliates.
4+
5+
## Prerequisites
6+
7+
* To run the SmallTalk Bot you would require Oracle Digital Assistant version 19.+
8+
* [Nodejs](https://nodejs.org/) installed on your machine. Oracle provides [Node.js binaries for Oracle Linux](https://yum.oracle.com/oracle-linux-nodejs.html) or you can install Node.js from upstream
9+
* [The Oracle Bots Node SDK](https://github.com/oracle/bots-node-sdk)
10+
11+
## Docs
12+
13+
* [Supported Bot Intents](docs/bot-intents.md)
14+
* [Chat Example](docs/demo-scripts.md)
15+
* [Use With Digital Assistant Routing](docs/smtlk-da-routing-usage.md)
16+
* [Use in YAML](docs/smtlk-yaml-usage.md)
17+
18+
## Installation
19+
20+
To be able to test the Smalltalk bot you would need to install and run the custom component, which is provided as part of this repository. You can run the custom component in 2 ways:
21+
22+
* Locally on your machine, in case you want to debug it or extend it
23+
* Into the Oracle Digital Assistant Embedded Container
24+
25+
## Import Oracle Digital Assistant Skill
26+
27+
The easiest way to install and test the bot is to deploy the exported Oracle Digital Assistant skill from the [resources](resources/) folder.
28+
29+
Open your ODA instance 19.x+ version, preferable 20.x+ and use the `Import Skill` button to import the skill under `resources/x.x.x` version folder. The version under the resource folder points to the version of the Smalltalk Bot and it is not related to the ODA version required. All Smalltalk bots versions 4+ would work with the latest Oracle Digital Assistant. The ODA ZIP file with the skill contains all the intents and configurations required to run the bot, with the exception of the custom component that would be required. To import the skill do the following:
30+
31+
* Go to your Oracle Digital Assistant instance
32+
* On the top right click the `Import Skill` button
33+
* From the newly openede window go to the the location, where you checkout the code and select the Skill to import under the folder `resources/x.x.x` version
34+
* If the bot is imported successfully you should see it available under the skills section in ODA
35+
* Make sure that you train the skill using the `Trainer Tm` which is the machine learning-based model. For more information check the Oracle Digital Assistant Documentation.
36+
37+
![import oda skill](./docs/imgs/oda_import_smalltalk_skill_v3.gif)
38+
39+
## Install Custom Component
40+
41+
To be able to use the Smalltalk Bot you have to install the custom component from the source code. You could run it on your machine and install as external component, which would allow you to debug it or you can compile it and install it into the Oracle Digital Assistant embedded container for the given skill.
42+
43+
Before we proceed with the installation make sure that the component runs properly. After you checkout the code, run `npm install` and then `npm start` to start it and confirm that there are no errors.
44+
45+
```shell
46+
# install dependencies
47+
npm install
48+
49+
# start server
50+
npm start
51+
52+
# get component metadata
53+
curl -X GET localhost:3000/components
54+
```
55+
56+
If the component runs properly you should see the message `Component Service Ready`.
57+
58+
![custom component npm start](./docs/imgs/customcomponentnpmstart.png)
59+
60+
With this we are now ready to register the component as an external service.
61+
62+
## Register the custom component as external service
63+
64+
To be able to access the custom component you would need to run a tunnel to your localhost. One option to do so is using [ngrok](https://ngrok.com/).
65+
66+
* Download the ngrok from the official website [here](https://ngrok.com/)
67+
* Run the ngrok to the `http` port `3000` like shown below
68+
69+
```shell
70+
./ngrok http 3000
71+
```
72+
73+
* If it runs you should see now the `https` Forwarding URL that can be used to tunnel your localhost. Copy that URL we will use it during the external service registration in the Oracle Digital Assistant
74+
![ngrok copy url](./docs/imgs/ngrokcopyurl.png)
75+
* Go to the Oracle Digital Assistance main console
76+
* Click the hamburger menu on the top left side and from under `Development` select `Skills`
77+
* Search for the Smalltalk skill that you imported previously
78+
![smalltalk skill search](./docs/imgs/smalltalksearch.png)
79+
* Select the skill
80+
* From the icons on the left side select the components icon, which it looks like a function. This is the location to register the custom components
81+
* Click on the Service button at the middle of the screen to register the component
82+
![register custom component service](./docs/imgs/registercustomcomponentservice.png)
83+
* From the newly opened window type the name of the service and select the `External` radiobox.
84+
* In the `Metadata URL` paste the URL from the `ngrok` and add `/components` at the end. URL should look like this: `https://<ngrok-url>/components`
85+
* Username and Password has to be provided but since we don't use them you can type into there whatever you like at the moment.
86+
![oda external services registration](./docs/imgs/odaexternalservice.gif)
87+
* Click on the create button to save the configuration. You should now be able to test the skill.
88+
* Click the skill tester icon on the left bottom side, it looks like a play button.
89+
* In the new opened window type `Hi`` and wait a few seconds to get response. Since we run the custom component on our local computer it would take some time to initialize. If everything runs properly, you should get a response.
90+
![testing bot skill](./docs/imgs/testingbotskill.png)
91+
* You should also be able to see the logging information in your terminal
92+
![terminal log](./docs/imgs/terminallog.png)
93+
94+
## Deploy as Oracle Digital Assistant Embedded Container
95+
96+
In case you don't want to debug or extend the custom component you could run it directly into the Oracle Digital Assistant Embedded Container. To deploy into the Embedded Container, you would need to build the component. From the root folder run `npm pack` to generate the package.
97+
98+
* Go to the folder where you checkout the repository
99+
* Under the main folder run `npm pack` to build the component
100+
101+
```shell
102+
npm pack
103+
```
104+
105+
* If the build process was successfully a new `tgz` file should be created into the root folder of the project called `smartdialog-component-pkg-4.0.x.tgz`
106+
![npm pack](./docs/imgs/npmpack.png)
107+
* Go to your Oracle Digital Asstant Console.
108+
* Find the smalltalk bot, under the skills section
109+
![smalltalk skill search](./docs/imgs/smalltalksearch.png)
110+
* From the icons on the left side select the components icon, which it looks like a function. This is the location to register the custom components
111+
* Click on the Service button and in the new opened window provide a name for the component and leave the `Embedded Container` radiobox selected
112+
* Click on the link `Upload a component package file` and search on your computer the location where the `smartdialog-component-pkg-4.0.x.tgz` was compiled
113+
* Select the `tgz` compiled file and wait for the upload and deployment process to finish
114+
* Click on the `Create` button to finish the process and wait for the final deployment to show it was successful
115+
![oda embedded services registration](./docs/imgs/odaembeddedcontainerdeploy.gif)
116+
117+
* `IMPORTANT:` if you have more than one Smalltalk services running make sure that you `Enabled` only the one you will be using. Every registered services has a checkbox called `Service Enabled` at the top.
118+
119+
The component code itself is under the `components` directory. Go to [COMPONENTS.md](COMPONENTS.md) for more information.
120+
121+
If you want to contribute please check [CONTRIBUTING.md](CONTRIBUTING.md)

0 commit comments

Comments
 (0)