#|
File: km-overview.script
Date: February 2000 updated June 2000

The following is a transcript of a session with KM, illustrating many of
the features which the language contains. This transcript just gives
short examples, with the semantics presented informally in English.
For the full formal semantics, see the Users Manual and Situations Manual 
at the KM Web Site at http://www.cs.utexas.edu/users/mfkb/km.html

Below, comments are preceded with a ";" or wrapped in "#| |#". KM> is
the KM prompt, followed by the user's assertion/query, and then the
response by the KM interpreter.

Peter Clark
Bruce Porter
|#

#|
PREVIEW: An example of a frame in KM, showing the class "Buy", with its
slots and values (some of which are themselves frames).

"All buy events have
 - a buyer and a seller (both of type agent)
 - an object which is bought
 - some money equal to the cost of the object
 - two `give' subevents, in which:
        1. The buyer gives the money to the seller
        2. The seller gives the object to the buyer.''

(Buy has (superclasses (Event)))                   ; Properties of the class
                                                   ; (`owns' properties)
(every Buy has                                     ; Properties of its members
  (buyer ((a Agent)))                              ' (`template' properties)
  (object ((a Thing)))
  (seller ((a Agent)))
  (money ((the cost of (the object of Self))))
  (subevent1 ((a Give with
               (agent ((the buyer of Self)))
               (object ((the money of Self)))
               (rcpt ((the seller of Self))))))
  (subevent2 ((a Give with
               (agent ((the seller of Self)))
               (object ((the object of Self)))
               (rcpt ((the buyer of Self)))))))
|#

;;; START OF THE TRANSCRIPT, WITH COMMENTS ADDED
;;; From the Lisp prompt, type (km) to reach the KM interpreter...
USER(2): (km)

KM>  (reset-kb)
Resetting KM...
(t)

;;; --- instances ---

;;; "Fred"
KM>  *Fred                      ; (* has no special meaning, is just a 
(*Fred)                         ;  convenient character to visually distinguish
                                ;  from classes)
;;; "1"
KM>  1
(1)

;;; --- existential quantification ---

;;; "A cat."
KM>  (a Cat)
(_Cat0)                         ; _Cat0 is a Skolem individual denoting that cat

;;; --- slot declarations (optional) ---

;;; "`age' is a slot relating physical objects (Physobj) to Numbers. 
;;;  A physical object has at most one age."
KM> (age has
      (instance-of (Slot))
      (domain (Physobj))
      (range (Number))
      (inverse (is-age-of))           ; name of the inverse slot
      (cardinality (N-to-1)))         ; one age per thing

;;; --- instance frames ---

;;; "Fred is a person."
KM>  (*Fred has 
        (instance-of (Person)))
(*Fred)

;;; "Fred's age is 32."
KM>  (*Fred has 
        (age (32)))
(*Fred)

;;; "Show me the frame representing Fred."
KM>  (showme *Fred)
(*Fred has 
  (instance-of (Person))
  (age (32)))

;;; "What is the age of Fred?"
KM>  (the age of *Fred)
(32)

;;; "Fred owns a car."
KM>  (*Fred has 
        (owns ((a Car))))
(*Fred)

;;; "What does Fred own?"
KM>  (the owns of *Fred)
(_Car1)                            ; (Skolem _Car1 created, denoting that car)

;;; "Show me the frame representing that last car."
KM>  (showme (thelast Car))
(_Car1 has 
  (instance-of (Car))
  (owns-of (*Fred)))         ; note the inverse slot (default name is "<slot>-of")

;;; --- inverses ---

;;; "Who owns the last car?"
KM>  (the owns-of of (thelast Car))
(*Fred)

;;; --- embedded units ---

;;; "Joe is a person, and owns a red car."
KM>  (*Joe has 
       (instance-of (Person))
       (owns ((a Car with 
                (color (*Red))))))

;;; --- access paths ---

;;; "What are the color(s) of the thing(s) which Joe owns?"
KM>  (the color of (the owns of *Joe))
(*Red)

;;; "What are the color(s) of the thing(s) which Joe owns?"
;;; (alternative, "linear path" syntax)
KM>  (*Joe owns * color)            ; here the 2nd "*" is a wildcard (see User Manual)
(*Red)

;;; --- class frames and inheritance ---

;;; "People are physical objects" (property of the class)
KM> (Person has (superclasses (Physobj)))                   

;;; "Every person lives in a house." (property of class members)
KM>  (every Person has 
        (lives-in ((a House))))
(Person)

;;; "Every house has a door and a roof."
KM>  (every House has 
        (parts ((a Door) (a Roof))))
(House)

;;; "What does Joe live in?"
KM>  (the lives-in of *Joe)
(_House3)

;;; "What are the parts of the thing which Joe lives in?"
KM>  (the parts of (the lives-in of *Joe))
(_Door4 _Roof5)

;;; --- tracing ---

KM>  (trace)
(Tracing of KM switched on)
(t)

;;; "What are the parts of the thing which Joe lives in?"
;;; (showing the computation)
KM>  (the parts of (the lives-in of *Joe))
1 -> (the parts of (the lives-in of *Joe))
2  -> (the lives-in of *Joe)
2   (1) Local value(s): _House3
2   (2) From inheritance: (a House)
2   (1-2) Combine 1-2 together
3   -> ((_House3) && ((a House)))
3   <- (_House3)              "((_House3) && ((a House)))"
2  <- (_House3)               "(the lives-in of *Joe)"
2  -> (the parts of _House3)
2   (1) Local value(s): (:set _Door4 _Roof5)
3   -> (:set _Door4 _Roof5)
3   <- (_Door4 _Roof5)        "(:set _Door4 _Roof5)"
2   (2) From inheritance: (:set (a Door) (a Roof))
2   (1-2) Combine 1-2 together
3   -> ((_Door4 _Roof5) && ((a Door) (a Roof)))
3   <- (_Door4 _Roof5)        "((_Door4 _Roof5) && ((a Door) (a Roof)))"
2  <- (_Door4 _Roof5)         "(the parts of _House3)"
1 <- (_Door4 _Roof5)          "(the parts of (the lives-in of *Joe))"
(_Door4 _Roof5)

KM>  (untrace)
(Tracing of KM switched off)
(t)

;;; "Show me the concept taxonomy." (I denotes instances, unmarked are 
;;;  classes, ? denotes those where KM has insufficient information to tell)
KM>  (taxonomy)
Thing
   Car
   Cat
   Door
   House
   Number
   Physobj
      Person
I        *Fred
I        *Joe
   Roof
   Slot
I     age
I     color
I     color-of
I     is-age-of
I     lives-in
I     lives-in-of
I     owns
I     owns-of
I     parts
I     parts-of
?  *Red

;;; --- rules ---

;;; "A person is a voter if he/she is older than 18."
KM>  (every Person has
      (is-voter ((if ((the age of Self) >= 18) then *Yes
                  else if ((the age of Self) < 18) then *No))))

;;; "Is Fred a voter?" [Fred is 32, asserted earlier]
KM>  (the is-voter of *Fred)
(*Yes)

;;; "Joe is 12 years old."
KM>  (*Joe has 
        (age (12)))
(*Joe)

;;; "Is Joe a voter?"
KM>  (the is-voter of *Joe)
(*No)

;;; --- Self ---

;;; "Fred's favorite color is blue."
KM>  (*Fred has 
        (favorite-color (*Blue)))
(*Fred)

;;; "Every person likes their favorite color(s)."
KM>  (every Person has 
        (likes-color ((the favorite-color of Self))))
(Person)

;;; "What color(s) does Fred like?"
KM>  (the likes-color of *Fred)
(*Blue)

;;; --- set expressions ---

