# Narval User Stories

Author: | Nicolas Chauvat
Date: | $Date$
Revision: | $Revision$
Description: | executable specification of Narval's features

Table of contents

- Engine control
  - shut down
  - start a plan
  - reschedule a plan
  - inspect memory
  - reload AIL rules
  - permissions on actions
- Introspection
  - log plans
  - dynamic help generation
  - generate documentation as docbook
- Instant messaging
  - add a user to jabber roster
  - determine nature of contacts
  - multiple agents in one forum
- Conferences
  - setup a conference
  - leave a conference room
  - observe conversation and take notes
  - learn what notes to take
  - learn when to ask for feedback
  - agent can explain why it logged/learned/etc.
- Conversational interface
  - predefined answers
  - fill some data into a xml file, governed by a template
  - reference a subject present in KB
  - predicts presence based on previous observations
- Agent-to-agent communication
  - Agent asks another agent a question
- Agent acting as secretary / representative
  - tell your master that
- Knowledge base
  - Adding and querying
    - add a statement
    - add a rule
    - search statements
    - RDQL queries
  - XML RDF
    - RDF import
    - RDF export
    - agent-to-agent RDF exchange
  - XML FOAF (Friend-Of-A-Friend)
    - import FOAF data
    - query FOAF data
    - asking for FOAF information
    - add Bulk FOAF information
    - add incremental FOAF information
    - generate FOAF file via dialog
    - export FOAF related data from the knowledge base
    - import some FOAF data to the knowledge base
    - agent-to-agent FOAF exchange
  - Metalog
- Entertainment
  - agent queries imdb, allocine and xmltv
- Personal Information Management
  - update personal information manager
  - use mozilla/sunbird for contacts
- Time-sheets / activity reports
  - Notify daily activity
  - Reset activity report
  - Print activity report

A Narval agent can connect to a jabber server to exchange messages and presence information using XMPP. Here are user stories describing the interaction between a Narval and a user.

# Engine control

## shut down

One can shut down one's assistant by asking it to shut down.

noTest

    DIALOG(jean,narvabot)

    jean: shut down
    [narvabot is disconnected]

There are other synonyms, like die.

use-recipe: | active-commands.narval-shutdown

## start a plan

One can ask one's assistant to start an arbitrary plan. This is a low-level action intended to help an advanced user make its assistant do things or debug.

Test

    DIALOG(jean,narvabot)

    jean: start-plan chat.say-hello
    narvabot: hello

use-recipe: | active-commands.narval-start-plan

## reschedule a plan

A running plan can be rescheduled to a later time. This is a way to delay the execution of plans.

Test

    DIALOG(jean,narvabot)

    jean: start-plan chat.say-hello
    narvabot: started plan with eid 366
    jean: reschedule plan 366 +3
    narvabot: plan 366 rescheduled (new eid 368)

use-recipe: | active-commands.narval-reschedule-plan

## inspect memory

One can use an arbitrary python expression to inspect narval's memory.

Test

    DIALOG(jean,narvabot)

    jean: inspect elmt.jabberid == 'jean'
    narvabot: bla bla bla

use-recipe: | active-commands.narval-introspection

## reload AIL rules

One can modify the pseudo-natural language processing rules of an agent while it is running. These rules are defined in the file pointed to by URL element named "uri:memory:rules". To test the changes, just tell the agent to reload its "ail brain".

Test

    DIALOG(jean,narvabot)

    jean: reload ail brain
    narvabot: ok boss, done

use-recipe: | active-commands.chat-reload-ail-brain

## permissions on actions

distinction between public/protected/private action

depending on permissions(?) of requester, allow action execution or not. Should handle groups.

see: | element bot-configuration in memory

# Introspection

## log plans

As an example of instrospection, one can log the state of the plans that are in memory. The corresponding recipe will not try to log itself in order to avoid infinite loop.

To try it, define a "uri:memory:planslog" URL element and start plan narval-log-started-plan.

Another recipe, narval-log-ended-plan, will write to a file the plans that are in the state failed or done.

log execution of plans: add a new recipe that will append a line to a file each time a plan is started and completed or failed

