nimble-api 0.0.4

nimble

Nimble API

APIs for composable AI Protocol

Install

There are three ways to install nimble

1. Through the installer:

$ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/nimble-technology/nimble/master/scripts/install.sh)"

2. With pip:

$ pip3 install nimble

3. From source:

$ git clone https://github.com/nimble-technology/nimble.git
$ cd nimble
$ python3 -m pip install -e ./

4. Using Conda (recommended for Apple M1):

$ conda env create -f ~/.nimble/nimble/scripts/environments/apple_m1_environment.yml
$ conda activate nimble

To test your installation, type:

$ nbcli --help

or using python

import nimble

CUDA

If you anticipate using PoW registration for subnets or the faucet (only available on staging), please install cubit as well for your version of python. You can find the Nimble Labs LTD cubit implementation and instructions here.

For example with python 3.10:

pip install https://github.com/nimble-technology/cubit/releases/download/v1.1.2/cubit-1.1.2-cp310-cp310-linux_x86_64.whl

Wallets

Wallets are the core ownership and identity technology around which all functions on nimble are carried out. nimble wallets consists of a coldkey and hotkey where the coldkey may contain many hotkeys, while each hotkey can only belong to a single coldkey. Coldkeys store funds securely, and operate functions such as transfers and staking, while hotkeys are used for all online operations such as signing queries, running miners and validating.

Wallets can be created in two ways.

1. Using the python-api

import nimble
wallet = nimble.wallet()
wallet.create_new_coldkey()
wallet.create_new_hotkey()
print (wallet)
"Wallet (default, default, ~/.nimble/wallets/)"

2. Or using nbcli

   Use the subcommand wallet or it's alias w:

$ nbcli wallet new_coldkey
    Enter wallet name (default):

    IMPORTANT: Store this mnemonic in a secure (preferably offline place), as anyone who has possession of this mnemonic can use it to regenerate the key and access your tokens.
    The mnemonic to the new coldkey is:
    **** *** **** **** ***** **** *** **** **** **** ***** *****
    You can use the mnemonic to recreate the key in case it gets lost. The command to use to regenerate the key using this mnemonic is:
    nbcli w regen_coldkey --mnemonic post maid erode shy captain verify scan shoulder brisk mountain pelican elbow

$ nbcli wallet new_hotkey
    Enter wallet name (default): d1
    Enter hotkey name (default):

    IMPORTANT: Store this mnemonic in a secure (preferably offline place), as anyone who has possession of this mnemonic can use it to regenerate the key and access your tokens.
    The mnemonic to the new hotkey is:
    **** *** **** **** ***** **** *** **** **** **** ***** *****
    You can use the mnemonic to recreate the key in case it gets lost. The command to use to regenerate the key using this mnemonic is:
    nbcli w regen_hotkey --mnemonic total steak hour bird hedgehog trim timber can friend dry worry text

In both cases you should be able to view your keys by navigating to ~/.nimble/wallets or viewed by running nbcli wallet list

$ tree ~/.nimble/
    .nimble/                 # nimble, root directory.
        wallets/                # The folder containing all nimble wallets.
            default/            # The name of your wallet, "default"
                coldkey         # You encrypted coldkey.
                coldkeypub.txt  # Your coldkey public address
                hotkeys/        # The folder containing all of your hotkeys.
                    default     # You unencrypted hotkey information.

Your default wallet Wallet (default, default, ~/.nimble/wallets/) is always used unless you specify otherwise. Be sure to store your mnemonics safely. If you lose your password to your wallet, or the access to the machine where the wallet is stored, you can always regenerate the coldkey using the mnemonic you saved from above.

$ nbcli wallet regen_coldkey --mnemonic **** *** **** **** ***** **** *** **** **** **** ***** *****

Using the cli

The nimble command line interface (nbcli) is the primary command line tool for interacting with the nimble network. It can be used to deploy nodes, manage wallets, stake/unstake, nominate, transfer tokens, and more.

Basic Usage

To get the list of all the available commands and their descriptions, you can use:

nbcli --help

usage: nbcli <command> <command args>

nimble cli v{nimble.__version__}

commands:
  subnets (s, subnet) - Commands for managing and viewing subnetworks.
  root (r, roots) - Commands for managing and viewing the root network.
  wallet (w, wallets) - Commands for managing and viewing wallets.
  stake (st, stakes) - Commands for staking and removing stake from hotkey accounts.
  sudo (su, sudos) - Commands for subnet management.
  legacy (l) - Miscellaneous commands.

Example Commands

Viewing Senate Proposals

nbcli root proposals

Viewing Senate Members

nbcli root list_delegates

Viewing Proposal Votes

nbcli root senate_vote --proposal=[PROPOSAL_HASH]

Registering for Senate

nbcli root register

Leaving Senate

nbcli root undelegate

Voting in Senate

nbcli root senate_vote --proposal=[PROPOSAL_HASH]

Miscellaneous Commands

nbcli legacy update
nbcli legacy faucet

Managing Subnets

nbcli subnets list
nbcli subnets create

Managing Wallets

nbcli wallet list
nbcli wallet transfer

Note

Please replace the subcommands and arguments as necessary to suit your needs, and always refer to nbcli --help or nbcli <command> --help for the most up-to-date and accurate information.

For example:

nbcli subnets --help

usage: nbcli <command> <command args> subnets [-h] {list,metagraph,lock_cost,create,register,pow_register,hyperparameters} ...

positional arguments:
  {list,metagraph,lock_cost,create,register,pow_register,hyperparameters}
                        Commands for managing and viewing subnetworks.
    list                List all subnets on the network.
    metagraph           View a subnet metagraph information.
    lock_cost           Return the lock cost to register a subnet.
    create              Create a new nimble subnetwork on this chain.
    register            Register a wallet to a network.
    pow_register        Register a wallet to a network using PoW.
    hyperparameters     View subnet hyperparameters.

options:
  -h, --help            show this help message and exit

Post-Installation Steps

To enable autocompletion for nimble CLI, run the following commands:

nbcli --print-completion bash >> ~/.bashrc  # For Bash
nbcli --print-completion zsh >> ~/.zshrc    # For Zsh
source ~/.bashrc  # Reload Bash configuration to take effect

The nimble Package

The nimble package contains data structures for interacting with the nimble ecosystem, writing miners, validators and querying the network. Additionally, it provides many utilities for efficient serialization of Tensors over the wire, performing data analysis of the network, and other useful utilities.

Wallet: Interface over locally stored nimble hot + coldkey styled wallets.

import nimble
# nimble's wallet maintenance class.
wallet = nimble.wallet()
# Access the hotkey
wallet.hotkey
# Access the coldkey
wallet.coldkey ( requires decryption )
# Sign data with the keypair.
wallet.coldkey.sign( data )

NbNetwork: Interfaces with nimble's blockchain and can perform operations like extracting state information or sending transactions.

import nimble
# nimble's chain interface.
nbnetwork = nimble.nbnetwork()
# Get the chain block
nbnetwork.get_current_block()
# Transfer Nim to a destination address.
nbnetwork.transfer( wallet = wallet, dest = "xxxxxxx..xxxxx", amount = 10.0)
# Register a wallet onto a subnetwork
nbnetwork.register( wallet = wallet, netuid = 1 )

Metagraph: Encapsulates the chain state of a particular subnetwork at a specific block.

import nimble
# nimble's chain state object.
metagraph = nimble.metagraph( netuid = 1 )
# Resync the graph with the most recent chain state
metagraph.sync()
# Get the list of stake values
print ( metagraph.S )
# Get endpoint information for the entire subnetwork
print ( metagraph.axons )
# Get the hotkey information for the miner in the 10th slot
print ( metagraph.hotkeys[ 10 ] )
# Sync the metagraph at another block
metagraph.sync( block = 100000 )
# Save the metagraph
metagraph.save()
# Load the same
metagraph.load()

Synapse: Responsible for defining the protocol definition between axon servers and dendrite clients

class Topk( nimble.Synapse ):
    topk: int = 2  # Number of "top" elements to select
    input: nimble.Tensor = pydantic.Field(..., allow_mutation=False)  # Ensure that input cannot be set on the server side.
    v: nimble.Tensor = None
    i: nimble.Tensor = None

def topk( synapse: Topk ) -> Topk:
    v, i = torch.topk( synapse.input.deserialize(), k = synapse.topk )
    synapse.v = nimble.Tensor.serialize( v )
    synapse.i = nimble.Tensor.serialize( i )
    return synapse

# Attach the forward function to the axon and start.
axon = nimble.axon().attach( topk ).start()

Axon: Serves Synapse protocols with custom blacklist, priority and verify functions.

import nimble

class MySynapse( nimble.Synapse ):
    input: int = 1
    output: int = None

# Define a custom request forwarding function
def forward( synapse: MySynapse ) -> MySynapse:
    # Apply custom logic to synapse and return it
    synapse.output = 2
    return synapse

# Define a custom request verification function
def verify_my_synapse( synapse: MySynapse ):
    # Apply custom verification logic to synapse
    # Optionally raise Exception

# Define a custom request blacklist function
def blacklist_my_synapse( synapse: MySynapse ) -> bool:
    # Apply custom blacklist
    # return False ( if non blacklisted ) or True ( if blacklisted )

# Define a custom request priority function
def prioritize_my_synape( synapse: MySynapse ) -> float:
    # Apply custom priority
    return 1.0

# Initialize Axon object with a custom configuration
my_axon = nimble.axon(config=my_config, wallet=my_wallet, port=9090, ip="192.0.2.0", external_ip="203.0.113.0", external_port=7070)

# Attach the endpoint with the specified verification and forwarding functions
my_axon.attach(
    forward_fn = forward_my_synapse,
    verify_fn=verify_my_synapse,
    blacklist_fn = blacklist_my_synapse,
    priority_fn = prioritize_my_synape
).start()

Dendrite: Inheriting from PyTorch's Module class, represents the abstracted implementation of a network client module designed to send requests to those endpoints to receive inputs.

Example:

dendrite_obj = dendrite( wallet = nimble.wallet() )
# pings the axon endpoint
await d( <axon> )
# ping multiple axon endpoints
await d( [<axons>] )
# Send custom synapse request to axon.
await d( nimble.axon(), nimble.Synapse() )
# Query all metagraph objects.
await d( meta.axons, nimble.Synapse() )

Setting weights on root network

Use the root subcommand to access setting weights on the network across subnets.

nbcli root weights --wallet.name <coldname> --wallet.hotkey <hotname>
Enter netuids (e.g. 0, 1, 2 ...):
# Here enter your selected netuids to set weights on
1, 2

>Enter weights (e.g. 0.09, 0.09, 0.09 ...):
# These do not need to sum to 1, we do normalization on the backend.
# Values must be > 0
0.5, 10

Normalized weights:
        tensor([ 0.5000, 10.0000]) -> tensor([0.0476, 0.9524])

Do you want to set the following root weights?:
  weights: tensor([0.0476, 0.9524])
  uids: tensor([1, 2])? [y/n]:
y

⠏ 📡 Setting root weights on test ...

Release

Run the following command to create dist folder

python setup.py sdist

Then use the following command to publish to pypi

twine upload dist/nimble-api-{version}.tar.gz

Make sure you store your credentials at ~/.pypirc

Contributions

Please review the contributing guide for more information before making a pull request.