November 30, 1999
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.
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 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
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).
StatusReturns the status of the ThoughtTreasure server. The server replies with a string response of up. For example:
C: Status S: up
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 <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 <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 <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 <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 <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 <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 <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:
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 <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 <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 <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 <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 <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 <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.
ClearContextThe 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
QuitThe server closes the connection. For example:
C: Quit S: [closes connection]
BringdownForces 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]
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
Server implementations:
Client implementations: