STML User Manual
================
Matt Welland <matt@kiatoa.com>
v1.0, 2012-6

FriendMaker is a minimalistic tool to help bring like-minded people together on sites such Second Life.

:numbered!:
[abstract]
Example Abstract
----------------

Due to the anonymous nature of sites such as Second Life meeting
like-minded and compatible people can be somewhat hit-or-miss. The
FriendMaker project (a subproject of the KiaToa project) sets
out to improve the quality of connections made by increasing the
probability of compatible people attending any given event.

Special thanks to kellogglicious who inspired this work and has been a
wonderful and supportive assistant in-world.

:numbered:

User Data Specification
-----------------------

.User Data
[width="100%",options="header",cols="<s,2m,2e,2e,2e",frame="topbot"]
|==============================
| Field            | Field Template    |Short form| Example                              | Description
| Age centerpoint  | :age              |:a        | :age 30                              | The center point of the age range that you are interested in meeting. E.g. If you wish to meet people from 25-35 years in age then the agecp would be 30
| Sex              | :sex              |:s        | :sex m                               | Male (m) or female (f)
| Orientation      | :orientation      |:o        | :orientation s                       | Straight (s), gay (g), bi (b)
| Country          | :country          |:c        | :country us                          | Two letter country code
| State or region  | :state or :region |:r        | :state az                            | Two letter state code or region code
| City or town     | :city  or :town   |:to       | :city Tempe                          | City or town name, note case is ignored
| Best time        | :besttime         |:bt       | :besttime afternoon,evening          | Times user is most likely to be on, list of; any, evening, morning, afternoon or time range
| Best days        | :bestdays         |:bd       | :bestdays mon,tues,fri,sun           | Days user is most likely to be on
| Interests        | :interests        |:i        | :interests romance, live music, sailing,theater | List of interests, i.e activities in SL you want to do
| Likes            | :likes            |:l        | :likes rock, jazz, blues             | List of things liked, used to narrow down music liked etc.
|==============================

// | <user items>     | :useritem      |                                      | User supplied key value pairs.
// | Age              | ::age           | age 35                              | NOT INITIALLY SUPPORTED Your age
// | agewant          | :agewant       | :agewant 30                          | NOT INITIALLY SUPPORTED The ideal partner age
// | Compound commands (NOT yes supported, are they needed?)|                |                                      |
// | About me         | :me            | :me m s us az Tempe 35               | Compact way to enter the basic info
// | Location         | :location      | :location us az Tempe                | One line entry of location for country, state/region and city/town

// Compact forms (NOT supported yet)
// 
// :me <sex> <orient> <country> <state> <city> <age cp> [<best time> [<best days>]]
// :location <country> <state> <city>
// 
// .Example compact forms
// -----------------------------
// :me f s us ca Burbank 25
// 
// note: If your city has spaces in the name it is best to use some short form
// 
// :me f s us ca sanfran 25
// -----------------------------

Interests
---------

mingling
dancing
conversation
exploring

Likes
-----



Age Specification
~~~~~~~~~~~~~~~~~

Initially only agecp will be supported. In future either specify agecp
or specify age and agewant. If both are specified then agecp will be
used.

The agecp idea works by clustering people around agecp numbers. A
statistical analysis is done on the aggregate agecp data and clusters
are identified, sliding group scales are applied and finally
individuals are placed in groups. Group edges are changed with every
iteration.

The probablity of being in a group will be roughly a bell curve of the
individual agecp with the group agecp.

General Comments
~~~~~~~~~~~~~~~~

  - The last setting is retained and the old value is lost.

User Commands
~~~~~~~~~~~~~

.User Commands
[width="100%",options="header",cols="<s,2m,2e",frame="topbot"]
|==============================
| Command            | Description             | Example
| showme             | Show my settings        | showme
| delete setting     | Remove setting          | delete interests
| deleteme           | Remove my record        |    
|==============================

Controller Commands
~~~~~~~~~~~~~~~~~~~

.Controller Commands
[width="100%",options="header",cols="<s,2m,2e",frame="topbot"]
|==============================
| Command                    | Description                                              | Example
| addvenue [venue] [master]  | Registers a venue and enables named avi to submit events, square brackets are required | addvenue [Tom Thumb] [Fishers Island]
|==============================

Event Specification
-------------------

Events are specified with a minimalist format intended to be unambiguous and yet fairly easy to type. This must be typed in as a single line.

.Data Types
[width="100%",options="header",cols="<s,2m,2e,2e,2e,2e",frame="topbot"]
|==============================
| Field          | Key          | Short Key | Field Template              | Example               | Description
| Date/Time spec | :time        | :t        | mm/dd/yy h AM/PM/am/pm      | 08/19/12 2 PM         | Start time of event
|                |              |           | mm/dd/yyyy h AM/PM/am/pm    | 08/19/2012 8 pm       | Start time with full year, lowercase am/pm ok
| Venue name     | :venue       | :v        | Venue name                  | Blue Marbles Jazz     | Generic name for the location
| Location spec  | :location    | :l        | Sim Name/1/2/3              | Sky Vista/1/2/3       | Second life location
| Event type     | :event       | :e        | type                        | livemusic,dancing     | Type of event
| Performer      | :performer   | :p        | Firstname Lastname          | Bo Carter             | Name of performer if applicable                      
| Genre          |              | :g        | genre1, genre2              | jazz, blues           | Genre of music
| Description    | :description | :d        |                             |                       |
|==============================

.Example events
-----------------------------
:time 08/19/12 2 PM  :venue Blue Marbles Jazz :location Sky Vista/1/2/3 :performer Bo Carter :event livemusic :genre light rock :description Let Bo Carter rock your night away.

Or use shorter form:

:t 06/28/12 9 PM :v Cove of dreams :l Fishers Island/15/116/24 :e livemusic :p BoCarter :g rock,jazz :d Join us for two hours of Bo Carter at Fishers Island at 9pm.
:t 06/28/12 8 PM :v The Oval :l Thira/95/139/40 :e livemusic :p Torben Asp :g new_age :d Float into the Recreative Universe of Torben Asp at 8pm for a one hour show.
-----------------------------

Event suggestions are keyed by the sender. If the sender is a
registered venue master then the event is displayed on the
calendar. Other events are revealed on the calendar by the number of
suggestions received. Events are keyed by an exact match on start time
and venue name.

// Compact Event Specification
// ---------------------------
// 
// This is just an idea. Not settled on or ratified.
// 
// -----------------------
// 07/05/2012
//   02:00 PM
//   :v Mystery :l Crescent/80/98/117 :e livemusic :p Alazarin Mobius :g furry rock :d Second life's only major furry band
//   :v Bella Vida :l Bella Vida/131/208/22 :e livemusic :p Curtis Cortes :g light rock :d Curtis sings songs from such artists as Stevie wonder, Beatles, Joe Cocker and Elton John
// -----------------------

<<<<<<<<<<<<<<<<<

Master Commands
---------------

.Master Commands
.User Commands
[width="100%",options="header",cols="<s,2m,2e",frame="topbot"]
|==============================
| Command            | Description                                  | Example
| follow [av-name]   | Have friendmaker follow the named avi, you should have "see on map" enabled to be followed | follow kiatoa resident
| follow -           | Stop friendmaker from following              |
| shadow [0\|1]      | Have friendmaker follow you (the master), 1 is "on" and 0 is "off", you must have "see on map" enabled for friendmaker | shadow 1
| logout             | Log friendmaker out                          |
| wear [folder]      | Have friendmaker wear the outfit from folder | wear sexyone
| outfit             | Restore outfit                               |                  
| cd [folder]        | make folder current                          | cd My Outfits       
| ls [folder]        | List inventory folder                        | ls outfits
| f, b, l, r, n, e, s, w | Move front, back, left, right, face north, east, south, west | f
| visit              | Take me to the bot                           |
|==============================

Interests and Likes Matching
----------------------------

.Interests and likes matching example table
[width="100%",options="header",cols="<2m,2m,2m,2m,2m",frame="topbot"]
|==============================
| Interests | Likes | Event     | Genre  | Score
| livemusic | rock  | livemusic | rock   | 1 1
| livemusic,dancing | jazz | livemusic,dancing | jazz | 1 1
|==============================

Grouping Algorythm
------------------

A multi pass methodology is used. On every pass the constraints are
loosened. Passes continue to be made until all people have been
assigned to groups. Groups are considered full at 40 people.

-------------------------
while events to fill
  while persons to process
    foreach person
      foreach group
         if person within tol
            add to group
            remove person from pool
-------------------------

Plan
----

Today
~~~~~

. Manual data entry method
. Snapshot of logs [Not really necessary?]
..   Busy mode
..   wait 10 sec
..   Copy logfile
..   cat /dev/null > logfile

Done Stuff
~~~~~~~~~~

