TT Client Library 1.0.0
C++ library for Tandem Tales clients.
Loading...
Searching...
No Matches
tt Namespace Reference

Tandem Tales is a platform that enables short, paired storytelling exercises between two agents over a network. More...

Classes

class  Client
 A client connects to a server to find a partner and play a role in a storytelling session. More...
class  ClientFactory
 A client factory continuously creates clients to connect to a server and is useful for deploying automated agents. More...
class  ExternalAPI
 Represents the external API used for text embedding and completion. More...
class  Choice
 The choice message is sent from an agent to the server to signal what turn the agent wants to take. More...
class  Connect
 The connect message is sent from the server to a client as soon as the agent connects to give details about which story worlds and agents are available for play. More...
class  End
 The end message is sent from the server to an agent to indicate that the session has ended and that they should now disconnect. More...
class  Entry
 A database entry represents an individual element in a database, including its meta-data, such as its title and description. More...
class  Error
 The error message is sent from the server to an agent if one of the agent's messages causes a problem or is incorrectly formatted. More...
class  Join
 The join message is the first message sent from a client to the server to provide the agent's credentials and its preferences for what story world, role, and partner they want for their session. More...
class  Message
 A message is information sent to or from a server in JSON format. More...
class  MessageFactory
 A helper class for deserializing messages. More...
class  Report
 The report message is sent from an agent to the server to indicate the value of a question on a survey about the session they are playing. More...
class  Start
 The start message is sent from the server to a client when a partner has been found and their session begins. More...
class  Stop
 The stop message can be sent from either the server or the client to indicate that no more turns will happen in the session (though reports may still happen) and that the session should end soon. More...
class  Update
 The update message is sent from the server to a client each time a turn is taken and the state of the story world changes. More...
class  Settings
 Constants and other project-wide settings. More...
class  Action
 An action is a signed asset that causes a change in a story world's state. More...
class  Assignment
 An assignment is a logical formula that asserts that some variable in a story world has a value. More...
class  Constant
 A constant is a logical value that always exists in all story worlds, such as the boolean concepts of True and False, numbers, and so on. More...
class  Ending
 An ending is a signed asset that represents one of several possible ways a story can end. More...
class  Entity
 An entity is an asset that represents a character, object, place, or idea in a story world. More...
class  Signature
 A signature is a logical object that identifies a parameterized asset in a story world. More...
class  State
 A state is an assignment of values to each variable in a story world. More...
class  Status
 A status contains the full history of a session in a story world, a description of its current state, and a list of turns that can be taken next (if any). More...
class  Turn
 A turn is one participant in a session communicating their intentions for an action to the other participant. More...
class  Value
 A value is a logical expression which evaluates to itself. More...
class  Variable
 A variable is an asset that represents a feature of the story world state that can change. More...
class  World
 A story world is a collection of assets needed for two partners in a session to tell a collaborative story. More...

Typedefs

using client_ptr = std::unique_ptr<Client>
 Alias for a pointer to a client to clean up code.
using json = nlohmann::json
 Alias for nlohmann's json.

Enumerations

enum  Role { GAME_MASTER , PLAYER , NONE }
 Represents the two roles in a collaborative storytelling session: the Player, who typically controls a single character, and the Game Master, who controls all other characters and the environment. More...

Functions

std::ostream & operator<< (std::ostream &os, const Client &a)
 Override stream insertion operator to allow printing the Client class.
std::ostream & operator<< (std::ostream &os, const ClientFactory &a)
 Override stream insertion operator to allow printing the ClientFactory class.
std::ostream & operator<< (std::ostream &os, const Message &a)
 Override stream insertion operator to allow printing the Message class.
template<typename T>
std::unique_ptr< Message > createFromJson (const nlohmann::json &j)
 Creates a message of a specified type from JSON.
void registerMessageTypes ()
 Helper function to register all message types.
Role getPartner (Role role)
 Returns the partner of this role.
std::string rtos (Role role)
 Returns the correct string value needed for the Tandem Tales Protocol for a given role value.
Role stor (std::string s)
 Returns the Role enum corresponding to the string value.
std::ostream & operator<< (std::ostream &os, const Role &a)
 Override stream insertion operator to allow printing a role enum value.
void requireNonEmpty (const std::string &s, const std::string &description)
 Throws an exception if the given string is empty.
template<typename T>
void requireNonNegative (const T &x, const std::string &description)
 Throws an exception if the given number is less than 0.
std::ostream & operator<< (std::ostream &os, const Action &a)
 Override stream insertion operator to allow printing the Action class.
std::ostream & operator<< (std::ostream &os, const Assignment &a)
 Override stream insertion operator to allow printing the Assignment class.
std::ostream & operator<< (std::ostream &os, const Ending &a)
 Override stream insertion operator to allow printing the Ending class.
std::ostream & operator<< (std::ostream &os, const Signature &a)
 Override stream insertion operator to allow printing the Signature class.
std::ostream & operator<< (std::ostream &os, const State &a)
 Override stream insertion operator to allow printing the State class.
std::ostream & operator<< (std::ostream &os, const Status &a)
 Override stream insertion operator to allow printing the Status class.
std::ostream & operator<< (std::ostream &os, const Turn &a)
 Override stream insertion operator to allow printing the Turn class.
std::string ttos (Turn::Type type)
 Utility function to get the string representation of a tt::Turn type.
Turn::Type stot (std::string s)
 Utility function to get the correct tt::Turn type enum from the string representation.
std::ostream & operator<< (std::ostream &os, const Value &obj)
 Override stream insertion operator to allow printing the Value class.
std::ostream & operator<< (std::ostream &os, const Variable &a)
 Override stream insertion operator to allow printing the Variable class.
std::ostream & operator<< (std::ostream &os, const World &a)
 Override stream insertion operator to allow printing the World class.

Detailed Description

Tandem Tales is a platform that enables short, paired storytelling exercises between two agents over a network.

This package defines the essential elements of a Tandem Tales client.

Enumeration Type Documentation

◆ Role

enum tt::Role

Represents the two roles in a collaborative storytelling session: the Player, who typically controls a single character, and the Game Master, who controls all other characters and the environment.

Author
Gage Birchmeier
Enumerator
GAME_MASTER 

The game master role, who controls all characters except the player character and the environment.

PLAYER 

The player role, who controls one character, often the main character of the story.

NONE 

No role, used as a "null" value.

Function Documentation

◆ createFromJson()

template<typename T>
std::unique_ptr< Message > tt::createFromJson ( const nlohmann::json & j)

Creates a message of a specified type from JSON.

Template Parameters
Tthe type of the message serialized
Parameters
jJSON of the serialized message
Returns
a pointer to the newly created message

◆ getPartner()

Role tt::getPartner ( Role role)

Returns the partner of this role.

If this role is the game master, this method returns the player. If this role is the player, this method returns the game master.

Returns
the partner of this role

◆ operator<<() [1/14]

std::ostream & tt::operator<< ( std::ostream & os,
const Action & a )

Override stream insertion operator to allow printing the Action class.

Parameters
osan output stream to insert into
aa reference to an action object
Returns
the output stream referenced

◆ operator<<() [2/14]

std::ostream & tt::operator<< ( std::ostream & os,
const Assignment & a )

Override stream insertion operator to allow printing the Assignment class.

Parameters
osan output stream to insert into
aa reference to an assignment object
Returns
the output stream referenced

◆ operator<<() [3/14]

std::ostream & tt::operator<< ( std::ostream & os,
const Client & a )

Override stream insertion operator to allow printing the Client class.

Parameters
osan output stream to insert into
aa reference to a client object
Returns
the output stream referenced

◆ operator<<() [4/14]

std::ostream & tt::operator<< ( std::ostream & os,
const ClientFactory & a )

Override stream insertion operator to allow printing the ClientFactory class.

Parameters
osan output stream to insert into
aa reference to a client factory object
Returns
the output stream referenced

◆ operator<<() [5/14]

std::ostream & tt::operator<< ( std::ostream & os,
const Ending & a )

