diff --git a/01 - Overview.md b/01 - Overview.md new file mode 100644 index 00000000..a2643c6f --- /dev/null +++ b/01 - Overview.md @@ -0,0 +1,202 @@ + +## What is a Bot Server? + +![General Bots Starting From Scrach](https://github.com/pragmatismo-io/BotServer/blob/master/docs/images/generalbots-open-core-starting-from-scratch.gif) + +Bot Server accelerates the process of developing a bot. It provisions all code +base, resources and deployment to the cloud, and gives you templates you can +choose from whenever you need a new bot. The server has a database and service +backend allowing you to further modify your bot package directly by downloading +a zip file, editing and uploading it back to the server (deploying process) with +no code. The Bot Server also provides a framework to develop bot packages in a more +advanced fashion writing custom code in editors like Visual Studio Code, Atom or Brackets. + +Everyone can create bots by just copying and pasting some files and using their +favorite tools like Excel (or any text editor) or Photoshop (or any image +editor). + +Package Quick Reference +------------ +|Whatsapp|Web|Core|KB| +|----|-----|----|----| +|[whatsapp.gblib](https://github.com/pragmatismo-io/BotServer/tree/master/packages/whatsapp.gblib)|[default.gbui](https://github.com/pragmatismo-io/BotServer/tree/master/packages/default.gbui)|[core.gbapp](https://github.com/pragmatismo-io/BotServer/tree/master/packages/core.gbapp)|[kb.gbapp](https://github.com/pragmatismo-io/BotServer/tree/master/packages/kb.gbapp)| + +### The bot development stack + +![General Bot Logo](https://raw.githubusercontent.com/pragmatismo-io/BotServer/master/docs/images/general-bots-stack.png) + +### The Bot Factory + +![General Bots Block Architecture](https://raw.githubusercontent.com/pragmatismo-io/BotServer/master/docs/images/general-bots-block-architecture.png) + +GeneralBots aims to delivery bots in azure in a very easy and fast fashion. Use Office tools like Word or Excel to edit your Bot - using code (JavaScript or TypeScript) just to empower custom requirements. + + +#### Use Excel for (Hierarchical) Knowledge Base Editing + +![General Bots Inside Excel can enable bot production the masses](https://github.com/pragmatismo-io/BotServer/blob/master/docs/images/general-bots-composing-subjects-json-and-excel.gif) + +#### Use Visual Studio for a complete .gbai package building system + +![General Bots Inside Visual Studio Code provides a complete artificial intelligence based conversational platform](https://raw.githubusercontent.com/pragmatismo-io/BotServer/master/docs/images/general-bots-inside-visual-studio-code-provides-a-complete-artificial-intelligence-based-conversational-platform.png) + + +How To +------ + +### Run the server locally + +1. Install [Node.js](https://www.npmjs.com/get-npm) the current generation General Bot code execution platform; +2. Open a **Terminal** on Linux and Mac or a **Command Prompt** window on Windows; +3. Type `npm install -g botserver` and press *ENTER*; +4. Type `gbot` to run the server core. + +Notes: + +* [*nodejs.install* Chocolatey Package](https://chocolatey.org/packages/nodejs.install) is also available. +* The zip source code of General Bot is also available for [Download](https://codeload.github.com/pragmatismo-io/BotServer/zip/master); + +### Configure the server to deploy specific directory + +1. Create/Edit the .env file and add the ADDITIONAL_DEPLOY_PATH key pointing to the .gbai local parent folder of .gbapp, .gbot, .gbtheme, .gbkb package directories. +2. Specify STORAGE_SYNC to TRUE so database sync is run when the server is run. +3. In case of Microsoft SQL Server add the following keys: STORAGE_SERVER, STORAGE_NAME, STORAGE_USERNAME, STORAGE_PASSWORD, STORAGE_DIALECT to `mssql`. + +Note: + +* You can specify several bots separated by semicolon, the BotServer will serve all of them at once. + +## Setup development environment (Windows) + +1. [Optional] Install [Chocolatey](https://chocolatey.org/install), a Windows Package Manager; +2. Install [git](`https://git-scm.com/`), a Software Configuration Management (SCM).; +3. Install [Node.js](npmjs.com/get-npm), a [Runtime system](https://en.wikipedia.org/wiki/Runtime_system). +(https://www.npmjs.com/get-npm) (suggested: LTS 8.x.x); +4. Install [Visual Studio Code](https://chocolatey.org/packages/nodejs.install), Brackets or Atom as an editor of your choice; +5. [Fork](https://en.wikipedia.org/wiki/Fork_(software_development)) by visiting https://github.com/pragmatismo-io/BotServer/fork +6. Clone the just forked repository by running `git clone /BotServer.git` ; +7. Run `npm install -g typescript`; +8. Run `npm install` on Command Prompt or PowerShell on the General Bot source-code folder; +9. Enter './packages/default.gbui' folder; +10. Run `npm install` folled by `npm run build` (To build default Bot UI); +11. Enter the On the downloaded folder (../..); +12. Compile the bot server by `tsc`. +13. Run the bot server by `npm start`. + +Note: + +* Whenever you are ready to turn your open-source bot ideas in form of .gbapp (source-code) and artifacts like .gbkb, .gbtheme, .gbot or the .gbai full package read [CONTRIBUTING.md](https://github.com/pragmatismo-io/BotServer/blob/master/CONTRIBUTING.md) about performing Pull Requests (PR) and creating other public custom packages repositories of your own personal or organization General Bot Community Edition powered packages. + +### Running unit tests + +1. Enter the BotServer root folder. +2. Run tests by `npm test`. + +### Just copy the source code to your machine + +1. [Download] the Zip file of (https://codeload.github.com/pragmatismo-io/BotServer/zip/master) + +### Updating the Bot Knoledge Base (.gbkb folder) + +The subjects.json file contains all information related to the subject tree and can be used to build the menu carrousel as well give a set of words to be used as subject catcher in the conversation. A hierarchy can be specified. + +### Creating a new Theme folder (.gbtheme folder) + +A theme is composed of some CSS files and images. That set of files can change +everything in the General Bot UI. Use them extensively before going to change +the UI application itself (HTML & JS). + +Package Types +------------- + +### .gbai + +Embraces all packages types (content, logic & conversation) into a pluggable bot +directory. [A sample .gbai is available](https://github.com/pragmatismo-io/IntranetBotQuickStart.gbai). + +### .gbapp + +The artificial intelligence extensions in form of pluggable apps. Dialogs, +Services and all model related to data. A set of interactions, use cases, +integrations in form of conversationals dialogs. +The .gbapp adds the General Bot base library (botlib) for building Node.js TypeScript Apps packages. + + +Four components builds up a General Bot App: + +* dialogs +* models +* services +* tests + +#### Dialogs + +All code contained in a dialog builds the flow to custom conversations in +built-in and additional packages . + + +#### Models + +Models builds the foundation of data relationships in form of entities. + + +#### Services + +Services are a façade for bot back-end logic and other custom processing. + +#### Tests + +Tests try to automate code execution validation before crashing in production. + + +### .gbot + +An expression of an artificial inteligence entity. A .gbot file defines +all bots dependencies related to services and other resources. + +### .gbtheme + +A theme of a bot at a given time. CSS files & images that can compose all UI +presentation and using it a branding can be done. [A sample .gbtheme is available](https://github.com/pragmatismo-io/Office365.gbtheme) + +### .gbkb + +A set of subjects that bot knows in a form of hierarchical menu-based QnA. [A sample .gbkb is available](https://github.com/pragmatismo-io/ProjectOnline.gbkb). + +### .gblib + +Shared code that can be used across bot apps. + +Reference +--------- + +### GeneralBots admin commands + +General Bot can be controlled by the same chat window people talk to, so +here is a list of admin commands related to deploying .gb* files. + +| Command | Description | +|-----------------|-----------------------------------------------------------------------------------------------------------------| +| deployPackage | Deploy a KB package. Usage **deployPackage** [package-name]. Then, you need to run rebuildIndex. | +| undeployPackage | Undeploy a KB. Usage **undeployPackage** [package-name]. | +| redeployPackage | Undeploy and then deploys the KB. Usage **redeployPackage** [package-name]. Then, you need to run rebuildIndex. | +| setupSecurity | Setup connection to user directories. | + +Discontinued commands: + +| Command | Description |Reason | +|-----------------| -----------------------------------------------------------------------------------------------------------------|------| +| rebuildIndex | Rebuild Azure Search indexes, must be run after **deployPackage** or **redeployPackage**. | Now it is called automatically | + +### Credits & Inspiration + +* Rodrigo Rodriguez (me@rodrigorodriguez.com) - Coding, Docs & Architecture +* David Lerner (david.lerner@hotmail.com) - UI, UX & Theming +* Eduardo Romeiro (eromeirosp@outlook.com) - Content & UX. +* Jorge Ramos (jramos@pobox.com) - Coding, Docs & Architecture +* PH Nascimento (ph.an@outlook.com) - Product Manager + +Powered by Microsoft [BOT Framework](https://dev.botframework.com/) and [Azure](http://www.azure.com). + +General Bot Code Name is [Guaribas](https://en.wikipedia.org/wiki/Guaribas), the name of a city in Brasil, state of Piaui. +[Roberto Mangabeira Unger](http://www.robertounger.com/en/): "No one should have to do work that can be done by a machine".