. ENSURE THAT AUTO ADDED PEOPLE DO NOT GET IM's UNTIL THEY SET SOME VARIABLE [DONE]
. Auto add from GIM [DONE]
. Correct pm to PM [DONE]
. Safely preserve single quotes [DONE]
. Trim region/state to two letters [DONE]
. Trim male, female and hermaphrodite to m, f, h [DONE]
. Trim straight, gay, bisexual to s, g, b [DONE]
. Transition to names table [DEFERED]
. Create calendar page [DONE]
. Create rough run script/makefile [DONE]
. Sort by date [DONE]
. Create stats page [DONE]
. Add first three people to interests/likes for event, fix
  connections [DONE (well, good enough for now)]
. Send IM's 
..   :aboutme [DONE]
..   notice of event [DONE]
..   :delete - send acknowledgement [Cannot do, once deleted info needed is gone]
. Prevent re-processing lines in chat and or remove "ignore" on [DONE]
. Change agecp to age [DONE]
. do not process chats from friendmaker resident [DONE]
. Trim message queue [DONE]
. Upgrade to latest pikkubot software [DONE]
. Fix Anna [DONE (good enough)]
. Write temporary web page [DONE]
. Create calendar page sync [DONE]
. Create stats page [DONE]
. Set up rsync of temporary web page [DONE]
. Request to send notecard with all keywords currently in use.

Phase 1
~~~~~~~

. Re-write temp web page, add graphic illustration.
..   Get snapshot of IM window [DONE]
. Integration [DONE]
..   Run script
...     read logs
...     commit logs
...     generate connections
...     send IM's
. Ensure defaults are good [DONE]
..   agecp = 30
..   orientation = "s"
..   location zxzxzx
..   besttime = "evening"
..   interests = livemusic
..   likes = soft rock
..   ensure date/time is normalized M/D/YY H AM/PM - yes [DONE (leading zeros and 2012 fixed)]


Phase 2
~~~~~~~

. :matchfactor      => set your minimum matchfactor
. :bug and :message => send a bug report or message to kiatoa
. Keep stats for friends on/offline and sometimes check for online using search.
. Support this format: Bill473 Live @ Lost Lovers Dancing Club at 8 am description
. Process payments
. Get alt locations working Sim (x,y,z)\s+.*
. Limit number of IM's per day or per hour
. Limit number of events per person
. Lowercase all data
. Add underscores for cities
. Data safety, remove quotes [DONE]
. Add needed commands
.. :me
.. :addlike, :addinterest
.. :success  - for when friendmaker succeeded in help 
. Create friendmaker@kiatoa.com
. Add :agree yes/no and agreement to web doc
. Add payment processing
. Add :help, :feedback

Phase 3
~~~~~~~

. For dating with a sophisticated hint of "flirt" check out Friendmaker.
. Need a server, never goes down
. Cron job(s)
. Integrate with KiaToa
. Setup fetchmail and procmail for friendmaker - delay for now.

Notes
-----

Maintenance mode

  1. switch to autorespond "Anna is in offline mode, please try again in one hour"
  2. copy the chat log to log.date
  3. cat /dev/null > log
  4. switch to autorespond "Thank you for using the friendmaker service!"

Leon

Anna

Schema
------

------------------------
sqlite> .schema
CREATE TABLE events (id INTEGER PRIMARY KEY,
                                   event_time TEXT DEFAULT '',
                                   venue TEXT DEFAULT '',
                                   location TEXT DEFAULT '',
                                   event TEXT DEFAULT '',
                                   genre TEXT DEFAULT '',
                                   performer TEXT DEFAULT '',
                                   description TEXT DEFAULT '', CONSTRAINT eventsconstraint UNIQUE (event_time, venue));
CREATE TABLE groupedwith (id INTEGER PRIMARY KEY,grouped_id INTEGER,person_id INTEGER);
CREATE TABLE logs (id INTEGER PRIMARY KEY,logfname TEXT,lasttime INTEGER);
CREATE TABLE people (id INTEGER PRIMARY KEY,
                                   firstname TEXT,
                                   lastname TEXT,
                                   target_age INTEGER DEFAULT 25,
                                   sex TEXT DEFAULT 'n',
                                   orientation TEXT DEFAULT 's',
                                   country TEXT DEFAULT 'zx',
                                   region TEXT DEFAULT 'zx',
                                   city TEXT DEFAULT 'zx',
                                   best_time TEXT 'any',
                                   interests TEXT DEFAULT '',
                                   likes TEXT DEFAULT '',
                                   points INTEGER DEFAULT 0, CONSTRAINT valsconstraint UNIQUE (firstname, lastname));
------------------------