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 | |
close()
Closes this client's socket.
Source code in src\tt\core.py
403 404 405 406 407 408 409 410 411 412 | |
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 | |
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 | |
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 | |
on_connect(connect)
Called after receiving the connect message from the server.
Source code in src\tt\core.py
414 415 416 417 418 | |
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 | |
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 | |
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 | |
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 | |
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 | |
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 | |
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 | |
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 | |
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:
connectis called to establish the socket. If this method raises an exception, it is raised immediately and no other methods run.on_connectis called after receiving the connect message from the server. This is the last chance to make changes to the join request.on_startis called after the session starts.on_updateis called each time the client receives an update to the story world status from the server.on_choiceis called when the client receives an update that requires it to make a choice of what action to take next.on_endis called if the story reaches a pre-defined ending.on_closeis 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.on_stopwill always be called if the client's session started.on_disconnectwill 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 | |
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 | |
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 | |
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 |
'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 | |
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 | |
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 | |
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 | |
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 | |
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 | |
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 | |
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 | |
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:
on_startis called when this method starts. If it raises an exception, no other methods are called.- The first client is created via
createand starts. - 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.
on_closeruns when the factory is closed via theclosemethod or if a client raises an exception.on_closeis not called if the factory was interrupted.on_closealways runs on the thread that called this method, even ifclosewas called by a different thread.- 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.
on_stopis always called after all clients have stopped.- 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 | |