Collaborative keywords mixing project

From LibreIdea
Jump to: navigation, search
Project
BulbgraphOnOff.gif
linked ingenie
Blue Glass Arrow.svg Gnome-preferences-other.svg
project
collaborative keywords mixing, Collaborative idea website Collaborative keywords mixing project
Français
Titre
projet mélange de mots-clés
Courte Description
Ce coci permet de générer des combinaisons afin de nous assister à trouver de bonnes ingénies
Description
Fichier
English
Title
Collaborative keywords mixing project
Short Description
This is a coci. The aim of this project is to generate new ingenies by presenting users a combination of different keywords.
Description
Files
Español‏‎
titulo
breve descripción
descripción
archivo
日本語‏‎
標題
簡短說明
解釋
Deutsch
Titel
Kurzbeschreibung
Beschreibung
Datei
Português
titulo
breve descrição
descrição
arquivo


Properties
Author User:Pavonia, User:Vev
Creation date 20151211165208
Modification date 20151211175208
Primary key 540
Linked ingenie(s) collaborative keywords mixing, Collaborative idea website
Website
Irc irc://irc.freenode.org/li-kwm
Mumble


Collaborative keywords mixing project

Author

User:Pavonia + , User:Vev +

Irc

Irc://irc.freenode.org/li-kwm +

Linked ingenies

Collaborative keyword mixing + , Collaborative idea website +

Page type

project  +

Primary key

540  +

Short description-en

This is a coci. The aim of this project is to generate new ingenies by presenting users a combination of different keywords.  +

Short description-fr

Ce coci permet de générer des combinaisons afin de nous assister à trouver de bonnes ingénies  +

Title-en

Collaborative keywords mixing project  +

Title-fr

projet mélange de mots-clés  +

Has query
This property is a special property in this wiki.

Collaborative keywords mixing project +

Creation date
This property is a special property in this wiki.

11 December 2015 16:52:08  +

Categories

Project , Software , Coci , Creation , Random , Libreidea

Modification date
This property is a special property in this wiki.

11 December 2015 17:52:08  +

hide properties that link here 

  No properties link to this page.

 



Overview[edit]

The aim of this project is to generate new ingenies by presenting users a combination of different keywords like this (but with only 3 or 4 mixing keywords this time of this list):

 What is it keywords
Devenir gaucher sous hypnoseexperience
hypnosis
handedness
Le vide n est pas videlaw
space
vacuum
atom
electron
gravity
>> cliquez pour voir la prochaine combinaison

Components and structure of the project:

 +---------+     +---------+     +----------+     +---------+
 | IRC Bot |     | SocialN |     | Software |     |   ...   |     user interfaces
 +----+----+     +----+----+     +-----+----+     +----+----+
      |               |                |               |
 +----+---------------+----------------+---------------+----+
 |                   Keyword Mixing Core                    |     computations
 +----------------------------+-----------------------------+
                              |
 +----------------------------+-----------------------------+
 |                        Database                          |     data storage
 +----------------------------------------------------------+

Users interfaces:

  • IRC bot
  • Social Networks: Diaspora/twitter/fb/salut à toi/movim/..
  • software on windows/GNU/Linux/FreeBSD/android/iphone/etc..

TODO: For using the Core module from user software we need a secure communication channel between client and server. For now, only interfaces running as server processes are secure!

Active developers (programming language):

  • Core: No active develompent (Haskell? PHP? Python?). If you are interested in working on that tool, please contact us on IRC!
  • IRC bot: pavonia (Haskell)
  • Database: pavonia (MySQL)

Core[edit]

Core is a web server process that handles requests from several user interfaces, computes combinations and manages storing the data in a database.

Keywords[edit]

Keywords are choosen from two list;

This two lists of keywords used to describe ingenies in libreidea. This list is always updated as long as there is new ingenies.

Advantanges:

  • Limit the number of possible combinations
  • Stay in the familiar environment of active users, i.e. if they are no doctors and no artists today on LI, there won't be words about those specialities in the list that active creators are not aware of

Data types[edit]

data CombinationFilter
Filter to select combinations from the database. (TODO)
newtype CombinationID = CombinationID Word
ID of a keyword combination.
newtype GameID = GameID Word
ID of a game.
data KeywordFilter
Filter to select keywords from the database. (TODO)
data Rating = Rating Word8
The rating a user can give to a combination is an integer number in the range from 1 to 10. Other values may be used for special cases, e.g. 0 for “bad” combinations.
UserID
ID of a user.
TODO: Use Wiki IDs or create new mapping?

Functions[edit]

Combination functions[edit]

Combination.new
This function creates a new combination of number different keywords. The keywords are choosen by applying filter to all available keywords in the database. Only keywords that match filter are used for the new combination. The function has to assert that only unique keyword combinations are generated to avoid duplicate checks later.
Parameters
number :: Int The number of keywords the combination consists of (default is keywordsPerCombination)
filter :: KeywordFilter The filter to be used for selecting keywords from the database (default is the filter that matches all keywords)
Returns
combID :: CombinationID
Exceptions
  • General database error
  • Not enough matching keywords to create a new combination
