Skip to content

Tandem Tales Client (Python) API Reference

tt.VERSION = '1.0.0' module-attribute

The client's version of the Tandem Tales protocol.

tt.DEFAULT_PORT = 9005 module-attribute

The default port on which to connect to the server.

tt.PLAYER = 'PLAYER' module-attribute

The string used by the Tandem Tales server for the player role.

tt.GM = 'GAME_MASTER' module-attribute

The string used by the Tandem Tales server for the game master role.

tt.PROPOSE = 'PROPOSE' module-attribute

The string used by the Tandem Tales server for turn types that propose an action.

tt.SUCCEED = 'SUCCEED' module-attribute

The string used by the Tandem Tales server for turn types that execute an action.

tt.FAIL = 'FAIL' module-attribute

The string used by the Tandem Tales server for turn types where an action fails.

tt.PASS = 'PASS' module-attribute

The string used by the Tandem Tales server for turn types that pass control to the partner.

tt.EMBED_TOKENS_LIMIT = 1000000 module-attribute

The maximum number of input tokens that can be used for text embedding requests.

tt.COMPLETE_IN_TOKENS_LIMIT = 1000000 module-attribute

The maximum number of input tokens that can be used for text completion requests.

tt.COMPLETE_OUT_TOKENS_LIMIT = 1000000 module-attribute

The maximum number of output tokens that can be used for text completion requests.

tt.COMPLETE_SEED = 0 module-attribute

The seed used for large language model text completion requests.

tt.Client

Bases: ABC, Thread

A Tandem Tales client connects to a server to participate in a paired storytelling session. The abstract method on_choice must be implemented to return the index of the desired choice when it is this client's turn. A client can be run as thread or directly by calling the run method.

Attributes:

Name Type Description
factory Factory

The factory object that created this client.

external ExternalAPI

The external API used for text embedding and completion.

join dict[str, Any]

This client's join message.

url str

The URL of the server to connect to.

port int

The port number to connect on.

world dict[str, Any]

Will be set to a world object once the session starts.

role str

The client's role in the story. Updated after session starts.

status dict[str, Any]

The most recent story world status received from the server.

choices list[dict[str, Any]]

The list of choices currently available to make.

stop dict[str, Any]

The stop message received from the server.

session str

The session ID received from the server after the session.

Parameters:

Name Type Description Default
name str

The name this client will use on the server.

required
password str

The password this client will use when connecting to the server. If None, will be read from the environment variables.

required
world str

The name of the story world this client wants to play in. None means willing to play in any world.

required
role str

Must be PLAYER or GM. All other values are treated as None, which means willing to play either role.

required
partner str

The name of the partner this client wants to play with. None means willing to play with any partner.

required
key str

The key this client will use to access the external API. If None, will be read from the environment variables.

required
url str

The URL of the server this client will connect to.

'localhost'
port int

The port number this client will connect to the server on.

DEFAULT_PORT
Source code in src\tt\core.py
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
class Client(ABC, threading.Thread):
    """
    A Tandem Tales client connects to a server to participate in a paired
    storytelling session. The abstract method `on_choice` must be implemented
    to return the index of the desired choice when it is this client's turn.
    A client can be run as thread or directly by calling the `run` method.

    Attributes:
        factory (Factory): The factory object that created this client.
        external (ExternalAPI): The external API used for text embedding and
            completion.
        join (dict[str, Any]): This client's join message.
        url (str): The URL of the server to connect to.
        port (int): The port number to connect on.
        world (dict[str, Any]): Will be set to a world object once the session
            starts.
        role (str): The client's role in the story. Updated after session
            starts.
        status (dict[str, Any]): The most recent story world status received
            from the server.
        choices (list[dict[str, Any]]): The list of choices currently available
            to make.
        stop (dict[str, Any]): The stop message received from the server.
        session (str): The session ID received from the server after the session.

    Arguments:
        name (str): The name this client will use on the server.
        password (str): The password this client will use when connecting to the
            server. If None, will be read from the environment variables.
        world (str): The name of the story world this client wants to play in.
            None means willing to play in any world.
        role (str): Must be PLAYER or GM. All other values are treated as
            None, which means willing to play either role.
        partner (str): The name of the partner this client wants to play with.
            None means willing to play with any partner.
        key (str): The key this client will use to access the external API. If
            None, will be read from the environment variables.
        url (str): The URL of the server this client will connect to.
        port (int): The port number this client will connect to the server on.
    """

    def __init__(self, name, password, world, role, partner, key, url='localhost', port=DEFAULT_PORT):
        super().__init__()
        if password is None and ENV_PASSWORD in os.environ:
            password = os.environ[ENV_PASSWORD]
        if key is None and ENV_API_KEY in os.environ:
            key = os.environ[ENV_API_KEY]
        self.factory = None
        self.external = ExternalAPI(key)
        self.join_message = {
            "type": "Join",
            "name": name,
            "password": password,
            "world": world,
            "role": role,
            "partner": partner
        }
        self.url = url
        self.port = port
        self.socket = None # Will be set when the agent connects.
        self.world = None # Will be set to the world object after session starts.
        self.role = role # Will be updated after session starts.
        self.status = None
        self.choices = None
        self.stop = None
        self.session = None

    def __str__(self):
        str = f"[Client: name={self.join_message['name']}"
        if 'password' in self.join_message:
            str += '; password="***"'
        if 'world' in self.join_message:
            str += f"; world=\"{self.join_message['world']}\""
        if 'role' in self.join_message:
            str += f"; role=\"{self.join_message['role']}\""
        if 'partner' in self.join_message:
            str += f"; partner=\"{self.join_message['partner']}\""
        return str + ']'

    def run(self):
        """
        Connects to the server, joins, waits for a session to start, sends the
        choices made by this client, and returns the session ID of the completed
        session. As this method runs, it calls other methods to notify the
        client of important events. Some of these methods are guaranteed to be
        called even if an exception is raised. The list of those methods is:

        1. `connect` is called to establish the socket. If this method raises
           an exception, it is raised immediately and no other methods run.
        2. `on_connect` is called after receiving the connect message from the
           server. This is the last chance to make changes to the join request.
        3. `on_start` is called after the session starts.
        4. `on_update` is called each time the client receives an update to the
           story world status from the server.
        5. `on_choice` is called when the client receives an update that
           requires it to make a choice of what action to take next.
        6. `on_end` is called if the story reaches a pre-defined ending.
        7. `on_close` is called when the client stops its session normally,
           like reaching the end of the story, closing, or disconnecting. If
           the client stopped because it was interrupted or because of an
           exception, this method is not called.
        8. `on_stop` will always be called if the client's session started.
        9. `on_disconnect` will always be called if the client connected.
        """
        # Warn if the password and API key are not set.
        if self.join_message['password'] == None and not ENV_PASSWORD in os.environ:
            self.on_warning(f"The environment variable \"{ENV_PASSWORD}\" is not set. This agent will not use a password.")
        if self.external.key == None and not ENV_API_KEY in os.environ:
            self.on_warning(f"The environment variable \"{ENV_API_KEY}\" is not set. This agent will not be able to use the external API.")
        # Connect to the server.
        self.connect()
        # If an exception is raised, save it to raise later.
        uncaught = None
        try:
            # Wait for the connect message.
            connect = self.receive('Connect')
            if connect != None:
                if connect['version'] != VERSION:
                    self.on_warning(f"This client is using version {VERSION} of the communication protocol, but the server is using version {connect['version']}. This may cause miscommunications.")
                self.on_connect(connect)
                self.send(self.join_message)
            # Wait for the start message.
            start = self.receive('Start')
            if start != None:
                self.world = start['world']
                self.role = start['role']
                if self.factory != None:
                    self.factory._on_start(self)
            # Receive and process messages from the server.
            while self.world != None:
                message = self.receive()
                # Stop if disconnected.
                if message == None:
                    break
                # Handle update messages.   
                elif message['type'] == "Update":
                    # If this is the first update, notify the client the session has started.
                    if self.status == None:
                        self.status = message['status']
                        self.choices = message['status']['choices']
                        self.on_start(self.world, self.role, self.status['state'])
                    # If this is not the first update, update the current status and choices.
                    else:
                        self.status = message['status']
                        self.choices = message['status']['choices']
                        self.on_update(self.status)
                    # If it is this client's turn, make a choice.
                    if len(self.choices) > 0:
                        index = self.on_choice(self.status)
                        self.choices = json.loads('[]')
                        choice = {
                            "type": "Choice",
                            "index": index
                        }
                        if not self.input.stopped:
                            self.send(choice)
                    # If the story has ended, notify this client.
                    elif self.status.get('ending') is not None:
                        self.on_end(self.status['ending'])
                # Immediately acknowledge stop messages.
                elif message['type'] == "Stop":
                    self.stop = message
                    stop = {
                        "type": "Stop",
                        "role": self.role
                    }
                    self.send(stop)
                    self.on_stop(self.stop['message'])
                # Get session ID from end message.
                elif message['type'] == "End":
                    self.session = message['session']
                    break
                # Handle errors reported by the server.
                elif message['type'] == "Error":
                    self.on_error(message['message'])
                # Handle unrecognized message types.
                else:
                    m = str(message)
                    if len(m) > 40:
                        m = m[:40] + '...'
                    self.on_error(f"The message \"{m}\" is not recognized.")
        # Register an uncaught exception.
        except Exception as exception:
            uncaught = exception
        # If the client is interrupted...
        except KeyboardInterrupt as interrupt:
            if uncaught == None:
                uncaught = Exception("Client was interrupted.")
        # If this client ended normally, close.
        if uncaught == None:
            try:
                self.on_close()
            except Exception as exception:
                uncaught = exception
        # If the session started but has not stopped, stop it.
        if self.world != None and self.stop == None:
            try:
                self.on_stop(None)
            except Exception as exception:
                if uncaught == None:
                    uncaught = exception
        # Close the socket.
        self.close()
        # Let this client know it has disconnected.
        try:
            self.on_disconnect()
        except Exception as exception:
            if uncaught == None:
                uncaught = exception
        # If there were no problems, return the session ID.
        if uncaught == None:
            return self.session
        else:
            raise uncaught

    def connect(self):
        """
        Creates a secure connection to the server and creates the client input
        and output utilities.
        """
        context = ssl.create_default_context()
        s = socket.create_connection((self.url, self.port))
        self.socket = context.wrap_socket(s, server_hostname=self.url)
        self.socket.do_handshake()
        self.input = _ClientInput(self.socket)
        self.output = _ClientOutput(self.socket)
        self.input.start()

    def receive(self, type=None):
        """
        Receives a message from the server as an object parsed from JSON,
        waiting if one is not available. None means the socket has been closed.
        If an exception was raised on the client listener thread, it is raised
        when this method is called instead of on that thread.
        """
        r = self.input.receive(type)
        return r

    def send(self, message):
        """
        Converts an object to JSON and send it to the server.
        """
        self.output.send(message)

    def close(self):
        """
        Closes this client's socket.
        """
        if self.socket is not None:
            try:
                self.socket.shutdown(socket.SHUT_RDWR)
                self.socket.close()
            except:
                pass

    def on_connect(self, connect):
        """
        Called after receiving the connect message from the server.
        """
        pass

    def on_start(self, world, role, state):
        """
        Called after the session starts.

        Arguments:
            world (dict[str, Any]): An object detailing the entities, variables,
                actions and endings available in this session's story world.
            role (str): The role this client is playing, which will be either
                PLAYER or GM.
            state (dict[str, Any]): An object giving the current value of all
                variables when the story starts.
        """
        pass

    def on_update(self, status):
        """
        Called when the server sends a story world status update.

        status['history'] is all turns that have happened so far.
        status['state'] gives the current value of all variables.
        status['ending'] gives the story's ending, or None if it is ongoing.
        status['descriptions'] gives descriptions of all visible entities.
        """
        pass

    @abstractmethod
    def on_choice(self, status) -> int:
        """
        Called when the server sends a story world status update that requires
        this client to choose what turn will happen next. This method must
        return the index (starting at 0) of the action it wants to take. The
        list of choices can be found in status['choices'].

        status['history'] is all turns that have happend so far.
        status['state'] gives the current value of all variables.
        status['ending'] gives the story's ending, or None if it is ongoing.
        status['descriptions'] gives descriptions of all visible entities.
        status['choices'] gives the list of currently available turns.
        """
        pass

    def on_end(self, ending):
        """
        Called when the story reaches one of its pre-defined endings.

        The `ending` object has a description of how the story ended.
        """
        pass

    def on_stop(self, message):
        """
        Always called at the end of the client's life if the session started.

        The `message` is a string explaining why the client stopped, and it may
        be None.
        """
        pass

    def on_close(self):
        """
        Called if the client stopped normally or because it was closed or
        disconnected. Not called if the client stopped because an exception was
        raised.
        """
        pass

    def on_disconnect(self):
        """
        Always called at the end of the client's life if it connected.
        """
        pass

    def on_warning(self, message):
        """
        Called if a non-fatal problem occurs with a string explanation.
        """
        print(f"Warning: {message}")

    def on_error(self, message):
        """
        Called if a fatal problem occurs with a string explanation.
        """
        raise RuntimeError(f"Error: {message}")

close()

Closes this client's socket.

Source code in src\tt\core.py
403
404
405
406
407
408
409
410
411
412
def close(self):
    """
    Closes this client's socket.
    """
    if self.socket is not None:
        try:
            self.socket.shutdown(socket.SHUT_RDWR)
            self.socket.close()
        except:
            pass

connect()

Creates a secure connection to the server and creates the client input and output utilities.

Source code in src\tt\core.py
374
375
376
377
378
379
380
381
382
383
384
385
def connect(self):
    """
    Creates a secure connection to the server and creates the client input
    and output utilities.
    """
    context = ssl.create_default_context()
    s = socket.create_connection((self.url, self.port))
    self.socket = context.wrap_socket(s, server_hostname=self.url)
    self.socket.do_handshake()
    self.input = _ClientInput(self.socket)
    self.output = _ClientOutput(self.socket)
    self.input.start()

on_choice(status) abstractmethod

Called when the server sends a story world status update that requires this client to choose what turn will happen next. This method must return the index (starting at 0) of the action it wants to take. The list of choices can be found in status['choices'].

status['history'] is all turns that have happend so far. status['state'] gives the current value of all variables. status['ending'] gives the story's ending, or None if it is ongoing. status['descriptions'] gives descriptions of all visible entities. status['choices'] gives the list of currently available turns.

Source code in src\tt\core.py
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
@abstractmethod
def on_choice(self, status) -> int:
    """
    Called when the server sends a story world status update that requires
    this client to choose what turn will happen next. This method must
    return the index (starting at 0) of the action it wants to take. The
    list of choices can be found in status['choices'].

    status['history'] is all turns that have happend so far.
    status['state'] gives the current value of all variables.
    status['ending'] gives the story's ending, or None if it is ongoing.
    status['descriptions'] gives descriptions of all visible entities.
    status['choices'] gives the list of currently available turns.
    """
    pass

on_close()

Called if the client stopped normally or because it was closed or disconnected. Not called if the client stopped because an exception was raised.

Source code in src\tt\core.py
478
479
480
481
482
483
484
def on_close(self):
    """
    Called if the client stopped normally or because it was closed or
    disconnected. Not called if the client stopped because an exception was
    raised.
    """
    pass

on_connect(connect)

Called after receiving the connect message from the server.

Source code in src\tt\core.py
414
415
416
417
418
def on_connect(self, connect):
    """
    Called after receiving the connect message from the server.
    """
    pass

on_disconnect()

Always called at the end of the client's life if it connected.

Source code in src\tt\core.py
486
487
488
489
490
def on_disconnect(self):
    """
    Always called at the end of the client's life if it connected.
    """
    pass

on_end(ending)

Called when the story reaches one of its pre-defined endings.

The ending object has a description of how the story ended.

Source code in src\tt\core.py
461
462
463
464
465
466
467
def on_end(self, ending):
    """
    Called when the story reaches one of its pre-defined endings.

    The `ending` object has a description of how the story ended.
    """
    pass

on_error(message)

Called if a fatal problem occurs with a string explanation.

Source code in src\tt\core.py
498
499
500
501
502
def on_error(self, message):
    """
    Called if a fatal problem occurs with a string explanation.
    """
    raise RuntimeError(f"Error: {message}")

on_start(world, role, state)

Called after the session starts.

Parameters:

Name Type Description Default
world dict[str, Any]

An object detailing the entities, variables, actions and endings available in this session's story world.

required
role str

The role this client is playing, which will be either PLAYER or GM.

required
state dict[str, Any]

An object giving the current value of all variables when the story starts.

required
Source code in src\tt\core.py
420
421
422
423
424
425
426
427
428
429
430
431
432
def on_start(self, world, role, state):
    """
    Called after the session starts.

    Arguments:
        world (dict[str, Any]): An object detailing the entities, variables,
            actions and endings available in this session's story world.
        role (str): The role this client is playing, which will be either
            PLAYER or GM.
        state (dict[str, Any]): An object giving the current value of all
            variables when the story starts.
    """
    pass

on_stop(message)

Always called at the end of the client's life if the session started.

The message is a string explaining why the client stopped, and it may be None.

Source code in src\tt\core.py
469
470
471
472
473
474
475
476
def on_stop(self, message):
    """
    Always called at the end of the client's life if the session started.

    The `message` is a string explaining why the client stopped, and it may
    be None.
    """
    pass

on_update(status)

Called when the server sends a story world status update.

status['history'] is all turns that have happened so far. status['state'] gives the current value of all variables. status['ending'] gives the story's ending, or None if it is ongoing. status['descriptions'] gives descriptions of all visible entities.

Source code in src\tt\core.py
434
435
436
437
438
439
440
441
442
443
def on_update(self, status):
    """
    Called when the server sends a story world status update.

    status['history'] is all turns that have happened so far.
    status['state'] gives the current value of all variables.
    status['ending'] gives the story's ending, or None if it is ongoing.
    status['descriptions'] gives descriptions of all visible entities.
    """
    pass

on_warning(message)

Called if a non-fatal problem occurs with a string explanation.

Source code in src\tt\core.py
492
493
494
495
496
def on_warning(self, message):
    """
    Called if a non-fatal problem occurs with a string explanation.
    """
    print(f"Warning: {message}")

receive(type=None)

Receives a message from the server as an object parsed from JSON, waiting if one is not available. None means the socket has been closed. If an exception was raised on the client listener thread, it is raised when this method is called instead of on that thread.

Source code in src\tt\core.py
387
388
389
390
391
392
393
394
395
def receive(self, type=None):
    """
    Receives a message from the server as an object parsed from JSON,
    waiting if one is not available. None means the socket has been closed.
    If an exception was raised on the client listener thread, it is raised
    when this method is called instead of on that thread.
    """
    r = self.input.receive(type)
    return r

run()

Connects to the server, joins, waits for a session to start, sends the choices made by this client, and returns the session ID of the completed session. As this method runs, it calls other methods to notify the client of important events. Some of these methods are guaranteed to be called even if an exception is raised. The list of those methods is:

  1. connect is called to establish the socket. If this method raises an exception, it is raised immediately and no other methods run.
  2. on_connect is called after receiving the connect message from the server. This is the last chance to make changes to the join request.
  3. on_start is called after the session starts.
  4. on_update is called each time the client receives an update to the story world status from the server.
  5. on_choice is called when the client receives an update that requires it to make a choice of what action to take next.
  6. on_end is called if the story reaches a pre-defined ending.
  7. on_close is called when the client stops its session normally, like reaching the end of the story, closing, or disconnecting. If the client stopped because it was interrupted or because of an exception, this method is not called.
  8. on_stop will always be called if the client's session started.
  9. on_disconnect will always be called if the client connected.
Source code in src\tt\core.py
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
def run(self):
    """
    Connects to the server, joins, waits for a session to start, sends the
    choices made by this client, and returns the session ID of the completed
    session. As this method runs, it calls other methods to notify the
    client of important events. Some of these methods are guaranteed to be
    called even if an exception is raised. The list of those methods is:

    1. `connect` is called to establish the socket. If this method raises
       an exception, it is raised immediately and no other methods run.
    2. `on_connect` is called after receiving the connect message from the
       server. This is the last chance to make changes to the join request.
    3. `on_start` is called after the session starts.
    4. `on_update` is called each time the client receives an update to the
       story world status from the server.
    5. `on_choice` is called when the client receives an update that
       requires it to make a choice of what action to take next.
    6. `on_end` is called if the story reaches a pre-defined ending.
    7. `on_close` is called when the client stops its session normally,
       like reaching the end of the story, closing, or disconnecting. If
       the client stopped because it was interrupted or because of an
       exception, this method is not called.
    8. `on_stop` will always be called if the client's session started.
    9. `on_disconnect` will always be called if the client connected.
    """
    # Warn if the password and API key are not set.
    if self.join_message['password'] == None and not ENV_PASSWORD in os.environ:
        self.on_warning(f"The environment variable \"{ENV_PASSWORD}\" is not set. This agent will not use a password.")
    if self.external.key == None and not ENV_API_KEY in os.environ:
        self.on_warning(f"The environment variable \"{ENV_API_KEY}\" is not set. This agent will not be able to use the external API.")
    # Connect to the server.
    self.connect()
    # If an exception is raised, save it to raise later.
    uncaught = None
    try:
        # Wait for the connect message.
        connect = self.receive('Connect')
        if connect != None:
            if connect['version'] != VERSION:
                self.on_warning(f"This client is using version {VERSION} of the communication protocol, but the server is using version {connect['version']}. This may cause miscommunications.")
            self.on_connect(connect)
            self.send(self.join_message)
        # Wait for the start message.
        start = self.receive('Start')
        if start != None:
            self.world = start['world']
            self.role = start['role']
            if self.factory != None:
                self.factory._on_start(self)
        # Receive and process messages from the server.
        while self.world != None:
            message = self.receive()
            # Stop if disconnected.
            if message == None:
                break
            # Handle update messages.   
            elif message['type'] == "Update":
                # If this is the first update, notify the client the session has started.
                if self.status == None:
                    self.status = message['status']
                    self.choices = message['status']['choices']
                    self.on_start(self.world, self.role, self.status['state'])
                # If this is not the first update, update the current status and choices.
                else:
                    self.status = message['status']
                    self.choices = message['status']['choices']
                    self.on_update(self.status)
                # If it is this client's turn, make a choice.
                if len(self.choices) > 0:
                    index = self.on_choice(self.status)
                    self.choices = json.loads('[]')
                    choice = {
                        "type": "Choice",
                        "index": index
                    }
                    if not self.input.stopped:
                        self.send(choice)
                # If the story has ended, notify this client.
                elif self.status.get('ending') is not None:
                    self.on_end(self.status['ending'])
            # Immediately acknowledge stop messages.
            elif message['type'] == "Stop":
                self.stop = message
                stop = {
                    "type": "Stop",
                    "role": self.role
                }
                self.send(stop)
                self.on_stop(self.stop['message'])
            # Get session ID from end message.
            elif message['type'] == "End":
                self.session = message['session']
                break
            # Handle errors reported by the server.
            elif message['type'] == "Error":
                self.on_error(message['message'])
            # Handle unrecognized message types.
            else:
                m = str(message)
                if len(m) > 40:
                    m = m[:40] + '...'
                self.on_error(f"The message \"{m}\" is not recognized.")
    # Register an uncaught exception.
    except Exception as exception:
        uncaught = exception
    # If the client is interrupted...
    except KeyboardInterrupt as interrupt:
        if uncaught == None:
            uncaught = Exception("Client was interrupted.")
    # If this client ended normally, close.
    if uncaught == None:
        try:
            self.on_close()
        except Exception as exception:
            uncaught = exception
    # If the session started but has not stopped, stop it.
    if self.world != None and self.stop == None:
        try:
            self.on_stop(None)
        except Exception as exception:
            if uncaught == None:
                uncaught = exception
    # Close the socket.
    self.close()
    # Let this client know it has disconnected.
    try:
        self.on_disconnect()
    except Exception as exception:
        if uncaught == None:
            uncaught = exception
    # If there were no problems, return the session ID.
    if uncaught == None:
        return self.session
    else:
        raise uncaught

send(message)

Converts an object to JSON and send it to the server.

Source code in src\tt\core.py
397
398
399
400
401
def send(self, message):
    """
    Converts an object to JSON and send it to the server.
    """
    self.output.send(message)

tt.ExternalAPI

Represents the external API used for text embedding and completion.

Attributes:

Name Type Description
key str

The API key used to make requests.

embed_tokens int

The number of input tokens used so far by the text embedding model.

complete_in_tokens int

The number of input tokens used so far by the text completion model.

complete_out_tokens int

The number of output tokens used so far by the text completion model.

Parameters:

Name Type Description Default
key str

The API key used to make requests.

required
Source code in src\tt\core.py
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
class ExternalAPI:
    """
    Represents the external API used for text embedding and completion.

    Attributes:
        key (str): The API key used to make requests.
        embed_tokens (int): The number of input tokens used so far by the text
            embedding model.
        complete_in_tokens (int): The number of input tokens used so far by the
            text completion model.
        complete_out_tokens (int): The number of output tokens used so far by
            the text completion model.

    Arguments:
        key (str): The API key used to make requests.
    """

    def __init__(self, key):
        self.key = key
        self.embed_tokens = 0
        self.complete_in_tokens = 0
        self.complete_out_tokens = 0

    def _check_key(self):
        """
        Raises an exception if the API key is not set.
        """
        if self.key == None:
            raise ValueError('This agent does not have an API key. It cannot use the external API.')

    def _check_in_limit(self, used, limit):
        """
        Raise an exception if the number of input tokens used exceeds the limit.
        """
        if used >= limit:
            raise ValueError(f"The input token limit {limit} has been exceeded.")

    def _check_out_limit(self, used, limit):
        """
        Raise an exception if the number of output tokens used exceeds the limit.
        """
        if used >= limit:
            raise ValueError(f"The output token limit {limit} has been exceeded.")

    def _check_nominal(self, name, value, values):
        """
        Raise an exception if the value given is not a string from a pre-defined
        list.
        """
        if isinstance(value, str) and value in values:
            pass
        else:
            raise ValueError(f"{name} must be one of {values}.")

    def _check_int(self, name, value, min=None, max=None):
        """
        Raise an exception if the given value is not an integer in the given
        range.
        """
        if not isinstance(value, int):
            raise ValueError(f"{name} must be an integer.")
        elif min != None and value < min:
            raise ValueError(f"{name} must be >= {min}.")
        elif max != None and value > max:
            raise ValueError(f"{name} must be <= {max}.")

    def _check_float(self, name, value, min=None, max=None):
        """
        Raise an exception if the given value is not a float in the given range.
        """
        if not isinstance(value, float):
            raise ValueError(f"{name} must be a float.")
        elif min != None and value < min:
            raise ValueError(f"{name} must be >= {min}.")
        elif max != None and value > max:
            raise ValueError(f"{name} must be <= {max}.")

    def embed(self, text, dim=1024):
        """
        Queries the external text embedding API and returns its response as an
        array of floats. Each time this method is called, the number of tokens
        used is added to `embed_tokens`. If the number of tokens used exceeds
        `EMBED_TOKENS_LIMIT`, this method will raise an exception.

        Arguments:
            text (str): The text which will be embedded as an array of floats.
            dim (int): The number of dimensions in the returned array.
        """
        # Check if this request is possible.
        self._check_key()
        self._check_in_limit(self.embed_tokens, EMBED_TOKENS_LIMIT)
        # Construct the data object.
        data = {
            'model': EMBED_MODEL,
            'input_type': 'string',
            'input': text,
            'encoding_format': 'float'
        }
        if dim != None:
            self._check_int('Dimensions', dim)
            data['dimensions'] = dim
        # Send the request.
        response = requests.post(
            url=EMBED_URL,
            headers={
                'Authorization': f"Bearer {self.key}",
                'Content-Type': 'application/json',
            },
            data=json.dumps(data)
        )
        # Process the response.
        response.raise_for_status()
        response_data = json.loads(response.text)
        self.embed_tokens += response_data['usage']['total_tokens']
        return response_data['data'][0]['embedding']

    def complete(self, messages, maxt=None, reasoning='low', temp=0.0, topk=None, topp=None, minp=None):
        """
        Queries the external text completion API and returns its response as a
            string. Each time this method is called, the number of tokens used
            in the prompt is added to `complete_in_tokens` and the number of
            tokens used in reasoning and completion is added to
            `complete_out_tokens`. If the number of tokens used exceeds
            `COMPLETE_IN_TOKENS_LIMIT` or `COMPLETE_OUT_TOKENS_LIMIT`
            respectively, this method will raise an exception.

        Arguments:
            messages (str): This can be either a single string or an array of
                strings representing a conversation. If it is a single string,
                the model will use its default system prompt and treat the
                string as a message from the user. If it is an array of strings,
                it must have an even numbered length. The first string will be
                used as the system prompt. Every odd numbered message will be
                treated as a message from the user. Every even numbered message
                (after the first) will be treated as a response from the
                assistant.
            maxt (int): The maximum number of tokens the model may use to
                generate its response.
            reasoning (str): The level of reasoning used by the large language
                model during text completion. Values include `max`, `high`,
                `low`, and `none`.
            temp (float): Influences the randomness of the response. A value of
                0.0 will give deterministic responses. The max value is 2.0.
            topk (int): When choosing a next token to add to the output, the
                model may only choose from the best k tokens.
            topp (float): When choosing a next token to add to the output, the
                model may only choose from tokens whose probability add to p.
            minp (float): When choosing a next token to add to the output, the
                model may only choose from tokens whose probability is p times
                the probability of the most likely token.
        """
        # Check if this request is possible.
        self._check_key()
        self._check_in_limit(self.complete_in_tokens, COMPLETE_IN_TOKENS_LIMIT)
        self._check_out_limit(self.complete_out_tokens, COMPLETE_OUT_TOKENS_LIMIT)
        # Construct the conversation.
        msg = []
        # If messages is a single string, use no system prompt.
        if isinstance(messages, str):
            msg.append({ 'role': 'user', 'content': messages })
        # Otherwise, assume messages is an array of strings.
        else:
            if(len(messages) % 2 == 1):
                raise ValueError('Conversation must have an even number of messages.')
            msg.append({ 'role': 'system', 'content': messages[0] })
            for i, m in enumerate(messages[1:], start=1):
                if i % 2 == 1:
                    msg.append({ 'role': 'user', 'content': m })
                else:
                    msg.append({ 'role': 'assistant', 'content': m })
        # Construct the data object.
        data = {
            'model': COMPLETE_MODEL,
            'messages': msg,
            'seed': COMPLETE_SEED
        }
        if maxt != None:
            self._check_int('Max output tokens', maxt, 1)
            data['max_completion_tokens'] = maxt
        if reasoning != None:
            self._check_nominal('Reasoning level', reasoning, {'max', 'high', 'low', 'none'})
            data['reasoning_effort'] = reasoning
        if temp != None:
            self._check_float('Temperature', temp, 0.0, 2.0)
            data['temperature'] = temp
        if topk != None:
            self._check_int('Top k', topk)
            data['top_k'] = topk
        if topp != None:
            self._check_float('Top p', topp, 0.0, 1.0)
            data['top_p'] = topp
        if minp != None:
            self._check_float('Min p', minp, 0.0, 1.0)
            data['min_p'] = minp
        # Send the request.
        response = requests.post(
            url=COMPLETE_URL,
            headers={
                'Authorization': f"Bearer {self.key}",
                'Content-Type': 'application/json',
            },
            data=json.dumps(data)
        )
        # Process the response.
        response.raise_for_status()
        response_data = json.loads(response.text)
        self.complete_in_tokens += response_data['usage']['prompt_tokens']
        self.complete_out_tokens += response_data['usage']['completion_tokens']
        return response_data['choices'][0]['message']['content']

complete(messages, maxt=None, reasoning='low', temp=0.0, topk=None, topp=None, minp=None)

Queries the external text completion API and returns its response as a string. Each time this method is called, the number of tokens used in the prompt is added to complete_in_tokens and the number of tokens used in reasoning and completion is added to complete_out_tokens. If the number of tokens used exceeds COMPLETE_IN_TOKENS_LIMIT or COMPLETE_OUT_TOKENS_LIMIT respectively, this method will raise an exception.

Parameters:

Name Type Description Default
messages str

This can be either a single string or an array of strings representing a conversation. If it is a single string, the model will use its default system prompt and treat the string as a message from the user. If it is an array of strings, it must have an even numbered length. The first string will be used as the system prompt. Every odd numbered message will be treated as a message from the user. Every even numbered message (after the first) will be treated as a response from the assistant.

required
maxt int

The maximum number of tokens the model may use to generate its response.

None
reasoning str

The level of reasoning used by the large language model during text completion. Values include max, high, low, and none.

'low'
temp float

Influences the randomness of the response. A value of 0.0 will give deterministic responses. The max value is 2.0.

0.0
topk int

When choosing a next token to add to the output, the model may only choose from the best k tokens.

None
topp float

When choosing a next token to add to the output, the model may only choose from tokens whose probability add to p.

None
minp float

When choosing a next token to add to the output, the model may only choose from tokens whose probability is p times the probability of the most likely token.

None
Source code in src\tt\core.py
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
def complete(self, messages, maxt=None, reasoning='low', temp=0.0, topk=None, topp=None, minp=None):
    """
    Queries the external text completion API and returns its response as a
        string. Each time this method is called, the number of tokens used
        in the prompt is added to `complete_in_tokens` and the number of
        tokens used in reasoning and completion is added to
        `complete_out_tokens`. If the number of tokens used exceeds
        `COMPLETE_IN_TOKENS_LIMIT` or `COMPLETE_OUT_TOKENS_LIMIT`
        respectively, this method will raise an exception.

    Arguments:
        messages (str): This can be either a single string or an array of
            strings representing a conversation. If it is a single string,
            the model will use its default system prompt and treat the
            string as a message from the user. If it is an array of strings,
            it must have an even numbered length. The first string will be
            used as the system prompt. Every odd numbered message will be
            treated as a message from the user. Every even numbered message
            (after the first) will be treated as a response from the
            assistant.
        maxt (int): The maximum number of tokens the model may use to
            generate its response.
        reasoning (str): The level of reasoning used by the large language
            model during text completion. Values include `max`, `high`,
            `low`, and `none`.
        temp (float): Influences the randomness of the response. A value of
            0.0 will give deterministic responses. The max value is 2.0.
        topk (int): When choosing a next token to add to the output, the
            model may only choose from the best k tokens.
        topp (float): When choosing a next token to add to the output, the
            model may only choose from tokens whose probability add to p.
        minp (float): When choosing a next token to add to the output, the
            model may only choose from tokens whose probability is p times
            the probability of the most likely token.
    """
    # Check if this request is possible.
    self._check_key()
    self._check_in_limit(self.complete_in_tokens, COMPLETE_IN_TOKENS_LIMIT)
    self._check_out_limit(self.complete_out_tokens, COMPLETE_OUT_TOKENS_LIMIT)
    # Construct the conversation.
    msg = []
    # If messages is a single string, use no system prompt.
    if isinstance(messages, str):
        msg.append({ 'role': 'user', 'content': messages })
    # Otherwise, assume messages is an array of strings.
    else:
        if(len(messages) % 2 == 1):
            raise ValueError('Conversation must have an even number of messages.')
        msg.append({ 'role': 'system', 'content': messages[0] })
        for i, m in enumerate(messages[1:], start=1):
            if i % 2 == 1:
                msg.append({ 'role': 'user', 'content': m })
            else:
                msg.append({ 'role': 'assistant', 'content': m })
    # Construct the data object.
    data = {
        'model': COMPLETE_MODEL,
        'messages': msg,
        'seed': COMPLETE_SEED
    }
    if maxt != None:
        self._check_int('Max output tokens', maxt, 1)
        data['max_completion_tokens'] = maxt
    if reasoning != None:
        self._check_nominal('Reasoning level', reasoning, {'max', 'high', 'low', 'none'})
        data['reasoning_effort'] = reasoning
    if temp != None:
        self._check_float('Temperature', temp, 0.0, 2.0)
        data['temperature'] = temp
    if topk != None:
        self._check_int('Top k', topk)
        data['top_k'] = topk
    if topp != None:
        self._check_float('Top p', topp, 0.0, 1.0)
        data['top_p'] = topp
    if minp != None:
        self._check_float('Min p', minp, 0.0, 1.0)
        data['min_p'] = minp
    # Send the request.
    response = requests.post(
        url=COMPLETE_URL,
        headers={
            'Authorization': f"Bearer {self.key}",
            'Content-Type': 'application/json',
        },
        data=json.dumps(data)
    )
    # Process the response.
    response.raise_for_status()
    response_data = json.loads(response.text)
    self.complete_in_tokens += response_data['usage']['prompt_tokens']
    self.complete_out_tokens += response_data['usage']['completion_tokens']
    return response_data['choices'][0]['message']['content']

embed(text, dim=1024)

Queries the external text embedding API and returns its response as an array of floats. Each time this method is called, the number of tokens used is added to embed_tokens. If the number of tokens used exceeds EMBED_TOKENS_LIMIT, this method will raise an exception.

Parameters:

Name Type Description Default
text str

The text which will be embedded as an array of floats.

required
dim int

The number of dimensions in the returned array.

1024
Source code in src\tt\core.py
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
def embed(self, text, dim=1024):
    """
    Queries the external text embedding API and returns its response as an
    array of floats. Each time this method is called, the number of tokens
    used is added to `embed_tokens`. If the number of tokens used exceeds
    `EMBED_TOKENS_LIMIT`, this method will raise an exception.

    Arguments:
        text (str): The text which will be embedded as an array of floats.
        dim (int): The number of dimensions in the returned array.
    """
    # Check if this request is possible.
    self._check_key()
    self._check_in_limit(self.embed_tokens, EMBED_TOKENS_LIMIT)
    # Construct the data object.
    data = {
        'model': EMBED_MODEL,
        'input_type': 'string',
        'input': text,
        'encoding_format': 'float'
    }
    if dim != None:
        self._check_int('Dimensions', dim)
        data['dimensions'] = dim
    # Send the request.
    response = requests.post(
        url=EMBED_URL,
        headers={
            'Authorization': f"Bearer {self.key}",
            'Content-Type': 'application/json',
        },
        data=json.dumps(data)
    )
    # Process the response.
    response.raise_for_status()
    response_data = json.loads(response.text)
    self.embed_tokens += response_data['usage']['total_tokens']
    return response_data['data'][0]['embedding']

tt.Factory

Bases: ABC

A factory continuously creates clients so that when a client starts its session a new one will take its place waiting on the server. The abstract method create must be implemented; it should return a new client object.

Attributes:

Name Type Description
max int

The maximum number of clients that may be running at a time or 0 for no limit.

queue Queue

A queue of operations waiting to run on the factory's thread.

waiting list[Client]

The clients currently connected to the server and waiting.

running list[Client]

The clients currently in sessions.

uncaught Exception

An exception raised on another thread waiting to be raised on the factory's thread.

closed boolean

If the factory has been closed.

Parameters:

Name Type Description Default
max int

The maximum number of clients that may be running at a time or 0 for no limit.

0
Source code in src\tt\core.py
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
class Factory(ABC):
    """
    A factory continuously creates clients so that when a client starts its
    session a new one will take its place waiting on the server. The abstract
    method `create` must be implemented; it should return a new client object.

    Attributes:
        max (int): The maximum number of clients that may be running at a time
            or 0 for no limit.
        queue (queue.Queue): A queue of operations waiting to run on the
            factory's thread.
        waiting (list[Client]): The clients currently connected to the server
            and waiting.
        running (list[Client]): The clients currently in sessions.
        uncaught (Exception): An exception raised on another thread waiting to
            be raised on the factory's thread.
        closed (boolean): If the factory has been closed.

    Arguments:
        max (int): The maximum number of clients that may be running at a time
            or 0 for no limit.
    """

    def __init__(self, max=0):
        self.max = max
        self.queue = queue.Queue()
        self.waiting = []
        self.running = []
        self.executor = ThreadPoolExecutor()
        self.uncaught = None
        self.closed = False

    def __str__(self):
        tos = '[Client Factory: '
        if self.max > 0:
            tos += str(len(self.waiting) + len(self.running)) + '/' + str(self.max) + ' clients; '
        tos += f"{len(self.waiting)} waiting; {len(self.running)} running]"
        return tos

    def run(self):
        """
        Starts the factory, starts the first client, and creates new clients as
        allowed when clients start or end their sessions. Each client starts on
        a different thread, but if they raise exceptions, they will be handled
        on this thread. Certain things are guaranteed to happen in order:

        1. `on_start` is called when this method starts. If it raises an
           exception, no other methods are called.
        2. The first client is created via `create` and starts.
        3. Each time a client starts its session, a new client is created to
           take its place on the server, unless this would violate the
           factory's limit on the max number of clients.
        4. `on_close` runs when the factory is closed via the `close` method or
           if a client raises an exception. `on_close` is not called if the
           factory was interrupted. `on_close` always runs on the thread that
           called this method, even if `close` was called by a different thread.
        5. Before shutting down, the factory closes all clients that have not
           started their sessions and waits for all clients that have started
           their sessions to stop.
        6. `on_stop` is always called after all clients have stopped.
        7. If an exception was raised at any point, it is thrown after
           `on_stop`. If everything shut down normally, this method returns
           None.
        """
        # Let this factory know it has started.
        self.on_start()
        try:
            # Start the first client.
            self.queue.put(_StartFirstClient(self))
            # Run commands until closed.
            while not self.closed:
                operation = self.queue.get()
                operation()
            # Let this factory know it has closed.
            self.on_close()
        except Exception as exception:
            if self.uncaught == None:
                self.uncaught = exception
        except KeyboardInterrupt as interrupt:
            if self.uncaught == None:
                self.uncaught = Exception("Factory was interrupted.")
        # Close waiting clients.
        for client in self.waiting:
            client.close()
        # Wait for all clients to stop.
        self.executor.shutdown(wait=True)
        # Let this factory know it has stopped.
        try:
            self.on_stop()
        except Exception as exception:
            if self.uncaught == None:
                self.uncaught = exception
        # If there were no problems, return None.
        if self.uncaught == None:
            return None
        else:
            raise self.uncaught

    def on_start(self):
        """
        Called when this factory starts. This is a good place to set up assets
        before any clients start.
        """
        pass

    def _create(self):
        client = self.create()
        client.factory = self
        self.waiting.append(client)
        self.executor.submit(_RunClient(self, client))

    @abstractmethod
    def create(self) -> Client:
        """
        Create and return a new Tandem Tales client object. This method always
        runs on the same thread that called `run`.
        """
        pass

    def _on_start(self, client):
        self.queue.put(_StartClient(self, client))

    def _on_stop(self, client):
        self.queue.put(_StopClient(self, client))

    def close(self):
        """
        Stop this factory from creating any new clients and begin the shutdown
        process. This method can be safely called from any thread.
        """
        self.queue.put(_CloseFactory(self))

    def on_close(self):
        """
        Runs after this factory has been closed either by the `close` method or
        because an exception was raised by the factory or one of its clients.
        This method always runs on the same thread that called `run` even if
        `close` was called on a different thread.
        """
        pass

    def on_stop(self):
        """
        Called after all clients have stopped and this factory is about to stop.
        This is a good place to clean up.
        """
        pass

close()

Stop this factory from creating any new clients and begin the shutdown process. This method can be safely called from any thread.

Source code in src\tt\core.py
920
921
922
923
924
925
def close(self):
    """
    Stop this factory from creating any new clients and begin the shutdown
    process. This method can be safely called from any thread.
    """
    self.queue.put(_CloseFactory(self))

create() abstractmethod

Create and return a new Tandem Tales client object. This method always runs on the same thread that called run.

Source code in src\tt\core.py
906
907
908
909
910
911
912
@abstractmethod
def create(self) -> Client:
    """
    Create and return a new Tandem Tales client object. This method always
    runs on the same thread that called `run`.
    """
    pass

on_close()

Runs after this factory has been closed either by the close method or because an exception was raised by the factory or one of its clients. This method always runs on the same thread that called run even if close was called on a different thread.

Source code in src\tt\core.py
927
928
929
930
931
932
933
934
def on_close(self):
    """
    Runs after this factory has been closed either by the `close` method or
    because an exception was raised by the factory or one of its clients.
    This method always runs on the same thread that called `run` even if
    `close` was called on a different thread.
    """
    pass

on_start()

Called when this factory starts. This is a good place to set up assets before any clients start.

Source code in src\tt\core.py
893
894
895
896
897
898
def on_start(self):
    """
    Called when this factory starts. This is a good place to set up assets
    before any clients start.
    """
    pass

on_stop()

Called after all clients have stopped and this factory is about to stop. This is a good place to clean up.

Source code in src\tt\core.py
936
937
938
939
940
941
def on_stop(self):
    """
    Called after all clients have stopped and this factory is about to stop.
    This is a good place to clean up.
    """
    pass

run()

Starts the factory, starts the first client, and creates new clients as allowed when clients start or end their sessions. Each client starts on a different thread, but if they raise exceptions, they will be handled on this thread. Certain things are guaranteed to happen in order:

  1. on_start is called when this method starts. If it raises an exception, no other methods are called.
  2. The first client is created via create and starts.
  3. Each time a client starts its session, a new client is created to take its place on the server, unless this would violate the factory's limit on the max number of clients.
  4. on_close runs when the factory is closed via the close method or if a client raises an exception. on_close is not called if the factory was interrupted. on_close always runs on the thread that called this method, even if close was called by a different thread.
  5. Before shutting down, the factory closes all clients that have not started their sessions and waits for all clients that have started their sessions to stop.
  6. on_stop is always called after all clients have stopped.
  7. If an exception was raised at any point, it is thrown after on_stop. If everything shut down normally, this method returns None.
Source code in src\tt\core.py
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
def run(self):
    """
    Starts the factory, starts the first client, and creates new clients as
    allowed when clients start or end their sessions. Each client starts on
    a different thread, but if they raise exceptions, they will be handled
    on this thread. Certain things are guaranteed to happen in order:

    1. `on_start` is called when this method starts. If it raises an
       exception, no other methods are called.
    2. The first client is created via `create` and starts.
    3. Each time a client starts its session, a new client is created to
       take its place on the server, unless this would violate the
       factory's limit on the max number of clients.
    4. `on_close` runs when the factory is closed via the `close` method or
       if a client raises an exception. `on_close` is not called if the
       factory was interrupted. `on_close` always runs on the thread that
       called this method, even if `close` was called by a different thread.
    5. Before shutting down, the factory closes all clients that have not
       started their sessions and waits for all clients that have started
       their sessions to stop.
    6. `on_stop` is always called after all clients have stopped.
    7. If an exception was raised at any point, it is thrown after
       `on_stop`. If everything shut down normally, this method returns
       None.
    """
    # Let this factory know it has started.
    self.on_start()
    try:
        # Start the first client.
        self.queue.put(_StartFirstClient(self))
        # Run commands until closed.
        while not self.closed:
            operation = self.queue.get()
            operation()
        # Let this factory know it has closed.
        self.on_close()
    except Exception as exception:
        if self.uncaught == None:
            self.uncaught = exception
    except KeyboardInterrupt as interrupt:
        if self.uncaught == None:
            self.uncaught = Exception("Factory was interrupted.")
    # Close waiting clients.
    for client in self.waiting:
        client.close()
    # Wait for all clients to stop.
    self.executor.shutdown(wait=True)
    # Let this factory know it has stopped.
    try:
        self.on_stop()
    except Exception as exception:
        if self.uncaught == None:
            self.uncaught = exception
    # If there were no problems, return None.
    if self.uncaught == None:
        return None
    else:
        raise self.uncaught