Constants¶

common.constants.ALGO_AMOUNT_CAP = 1000¶

Hard limit for all transaction amounts. Prevents test accounts from being drained

class common.constants.OpCodes¶

Valid op codes to be included in transactions

__init__() → None¶

Utils¶

common.utils.check_balance(address: str)¶

Returns the current balance of the given address

Parameters:

address – The algorand address to check the balance of

Returns:

The balance of the account

common.utils.create_account()¶

Creates an algorand wallet

Returns:

The credentials to the account

common.utils.flatten_locals(local_args: dict)¶

Takes in an attribute dict from locals(), inlines any kwargs and removes special keys

Parameters:

local_args – A dictionary of local variables to flatten

Returns:

A flattened dictionary of the attributes

common.utils.search_transactions(limit=10, **kwargs)¶

Searches the blockchain for recent transactions matching some given criteria

Parameters:

limit – The maximum number of transactions to return

common.utils.transact(sender: str, sender_secret: str, receiver: str, amount: int, note: str | None = None)¶

Creates a transaction and sends it to the blockchain

Parameters:

• sender – The address of the transaction sender

• sender_secret – The secret key of the sender to sign the transaction

• receiver – The address of the transaction recipient

• amount – The amount to send

• note – The note to send along with the transaction

Returns:

The id of the transaction

ClientCore¶

class client.clientCore.ClientState¶

Allows for the client state to persist between classes

classmethod init()¶

Loads in the client credentials and initializes the monitor

class client.clientCore.ClientTransactionMonitor(address: str, all_time=False)¶

Class to keep the user updated on incoming transactions or responses from the oracle

__init__(address: str, all_time=False)¶

Class to keep the user updated on incoming transactions or responses from the oracle

Parameters:

• address – The address of the user

• all_time – Gathers complete transaction history if True instead of just recent transactions

clear_queue()¶

Removes all unobserved transactions from the queue

Returns:

The list of queued transactions

process_incoming(txn: dict[str, Any])¶

Processes the latest incoming transactions to the user

Parameters:

txn – The incoming transaction dictionary

txn_queue¶

Stores queue of recent transactions for the user to see

client.clientCore.add_dataset(ds_name: str, ds_link: str, ds_size: int, time_attrib: str, endpoint='', sub_split_attrib='')¶

Creates a transaction to ask for a new dataset to be added and trained on a base model

Parameters:

• ds_name – The name that will be assigned to the new dataset

• ds_link – The URL that links to the dataset. This URL must yield a stream of bytes upon GET

• ds_size – The size of the dataset

• time_attrib – The attribute of the data that denotes the passage of time

• endpoint – The name of the endpoint that is associated with the dataset

• sub_split_attrib – The attribute that is used to split the dataset into independent subsets

Returns:

The id of the transaction to the oracle

client.clientCore.add_dataset_api()¶

Requests to add a dataset from the UI to the client

JSON Data

• ds_name (str) - The name that will be assigned to the new dataset

• ds_link (str) - The URL that links to the dataset. This URL must yield a stream of bytes upon GET

• ds_size (str) - The size of the dataset

• time_attrib (str) - The attribute of the data that denotes the passage of time

Optional JSON Data

• endpoint (str) - The name of the endpoint that is associated with the dataset

• sub_split_attrib (str) - The attribute that is used to split the dataset into independent subsets

Returns:

The id of the transaction that was created

client.clientCore.create_new_account()¶

Creates a new account keypair and returns it

Returns:

Newly generated address credentials

client.clientCore.dataset_upload_price()¶

Requests to see the price for uploading a dataset

Query Params

• ds_size (int) - The size of the dataset in bytes

Returns:

The price of the transaction and the transaction id where that price was last changed

client.clientCore.docs()¶

Gets the index page for the documentation

Returns:

The index page for the documentation

client.clientCore.get_dataset_upload_price(ds_size: int) → tuple[int, str]¶

