ThoughtTreasure Server Protocol version 0.00022 (TTSP22)

A protocol for querying commonsense and lexical databases

by Erik T. Mueller

November 30, 1999


The ThoughtTreasure Server Protocol (TTSP) enables client software to communicate with a ThoughtTreasure server in order to query its commonsense knowledge base and to carry out natural language processing tasks such as parsing and generation.

Operation of protocol

A ThoughtTreasure server starts the TTSP service by listening on TCP port number 1832. (This is a registered port number listed by the Internet Assigned Numbers Authority [IANA]). A client wishing to use the ThoughtTreasure server requests a connection to the server host on that TCP port. Once connected, the client sends a command to the server. The server processes the command and sends a response to the client. This command-response cycle continues any number of times until the connection is closed or aborted.

Commands and responses

Commands and responses consist of characters from the ISO 8859-1 character set.

A command consists of a single line. The line contains a case-insensitive keyword, followed by zero or more arguments, followed by a LF character. The length of a command line is unlimited.

Responses consist of one or more lines, where each line is terminated with a LF character. The length of a response line is unlimited.

There are several types of responses:

ThoughtTreasure strings

ThoughtTreasure strings used in this document are defined by the following Extended Backus-Naur Form (EBNF) grammar:

Concept        ::= Assertion | Token
Assertion      ::= (TimestampRange '|')? '[' Concept (' ' Concept)* ']'
TimestampRange ::= '@' Timestamp ':' Timestamp
Timestamp      ::= 'na' | '-Inf' | '+Inf' | 'Inf' | ISO8601Subset
ISO8601Subset  ::= Y Y Y Y M M D D 'T' H H M M S S 'Z'
                   | Y Y Y Y M M D D 'T' H H M M S S
                   | Y Y Y Y M M D D 'T' H H M M S S '-' H H M M
                   | Y Y Y Y M M D D 'T' H H M M S S '+' H H M M
                   | Y Y Y Y M M D D
                   | Y Y Y Y M M
                   | Y Y Y Y
Y              ::= Digit
M              ::= Digit
D              ::= Digit
H              ::= Digit
M              ::= Digit
S              ::= Digit
Token          ::= ObjName | String | Number | TimestampRange | Name
ObjName        ::= ObjNameChar+
ObjNameChar    ::= Digit | Letter | '-' | '?'
String         ::= ('STRING:' ObjName ':')? '"' StringChar* '"'
Number         ::= 'NUMBER:' ObjName ':' Double
Name           ::= 'NAME:' '"' StringChar* '"'
PNode          ::= PNodeLexitem | PNodeConstit | PNodeName | PNodeTsRange
                   | PNodeTelno | PNodeString
PNodeLexitem   ::= '[' 'PNODE:' FeatureChar ':L:"' Text '":"' Features '":"'
                   Text '":"' Features '"' ']'
PNodeConstit   ::= '[' 'PNODE:' FeatureChar ' ' PNode (' ' PNode)? ']'
PNodeName      ::= '[' 'PNODE:' FeatureChar ':NAME:"'  Text '"' ']'
PNodeTsRange   ::= '[' 'PNODE:' FeatureChar ':TSRANGE:"'  TimestampRange '"' ']'
PNodeTelno     ::= '[' 'PNODE:' FeatureChar ':TELNO:"' Text '"' ']'
PNodeString    ::= '[' 'PNODE:' FeatureChar ':STRING:"' Text '"' ']'
Digit          ::= '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9'
Text           ::= StringChar*
Features       ::= FeatureChar+
StringChar is any character except "
FeatureChar is any ThoughtTreasure feature character.
Letter is a-z or A-Z (ISO 8859-1 letters are not included)
Double is the output of C printf %g

List of commands and responses

This section discusses the particular commands and responses. The command keywords are shown here in mixed case, though their case is ignored by the server. In the examples below, C: indicates a command sent by the client to the server; S: indicates a response sent by the server to the client.

In addition to the server's response to each command as described below, the server may respond with an error response if there is an error in processing the command (due to, say, an invalid command keyword or missing arguments).

Status

Status
Returns the status of the ThoughtTreasure server. The server replies with a string response of up. For example:
C: Status
S: up

ISA

ISA <ObjName1> <ObjName2>
Tests whether the specified object (ObjName2) is of the specified class (ObjName1). The server replies with a boolean response of 1 or 0. For example:
C: ISA beverage Evian
S: 1

IsPartOf

IsPartOf <PartObjName> <WholeObjName>
Tests whether the specified object (PartObjName) is a part of another specified object (WholeObjName). The server replies with a boolean response of 1 or 0. For example:
C: IsPartOf fingernail human
S: 1
C: IsPartOf fingernail chest
S: 0

Parents

Parents <ObjName>
Returns the parents of the specified object (ObjName). The server replies with a colon list response, where each token is either an ObjName or a filename. For example:
C: Parents human
S: Homo-sapiens:db/human.txt

Children

Children <ObjName>
Returns the children of the specified object (ObjName). The server replies with a colon list response, where each token is an ObjName. For example:
C: Children phase-of-life
S: not-alive:alive

