threeza

threeza / Template / 0.3.0

README.md

Overview

This algorithm provides a template you can modify. It illustrates conveniences offered by www.3za.org such as the ability to:

  • Create a www.3za.org/mutable/ page which tells Threeza how to call your algo and render it at www.3za.org/pipe
  • Subscribe your algorithm to receive data from a page at www.3za.org/mutable when it changes
  • Publish output from your model to a www.3za.org/mutable page without having to deal with publishing and write key management of the output page(s) directly.
  • Participate in challenges where you may be rewarded for accuracy.

You need only be familiar with some lightweight conventions which apply both to the algorithm input/output but also to this documentation page.

Don't call this algorithm

Copy the code and make one for yourself. You algorithm will make use of data://.my/algo/perm/self.json to create its unique identifier using to hash inza to outza ... more on that later.

You must write a /doc !

This documentation page is as important as the code because it is read by the sophons and used to authorize pipe pages.

List authorized pipe pages in doc

A pipe page is a mutable page which tells Threeza how to invoke your function, which it will do if someone visits the corresponding www.3za.org/pipe page.

Authorized pipe pages for threeza/template
threeza-template-pipe-example-input.json

Threeza will only invoke your function if the pipe page name is mentioned somewhere on this documentation page. Otherwise Threeza won't call invoke when a call to www.3za.org/pipe/ is made.

Pipe page example

This algo has a pipe page at mutable/threeza-template-pipe-example-input.json which contains instructions used by Threeza to render the page pipe/threeza-template-pipe-example-input.json. On the other hand, this page won't invoke this function because the URL www.3za.org/pipe/threeza-template-unauthorized-pipe-page.json isn't mentioned on this page.

How pipe pages work

If you take a look at the instructions page you will see that there is a code 505e7ab1-600b-3a52-9b91-d0e9c07703cd mentioned. This is a hash of any valid Algorithmia API key which can call this algorithm. The Algorithmia API key previously been supplied to Threeza at threeza/ApiKeyRegistration. Threeza stores a lookup of hashes to algorithm keys.

How to make a pipe page

Copy threezatemplates/PipePage Use a UUID for the name of the page if you don't want others to use it.

Attribution to user "0@3za.org"

This algorithm is attributed to user=0@3za.org because the organization owner at user page has used the Algorithmia name to tie an Algorithmia username to a Threeza identity. This identity was previously obtained at threeza/Self Registration. This can be useful for key and page management, alerts and notifications and so forth. It is recommended.

Input / Output conventions

Now we return to algorithm.

Implicit output stream creation

Some Threeza participating algorithms such as this example receive and return dictionaries and, furthermore, expect a value for inza in the input and, furthermore, return a dictionary with outza in the output. Do read about inza and outza and the rule of three.

Don't create predictable outza

# Anti-pattern ! Don't do this !
outza = str(uuid.uuid3(namespace=uuid.NAMESPACE_DNS, inza))   

See the source code of this algorithm for better ideas and as they say in Ghostbusters, don't cross the streams!

Save an example input when publishing

Your algorithm and the feed you subscribe to will likely have many other fields as well. Good citizens of Threeza will create example input/output examples when publishing because these can be seen by the sophons and other members of the community. And this isn't hard. See jsonpath/threeza-template-inza-outza.json for a rendering of the example input/output for this algorithm, driven by instructions at mutable/threeza-template-inza-outza.json which were in turn created by threezatemplates/InputOutputJsonPage.

Error logging

Coming soon.

Output logging

Coming soon.

Algorithm benchmarking

Coming soon.