Combination.random
Chooses a random combination matching filter from the database.
Parameters
filter :: CombinationFilter The filter to be used for selecting combinations from the database (default is the filter that matches all combinations)
Returns
combID :: CombinationID
Exceptions
  • General database error
  • No combination matches
Combination.filter
Returns all combinations that match filter from the database.
Parameters
filter :: CombinationFilter The filter to be used for selecting combinations from the database
Returns
combIDs :: [CombinationID]
Exceptions
  • General database error

Game functions[edit]

Game.start
Starts a new game and returns a fresh game ID.
Parameters
None
Returns
gameID :: GameID
Exceptions
  • General database error
Game.end
Ends an active game with ID gameID. If there are still active combinations or players in the game they have to be marked as inactive.
Parameters
gameID :: GameID
Returns
Nothing
Exceptions
  • General database error
  • gameID doesn't exist
Game.addUser
Adds the user with ID userID to the game with ID gameID or marks it active if they have played that game before.
Parameters
userID :: UserID
gameID :: GameID
Returns
Nothing
Exceptions
  • General database error
  • userID doesn't exist
  • gameID doesn't exist
Game.update
Updates the combinations for Game with ID gameID. This function has to make sure all combinations that were active before the update are kept. If there are users in the game that aren't able to rate at least minUnrated combinations, new combinations have to be added to the game until this property is satisfied. Only combinations matching filter are added. The number of new combinations should be kept to a minimum.
Parameters
gameID :: GameID
minUnrated :: Int Minimum number of unrated combinations for each user in the game (default is unratedGameCombinationsPerUser)
filter :: CombinationFilter The filter to be used for selecting combinations from the database (default is the filter that matches all combinations)
Returns
combIDs :: [CombinationID] The (possibly empty) list of combination IDs that were added to the game
Exceptions
  • General database error
  • gameID doesn't exist
  • New combinations would have to be added but not enough combinations match the filter
Game.removeUser
Marks the user with ID userID as inactive for the game with ID gameID.
Parameters
userID :: UserID
gameID :: GameID
Returns
Nothing
Exceptions
  • General database error
  • userID doesn't exist
  • gameID doesn't exist
  • User userID isn't playing game gameID
Game.rate
Adds a rating with an optional comment from user userID for a combination comb.
Parameters
userID :: UserID
combID :: CombinationID
rating :: Rating
comment :: Maybe Text
Returns
Nothing
Exceptions
  • General database error
  • userID doesn't exist
  • gameID doesn't exist
  • User userID has already rated combination combID

Global constants[edit]

This is a list of global constants used in various functions. These constants should be configurable from the database eventually.

keywordsPerCombination = 3 :: Int The number of keywords for new combinations.
unratedGameCombinationsPerUser = 1 :: Int The number of unrated combinations in a game that must be rateable for each user.
maximumRatingsPerGame = 3 :: Int The maximum number of ratings for a combination per game. If the number of ratings for a combination reaches this limit, it's out of the game.
badCombinationThreshold = ??? :: Float The average value of ratings for a combination that marks this combination as bad.

Client–Server communication[edit]

The client communicates with the server by sending HTTP requests describing the action to be performed; the server answers them by replying with a JSON object that either includes the action's result or information about errors that occured while processing the request.

TODO: Use OAuth for secure communication?

Client requests[edit]

Clients send HTTP requests in a RESTful style. Each request represents a single server function call. Requests that only query database entries but do not alter the database are sent as GET requests; all other requests are sent as POST requests. The request's path takes the form /<namespace>/<function_name> where <namespace> is the namespace of the server function, e.g. combination or game, and <function_name> the name of the function to be processed. All parameters of the server function are passed as parameters of the corresponding HTTP method with their values properly encoded as application/x-www-form-urlencoded.

Examples:

 GET  /combination/new?number=3&filter=all
 POST /game/start
 POST /game/removeUser; userID=123&gameID=45

TODO: GET /constant/<constant_name> requests for global constants?

Server responses[edit]

Server responses are sent as a single JSend-compliant JSON object. Each object therefore has two mandatory fields: status, giving information about success or client-side/server-side errors, and data, including the requested data or additional information about errors that occurred. In case of a server-side error the data field is replaced by message.

Successful requests

Successful requests are answered with a field "status" : "success". If there wasn't any response data the data field is set to null, otherwise it's an object with a key/value mapping representing the result parameters with their corresponding values.

Examples:

 Request: GET /combination/filter?filter=all
 Response: {
   "status" : "success",
   "data" : {
      "combIDs" : ["i3", "i7", "i24"]
   }
 }

Client-side errors

If a request couldn't be parsed correctly, had missing or included unknown parameters, or were erroneous in any other way, the server responds with an object that has its status field set to "fail". The data field is an object with keys for each parameter that was missing, superfluous or badly formed, or in case of an unknown function call a key of the function name. The corresponding value is an error message describing the problem.

