{"id":20323528,"url":"https://github.com/dplocki/generic-conversation-bot","last_synced_at":"2026-04-25T23:34:53.119Z","repository":{"id":42891324,"uuid":"209118470","full_name":"dplocki/generic-conversation-bot","owner":"dplocki","description":"The chat bot with programmable conversation mechanism","archived":false,"fork":false,"pushed_at":"2024-07-11T19:36:41.000Z","size":156,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-01-14T14:11:34.472Z","etag":null,"topics":["bot","conversation","conversation-bot","conversation-tree","framework","javascript","js","json","parser","preparser","state-machine"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dplocki.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-09-17T17:37:47.000Z","updated_at":"2024-07-11T19:36:37.000Z","dependencies_parsed_at":"2024-11-14T19:33:10.873Z","dependency_job_id":null,"html_url":"https://github.com/dplocki/generic-conversation-bot","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dplocki%2Fgeneric-conversation-bot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dplocki%2Fgeneric-conversation-bot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dplocki%2Fgeneric-conversation-bot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dplocki%2Fgeneric-conversation-bot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dplocki","download_url":"https://codeload.github.com/dplocki/generic-conversation-bot/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241827169,"owners_count":20026601,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bot","conversation","conversation-bot","conversation-tree","framework","javascript","js","json","parser","preparser","state-machine"],"created_at":"2024-11-14T19:28:31.147Z","updated_at":"2026-04-25T23:34:53.067Z","avatar_url":"https://github.com/dplocki.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Generic conversation bot\n\n## Project description\n\nA simple conversation bot with ability of reading the dialogue scripts from  [JSON](https://en.wikipedia.org/wiki/JSON) files.\n\n## Installation\n\nThe packages are publish on [Github NPM repository](https://npm.pkg.github.com).\n\n```sh\nnpm install @dplocki/generic-conversation-bot\n```\n\n## Internal architecture\n\nThe bot (class `Bot`) is a state machine. The state contain the logic of reaction on received `message` (from user). The reaction is collection of `actions`. User input, provide also `memory` cache.\n\n### State\n\nState is an object. Each state need to implements two methods: `*beforeMessage()` and `*analyse(message)`.\n\nBoth return collection of actions (as [generator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Iterators_and_Generators#Generator_functions)).\nThe `beforeMessage` is called when bot is change its internal state. The `analyse` method is called when Bot receive the new message.\n\n```js\nclass State {\n    *beforeMessage() {\n    }\n\n    *analyse(message) {\n    }\n}\n```\n\n#### States available by default\n\n* ChooseState - Similar in work as `switch` code\n* IfElse - Similar in work as `if else` code\n* MoveNextState - Displays the given text, no matter the input will call all provided actions\n* WaitForActivationState - The starting state, bot will ignore all input until given phrase (like: \"hi\") will be given\n\n### Actions\n\nEach action is function. The action is taking two parameters:\n\n* `bot` - the Bot object\n* `message` - the whole message object received by the Bot\n\nThe return value of action is ignored.\n\n```js\nfunction action(bot, message) {\n}\n```\n\nFor simplicity the the action builders are store in the `actions.js` file. Those are functions returning actions functions.\n\n#### Actions available by default\n\n* `response(text)` - Sets the response of Bot\n* `staySilence()` - Removes all response\n* `setState(state)` - Sets the given state as next one\n* `endConversation()` - Resets the Bot\n* `jumpToState(stateName)` - Sets the state from states list by its name\n* `remember(key, value)` - Saves the value in `memory` on provided `key`\n* `rememberInputAs(key)` - Saves the input (user message, only text) in `memory` on provided `key`\n* `increaseRemembered(key)` - Increase the value from `memory` on `key` by one (if value is not numeric, will be replace by 1)\n* `decreaseRemembered(key)` - Decrease the value from `memory` on `key` by one (if value is not numeric, will be replace by -1)\n\n## Parser\n\nThe Bot state machine can be loaded from [JSON](https://en.wikipedia.org/wiki/JSON) file. The file needs to be parsed first.\n\nThe parser is provided by `ParserBuilder` object. You can create parser containing additional states, actions or preparser actions.\n\n```js\nconst states = new ParserBuilder()\n    .addCustomActions(require('./actions'))\n    .addCustomStates(require('./states'))\n    .addPreParsers(require('./preParsers'));\n    .parse(\n        JSON.parse(fs.readFileSync('input.json', 'utf8'))\n    );\n```\n\n### The input file\n\nThe json file contain an array of objects. Each of it need to have two attributes: `type` and `name`.\n\n```json\n[\n    {\n        \"type\": \"type_of_state\",\n        \"name\": \"name_of_state\"\n    }\n]\n```\n\nThe parsing process transform the file into the object, where key is name of state.\n\n### Preparser\n\nThe preparser are called before the parsing process, for given **pre-states**. To call them you need provide two attribute: `pre_parser` and `pre_states`.\n\n```json\n[\n    {\n        \"pre_parser\": \"pre_parser_name\",\n        \"pre_states\": [\n            { },\n            { }\n        ]\n    }\n]\n```\n\nThe `pre_parser` value indicate which preparser needs to be called on given `pre_states`. The result: the collection of ready-to-parsing-states, will be input for parsing.\n\n#### Example of preprocessor\n\n```js\nfunction preprocessor(state, index, allStates) {\n    return state;\n};\n```\n\n## Examples\n\nBoth example bot can use `BitClient`. The function use the Node `readline` module for terminal usage.\n\n### Running examples\n\nAll require [installation of package](#Installation).\n\n### Simple\n\nA linear conversation. The bot will ask about name and use it back.\n\nThe example demonstrate the memory usage.\n\n### Quiz\n\nA linear conversation. The bot will ask few simple question and save the results showing the summary on the end.\n\nThe example demonstrate own additional (the `SummaryState` class) state.\n\n### Exam\n\nA nonlinear exam conversation. The bot will ask few simple question but user can skip and returning to them letter. Bot will summaries the result on end.\n\nThe example demonstrate preparser.\n\n## Tests\n\nThe unit test are based on [Mocha](https://mochajs.org/).\n\n### Running\n\n```bash\nnpm test\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdplocki%2Fgeneric-conversation-bot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdplocki%2Fgeneric-conversation-bot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdplocki%2Fgeneric-conversation-bot/lists"}