Override stream insertion operator to allow printing the Ending class.

Parameters
osan output stream to insert into
aa reference to an ending object
Returns
the output stream referenced

◆ operator<<() [6/14]

std::ostream & tt::operator<< ( std::ostream & os,
const Message & a )

Override stream insertion operator to allow printing the Message class.

Parameters
osan output stream to insert into
aa reference to a message object
Returns
the output stream referenced

◆ operator<<() [7/14]

std::ostream & tt::operator<< ( std::ostream & os,
const Role & a )

Override stream insertion operator to allow printing a role enum value.

Parameters
osan output stream to insert into
aa role enum
Returns
the output stream referenced

◆ operator<<() [8/14]

std::ostream & tt::operator<< ( std::ostream & os,
const Signature & a )

Override stream insertion operator to allow printing the Signature class.

Parameters
osan output stream to insert into
aa reference to a signature object
Returns
the output stream referenced

◆ operator<<() [9/14]

std::ostream & tt::operator<< ( std::ostream & os,
const State & a )

Override stream insertion operator to allow printing the State class.

Parameters
osan output stream to insert into
aa reference to a state object
Returns
the output stream referenced

◆ operator<<() [10/14]

std::ostream & tt::operator<< ( std::ostream & os,
const Status & a )

Override stream insertion operator to allow printing the Status class.

Parameters
osan output stream to insert into
aa reference to an status object
Returns
the output stream referenced

◆ operator<<() [11/14]

std::ostream & tt::operator<< ( std::ostream & os,
const Turn & a )

Override stream insertion operator to allow printing the Turn class.

Parameters
osan output stream to insert into
aa reference to a turn object
Returns
the output stream referenced

◆ operator<<() [12/14]

std::ostream & tt::operator<< ( std::ostream & os,
const Value & obj )

Override stream insertion operator to allow printing the Value class.

Parameters
osan output stream to insert into
obja reference to a value object
Returns
the output stream referenced

◆ operator<<() [13/14]

std::ostream & tt::operator<< ( std::ostream & os,
const Variable & a )

Override stream insertion operator to allow printing the Variable class.

Parameters
osan output stream to insert into
aa reference to a variable object
Returns
the output stream referenced

◆ operator<<() [14/14]

std::ostream & tt::operator<< ( std::ostream & os,
const World & a )

Override stream insertion operator to allow printing the World class.

Parameters
osan output stream to insert into
aa reference to a world object
Returns
the output stream referenced

◆ registerMessageTypes()

void tt::registerMessageTypes ( )

Helper function to register all message types.

Runs when the first tt::Client is created.

◆ requireNonEmpty()

void tt::requireNonEmpty ( const std::string & s,
const std::string & description )
inline

Throws an exception if the given string is empty.

Parameters
sthe string which should not be empty
descriptiona short description of the type of string, used in the message of the exception which is thrown if the string is empty
Exceptions
std::invalid_argumentif the string given is empty

◆ requireNonNegative()

template<typename T>
void tt::requireNonNegative ( const T & x,
const std::string & description )
inline

Throws an exception if the given number is less than 0.

Parameters
xthe number which should not be negative
descriptiona short description of the number, used in the message of the exception which is thrown if the number is negative
Exceptions
std::invalid_argumentif the number is negative

◆ rtos()

std::string tt::rtos ( Role role)

Returns the correct string value needed for the Tandem Tales Protocol for a given role value.

Parameters
rolea role enum
Returns
a string holding the value of the role

◆ stor()

Role tt::stor ( std::string s)

Returns the Role enum corresponding to the string value.

This is based on the Tandem Tales Protocol.

Parameters
sa string holding a role value
Returns
the corresponding role enum value

◆ stot()

Turn::Type tt::stot ( std::string s)

Utility function to get the correct tt::Turn type enum from the string representation.

Parameters
sthe string representing a turn type
Returns
the corresponding turn type enum value

◆ ttos()

std::string tt::ttos ( Turn::Type type)

Utility function to get the string representation of a tt::Turn type.

Parameters
typethe type of turn
Returns
the string representation of that turn type