Project December API

This API allows you to participate in a conversation with a specific personality matrix programmatically.

The matrix that you specify will be spun up as a "hidden" matrix for your account (not accessible from your owned matrix menu inside the Project December client terminal). This matrix will not burn credits when it is created, but instead will burn credits as needed when you talk to it. If you run out of credits, you will be unable to talk to it further until you add more credits to your account. But the matrix itself will effectively "live forever."

Dialog Example

This URL is split onto multiple lines for clarity:

http://projectdecember.net/novemberServer/server.php
?action=single_response
&email=test@test.com
&sequence_number=3046
&hash_value=EA8912B3FB4407530916EF3EA62D551AA7A539F4
&ai_name=CONCORD+G3
&client_command=Hello+there

The email, ai_name, and client_command parameters are self-explanatory.

Note that client_command can be wipe to wipe the buffer of the hidden matrix.

Personality Creation Example

This URL is split onto multiple lines for clarity:

http://projectdecember.net/novemberServer/server.php
?action=remote_custom_create
&email=test@test.com
&sequence_number=3046
&hash_value=EA8912B3FB4407530916EF3EA62D551AA7A539F4
&ai_name=ALICE+3
&ai_cost=200
&ai_color=%238888FF
&human_color=%23FF8888
&ai_label=Alice
&human_label=Bob
&intro_paragraph=What+follows+is+a+conversation+
between+Alice%2C+an+AI+assistant%2C+and+Bob%2C+her+human+
client.++Alice+is+helpful+and+friendly%2C+but+she+
also+has+a+sharp+wit.++She+keeps+Bob+on+his+toes.
&example_utterance=Hello%2C+Bob%2C+what+can+I+do+for+you+today%3F
&ai_engine=g4

These parameters correspond to the questions asked during custom personality creation inside the Project December terminal.

Note that because personalities are accessed using ai_name in your single_response calls, each ai_name that you create should be unique.

Getting a sequence_number

The sequence number prevents replay attacks using the same hash, and can only be used to issue one command to the server. After that, the next-higher sequence number can be used.

http://projectdecember.net/novemberServer/server.php
?action=get_client_sequence_number
&email=test@test.com

Computing a hash_value

The has value is computed like this:

HMAC_SHA1( $pass_words, $sequence_number )

Where $pass_words has no spaces between words (all words run together, in order) and is all lowercase.

How you you actually compute HMACs will vary with your programming language. In PHP, for example, it is computed like this:

hash_hmac( "sha1", $sequence_number, $pass_words );

Managing sequence numbers

Every valid client command on the server increments that account's sequence number. If you are going to issue a sequence of commands, you can get the sequence number once in the beginning, and then track and increment it yourself on your end, without fetching it again before each new command.

Forcing short responses

In some contexts, like speech-based integrations, long-winded responses are cumbersome. Specifying:

&force_short=1

as a parameter to the above URL will cut off extended generation at the end of the first complete sentence.

Remote observation

You can observe conversations with your hidden matrices (which are created through this API), with the following URL:

http://projectdecember.net/terminal/observe.html

You can also fetch this observation text programmatically with the following API url:

http://projectdecember.net/novemberServer/server.php
?action=observe_text
&email=test@test.com
&sequence_number=3046
&hash_value=EA8912B3FB4407530916EF3EA62D551AA7A539F4
&ai_name=Concord+g3

Note that this call does NOT increment the sequence number, because it's meant to be called in parallel with another command stream. So it's best to call get_client_sequence_number each time, before each subsequent call to observe_text.