Retrieves the upload price from the oracle. This can be verified with the returned transaction id

Parameters:

ds_size – The size of the dataset that is planned to upload

Returns:

The price of uploading a dataset and the transaction id where that price was last modified

client.clientCore.get_datasets()¶

Gets a dictionary of all the stored datasets and their attributes

Returns:

A dictionary of all the stored datasets and their attributes

client.clientCore.get_model_query_price(trained_model: str) → tuple[int, str]¶

Retrieves the query price from the oracle. This can be verified with the returned transaction id

Parameters:

trained_model – The name of the trained model to query

Returns:

The price of querying a model and the transaction id where that price was last modified

client.clientCore.get_model_train_price(raw_model: str, ds_name: str, hidden_dim: int, num_hidden_layers: int) → tuple[int, str]¶

Retrieves the model price from the oracle. This can be verified with the returned transaction id

Parameters:

• raw_model – The name of the base model

• ds_name – The name of the dataset to train the model on

• hidden_dim – The dimension of the hidden layers

• num_hidden_layers – The number of hidden layers to put into the model

Returns:

The price of training a model and the transaction id where that price was last modified

client.clientCore.get_models()¶

Gets a dictionary of all the stored models and their attributes

Returns:

A dictionary of all the stored models and their attributes

client.clientCore.model_query_price()¶

Requests to see the price for querying a model

Query Params

• trained_model (str) - The name of the trained model to query

Returns:

The price of the transaction and the transaction id where that price was last changed

client.clientCore.model_train_price()¶

Requests to see the price for training a model

Query Params

• raw_model (str) - The name of the raw model to train

• ds_name (str) - The name of the dataset to train the model on

• hidden_dim (int) - The dimension of the hidden layers

• num_hidden_layers (int) - The number of hidden layers to put into the model

Returns:

The price of the transaction and the transaction id where that price was last changed

client.clientCore.ping()¶

Accepts pings to report that the client is running properly

Returns:

A ping message

client.clientCore.query_model(trained_model: str, model_input: list)¶

Creates a transaction to ask for a query from the specified model

Parameters:

• trained_model – The trained model to query

• model_input – The input to the trained model

Returns:

The id of the transaction to the oracle

client.clientCore.query_model_api()¶

Requests to query a model from the UI to the client

JSON Data

• trained_model (str) - The name of the trained model to query

• model_input (str) - The input to the model

Returns:

The id of the transaction that was created

client.clientCore.send_static_file(filename)¶

Gets any folder located in the _static directory of the sphinx documentation

Parameters:

filename – The name of the file to get

Returns:

The corresponding file

client.clientCore.train_model(raw_model: str, trained_model: str, ds_name: str, num_epochs: int, target_attrib: str, hidden_dim: int, num_hidden_layers: int, **kwargs)¶

Creates a transaction to ask for a new dataset to be added and trained on a base model

Parameters:

• raw_model – The raw model to train

• trained_model – The name of the new trained model

• ds_name – The name of the dataset to train the model on

• num_epochs – The number of epochs to train the model for

• target_attrib – The name of the attribute that is used to test

• hidden_dim – The size of the hidden layers

• num_hidden_layers – The number of hidden layers

Returns:

The id of the transaction to the oracle

client.clientCore.train_model_api()¶

Requests to train a model from the UI to the client

JSON Data

• raw_model (str) - The raw model to train

• trained_model (str) - The name of the new trained model

• ds_name (str) - The name of the dataset to train the model on

• num_epochs (int) - The number of epochs to train the model for

• target_attrib (str) - The name of the attribute that is used to test

• hidden_dim (int) - The size of the hidden layers

• num_hidden_layers (int) - The number of hidden layers

Optional JSON Data

• sub_split_value (str) - The value used to split the data along the saved sub_split attribute

• loss_fn_name (str) - The name of the loss function to use while training

• optimizer_name (str) - The name of the optimizer to use while training

• learning_rate (float) - The learning rate to use while training

• training_lookback (int) - The size of the lookback window to use when training time series networks

Returns:

The id of the transaction that was created

client.clientCore.update_state()¶

Gets a report of recent updates to the state of the blockchain and reports them back to the user

Returns:

A list of transactions that have recently been received by the client address

OracleCore¶

class oracle.oracleCore.OracleState¶

Allows for the client state to persist between classes

classmethod init()¶

Initializes the internal state of the oracle and initializes the monitor

class oracle.oracleCore.OracleTransactionMonitor(all_time=False)¶

Keeps the oracle updated on incoming transactions from users, real world events

__init__(all_time=False)¶

Keeps the oracle updated on incoming transactions from users, real world events

Parameters:

all_time – Gathers complete transaction history if True instead of just recent transactions

process_incoming(txn)¶

Execute operations based on the OP code of the incoming transaction

Parameters:

txn – The incoming transaction

class oracle.oracleCore.Pricing¶

Class to keep track and modify the pricing of transactions

classmethod calc_dataset_upload_price(ds_size: int)¶

Calculates and returns the latest price and the transaction id where it was changed

Parameters:

ds_size – The size of the dataset that is to be uploaded

Returns:

The price of uploading a dataset and the transaction id of the last time the price multiplier was changed

classmethod calc_ds_usage_incentive(ds_size: int, accuracy: float)¶

Calculates and returns the reward for a dataset being used in a model

Parameters:

• ds_size – The size of the dataset that has been used

• accuracy – The accuracy attained by the model trained on the dataset

Returns:

The reward for having uploaded a useful dataset and the transaction id of the last time the reward multiplier was changed

classmethod calc_model_query_price(trained_model: str)¶

Calculates and returns the latest price and the transaction id where it was changed

Parameters:

trained_model – The name of the trained model to query

Returns:

The price of querying that model and the transaction id of the last time the price multiplier was changed

classmethod calc_model_train_price(raw_model: str, ds_name: str, hidden_dim: int, num_hidden_layers: int)¶

Calculates and returns the latest price and the transaction id where it was changed

Parameters:

• raw_model – The name of the raw model to train

• ds_name – The name of the dataset to train the model on

• hidden_dim – The dimension of the hidden layers

• num_hidden_layers – The number of hidden layers to put into the model

Returns:

The price of training a model and the transaction id of the last time the price multiplier was changed

classmethod calc_model_usage_incentive(accuracy: float)¶

Calculates and returns the reward for a model being used

Parameters:

accuracy – The accuracy attained by the model trained on the dataset

Returns:

The reward for having trained a useful model and the transaction id of the last time the reward multiplier was changed

classmethod calc_op_price(op: str, ds_name=None, ds_size=None, raw_model=None, trained_model=None, hidden_dim=None, num_hidden_layers=None, **_)¶

Helper method to get the price for any given operation

Parameters:

• op – The operation to calculate the price for

• ds_name – The name of the dataset if involved in the operation

• ds_size – The size of the dataset if involved in the operation

• raw_model – The name of the raw model if involved in the operation

• trained_model – The name of the trained model if involved in the operation

• hidden_dim – The dimension of the hidden layers

• num_hidden_layers – The number of hidden layers to put into the model

Returns:

The price of the given operation and the transaction id of the last time the price multiplier was changed

classmethod get_price_multiplier(mul_op: str) → tuple[float, str]¶

Gets the price multiplier from the database and returns it and the transaction id where it was last changed

Parameters:

mul_op – The operation to get the multiplier for

Returns:

The multiplier and the transaction id of the last time the multiplier was changed

mult_cache = {}¶

Dict to keep track of the multipliers for all of the prices

classmethod set_price_multiplier(mul_op: str, new_mul: float)¶

Sends an update txn. Stores transaction id and the new price multiplier in the database

Parameters:

• mul_op – The operation to set the multiplier for

• new_mul – The new multiplier for the price/reward associated with the operation

Returns:

The transaction id of the multiplier changing transaction

oracle.oracleCore.get_datasets()¶

Gets a dictionary of all the stored datasets and their attributes

Returns:

A dictionary of all the stored datasets and their attributes

oracle.oracleCore.get_models()¶

Gets a dictionary of all the stored models and their attributes

Returns:

A dictionary of all the stored models and their attributes

oracle.oracleCore.ping()¶

Accepts pings to report that the oracle is running properly

Returns:

A ping message

oracle.oracleCore.report_dataset_upload_price()¶

Requests to see the price for uploading a dataset

Query Params

• ds_size (int) - The size of the dataset in bytes

Returns:

The price of the transaction and the transaction id where that price was last changed

oracle.oracleCore.report_model_query_price()¶

Requests to see the price for querying a model

Query Params

• trained_model (str) - The name of the trained model to query

Returns:

The price of the transaction and the transaction id where that price was last changed

oracle.oracleCore.report_model_train_price()¶

Requests to see the price for training a model

Query Params

• raw_model (str) - The name of the raw model to train

• ds_name (str) - The name of the dataset to train the model on

• hidden_dim (int) - The dimension of the hidden layers

• num_hidden_layers (int) - The number of hidden layers to put into the model

Returns:

The price of the transaction and the transaction id where that price was last changed

DataManager¶

class oracle.dataManager.Database(use_redis=True)¶

Class used to store oracle information and provide compatability when redis is not available

__init__(use_redis=True)¶

Class used to store oracle information and provide compatability when redis is not available

Parameters:

use_redis – Flag that determines if the usage of redis should be attempted

exists(key: str)¶

Checks if a key exists in the database

Parameters:

key – The key to check for

Returns:

1 if the key is in the database, 0 otherwise

get(key: str) → dict¶

Gets the value of a key in the database

Parameters:

key – The key to retrieve the value of

Returns:

The value of the key

keys()¶

Returns a list of all keys in the database

Returns:

The list of database keys

scan_iter(prefix=None)¶

Returns an iterator that iterates over the keys in the database

Parameters:

prefix – Filters out all keys that do not begin with this value

Returns:

An iterator over all the keys

set(key: str, value: dict)¶

Sets a key, value pair in the database

Parameters:

• key – The key to store

• value – The value to store

oracle.dataManager.database = <oracle.dataManager.Database object>¶

Database used to store oracle information

oracle.dataManager.enum_database(env: str, prefix: str)¶

Enumerates the given database, filtering keys by the given prefix

Parameters:

• env – The environment to look for the data in

• prefix – The common prefix between all the entry keys that will be enumerated

Returns:

A dictionary of all the selected keys

oracle.dataManager.load_database(filepath: str, overwrite=False)¶

Loads the contents of a json file and puts each item into the database

Parameters:

• filepath – The path to the file to be loaded

• overwrite – Flag to determine if an existing key will be overwritten by an incoming value

oracle.dataManager.save_database(filepath: str)¶

Saves the contents of the database to a file

Parameters:

filepath – The file to save the database to

oracle.dataManager.web3 = <web3storage.Client object>¶

The storage client for IPFS

Models¶

class oracle.models.BaseNN(model_name: str, data_handler: DataHandler, hidden_dim: int, num_hidden_layers: int, loss_fn_name: str = 'mae', **kwargs)¶

Parent class encapsulating the behaviour of other neural network classes

__init__(model_name: str, data_handler: DataHandler, hidden_dim: int, num_hidden_layers: int, loss_fn_name: str = 'mae', **kwargs)¶

Parent class encapsulating the behaviour of other neural network classes

Parameters:

• model_name – The name given to this instance of a model

• data_handler – The handler for the dataset that the model will use

• hidden_dim – The dimension of the hidden layers

• num_hidden_layers – The number of hidden layers to put into the model

• loss_fn_name – The name of the loss function that the model will use

eval_model(target_attrib: str, plot_eval=False, **kwargs)¶

Evaluates the performance of the network

Parameters:

• target_attrib – The attribute of the dataset to serve as the classifier

• plot_eval – Flag to govern weather pyplots will be generated during evaluation

Returns:

The average accuracy of the model and the average loss of the value

load(save_location)¶

Loads the model from disk, reapplying all of its loaded attributes

Parameters:

save_location – The location to load the model from

preprocess_data(target_attrib: str, training_lookback=2, sub_split_value=None, **_)¶

Processes the dataframe from the data handler into labeled training and testing sets

Parameters:

• target_attrib – The attribute of the dataset to serve as the classifier

• training_lookback – The size of the sliding time window to give to recurrent models

• sub_split_value – The value used to split the data along the saved sub_split attribute

Returns:

The labeled training and testing sets

save(save_location)¶

Saves the model to disk and returns a dict of its attributes

Parameters:

save_location – Saves the information of this given model to the given location

train_model(num_epochs: int, target_attrib: str, learning_rate=0.01, optimizer_name='adam', **kwargs)¶

Trains the current neural net, giving regular eval updates over

Parameters:

• num_epochs – The number of epochs to train the model for

• target_attrib – The attribute of the dataset to serve as the classifier

• learning_rate – The learning rate ofr training

• optimizer_name – The name of the optimizer to use while training

class oracle.models.GRU(model_name: str, data_handler: DataHandler, hidden_dim: int, num_hidden_layers: int, loss_fn_name: str = 'mae', drop_prob=0.0, **_)¶

GRU implementation

__init__(model_name: str, data_handler: DataHandler, hidden_dim: int, num_hidden_layers: int, loss_fn_name: str = 'mae', drop_prob=0.0, **_)¶

GRU implementation

Parameters:

• model_name – The name given to this instance of a model

• data_handler – The handler for the dataset that the model will use

• hidden_dim – The dimension of the hidden layers

• num_hidden_layers – The number of hidden layers to put into the model

• loss_fn_name – The name of the loss function that the model will use

• drop_prob – Probability of dropout

forward(x)¶

Defines the computation performed at every call.

Should be overridden by all subclasses.

Note

Although the recipe for forward pass needs to be defined within this function, one should call the Module instance afterwards instead of this since the former takes care of running the registered hooks while the latter silently ignores them.

class oracle.models.LSTM(model_name: str, data_handler: DataHandler, hidden_dim: int, num_hidden_layers: int, loss_fn_name: str = 'mae', drop_prob=0.0, **_)¶

LSTM implementation

__init__(model_name: str, data_handler: DataHandler, hidden_dim: int, num_hidden_layers: int, loss_fn_name: str = 'mae', drop_prob=0.0, **_)¶

LSTM implementation

Parameters:

• model_name – The name given to this instance of a model

• data_handler – The handler for the dataset that the model will use

• hidden_dim – The dimension of the hidden layers

• num_hidden_layers – The number of hidden layers to put into the model

• loss_fn_name – The name of the loss function that the model will use

• drop_prob – Probability of dropout

forward(x)¶

Defines the computation performed at every call.

Should be overridden by all subclasses.

Note

Although the recipe for forward pass needs to be defined within this function, one should call the Module instance afterwards instead of this since the former takes care of running the registered hooks while the latter silently ignores them.

class oracle.models.MLP(model_name: str, data_handler: DataHandler, hidden_dim: int, num_hidden_layers: int, loss_fn_name: str = 'mae', **_)¶

Multi-layered perceptron implementation

__init__(model_name: str, data_handler: DataHandler, hidden_dim: int, num_hidden_layers: int, loss_fn_name: str = 'mae', **_)¶

Multi-layered perceptron implementation

Parameters:

• model_name – The name given to this instance of a model

• data_handler – The handler for the dataset that the model will use

• hidden_dim – The dimension of the hidden layers

