nimble-api 0.0.4
nimble
License: MIT
Requires Python: >=3.8

# Nimble API

APIs for composable AI Protocol

# Install

There are three ways to install nimble

1. Through the installer:

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

2. With pip:

```bash
$ pip3 install nimble
```

3. From source:

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

4. Using Conda (recommended for **Apple M1**):

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

To test your installation, type:

```bash
$ nbcli --help
```

or using python

```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](https://github.com/nimble-technology/cubit).

For example with python 3.10:

```bash
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

```python
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`:

```bash
$ 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`

```bash
$ 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.

```bash
$ 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:

```bash
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

```bash
nbcli root proposals
```

#### Viewing Senate Members

```bash
nbcli root list_delegates
```

#### Viewing Proposal Votes

```bash
nbcli root senate_vote --proposal=[PROPOSAL_HASH]
```

#### Registering for Senate

```bash
nbcli root register
```

#### Leaving Senate

```bash
nbcli root undelegate
```

#### Voting in Senate

```bash
nbcli root senate_vote --proposal=[PROPOSAL_HASH]
```

#### Miscellaneous Commands

```bash
nbcli legacy update
nbcli legacy faucet
```

#### Managing Subnets

```bash
nbcli subnets list
nbcli subnets create
```

#### Managing Wallets

```bash
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:

```bash
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:

```bash
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.

```python
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.

```python
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.

```python
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

```python
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.

```python
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:

```python
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.

```bash
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
```bash
python setup.py sdist
```

Then use the following command to publish to pypi
```bash
twine upload dist/nimble-api-{version}.tar.gz
```
Make sure you store your credentials at `~/.pypirc`

## Contributions

Please review the [contributing guide](./contrib/CONTRIBUTING.md) for more information before making a pull request.