;;; "Show me every person [in the KB so far]?"
KM>  (every Person)
(*Joe *Fred)

;;; "Which people are over 18?"
KM>  (allof (the all-instances of Person) where ((the age of It) > 18))
(*Fred)

;;; "What is the favorite color(s) of the people over 18?"
KM>  (forall (the all-instances of Person) where ((the age of It) > 18)
      (the favorite-color of It))
(*Blue)

;;; --- arithmetic ---

;;; "What is 1 + 1?"
KM>  (1 + 1)
(2)

;;; "A person's age in days is their age [in years] times 365."
KM>  (every Person has 
        (age-in-days (((the age of Self) * 365))))
(Person)

;;; "What is Fred's age in days?"
KM>  (the age-in-days of *Fred)
(11680)

;;; --- reference by description ---

;;; "Which person includes blue in his/her favorite colors?"
;;; [Assumes exactly one answer, generates an error otherwise]
KM>  (the Person with (favorite-color (*Blue)))
(*Fred)

;;; "Which people includes blue in their favorite-colors?"
KM>  (every Person with (favorite-color (*Blue)))
(*Fred)

;;; --- multiple inheritance ---

;;; "Every big car has a large engine."
KM>  (every Big-Car has 
        (parts ((a Engine with 
                   (size (*Large))))))
(Big-Car)

;;; "Every powerful car has a powerful engine."
KM>  (every Powerful-Car has
        (parts ((a Engine with 
                   (power (*Lots))))))
(Powerful-Car)

;;; "Suburbans are both big and powerful cars."
KM>  (Suburban has 
        (superclasses (Big-Car Powerful-Car)))