use-recipe: | active-commands.log-started-plans
use-recipe: | active-commands.log-ended-plans

## dynamic help generation

generate chatbot help for available commands by introspecting active plan. look at existing active plan (and at chatbot.ail file ?!) and generate a help message

Test

    DIALOG(jean,narvabot)

    jean: help
    narvabot: ...
    jean: help start-plan
    narvabot: ...

use-recipe: | active-commands.narval-help

## generate documentation as docbook

The recipe narval-generate-docbook will look at all the available recipes and generate a docbook/xml file that can be turned into a PDF file.

Test

    DIALOG(jean,narvabot)

    jean: generate recipe docbook
    narvabot: ok

Generated files should be found in the home directory.

use-recipe: | active-commands.narval-generate-docbook

# Instant messaging

## add a user to jabber roster

One can ask his assistant to add a known jabber id to its personal roster. The agent will then send a jabber request message to the user who will have to accept the subcription for the agent to be able to actually receive the user's presence messages.

Test

    DIALOG(jean,narvabot)

    jean: subscribe toto

use-recipe: | active-commands.chat-subscribe

## determine nature of contacts

detect if a user is a narval on incoming presence elements

when an unknown user send a presence to a narval, this one asks the new user if he is a narval agent or not, and add the answer to his knowledge base.

Narval can ask all jabber users if they are a Narval

FIXME: duplique l'histoire au dessus, non ? Narval asks if other jabber users are a Narval implementation.

a Narval agent will answer yes, while human being and others programs are supposed to answer no to the "are you a narval?" question

acceptance test: A narval can enter a conference room and answer the question if there are any other Narval users.

add jabber user information to the knowledge base

use-recipe: | active-commands.kb-respond-to-presence
use-recipe: | active-commands.kb-state-you-are-a-narval
use-recipe: | active-commands.kb-register-user-type

## multiple agents in one forum

as agents know whether other participants are Narval agents or not, they take care to ignore the messages sent in forums by other agents. this is to avoid witnessing endless and useless agent-to-agent conversations.

see: | recipe chat.handle-commands

# Conferences

## setup a conference

Jean asks his agent to set up a jabber meeting with a list of participants. Narval opens a forum and invites participants.

Test

    DIALOG(jean,narvabot)

    jean: setup conf agents narvabot jean

    FORUM(agents,jean,narvabot)
    [narvabot invites jean to forum agents]
    [jean accepts invitation to forum agents]
    [narvabot is present in forum agents]
    jean: narvabot: thanks
    narvabot: jean: you are welcome

When asked to, agents can set up jabber conferences and invite people to join.

Test

    DIALOG(jean,narvabot)

    jean: setup conf agents narvabot jean
    narvabot: ok

Such conferences can also be scheduled ahead.

Test

    DIALOG(jean,narvabot)

    jean: setup conf in 5 minutes in room agents with narvabot jean
    narvabot: ok

use-recipe: | active-commands.chat-conf-setup
use-recipe: | active-commands.chat-delayed-conf-setup

## leave a conference room

One can instruct his agent to leave a conference room.

Test

    FORUM(agents,jean,narvabot)
    jean: quit
    narvabot: i am leaving.
    [narvabot quits the room]

use-recipe: | active-commands.chat-conf-kickout

## observe conversation and take notes

We are chatting with a Narval agent and we want it to remember some of what we say. It could be for example that it records every sentence that contains the word 'action'.

Test

    DIALOG(jean,narvabot)

    jean: hi
    narvabot: hi
    jean: It is a nice day.
    jean: action: I will go for a hike.
    jean: and try not to forget my backpack
    jean: tell me about action
    narvabot: jean: "action: I will go for a hike."
    jean: tell me about backpack
    narvabot: nothing known about backpack.
    jean: tell me about hike
    narvabot: jean "action: I will go for a hike."

use-recipe: | docomo FIXME

## learn what notes to take

observe conversation : learn what to write down. Learn what sentences to write down using reinforcement.

use-recipe: | docomo FIXME

## learn when to ask for feedback