• num_hidden_layers – The number of hidden layers to put into the model

• loss_fn_name – The name of the loss function that the model will use

forward(x)¶

Defines the computation performed at every call.

Should be overridden by all subclasses.

Note

Although the recipe for forward pass needs to be defined within this function, one should call the Module instance afterwards instead of this since the former takes care of running the registered hooks while the latter silently ignores them.

class oracle.models.PredictModel(model_name: str, data_handler: DataHandler, loss_fn_name: str = 'mae', **kwargs)¶

Interface for unifying behavior of different predictive models

__init__(model_name: str, data_handler: DataHandler, loss_fn_name: str = 'mae', **kwargs)¶

Interface for unifying behavior of different predictive models

Parameters:

• model_name – The name given to this instance of a model

• data_handler – The handler for the dataset that the model will use

• loss_fn_name – The name of the loss function that the model will use

classmethod create(raw_model: str, trained_model: str, data_handler: DataHandler, loss_fn_name='mae', **kwargs) → PredictModel¶

Creates a model based off of a model name, returning an instance based off other provided parameters

Parameters:

• raw_model – The name of the base model of this instance

• trained_model – The name given to this instance of a model

• data_handler – The handler for the dataset that the model will use

• loss_fn_name – The name of the loss function that the model will use

Returns:

An instance of the specified model

abstract eval_model(**kwargs)¶

Evaluates the model

static get_loss_fn(name: str)¶

Gets a loss function by name

Parameters:

name – The name of the loss function

Returns:

The torch loss function

static get_optimizer(name: str)¶

Gets an optimizer by name

Parameters:

name – The name of the optimizer

Returns:

The torch optimizer

init(model_name: str, data_handler: DataHandler, loss_fn_name: str = 'mae', **kwargs)¶

Initializes the values common to all types of predict model

Parameters:

• model_name – The name given to this instance of a model

• data_handler – The handler for the dataset that the model will use

• loss_fn_name – The name of the loss function that the model will use

abstract load(save_location)¶

Loads the model from disk, reapplying all of its loaded attributes

Parameters:

save_location – The location to load the model from

abstract save(save_location) → dict¶

Saves the model to disk and returns a dict of its attributes

Parameters:

save_location – Saves the information of this given model to the given location

classmethod subclass_walk(target_cls)¶

Recursively gathers all subclasses of a particular class

Parameters:

target_cls – The class to search the subclasses of

Returns:

A list of all the subclasses of this class

abstract train_model(**kwargs) → tuple[float, float]¶

Trains the model using the given parameters

class oracle.models.RNN(model_name: str, data_handler: DataHandler, hidden_dim: int, num_hidden_layers: int, loss_fn_name: str = 'mae', **_)¶

RNN implementation

__init__(model_name: str, data_handler: DataHandler, hidden_dim: int, num_hidden_layers: int, loss_fn_name: str = 'mae', **_)¶

RNN implementation

Parameters:

• model_name – The name given to this instance of a model

• data_handler – The handler for the dataset that the model will use

• hidden_dim – The dimension of the hidden layers

• num_hidden_layers – The number of hidden layers to put into the model

• loss_fn_name – The name of the loss function that the model will use

forward(x)¶

Defines the computation performed at every call.

Should be overridden by all subclasses.

Note

Although the recipe for forward pass needs to be defined within this function, one should call the Module instance afterwards instead of this since the former takes care of running the registered hooks while the latter silently ignores them.

oracle.models.get_trained_model(model_name: str)¶

Gets a trained model by name and returns the model along with transaction and user metadata

Parameters:

model_name – The name of the trained model to load

Returns:

The loaded model and associated metadata

oracle.models.save_trained_model(model: PredictModel, txn_id: str, user_id: str)¶

Saves a model to disk and to the database along with user and metadata information

Parameters:

• model – The model to save

• txn_id – The id of the transaction that initiated the saving of this model

• user_id – The address of the user that is saving this model