Wove - talk to SliTaz
================================================================================

Wove lets a SliTaz user configure the system in plain words, in French,
English or any language with a lexicon:

  $ wove "je veux un nouvel éditeur de texte"
  Voici ce que je peux installer :
     1  geany - Small and fast IDE using GTK+ toolkit.  installé
     2  beaver - Simple and very light advanced text editor
     3  leafpad - GTK simple text editor.
     ...
  $ wove "connecte-moi au wifi"        scan, pick a network, password, connect
  $ wove "le son ne marche pas"        looks, explains, proposes the fix
  $ wove "mets le clavier en azerty"
  $ wove "annule"                      puts back what the last action changed

Wove is a thin layer: it understands, asks what is missing, shows what
it will run and runs it with trame (the system) and spk (packages). It
never runs a guess: when two things fit, or a value is missing, it asks;
every change is shown first (from trame --explain) and confirmed.


Usage
--------------------------------------------------------------------------------

  wove-gui                 the window: suggestions, buttons, no command line
  wove                     talk in a terminal until "bye" (Ctrl-D)
  wove "sentence"          do one thing and quit
  wove --dry-run "s"       show the commands, run nothing
  wove --pipe              talk with a front-end (doc/PROTOCOL)
  wove doctor              what Wove needs, what trame offers it does not use
  wove intents             everything Wove can do
  wove debug "s"           how a sentence is understood

"how do I ..." / "comment je ..." shows the command without running it:
Wove also teaches the commands behind the words.


How it understands
--------------------------------------------------------------------------------

  sentence --> lexicon --> concepts --> intent --> slots --> plan --> run
              (fr, en)    audio set    audio.set  percent   --explain
                          #num=40                  =40

1. share/wove/lang/<lang>.lex turns words into concepts: "son", "sound",
   "volume" are all "audio"; "éditeur de texte" is need:text-editor.
   One file per language, plain text: translating Wove to a new language
   is writing one lexicon, no code. The user's language and English are
   loaded.

2. share/wove/intents, the same for every language, says what each intent
   needs: "audio.set when audio set #num". The intent whose rule has the
   most elements wins. A tie or a domain named alone ("wifi") is a
   question to the user. The order of the rules does not matter.

3. Slots (a percent, a network, a service...) are read from the sentence
   or asked, with choices taken from the system itself: Wi-Fi networks
   from trame wifi scan, services from trame service list...

4. Changes are confirmed after showing the plan; "undo" replays the
   inverse action with the value read before the change.

All of it is one awk pass (about 30 ms) and POSIX shell: it runs on i486.


The brain (optional)
--------------------------------------------------------------------------------

When the lexicon finds nothing, Wove can ask decide (a small decision
model, one forward pass, its answer is always one of the given choices:
it cannot invent an action). It needs x86_64 with AVX2 and a model:

  decide pull laya-multilingual

Its guess is only proposed above 75 % and always confirmed by the user.
BRAIN=rules in /etc/slitaz/wove.conf turns it off; on i486 Wove runs on
its lexicons alone.


Files
--------------------------------------------------------------------------------

  bin/wove                  the command
  lib/understand.awk        the analyzer: words -> concepts -> intents
  lib/understand.sh         run it, query its result
  lib/dialog.sh             the conversation: resolve, slots, plan, run, undo
  lib/slots.sh              slot types: read from the sentence, ask with choices
  lib/flows.sh              multi-step intents (Wi-Fi, repairs, packages...)
  lib/packages.sh           package lookups (one awk pass on packages.info)
  lib/brain.sh              the optional decision model
  lib/ui-term.sh            terminal interface
  lib/ui-pipe.sh            front-end interface (doc/PROTOCOL)
  share/wove/intents        what Wove can do
  share/wove/lang/*.lex     the words, one file per language
  share/wove/needs          need -> packages to propose
  share/wove/langs          language -> keyboard and locale
  share/wove/services       common names of init scripts
  po/                       translations of the messages (gettext, domain wove)
  gui/wove-gui.c            GTK3 front-end
  tests/                    make test


Adding things
--------------------------------------------------------------------------------

A word Wove misses: add it to the concept line of lang/<lang>.lex, add
the sentence to tests/cases.<lang>, run make test.

A new action: a stanza in share/wove/intents (label, when, run, slots),
the words in the lexicons if new concepts are needed, an example line
"> intent: sentence" in each lexicon, then make pot msgmerge, translate
the label in po/fr.po, make test. wove doctor lists the trame actions
not used yet.

A new language: copy lang/en.lex to lang/<lang>.lex and replace the
words (keep the concept names), add po/<lang>.po.


Requirements
--------------------------------------------------------------------------------

  trame, spk, jq, busybox; decide and a model for the brain (optional);
  gtk+3 for wove-gui (optional).