Ancestors

Ancestors <ObjName>
Returns the ancestors of the specified object (ObjName). The server replies with a colon list response, where each token is either an ObjName or a filename. For example:
C: Ancestors physical-object
S: db/all.txt:concept:object:matter

Descendants

Descendants <ObjName>
Returns the ancestors of the specified object (ObjName). The server replies with a colon list response, where each token is an ObjName. For example:
C: Descendants child
S: teenager:infant

Retrieve

Retrieve <picki> <anci> <desci> <mode> <ptn>
Retrieves assertions from the database matching the specified pattern.

If picki is not -1, it is the index of the object to be picked out of the result assertion.

Anci indicates the index on which to move up (mode=anc or mode=ancdesc) the hierarchy. Anci should be -1 if the mode is neither anc nor ancdesc.

Desci indicates the index on which to move down (mode=desc or ancdesc) the hierarchy. Desci should be -1 if the mode is neither desc nor ancdesc.

Mode is either exact, anc, desc, or ancdesc.

Ptn is a sequence of ObjNames such as duration-of attend-play ?.

The server replies with a multiline response where each content line is a Concept. For example:

C: Retrieve 2 1 -1 anc duration-of attend-play ?
S: NUMBER:second:7200
C: Retrieve -1 -1 -1 exact min-value-of young-adult ?
S: @-Inf:Inf|[min-value-of young-adult NUMBER:year:18]
C: Retrieve -1 -1 1 desc at-grid mini-bar
S: @19870101T000000:na|[at-grid mini-bar1934 Park-Plaza-1E [GRIDSUBSPACE 1 19]]

PhraseToConcepts

PhraseToConcepts <Features> <Text>
Returns the ThoughtTreasure ObjNames and other information for the specified word or phrase (Text) with the specified features. The feature "z" indicates English; the feature "y" indicates French. (See the complete list of feature characters.) The server replies with a multiline response where each content line is a word-meaning association. A word-meaning association consists of the following items separated by colons: Weights are used for representing gradable concepts. In this scheme, cold is represented as hot with a negative weight. Weights range from -1.0 to 1.0. The from range and to range represent the lower and upper bounds for the weight of this word-meaning association. For example, the link from the word cold to the meaning hot might have a from range of -1.0 and a to range of -0.1. This means that hot with a weight in that range is called cold.

For example:

C: PhraseToConcepts z cheap
S: cheap:Az:cheap:Az:expensive:T:-1:-0.1
S: .
C: PhraseToConcepts z granddads
S: granddad:MNz:granddads:PNz:grandfather-of:T:0.1:1
S: .

ConceptToLexEntries

ConceptToLexEntries <ObjName>
Returns the lexical entries associated with the specified object (ObjName) in the lexicon. The server replies with a multiline response where each content line is a word-meaning association as defined above. For example:
C: ConceptToLexEntries adult
S: grown woman:FNz:grown woman:FNz:adult:þ:0.1:1
S: grown man:MNz:grown man:MNz:adult:þ:0.1:1
S: adult:Az¸:adult:Az¸:adult:¹:0.1:1
S: adult:Nz¸:adult:Nz¸:adult:¹:0.1:1
S: .

Tag

Tag <Features> <Text>
Performs part-of-speech (and other) tagging of the specified natural language text with the specified features. The text should be terminated with one or more space characters. The server replies with a multiline response where each content line consists of a word-meaning association as defined above plus a start position and end position in the Text. For example:
C: Tag z bright blues and greens 
S: bright:Az¸:bright:Az¸:bright:¹:0.1:1:0:6
S: blues:·Nz¸:blues:·Nz¸:blues:m:0.1:1:7:12
S: blue:·Nz¸:blues:P·Nz¸:other-uniform:Pï:0.1:1:7:12
S: blue:·Nz¸:blues:P·Nz¸:blue:¹:0.1:1:7:12
S: and:Kz¸:and:Kz¸:and:¹w©:0.1:1:13:16
S: and:Kz¸:and:Kz¸:add:T:0.1:1:13:16
S: green:Nz¸:greens:PNz¸:green:¹:0.1:1:17:23
S: green:Nz¸:greens:PNz¸:aasn-Green::0.1:1:17:23
S: .

SyntacticParse

SyntacticParse <Features> <Text>
Syntactically parses the specified natural language text with the specified features. The text should be terminated with one or more space characters. The server replies with a multiline response where each content line consists of either the word SENTENCE, indicating the beginning of the next sentence, or a PNode.
C: SyntacticParse z yellow bacon. 
S: SENTENCE
S: [PNODE:X [PNODE:E [PNODE:A:L:"yellow":"Az¸":"yellow":"Az¸"]] [PNODE:X [PNODE:N:L:"bacon":"Nz":"bacon":"SNz"]]]
S: .
C: SyntacticParse z My phone number is 212-555-1212. 
S: SENTENCE
S: [PNODE:Z [PNODE:X [PNODE:D:L:"his":"·Dz¸":"My":"1S·Dz¸"] [PNODE:X [PNODE:N:L:"phone number":"Nz":"phone number":"SNz"]]] [PNODE:W [PNODE:W [PNODE:V:L:"be":"Vz¸":"is":"p3SVz¸"]] [PNODE:X [PNODE:N:TELNO:"12125551212"]]]]
S: .