Learn when to ask or not to ask for feedback when learning what notes to take. Asking too often if writing down a sentence was the right thing to do disrupts conversations. On the other hand, the assistant can not learn without asking for feedback.

use-recipe: | docomo FIXME

## agent can explain why it logged/learned/etc.

user says something. agent says "logged", users asks "why?" and agent answers that word such and such triggered its action.

use-recipe: | docomo FIXME

# Conversational interface

## predefined answers

automatically transfert some predefined answers to some input sentences. Let us begin with the simplest example of all. We have an agent named narvabot and a user named Jean.

Test

    DIALOG(jean,narvabot)

    jean: hello
    narvabot: hi

use-recipe: | active-commands.chat-filtered-response

## fill some data into a xml file, governed by a template

use-recipe: | active-commands.chat-start-templated-discussion
use-recipe: | active-commands.chat-continue-templated-discussion
see: | file foaf.template in the narval home

## reference a subject present in KB

was creating a meeting in several sentences: "meeting on 2004-09-28 1:00 duration is 40 min", "meeting on 2004-09-28 1:00 start at 14:00".

## predicts presence based on previous observations

narval agent analyzes presence informations of people in its roster to be able to answer the following question : "when'll paul master be back ?".

an agent should also be able to answer to the question "when will your master be back?"

use-recipe: | active-commands.chat-when-user-will-be-back

# Agent-to-agent communication

## Agent asks another agent a question

A user enters a conference room with his personal agent. The personal agent asks other agents for their public KB via RDF export.

use-recipe: | active-commands.kb-rdf-extract
use-recipe: | active-commands.kb-rdf-export
use-recipe: | active-commands.kb-rdf-import

# Agent acting as secretary / representative

## tell your master that

when user is off-line but agent is on-line, tell the agent to tell something to its master. agent will then figure out what to do. keep the message until the user logs on, send an SMS, send e-mail, make phone call, etc. (yes, we can start with something simple :-)

forward a message to master via phone, email or instant messaging

use-recipe: | active-commands.comm-tell-master
use-recipe: | active-commands.comm-shtoom-tell-master

# Knowledge base

## Adding and querying

### add a statement

One can add facts to the knowledge base of his agent.

Test

    DIALOG(jean,narvabot)

    jean: add jean likes agents.
    narvabot: ok

use-recipe: | active-commands.kb-add-stmts

### add a rule

One can add rules to the knowledge base of his agent.

Test

    DIALOG(jean,narvabot)

    jean: rule: X grandchild Y if X child Z and Z child Y
    narvabot: ok

use-recipe: | active-commands.kb-add-rule

### search statements

One can has his agent about something and have it search its own knowledge base for the information. The simplest possible search is to find a sentence containing the same word.

Test

    DIALOG(jean,narvabot)

    jean: tell me about narval
    narvabot: narval is an agent platform.

use-recipe: | active-commands.kb-search

### RDQL queries

Narval agents can store some information as RDF. One can then ask an agent a question formatted as an RDQL query.

Test

    DIALOG(jean,narvabot)

    jean: tell me about narval
    narvabot: narval is an agent platform.

use-recipe: | active-commands.kb-rdql-query
note: | needs the redland kb backend

## XML RDF

### RDF import

one can import some XML-RDF to the knowledge base

Knowledge exchanged to Narvals as a RDF triple in the form (the subject, the object, the predicate) can be placed into Narvals KB

acceptance test: the RDF statement for "tony eats pizza." can be captured and exported as rdf triples and end up in another Narvals KB.

use-recipe: | active-commands.kb-rdf-import

### RDF export

one can export the knowledge base's content as XML-RDF

Knowledge captured in Narvals KB as a RDF triple in the form (the subject, the object, the predicate)

Example: | the english statement "jean eats pizza." can be captured and exported to rdf triples. (sentence "todays meeting was created yesterday" is not parsed in a generic way yet).

Test

    DIALOG(jean,narvabot)

    jean: paul eats pizza.
    jean: who eats pizza?
    narvabot: paul eats pizza.

use-recipe: | active-commands.kb-rdf-export

### agent-to-agent RDF exchange

export the knowledge base's content as XML-RDF, formatted to be given to another agent

see: | Agent asks another agent a question

## XML FOAF (Friend-Of-A-Friend)

### import FOAF data

import FOAF data into knowledge base

use-recipe: | active-commands.kb-foaf-import

### query FOAF data

query the FOAF data previously imported as in "who does <foaf:name> <foaf:know>"

use-recipe: | active-commands.kb-rdql-query

### asking for FOAF information

Asking the FOAFbot for information. This would mean that we would set up the redland framework and wrap the existing bot to appear as a narval. since the FOAFbot alread knows FOAF and RDF Query language we can leverage that

???: | !!!

### add Bulk FOAF information

Use the FOAFbot to add bulk information. This would mean that a foaf.rdf document would need to be constructed and then inform the FOAFbot of the link so that it can be read by and consumed by the bot.

???: | !!!

### add incremental FOAF information

Use the FOAFbot to add incremental information. This would mean using (subject, predicate, object) triples to add information to the FOAF redland framework.

???: | !!!

### generate FOAF file via dialog

Have an agent ask its user about missing information to generate a simple FOAF file and/or Observe forum discussion and if user talks with someone a lot, offer to add that person as a foaf:knows.

The vocabulary should be parsed allowing the dialog presented to the user to not be tightly coupled to the RDFS vocabulary. This loose coupling would allow new schema and other templates to be used to proactively receive input from the user.

see: | fill some data into a xml file, governed by a template

### export FOAF related data from the knowledge base

use-recipe: | active-commands.kb-foaf-export

### import some FOAF data to the knowledge base

use-recipe: | active-commands.kb-foaf-import

### agent-to-agent FOAF exchange

export the knowledge base's content as FOAF XML-RDF, formatted to be given to another agent :use-recipe: active-commands.kb-foaf-extract :use-recipe: active-commands.kb-foaf-export :use-recipe: active-commands.kb-foaf-import

## Metalog

Metalog is a semantic web research tool that includes Pseudo Natural Language pre-processing and insertion/querying of RDF triples. Metalog was wrapped as a Narval component and can be used in place of the other pseudo natural language and knowledge manipulation tools.

Test

    DIALOG(jean, narvabot)

    jean: metalog
    narvabot: switching personnalities
    jean: NARVAL represents "Narval" from "http://www.logilab.org/projects/".
    jean: IS represents "is" from "http://www.relationships.net/verbs".
    jean: NARVAL IS "agent platform".
    jean: NARVAL IS SOMETHING ?
    narvabot: NARVAL IS "agent platform"

Pluging-in Metalog contributed to proving the extensibility of the platform, but Metalog in itself is not of very high quality in its current version and tends to generate a lot of usage problems.

use-recipe: | active-commands.metalog-categorize

# Entertainment

## agent queries imdb, allocine and xmltv

Once can ask its agent to query on-line databases about movies, theaters and TV shows.

XMLTV is a tool to query TV programs. IMDB is the Internet Movide Database and Allocine is a french web site that knows everything about movies and theaters.

Test

    DIALOG(jean,narvabot)

    jean: what nice movies are playing in my neighborhood ?
    narvabot: "I, Robots" is showing at 19:30 at Montparnasse.

use-recipe: | active-commands.entertainment

# Personal Information Management

## update personal information manager

Narval listens to a jabber conversation and adds events to the calender of the kontact pim framework.

Test

    FORUM(agents,jean,narvabot)

    jean: sounds like we agree on this meeting then.
    jean: meeting 2004-09-27 14:00 project narval
    narvabot: this is a date.

Narvabot should have added the above item to jean's PIM tool.

That user story could have to work with kontact, sunbird, evolution, etc.

???: | !!!

## use mozilla/sunbird for contacts

same as above, but using the mozilla suite. namely version 1.7.2 and sunbird.

acceptance test: see above story 11. start sunbird. check there is no meeting. stop sunbird. type "meeting 2004-09-24 14:00 topic" in jabber. will answer "this is a date". start sunbird and check the meeting is there.

Test

    FORUM(agents,jean,narvabot)

    jean: meeting 2004-09-24 14:00 topic
    narvabot: this is a date

???: | !!!

# Time-sheets / activity reports

## Notify daily activity

This command is used to enter a daily ratio for an activity. An email is sent when the sum of ratios of all activities reaches 1. Notification can use positive or negative ratio, the agent will increment or decrement the existing value (if existing). If the total ratio goes under 0, the activity is deleted.

Syntax: | ([+-]?d/d)s+(.+)$ ([+-]?d([.,]dd?)?|[+-]?[.,]dd?)s+(.+)$

Example:

1/2 narval
  assigns half of the working load of the day on the narval project
+0.2 redaction
  assign 20% of the working load to an activity called redaction
-0.1 narval
  decrement load on narval by 10%
.4 meeting
  Fill daily load with 40% of the time spent in a reunion

Watch out

An email is sent as soon as the sum of all activities comes up to 1. All the same, activities may still be notified and will generate other notification mails as long as the sum remains over 1 Restriction

Restrictions weight on the ratio exclusively, meaning the user is free to use any name for his activity.

> - ratio must be parseable into a float (or an integer)
> - -1 <= ratio <= 1

Test

    DIALOG(jean,narvabot)

    jean: delete all activities
    narvabot: Activity report reset
    jean: 1/2 narval
    narvabot: you have only specified 0.50 of your daily activity, please complete (now or later today)
    jean: +0.2 redaction
    narvabot: you have only specified 0.70 of your daily activity, please complete (now or later today)
    jean: -0.1 narval
    narvabot: you have only specified 0.60 of your daily activity, please complete (now or later today)
    jean: .4 meeting
    narvabot: your daily activity report has been sent to hr@somedomain.com
    jean: -.2 redaction
    narvabot: activity deleted (ratio 0.00)
    jean: .2 narval
    narvabot: your daily activity report has been sent to hr@somedomain.com
    jean: 2.3 narval
    narvabot: ratio 2.30 out of range (-1 <= ratio <= 1)
    jean: -2 narval
    narvabot: ratio -2.00 out of range (-1 <= ratio <= 1)

wait for daily activity notification and generate daily report if the full day activity has been reported

use-recipe: | active-commands.activity-notify
use-recipe: | active-commands.activity-wait

## Reset activity report

Reset the current report of activity

Syntax: | RESET CURRENT ACTIVITY( REPORT)? (DELETE)|(FLUSH)( ALL)? ACTIVITIES FLUSH
Example: | flush reset current activity report delete all activities

Any of the above will delete all daily activities entered so far.

Watch out

The effect is this command is irreversible. All activities entered for this day will be removed

Test

    DIALOG(jean,narvabot)

    jean: delete all activities
    narvabot: Activity report reset
    jean: .5 narval
    narvabot: you have only specified 0.50 of your daily activity, please complete (now or later today)
    jean: flush
    narvabot: Activity report reset
    jean: .2 redaction
    narvabot: you have only specified 0.20 of your daily activity, please complete (now or later today)
    jean:  .4 meeting
    narvabot: you have only specified 0.60 of your daily activity, please complete (now or later today)
    jean: delete all activities
    narvabot: Activity report reset
    jean: reset current activity report
    narvabot: Activity report reset
    jean: .1 narval
    narvabot: you have only specified 0.10 of your daily activity, please complete (now or later today)

use-recipe: | active-commands.activity-flush

## Print activity report

Print the current report of activity

Syntax: | WHAT ARE MY ACTIVITIES( SO FAR)?? PRINT MY ACTIVITY REPORT ACTIVITIES
Example: | activities print my activity report what are my activities

Any of the above will print the current report of activity for the current day.

Test

    DIALOG(jean,narvabot)

    jean: delete all activities
    narvabot: Activity report reset
    jean: .5 narval
    narvabot: you have only specified 0.50 of your daily activity, please complete (now or later today)
    jean: print my activity report
    narvabot: so far, your report for today is 0.5 narval
    jean: .25 meeting
    jean: activities
    narvabot: so far your report for today is 0.5 narval and 0.25 meeting

use-recipe: | active-commands.activity-report