;;; "What are the parts of a Suburban?"
;;; [Note: Here KM makes a non-deductive step, deciding the two 
;;;  inherited Engines are coreferential because they are (i) of the
;;;  same class (or one's classes subsumes the others') and (ii) their
;;;  unification doesn't violate any constraints. See the result below.]
KM>  (the parts of (a Suburban))
(COMMENT: (_Engine7 && _Engine8) unified to be _Engine7)
(_Engine7)

;;; "Show me the frame representing the last engine."
;;; [Note the result of the unification: The resulting Engine is both 
;;;  powerful and average-sized]
KM>  (showme (thelast Engine))
(_Engine7 has 
  (size (*Large))
  (instance-of (Engine))
  (power (*Lots))
  (parts-of (_Suburban6)))

;;; --- another example ---

;;; "Every person has two legs and a head."
KM>  (every Person has 
        (parts ((a Head) (a Leg) (a Leg))))
(Person)

;;; "Fred has a leg."
KM>  (*Fred has 
        (parts ((a Leg))))
(*Fred)

;;; "What are the parts of Fred?"
;;; [Note: two legs -- KM unifies one of the two legs on Person with the 
;;;  leg on Fred]
KM>  (the parts of *Fred)
(_Leg9 _Head10 _Leg11)

;;; --- constraints ---

;;; "A person's friends must all be of class Person."
KM>  (every Person has 
        (friends ((must-be-a Person))))
(Person)

;;; "A person cannot marry him/herself." (<> means "cannot equal")
KM>  (every Person has 
        (spouse ((<> Self))))
(Person)

;;; "Fred's spouse is himself."
KM>  (*Fred has 
        (spouse (*Fred)))
(*Fred)

;;; "Who is Fred's spouse?"
;;; [The constraint violation is detected at query time]
KM>  (the spouse of *Fred)
ERROR! Constraint violation! Discarding value *Fred (conflicts with (<>
                                                                     *Fred))

        -------------------------
        **Switching on debugger** 
Options include:
  g: to see the goal stack
  r: to retry current goal
  a: to abort
  o: to switch off debugger
  ?: to list more options
        -------------------------

1 <- FAIL!                    "(the spouse of *Fred)"o
(Tracing of KM switched off)
NIL

;;; "Every Airplane has exactly two wings."
KM>  (every Airplane has 
        (parts ((exactly 2 Wing))))
(Airplane)

;;; --- defined classes ---

;;; "A Mexican is a person who lives in Mexico,
;;;  AND every person living in Mexico is a Mexican."
KM>  (every Mexican has-definition 
        (instance-of (Person))
        (lives-in (*Mexico)))
(COMMENT: Noting definition for Mexican...)
(Mexican)

;;; "Fred lives in Mexico."
;;; [Note Fred is thus classified as a Mexican]
KM>  (*Fred has 
        (lives-in (*Mexico)))
(COMMENT: *Fred satisfies definition of Mexican,)
(COMMENT: so changing *Fred's classes from (Person) to (Mexican))
(*Fred)

;;; "Every Mexican is happy."
KM>  (every Mexican has 
        (mood (*Happy)))
(Mexican)

;;; "What is Fred's mood?"
KM>  (the mood of *Fred)
(*Happy)

;;; "What is the mood of a person who lives in Mexico?"
KM>  (the mood of (a Person with 
                    (lives-in (*Mexico))))
(COMMENT: _Person12 satisfies definition of Mexican,)
(COMMENT: so changing _Person12's classes from (Person) to (Mexican))
(*Happy)

;;; --- text generation ---

;;; [Define sequence of text fragments for Remove instances]
KM>  (every Remove has
      (text ((:seq "Remove" (Self object) "from" (Self location)))))
(Remove)

;;; "What is are the text fragments for a removal event, where a sample is
;;;  being removed from a box?"
KM>  (the text of
       (a Remove with 
          (object ((a Sample))) 
          (location ((a Box)))))
((:seq "Remove" _Sample14 "from" _Box15))

;;; "Make a sentence from these fragments."
KM>  (make-sentence
      (the text of
       (a Remove with 
          (object ((a Sample))) 
          (location ((a Box))))))
(COMMENT: anglifying ((:seq "Remove" _Sample17 "from" _Box18)))
("Remove the sample from the box.")

;;; "Make a sentence from the text fragments for removing a disk from
;;;  a disk drive."
KM>  (make-sentence
      (the text of
       (a Remove with 
          (object ((a Disk))) 
          (location ((a Disk-Drive))))))
(COMMENT: anglifying ((:seq "Remove" _Disk20 "from" _Disk-Drive21)))
("Remove the disk from the disk-drive.")

;;; --- slot hierarchies ---

;;; "parts has subslots mechanical-parts."
KM>  (parts has 
        (instance-of (Slot)) 
        (subslots (mechanical-parts)))
(parts)

;;; "Every airplane has a jet engine as one of its mechanical parts."
KM>  (every Airplane has 
        (mechanical-parts ((a Jet-Engine))))
(Airplane)

;;; "What are the parts of an airplane?"
KM>  (the parts of (a Airplane))
(_Jet-Engine23)

;;; --- situations ---

;;; "Mike was born in 1963."
KM>  (*Mike has 
        (birthdate (1963)))
(*Mike)

;;; "birthdate is a constant (`non-fluent')"
KM> (birthdate has
      (instance-of (Slot))
      (fluent-status (*Non-Fluent)))

;;; "age may vary, but by default will remain unchanged."
KM> (age has
      (instance-of (Slot))
      (fluent-status (*Inertial-Fluent)))

;;; "Create a new situation."
KM>  (new-situation)
(COMMENT: Changing to situation _Situation24)
(t)

;;; "In this situation, Mike is 27 years old."
[_Situation24] KM>  (*Mike has 
                       (age (27)))
(*Mike)

;;; "What is Mike's age [in this situation]?"
[_Situation24] KM>  (the age of *Mike)
(27)

;;; "Go back into the last situation."
KM>  (in-situation (thelast Situation))
(COMMENT: Changing to situation _Situation24)
(_Situation24)

;;; "What year was Mike born in?"
;;; [Note, this situation `inherits' from the global situation.]
[_Situation24] KM>  (the birthdate of *Mike)
(1963)

;;; "Create and goto a new situation, which is the temporal successor of the 
;;;  current situation."
[_Situation24] KM>  (next-situation)
(COMMENT: Doing null action...)
(COMMENT: Changing to situation _Situation25)
(_Situation25)

;;; "What is Mike's age [in this situation]?"
;;; [Note: Mike's age is `projected' from the previous situation]
[_Situation25] KM>  (the age of *Mike)
(COMMENT: Projected *Mike age = (27) from _Situation24 to _Situation25)
(27)

;;; "Create and goto the temporally next situation."
[_Situation25] KM>  (next-situation)
(COMMENT: Doing null action...)
(COMMENT: Changing to situation _Situation26)
(_Situation26)

;;; "In this situation, Mike is 28 years old."
[_Situation26] KM>  (*Mike has 
                       (age (28)))
(*Mike)

;;; "What is Mike's age [in this situation]?"
;;; [Note `27' is not projected, as `28' overrides it and this slot cannot
;;;  have multiple values.]
[_Situation26] KM>  (the age of *Mike)
(28)

;;; "Exit this situation, and return to the `global situation'."
[_Situation26] KM>  (global-situation)
(COMMENT: Changing to situation *Global)
(t)

;;; "In the last situation created, what was Mike's age?"
KM>  (in-situation (thelast Situation) (the age of *Mike))
(28)

;;; "In which situations was Mike 27?"
KM>  (allof (the all-instances of Situation)
      where (in-situation It ((the age of *Mike) = 27)))
(_Situation25 _Situation24)

;;; --- actions ---

;;; "Every switching on is an Action."
KM>  (Switching-On has (superclasses (Action)))
(Switching-On)

;;; "All actions are Events." 
;;; NOTE: KM requires that all state-change operations must be instances
;;; 	  of the built-in class Event.
KM> (Action has (superclasses (Event)))
(Action)

;;; "Every switching on changes a switch's position from down to up."
KM>  (every Switching-On has 
        (object ((a Switch)))
        (del-list ((:triple (the object of Self) position *Down)))
        (add-list ((:triple (the object of Self) position *Up))))
(Switching-On)

;;; "position should, dy default, persist from one situation to another."
KM> (position has 
     (instance-of (Slot))
     (fluent-status (*Inertial-Fluent)))

;;; "Create a new situation."
KM>  (new-situation)
(COMMENT: Changing to situation _Situation27)
(t)

;;; "There is a switch whose position [in this situation] is down."
[_Situation27] KM> (*MySwitch == (a Switch with 
		                      (position (*Down))))
(*MySwitch)

;;; "Create and enter the situation resulting from switching that switch on."
[_Situation27] KM> (do-and-next
                     (a Switching-On with 
                        (object (*MySwitch))))
(COMMENT: Changing to situation _Situation30)
(_Situation30)

;;; "What is the position [in this new situation] of that switch?"
[_Situation30] KM> (the position of *MySwitch)
(*Up)

;;; "What is the current situation?"
[_Situation30] KM> (curr-situation)
(_Situation30)

;;; "What is the previous situation?"
[_Situation30] KM> (the prev-situation of (curr-situation))
(_Situation27)

[_Situation30] ;;; --- previous situations are preserved ---

;;; "In the previous situation, what was the position of the switch?"
[_Situation30] KM> (in-situation
                     (the prev-situation of (curr-situation))
                     (the position of *MySwitch))
(*Down)

;;; "In which situations was the switch down?"
[_Situation30] KM> (allof (the all-instances of Situation)
                     where (in-situation It 
                                ((the position of *MySwitch) = *Down)))
(_Situation27)

;;; "Quit KM"
[_Situation30] KM> q            

USER(3):                        ; (back to the Lisp prompt)

;;; --- end ---