Examples:

 Request: POST game/remove; gameID=100
 Response: {
   "status" : "fail",
   "data" : {
      "game/remove" : "Unknown function `Game.remove'"
   }
 }
 Request: POST game/end; gameID=100
 Response: {
   "status" : "fail",
   "data" : {
      "gameID" : "No game with ID 100 found"
   }
 }

Server-side error

Requests that couldn't be handled because of an error that occurred while processing a correctly formed request, e.g. due to a database error, are answered with the status field set to "error". Instead of a data field, error responses include a message field with a descriptive error message.

Examples:

 Request: game/end; gameID=100
 Response: {
   "status" : "error",
   "message" : "Table `games' not found in database"
 }

IRC bot[edit]

The bot makes it possible to rate keyword combinations from IRC channels by several user playing rating games.

Functioning[edit]

Whenever the bot joins an IRC channel, a new game is started (Game.start) with zero players playing it. All users in a channel can then join the current game. Games in different channels have to be joined separately. There are no private games for now (games played outside of a channel), so users cannot communicate with the bot via private messages. Games cannot be stopped by users, the bot stops them when it leaves a channel or quits.

If a new user joins a game (Game.addUser), a call of Game.update is issued and all new combinations are presented. All users playing the game can now rate (Game.rate) these new combinations (including all old combinations if there are any). If no new combinations have been added to the game, the user can display a set of combinations rateable by them. Each user can leave the game at any point of the game (Game.removeUser).

Every user can rate any active combination in a game. If maximumRatingsPerGame users rated the same combination, this combination is out of the game and will be marked either as a bad combination (average rating < badCombinationThreshold) or as a good combination otherwise. The same user cannot rate the same combination twice. If they tries, a random unrated combination is shown as a hint. After a user has rated a combination, Game.update is issued such that a new combination is available for further rating.

TODO: What to do on network interruptions?
TODO: Continue old game when re-joining the same channel at another time?
TODO: How to associate IRC nick names with Wiki account names?

Bot commands[edit]

Syntax
variable Normal text denotes variable names
keyword Bold text denotes literal syntax (keywords etc.)
[optional] Text in square brackets is optional syntax
alternative1 | alternative2 The pipe character denotes alternative syntax. Parentheses can be used to delimit the scope of the pipes, e.g. foo (bar | baz) is different from foo bar | baz.


:game join
Adds a user to the active game in the channel.

 <Antoine>  :game join
 <IdeaBot>  Antoine joined the game.
 <Antoine>  :game join
 <IdeaBot>  You already are in the game.

:game (leave | part)
Removes a user from the game in the channel.

 <Antoine>  :game leave
 <IdeaBot>  Antoine left the game.
 <Antoine>  :game leave
 <IdeaBot>  You are not in the game.

:game rate combinationID rating [comment]
Adds a rating with an optional comment for a keyword combination by a user.

 <Berta>    :game rate i2 10 Super great ingenie!!1!
 <IdeaBot>  ...
 <Berta>    :game rate i3 7
 <IdeaBot>  ...
 <Berta>    :game rate i3 7
 <IdeaBot>  Sorry, you've already rated combination [i3].
 <IdeaBot>  ...
 <Berta>    :game rate i4 3
 <IdeaBot>  No combination found for ID [i4].

:game list
List all combinations rateable by the user.

:game register username (temporary command)
Associates the current IRC nick name with the user name username. The user name will be stored in the database, and all ratings, issued by a nick that is associated with this user name, will be stored for the same user. Ideally, this user name should be the Wiki account name.

 <Charly>   :register Charles
 <IdeaBot>  Associated nick Charly with user Charles.
 <Charly>   :rate i3 8
 <IdeaBot>  ...
 Charly changes nick to Karl
 <Karl>     :register Charles
 <IdeaBot>  Associated nick Karl with user Charles.
 <Karl>     :rate i3 8
 <IdeaBot>  Sorry, you've already rated combination [i3].

NOTE: This is only a temporary hack which is used until a more sophisticated user registration scheme has been introduced.

Database[edit]

For the storage a MySQL database is used. As some data, e.g. keywords, has to be accessed from the keyword mixing tool and the wiki, the wiki database will be used for the storage.

Table structure[edit]

field_name :: type_name, PK = primary key, FK = foreign key. The given types are (Haskell) synonyms for underlying MySQL types, e.g. types ending with “ID” are usually synonyms for INT UNSIGNED.

combination
PK id :: CombinationID
keyword
PK id :: KeywordID
name :: Text
Note: This shouldn't be a new table but a reference to the Wiki table for categories
combination_keyword
PK FK combination_id :: CombinationID
PK FK keyword_id :: KeywordID
rating
PK FK combination_id :: CombinationID
PK FK user_id :: UserID
rating :: Rating
game
PK id :: GameID
active :: Bool
game_combination
PK FK game_id :: GameID
PK FK combination_id :: CombinationID
active :: Bool Is the combination still in that game?
game_user
PK FK game_id :: GameID
PK FK user_id :: UserID
active :: Bool Is the user still playing that game?
user
PK id :: UserID
Note: This also shouldn't be a new table but a reference to the Wiki table for registered users