SemanticParse

SemanticParse <Features> <Text>
Syntactically and semantically parses the specified natural language text with the specified features. The text should be terminated with one or more space characters. The server replies with a multiline response where each content line consists of either the word SENTENCE, indicating the beginning of the next sentence, a Concept, or a PNode. The PNode is the parse tree corresponding to the previous Concept. For example:
C: SemanticParse z bright whites. 
S: SENTENCE
S: [bright white]
S: [PNODE:X [PNODE:E [PNODE:A:L:"bright":"Az¸":"bright":"Az¸"]] [PNODE:X [PNODE:N:L:"white":"Nz¸":"whites":"PNz¸"]]]
S: .
C: SemanticParse z Mary had a little lamb. 
S: SENTENCE
S: [past-participle [eat [such-that human [NAME-of human NAME:"Mary"]] [such-that lamb-food [a-little lamb-food]]]]
S: [PNODE:Z [PNODE:X [PNODE:N:NAME:"Mary"]] [PNODE:W [PNODE:W [PNODE:V:L:"have":"Vz¸":"had":"dVz¸"]] [PNODE:X [PNODE:E [PNODE:A:L:"a little":"Az":"a little":"Az"]] [PNODE:X [PNODE:N:L:"lamb":"Nz¸":"lamb":"SNz¸"]]]]]
S: .

Generate

Generate <Features> <Assertion>
Generates the specified assertion in natural language with the specified language, dialect, and style (Features). The server replies with a string response. For example:
C: Generate z [good Jim]
S: Jim Garnier is wonderful. 
C: Generate zT [good Jim]
S: He is great.
C: Generate za [good Jim]
S: He is slamming. 
C: Generate z [occupation-of Jim artist]
S: He is an artist. 

Chatterbot

Chatterbot <Features> <Text>
Sends natural language input text with the specified features to the chatterbot. The server replies with a string response. For example:
C: Chatterbot z Hello. 
S: Hello. 
C: Chatterbot z What's your name? 
S: Thomas. 
C: Chatterbot z What color is the sky? 
S: The sky is sky blue. 
C: Chatterbot z Bye. 
S: Goodbye. 

ClearContext

ClearContext
The discourse context is normally maintained for each client. This allows, for example, pronouns to be understood and generated (as in "He is an artist" above). ClearContent clears the discourse context (to force generation of "Jim Garnier is an artist" above). The server replies with a boolean response of 1. For example:
C: ClearContext
S: 1

Quit

Quit
The server closes the connection. For example:
C: Quit
S: [closes connection]

Bringdown

Bringdown
Forces ThoughtTreasure to break out of the server select loop, so that it can process further ThoughtTreasure shell commands. The server closes the connection. For example:
C: Bringdown
S: [closes connection]

Command/response summary

Here is a summary of commands and responses:
Status => string
  "Is the server running?"
ISA ObjName ObjName => boolean
  "Is ___ an instance of ___?"
IsPartOf ObjName ObjName => boolean
  "Is ___ a part of ___?"
Parents ObjName => colon list
  "What are all the parents of ___?"
Children ObjName => colon list
  "What are all the children of ___?"
Ancestors ObjName => colon list
  "What are all the ancestors of ___?"
Descendants ObjName => colon list
  "What are all the descendants of ___?"
Retrieve N N N Mode Ptn => multiline Concept
  "___?" (arbitrary query of database such as:
    "How long does ___ typically last?"
    "How many ___ does a person typically have?" [husband, friend]
    "At what age is someone called ___?" [teenager, adult]
    "Where are ___ typically found?")
PhraseToConcepts Features Text => multiline word-meaning association
  "What concepts does ___ express?"
ConceptToLexEntries ObjName => multiline word-meaning association
  "What words or phrases express ___?"
Tag Features Text => multiline word-meaning association, start, stop
  "What words or phrases are in ___?"
SyntacticParse Features Text => multiline SENTENCE or PNode
  "What are the synactic parse trees of ___?"
SemanticParse Features Text => multiline SENTENCE, Concept, or PNode
  "What assertions does ___ express?"
Generate Features Assertion => string
  "What sentence expresses ___?"
Chatterbot Features Text => string
  "___?" (arbitrary natural language query)
ClearContext => boolean
  "Clear the discourse context."
Quit => [server closes connection]
  "I'm done."
Bringdown => [server closes connection]
  "Bring down the server."

Optionally for all of the above: error

TTSP implementations

Server implementations:

Client implementations:

References

Internet Assigned Numbers Authority. Port numbers. http://www.isi.edu/in-notes/iana/assignments/port-numbers.
ThoughtTreasure documentation | ThoughtTreasure home

Questions or comments? webmaster@signiform.com
Copyright © 2000 Signiform. All Rights Reserved. Terms of use.