Add documentation for primitive and chatbot

README.md

@@ -4,16 +4,6 @@ Maid-chan name is inspired from [Sakurasou's Artificial Intelligence](http://sak
 
 If you have any other ideas, I am accepting contributions :) For developers, you could access [the documentation pages for developers here](https://messenger-maid-chan.readthedocs.io/). For others who are interested in using Maid-chan features, please ask me directly and head to [Maid-chan Facebook Page](https://www.facebook.com/maidchan2/).
 
-## How to Run
-
-1. For initial configuration, you need to create `maidchan/config.py` based on `maidchan/config.py.example` and fill those values based on your own configuration.
-
-2. Maid-chan is using Redis as the database. Redis can be downloaded via https://redis.io/download. Run Redis as a background process in port 6379 (default port).
-
-3. It is recommended to use `virtualenv` (e.g.: `virtualenv venv` then `source venv/bin/activate`). You need to install all dependencies via `pip install -r requirements.txt`.
-
-4. Run `python setup.py install` to build Maid-chan. Finally, you can execute `maidchan` in the background process to run this bot.
-
 
 ## Available Features
 
@@ -49,6 +39,17 @@ All time-related features are currently handled in **UTC+9 (Japan Time)**.
 - `show profile`: Do you want to know what Maid-chan knows about you? Then, you could use this command!
 
 
+## How to Run
+
+1. For initial configuration, you need to create `maidchan/config.py` based on `maidchan/config.py.example` and fill those values based on your own configuration.
+
+2. Maid-chan is using Redis as the database. Redis can be downloaded via https://redis.io/download. Run Redis as a background process in port 6379 (default port).
+
+3. It is recommended to use `virtualenv` (e.g.: `virtualenv venv` then `source venv/bin/activate`). You need to install all dependencies via `pip install -r requirements.txt`.
+
+4. Run `python setup.py install` to build Maid-chan. Finally, you can execute `maidchan` in the background process to run this bot.
+
+
 ## Priority Ideas
 
 - RSS monitoring (similar to my previous RSS Twilio bot: https://github.com/freedomofkeima/rss-twilio-bot)

docs/chatbot.rst

@@ -5,11 +5,48 @@ Chatbot with ChatterBot
 How It Works
 ------------
 
-How to Run
-----------
+`ChatterBot`_ is a machine-learning based conversational dialog engine which is able to generate
+responses based on collections of known conversations.
+
+.. autoclass:: maidchan.chatbot.ChatBotDriver
+
+Maid-chan is trained with the provided Indonesian corpus, English corpus, and an additional corpus
+which is stored at `maidcorpus`_ of this project (some of them are Japanese words). Each time a user
+enters a statement, Chatterbot stores the text and its response for the next learning process.
+
+ChatterBot is language independent, which means that Maid-chan could support 3 different languages
+quite easily.
+
+.. automethod:: maidchan.chatbot.ChatBotDriver.get_response_from_chatbot
+
+.. automethod:: maidchan.chatbot.ChatBotDriver.get_response
+
+The initial idea was to check whether user's language is in the supported list. However, it seems
+the accuracy of `langdetect`_ is quite low, so it only checks whether the input is a valid language
+or not (e.g.: emoticon).
 
 Storage Adapter
 ---------------
 
+By default, ChatterBot uses `chatterbot.storage.JsonFileStorageAdapter` as its database adapter.
+However, after receiving messages from number of users, ChatterBot becomes slow (more than 5 seconds per query).
+Therefore, it is recommended to use MongoDB adapter (`chatterbot.storage.MongoDatabaseAdapter`) for production.
+
+See http://chatterbot.readthedocs.io/en/stable/storage/index.html for full references.
+
 Maid-chan Corpus
 ----------------
+
+Maid-chan corpus consists of 3 files:
+
+- conversations.corpus.json
+
+- greetings.corpus.json
+
+- trivia.corpus.json
+
+You could append any other training materials as long as the file has the format of `corpus.json`.
+
+.. _ChatterBot: https://github.com/gunthercox/ChatterBot
+.. _maidcorpus: https://github.com/freedomofkeima/messenger-maid-chan/tree/master/maidcorpus
+.. _langdetect: https://github.com/Mimino666/langdetect

docs/idea.rst

@@ -5,8 +5,24 @@ Ideas
 Priority Ideas
 --------------
 
+- RSS monitoring (similar to my previous RSS Twilio bot: https://github.com/freedomofkeima/rss-twilio-bot)
+- Translate text (feat: https://github.com/soimort/translate-shell)
+- (Admin only) Send link to download at home, e.g.: Youtube (feat https://github.com/soimort/you-get), image files, etc
+
 Existing Feature Improvement Ideas
 ----------------------------------
 
+- (Admin only) Broadcast message to all users which have talked to Maid-chan at least once
+- Modifiable daily Japanese Kanji & Vocabulary time
+- Automatic offerings update from upstream
+
 Future Ideas
 ------------
+
+- Japanese language quiz
+- Image recognition, e.g.: waifu recognizer - https://github.com/nagadomi/lbpcascade_animeface or self-created
+- Natural Language processing for conversing daily conversation (Naturally we can improve it with IBM Watson or Google Cloud Speech, but the model "probably" differs from Maid-chan requirement)
+- Mini games
+- Location-aware features: Recommendation, weather, train status, etc
+- IoT with home electronics
+- etc

docs/primitive.rst

@@ -5,11 +5,41 @@ Image Processing with Primitive
 How It Works
 ------------
 
-Installation
-------------
+`Primitive`_ is a machine-learning based program which converts images to its geometric primitives form (written in Go).
+
+.. autofunction:: maidchan.primitive.process_image
+
+Initially, Maid-chan will validate whether the image input is either `.png` or `.jpg`.
+
+.. autofunction:: maidchan.primitive.create_primitive_image
+
+Maid-chan creates 3 different images via Primitive. The shell command which is executed:
+
+.. code-block:: bash
+
+   $ primitive -i /tmp/{input_file} -o /tmp/{primitive_output_file} -n 175 -v
+
+.. autofunction:: maidchan.primitive.generate_gif_file_from_primitive
+
+Finally, `ImageMagick`_ converts those 3 generated images to a GIF file with:
+
+.. code-block:: bash
+
+   $ convert -delay 1x5 -loop 0 /tmp/{primitive_output_files} /tmp/{gif_output_file}
+
+Since primitive uses hill climbing and simulated annealing in image generation,
+the entire process might take several minutes depending on CPU capacity.
 
 How to Run
 ----------
 
-Parameters
-----------
+1. Ensure you have `ImageMagick`_ installed.
+
+2. Then, you can start running Maid-chan primitive worker by executing:
+
+.. code-block:: bash
+
+   $ maidchan_primitive
+
+.. _Primitive: https://github.com/fogleman/primitive
+.. _ImageMagick: https://www.imagemagick.org/script/index.php

docs/setup.rst

@@ -12,7 +12,7 @@ Maid-chan Installation
 
 .. code-block:: bash
 
-   git clone https://github.com/freedomofkeima/messenger-maid-chan.git
+   $ git clone https://github.com/freedomofkeima/messenger-maid-chan.git
 
 2. You need to fill Facebook token information in `maidchan/config.py` based on `maidchan/config.py.example`.
 
@@ -80,4 +80,3 @@ Maid-chan has 3 executables (recommended to use `screen`):
 .. _Facebook Messenger Bot: https://developers.facebook.com/docs/messenger-platform/guides/quick-start
 .. _davidchua/pymessenger: https://github.com/davidchua/pymessenger/blob/master/examples/echo_bot.py
 .. _Chatterbot Documentation: http://chatterbot.readthedocs.io/en/stable/storage/index.html
-.. _chatbot: