diff --git a/README.md b/README.md index 3f3587f..206cf4a 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ The Actions SDK is a Python library designed to facilitate the development of ZK ## Where to start? -Check out our extensive [documentation](https://actions.gizatech.xyz/welcome/giza-actions-sdk) to understand concepts and follow how-to-guides. +Check out our extensive [documentation](https://actions.gizatech.xyz/welcome/giza-actions-sdk) to understand the concepts and follow how-to-guides. ## Installation @@ -47,7 +47,7 @@ Optional: you can create an API Key for your user in order to not regenerate you $ giza users create-api-key ``` -To create Actions Runs you will need a Giza Workspace, create it executing the following command in your terminal: +To create Actions Runs you will need a Giza Workspace, create it by executing the following command in your terminal: ```bash $ giza workspaces create @@ -113,9 +113,9 @@ Running this script will do two things: ### Creating Agents -Agents are the entities that interact with the Giza Platform to handle predictions verification and interacting with Smart Contracts. They are responsible for wating until the proof of the prediction is available and verified, and then handling the interaction with the contract. +Agents are the entities that interact with the Giza Platform to handle verification of predictions and interactions with Smart Contracts. They are responsible for wating until the proof of the prediction is available and verified, and then handling the interaction with the contract. -To create the agent, you will first need to create locally an [ape](https://apeworx.io/framework/) account: +To create the agent, you will first need to locally create an [ape](https://apeworx.io/framework/) account: ```bash $ ape accounts generate @@ -159,7 +159,7 @@ Enter the account name: my_account } ``` -Now to interact with the agent and the contract wou will need to export the passphrase of the account to the environment. The variable name should be `_PASSPHRASE` all in caps. Make sure to keep this secret: +Now, to interact with the agent and the contract, wou will need to export the passphrase of the account to the environment. The variable name should be `_PASSPHRASE`, all in caps. Make sure to keep this secret: ```bash $ export _PASSPHRASE= @@ -176,7 +176,7 @@ result = agent.predict(data={"input": "data"}) # Handle the contracts with agent.execute() as contracts: - # Wait for the verification and the execute the contract + # Wait for the verification and then execute the contract contract_result = contracts.my_contract.function(result.value) # Do anything with the result diff --git a/examples/agents/action_agent.py b/examples/agents/action_agent.py index 4f5342a..764e286 100644 --- a/examples/agents/action_agent.py +++ b/examples/agents/action_agent.py @@ -7,18 +7,18 @@ from prefect import get_run_logger -# Process image +# Process the image @task def process_image(img): img = np.resize(img, (28,28)) img = img.reshape(1,1,28,28) img = img/255.0 print(img.shape) - # For now, we will just use a small tensor as input to a single layer softmax. We will change this when the PoC works + # For now, we will just use a small tensor as input to a single-layer softmax. We will change this when the PoC works tensor = np.random.rand(1,3) return tensor -# Get image +# Get the image @task def get_image(path): with Image.open(path) as img: @@ -26,7 +26,7 @@ def get_image(path): img = np.array(img) return img -# Create Action +# Create the Action @action(log_prints=True) def transmission(): logger = get_run_logger() diff --git a/examples/agents/mnist_agent_tutorial.ipynb b/examples/agents/mnist_agent_tutorial.ipynb index edd7d19..ee29761 100644 --- a/examples/agents/mnist_agent_tutorial.ipynb +++ b/examples/agents/mnist_agent_tutorial.ipynb @@ -10,9 +10,9 @@ "\n", "Agents serve as intermediaries between users and Smart Contracts, facilitating seamless interaction with verifiable ML models and executing associated contracts. They handle the verification of proofs, ensuring the integrity and authenticity of data used in contract execution.\n", "\n", - "In this notebook, we will create an AI Agent to mint a MNIST NFT. Using an existing MNIST endpoint, we will perfomr a prediction on the MNIST dataset and mint an NFT based on the prediction.\n", + "In this notebook, we will create an AI Agent to mint an MNIST NFT. Using an existing MNIST endpoint, we will perform a prediction on the MNIST dataset and mint an NFT based on the prediction.\n", "\n", - "This tutorial can be thought as the continuation of the previous tutorial [Build a Verifiable Neural Network with Giza Actions](https://actions.gizatech.xyz/tutorials/build-a-verifiable-neural-network-with-giza-actions) where we created a verifiable MNIST model ([notebook](https://github.com/gizatechxyz/actions-sdk/blob/main/examples/verifiable_mnist/verifiable_mnist.ipynb)).\n", + "This tutorial can be thought of as the continuation of the previous tutorial [Build a Verifiable Neural Network with Giza Actions](https://actions.gizatech.xyz/tutorials/build-a-verifiable-neural-network-with-giza-actions) where we created a verifiable MNIST model ([notebook](https://github.com/gizatechxyz/actions-sdk/blob/main/examples/verifiable_mnist/verifiable_mnist.ipynb)).\n", "\n", "## Before you begin\n", "\n", @@ -20,9 +20,9 @@ "2. Giza CLI must be installed on your machine. You can install it by running `pip install giza-cli`\n", "3. Actions-SDK should be installed with the extra `agents`. You can install it by running `pip install giza-actions[agents]`\n", "4. You must have an active Giza account. If you don't have one, you can create one [here](https://cli.gizatech.xyz/examples/basic).\n", - "5. You must have a MNIST model deployed on Giza. You can follow the tutorial [Build a Verifiable Neural Network with Giza Actions](https://actions.gizatech.xyz/tutorials/build-a-verifiable-neural-network-with-giza-actions) to deploy a MNIST model on Giza.\n", - "6. During the tutorial, you will need to interact with the Giza CLI, Ape's framework, and provide multiple inputs, like `model-id`, `version-id`, `account name`, etc.\n", - "7. You have to be logged in to the Giza CLI or have an API KEY.\n", + "5. You must have an MNIST model deployed on Giza. You can follow the tutorial [Build a Verifiable Neural Network with Giza Actions](https://actions.gizatech.xyz/tutorials/build-a-verifiable-neural-network-with-giza-actions) to deploy an MNIST model on Giza.\n", + "6. During the tutorial, you will need to interact with the Giza CLI, and Ape's framework, and provide multiple inputs, like `model-id`, `version-id`, `account name`, etc.\n", + "7. You must be logged in to the Giza CLI or have an API KEY.\n", "\n", "## Installing the required libraries\n", "\n", @@ -48,9 +48,9 @@ "```\n", "\n", "This will create a new account under `$HOME/.ape/accounts` using the keyfile structure from the [eth-keyfile library](https://github.com/ethereum/eth-keyfile)\n", - ", for more information on the account management, you can refer to the [Ape's framework documentation](https://docs.apeworx.io/ape/stable/userguides/accounts.html#keyfile-accounts).\n", + ". For more information on account management, you can refer to the [Ape's framework documentation](https://docs.apeworx.io/ape/stable/userguides/accounts.html#keyfile-accounts).\n", "\n", - "In this account generation we will be prompted to enter a passphrase to encrypt the account, this passphrase will be used to unlock the account when needed, so **make sure to keep it safe**.\n", + "During account generation we will be prompted to enter a passphrase to encrypt the account, which will be used to unlock the said account when needed, so **make sure to keep it safe**.\n", "\n", "We encourage the creation of a new account for each agent, as it will allow you to manage the agent's permissions and access control more effectively, but importing accounts is also possible.\n", "\n", @@ -58,15 +58,15 @@ "\n", "Before we can create an AI Agent, we need to fund the account with some ETH. You can do this by sending some ETH to the account address generated in the previous step.\n", "\n", - "In this case we will use Sepolia testnet, you can get some testnet ETH from a faucet like [Alchemy Sepolia Faucet](https://www.alchemy.com/faucets/ethereum-sepolia) or [LearnWeb3 Faucet](https://learnweb3.io/faucets/sepolia/). This faucets will ask for security meassures to make sure that you are not a bot like having a specific amount of ETH in mainnet or a Github account. There are many faucets available, you can choose the one that suits you the best.\n", + "In this case, we will use Sepolia testnet, you can get some testnet ETH from a faucet like [Alchemy Sepolia Faucet](https://www.alchemy.com/faucets/ethereum-sepolia) or [LearnWeb3 Faucet](https://learnweb3.io/faucets/sepolia/). These faucets will ask for security measures to make sure that you are not a bot (by checking whether you have a specific amount of ETH in the mainnet or a GitHub account, for example). There are many faucets available and you are free to choose the one that suits you the best.\n", "\n", - "Once, we can recieve the testnet ETH and we have a funded account, we can proceed to create an AI Agent.\n", + "Once the testnet ETH have been received and the account has been funded, we can proceed with the creation of an AI Agent.\n", "\n", "![account](img/account.png)\n", "\n", "## Creating an AI Agent\n", "\n", - "Now that we have a funded account, we can create an AI Agent. We can do this by running the following command:\n", + "Now that we have a funded account, we can create an AI Agent. This can be done by running the following command:\n", "\n", "```bash\n", "giza agents create --model-id --version-id --name --description \n", @@ -76,7 +76,7 @@ "giza agents create --endpoint-id --name --description \n", "```\n", "\n", - "This command will prompt you to choose the account you want to use with the agent, once you select the account, the agent will be created and you will receive the agent id. The output will look like this:\n", + "This command will prompt you to choose the account you want to use with the agent. Once you select the account, the agent will be created and you will receive the agent id. The output will look like this:\n", "\n", "```console\n", "[giza][2024-04-10 11:50:24.005] Creating agent ✅\n", @@ -108,7 +108,7 @@ "\n", "## How to use the AI Agent\n", "\n", - "Now that the agent is created we can start using it through `giza-actions` library. As we will be using the agent to mint a MNIST NFT, we will need to provide the MNIST image to the agent and preprocess it before sending it to the model.\n" + "Now that the agent is created we can start using it through the `giza-actions` library. As we will be using the agent to mint an MNIST NFT, we will need to provide the MNIST image to the agent and preprocess it before sending it to the model." ] }, { @@ -146,7 +146,7 @@ "* Access the prediction result\n", "* Mint an NFT based on the prediction result\n", "\n", - "To load and preprocess the image we can use the function that we already created in the previous tutorial [Build a Verifiable Neural Network with Giza Actions](https://actions.gizatech.xyz/tutorials/build-a-verifiable-neural-network-with-giza-actions)." + "To load and preprocess the image, we can use the function that we already created in the previous tutorial [Build a Verifiable Neural Network with Giza Actions](https://actions.gizatech.xyz/tutorials/build-a-verifiable-neural-network-with-giza-actions)." ] }, { @@ -181,7 +181,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Now, we will create a function to create an instance of the agent. The agent is an exttension of the `GizaModel` class, so we can execute the `predict` as if we were using a model, but the agents needs more information:\n", + "Now, we will create a function to create an instance of the agent. The agent is an extension of the `GizaModel` class, so we can execute `predict` as if we were using a model, but the agents needs more information:\n", "\n", "* chain: The chain where the contract and account are deployed\n", "* contracts: This is a dictionary in the form of `{\"contract_alias\": \"contract_address\"}` that contains the contract alias and address.\n", @@ -248,9 +248,9 @@ "source": [ "Once we have the result, we need to access it. The `AgentResult` object contains the `value` attribute that contains the prediction result. In this case, the prediction result is a number from 0 to 9 that represents the digit that the model predicted.\n", "\n", - "When we access the value, the execution will be blocked until the proof of the prediction has been created and once created it is verified. If the proof is not valid, the execution will raise an exception.\n", + "When we access the value, the execution will be blocked until the proof of the prediction has been created and verified. If the proof is not valid, the execution will raise an exception.\n", "\n", - "This task is more for didactic purposes, to showcase in the workspaces the time that it can take to verify the proof. In a real scenario, you can use the `AgentResult` value directl in any other task." + "This task is more for didactic purposes, to showcase in the workspaces the time that it takes to verify the proof. In a real scenario, you can use the `AgentResult` value directly in any other task." ] }, { @@ -278,14 +278,14 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Finally, we will create a task to mint an NFT based on the prediction result. This task will use the prediction result to mint an NFT with the image of the MNIST digit predicted.\n", + "Finally, we will create a task to mint an NFT based on the predicted result. This task will use the result to mint an NFT with the image of the MNIST digit predicted.\n", "\n", - "To execute the contract we have the `GizaAgent.execute` context that will yield all the initialized contracts and the agent instance. This context will be used to execute the contract as it handles all the connections to the nodes, networks and contracts.\n", + "To execute the contract, we have the `GizaAgent.execute` context that will yield all the initialized contracts and the agent instance. This context will be used to execute the contract as it handles all the connections to the nodes, networks and contracts.\n", "\n", - "In our instanciation of the agent we added an `mnist` alias to access the contract to ease its use. For example:\n", + "In our instantiation of the agent, we added an `mnist` alias to access the contract to ease its use. For example:\n", "\n", "```python\n", - "# A context is created that yields alll the contracts used in the agent\n", + "# A context is created that yields all the contracts used in the agent\n", "with agent.execute() as contracts:\n", " # This is how we access the contract\n", " contracs.mnist\n", @@ -332,15 +332,15 @@ "source": [ "@action(name=\"Mint an NFT with a prediction.\", log_prints=True)\n", "def mint_nft_with_prediction():\n", - " # Preprocess image\n", + " # Preprocess the image\n", " image = preprocess_image(\"seven.png\")\n", - " # Create Giza agent\n", + " # Create the Giza agent\n", " agent = create_agent(MODEL_ID, VERSION_ID, CHAIN, MNIST_CONTRACT)\n", - " # Predict digit\n", + " # Predict the digit\n", " prediction = predict(agent, image)\n", - " # Get digit\n", + " # Get the digit\n", " digit = get_digit(prediction)\n", - " # Execute contract\n", + " # Execute the contract\n", " result = execute_contract(agent, digit)\n", " pprint.pprint(result)\n" ] @@ -349,7 +349,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Remember that we should have kept the passphrase in a safe place? Now it is time to use it. For learning purposes we will use the passphrase in the code, but in a real scenario, you should keep it safe and not hardcode it in the code." + "Remember the passphrase that had to be safely kept? It is now time to use it. For the purpose of learning, we will use the passphrase in the code as an example, but in a real scenario, you should keep it safe and not hardcode it." ] }, { @@ -367,7 +367,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Now lets execute the action." + "Now let's execute the action." ] }, { @@ -385,9 +385,9 @@ "source": [ "## What we have learned\n", "\n", - "In this tutorial, we learned how to create an AI Agent to mint a MNIST NFT. We created an AI Agent using Ape's framework and interacted with the agent to mint an NFT based on the prediction result of a MNIST image.\n", + "In this tutorial, we learned how to create an AI Agent to mint an MNIST NFT. We created an AI Agent using Ape's framework and interacted with it to mint an NFT based on the predicted result of an MNIST image.\n", "\n", - "We learned how to load and preprocess the MNIST image, create an instance of the agent, predict the MNIST image using the agent, access the prediction result, and mint an NFT based on the prediction result." + "We learned how to load and preprocess the MNIST image, create an instance of the agent, predict the MNIST image using the agent, access the predicted result, and mint an NFT based on the result." ] } ], diff --git a/examples/agents/read_contracts.py b/examples/agents/read_contracts.py index f315e4f..4ca61fd 100644 --- a/examples/agents/read_contracts.py +++ b/examples/agents/read_contracts.py @@ -1,20 +1,20 @@ """ -For this to work we need to have the PASSPHRASE as an environment variable +For this to work, we need to have the PASSPHRASE as an environment variable This variable should have the form of "{ACCOUNT_ALIAS}_PASSPHRASE={PASSPHRASE}" For example, if the ACCOUNT_ALIAS is "sepolia", then the environment variable should be "SEPOLIA_PASSPHRASE" This is because the GizaAgent will look for the environment variable "{ACCOUNT_ALIAS}_PASSPHRASE" to allow auto signing -In this example we instantiate the agent with the model id, version id, and the addresses of the contracts we want to interact with. +In this example, we instantiate the agent with the model id, version id, and the addresses of the contracts we want to interact with. The contracts are stored in a dictionary where the key is the contract name and the value is the contract address. -We also specify the chain we want to interact with and the account alias we want to use to sign transactions, in this case "sepolia". +We also specify the chain we want to interact with and the account alias we want to use to sign transactions, which, in this case is "sepolia". -To interact with the contracts we use the execute method of the agent in a `with` block, then the contracts will be available using the dot notation. -For example, our agent has two contracts, "mnist" and "token", so we can access them using `contracts.mnist` and `contracts.token` respectively. +To interact with the contracts, we use the execute method of the agent in a `with` block, so that the contracts will be available using the dot notation. +For example, if our agent has two contracts, "mnist" and "token", then we can access them using `contracts.mnist` and `contracts.token`, respectively. -In this example we call the `name` method of the contracts, which is a method that returns the name of the contract, and we print the result but we could execute any function of a contract in the same way. +In this example, we call the `name` method of the contracts, which is a method that returns the name of the contract, and then we print the result. But we could execute any function of a contract in the same way. """ from giza_actions.agent import GizaAgent diff --git a/examples/agents/using_arbitrum.ipynb b/examples/agents/using_arbitrum.ipynb index acc0b2d..269f84d 100644 --- a/examples/agents/using_arbitrum.ipynb +++ b/examples/agents/using_arbitrum.ipynb @@ -6,11 +6,11 @@ "source": [ "# Using Arbitrum with Agents\n", "\n", - "In the previous tutorial we have seen how to use the `GizaAgent` class to create a simple agent that can interact with the Ethereum blockchain. In this tutorial we will see how to use other chains with the `GizaAgent` class.\n", + "In the previous tutorial, we have seen how to use the `GizaAgent` class to create a simple agent that can interact with the Ethereum blockchain. In this tutorial, we will learn how to use other chains with the `GizaAgent` class.\n", "\n", - "As we rely on `ape` to interact with the blockchain, we can use any chain that ape supports. The list of supported chains via plugins can be found [here](https://docs.apeworx.io/).\n", + "As we rely on `ape` to interact with the blockchain, we can use any chain that it supports. The list of supported chains via plugins can be found [here](https://docs.apeworx.io/).\n", "\n", - "In this tutorial we will use `Arbitrum` as an example. The `Arbitrum` is a layer 2 solution for Ethereum that provides low cost and fast transactions. The `Arbitrum` is supported by `ape` and we can use it with the `GizaAgent` class.\n", + "In this tutorial, we will use `Arbitrum` as an example. `Arbitrum` is a layer 2 solution for Ethereum that provides low cost and fast transactions. It is supported by `ape` and we can use it with the `GizaAgent` class.\n", "\n", "## Before you begin\n", "\n", @@ -18,9 +18,9 @@ "2. Giza CLI must be installed on your machine. You can install it by running `pip install giza-cli`\n", "3. Actions-SDK should be installed with the extra `agents`. You can install it by running `pip install giza-actions[agents]`\n", "4. You must have an active Giza account. If you don't have one, you can create one [here](https://cli.gizatech.xyz/examples/basic).\n", - "5. You must have a model deployed on Giza. You can follow the tutorial [Build a Verifiable Neural Network with Giza Actions](https://actions.gizatech.xyz/tutorials/build-a-verifiable-neural-network-with-giza-actions) to deploy a MNIST model on Giza.\n", + "5. You must have a model deployed on Giza. You can follow the tutorial [Build a Verifiable Neural Network with Giza Actions](https://actions.gizatech.xyz/tutorials/build-a-verifiable-neural-network-with-giza-actions) to deploy an MNIST model on Giza.\n", "6. During the tutorial, you will need to interact with the Giza CLI, Ape's framework, and provide multiple inputs, like `model-id`, `version-id`, `account name`, etc.\n", - "7. You have to be logged in to the Giza CLI or have an API KEY.\n", + "7. You must be logged in to the Giza CLI or have an API KEY.\n", "\n", "## Installing the required libraries\n", "\n", @@ -46,15 +46,15 @@ "```\n", "\n", "This will create a new account under `$HOME/.ape/accounts` using the keyfile structure from the [eth-keyfile library](https://github.com/ethereum/eth-keyfile)\n", - ", for more information on the account management, you can refer to the [Ape's framework documentation](https://docs.apeworx.io/ape/stable/userguides/accounts.html#keyfile-accounts).\n", + ". For more information on the account management, you can refer to the [Ape's framework documentation](https://docs.apeworx.io/ape/stable/userguides/accounts.html#keyfile-accounts).\n", "\n", - "In this account generation we will be prompted to enter a passphrase to encrypt the account, this passphrase will be used to unlock the account when needed, so **make sure to keep it safe**.\n", + "During account generation we will be prompted to enter a passphrase to encrypt the account, which will be used to unlock the said account when needed, so **make sure to keep it safe**.\n", "\n", "We encourage the creation of a new account for each agent, as it will allow you to manage the agent's permissions and access control more effectively, but importing accounts is also possible.\n", "\n", "## Creating an AI Agent\n", "\n", - "Now that we have a funded account, we can create an AI Agent. We can do this by running the following command:\n", + "Now that we have a funded account, we can create an AI Agent. This can be done by running the following command:\n", "\n", "```bash\n", "giza agents create --model-id --version-id --name --description \n", @@ -64,7 +64,7 @@ "giza agents create --endpoint-id --name --description \n", "```\n", "\n", - "This command will prompt you to choose the account you want to use with the agent, once you select the account, the agent will be created and you will receive the agent id. The output will look like this:\n", + "This command will prompt you to choose the account you want to use with the agent. Once you select the account, the agent will be created and you will receive the agent id. The output will look like this:\n", "\n", "```console\n", "[giza][2024-04-10 11:50:24.005] Creating agent ✅\n", @@ -112,7 +112,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "We can confirm if it has been installed by executing `ape networks list` in the terminal." + "We can confirm whether it has been installed, by running `ape networks list` in the terminal." ] }, { @@ -160,27 +160,26 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Here we can se that we have multiple networks available, including `arbitrum`. So now we can use it when instantiating the `GizaAgent` class.\n", + "Here, we can see that we have multiple networks available, including `arbitrum`. So now we can use it when instantiating the `GizaAgent` class.\n", "\n", - "For this execution, we will use Arbitrum mainnet and use a private RPC node, this is because public nodes have small quotas that can easily be reached.\n", + "For this execution, we will use the Arbitrum mainnet and a private RPC node. This is because public nodes have small quotas that can easily be reached.\n", "\n", - "The contract is a verified contract selected at random from [arbiscan](https://arbiscan.io/), the mission is to showcase that we can read properties from this contract, which means that we could also be able to execute a write function.\n", + "The contract is a verified contract selected at random from [arbiscan](https://arbiscan.io/). The aim is to show that we can read properties from this contract, which means that we could also execute a write function.\n", "\n", - "In this case as we are only executing a read function we dont need a funded wallet to do anything as we won't sign any transactions.\n", + "In this case, as we are only executing a read function, there is no need for a funded wallet because we won't be signing any transactions.\n", "\n", - "Remember that we will need to specify the `_PASSPHRASE` if you are launching your operation as a script, exporting it will be enough:\n", + "Remember that you will need to specify the `_PASSPHRASE`. If you wish to launch your operation as a script, exporting it will be enough:\n", "\n", "```bash\n", "export _PASSPHRASE=your-passphrase\n", "```\n", "\n", - "If you are using it from a notebook you will need to launch the notebook instance from an environment with the passphrase variable or set it in the code prior to importing `giza_actions`:\n", + "If you are using it from a notebook, you will need to launch the notebook instance from an environment with the passphrase variable or set it in the code before importing `giza_actions`:\n", "\n", "```python\n", "import os\n", "os.environ[\"_PASSPHRASE\"] = \"your-passphrase\"\n", "\n", - "\n", "from giza_actions.agent import GizaAgent\n", "...\n", "```\n", @@ -220,7 +219,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Now that we have the agent instance we can enter the `execute()` context and call the read function from an Arbitrum smart contract:" + "Now that we have the agent instance, we can enter the `execute()` context and call the read function from an Arbitrum smart contract:" ] }, { @@ -252,14 +251,14 @@ "\n", "In this tutorial, we learned how to create an AI Agent and interact with Arbitrum.\n", "\n", - "For this we needed to:\n", + "For this, we needed to:\n", "\n", - "* Install the arbitrum plugin\n", + "* Install the `arbitrum` plugin\n", "* Check that the new network is available\n", - "* Got a contract from arbiscan\n", - "* Use an agent to execute a function from an arbitrum smart contract\n", + "* Got a contract from `arbiscan`\n", + "* Use an agent to execute a function from an `arbitrum` smart contract\n", "\n", - "Now this same steps can be followed to use any other network supported by `ape` and interact with different chains." + "Now these same steps can be followed to use any other network supported by `ape` and interact with different chains." ] } ], diff --git a/examples/ezkl/linear_regression/README.md b/examples/ezkl/linear_regression/README.md index d4531f4..38e6610 100644 --- a/examples/ezkl/linear_regression/README.md +++ b/examples/ezkl/linear_regression/README.md @@ -1,14 +1,14 @@ -# Train a Linear Regression Using EZKL backend +# Train a Linear Regression Using the EZKL backend This example demonstrates how to train a linear regression model using the EZKL backend. -First, install the `torch`, `hummingbird-ml` and `scikit-learn` packages by running the following command: +First, install the `torch`, `hummingbird-ml`, and `scikit-learn` packages by running the following command: ```bash pip install torch hummingbird-ml scikit-learn ``` -This example uses the `scikit-learn` package to train a linear regression model and the `hummingbird-ml` package to convert the trained model to `torch` and then into ONNX, this is to maximize compatibiloity with `ezkl`. +This example uses the `scikit-learn` package to train a linear regression model and the `hummingbird-ml` package to convert the trained model to `torch` and then into ONNX, this is to maximize compatibility with `ezkl`. The code can be found in the [train_linear_regression.py](train_linear_regression.py) file, but we will explain each step. @@ -66,9 +66,9 @@ Now that we have a torch model, we can export it to ONNX using the default utili ) ``` -## Create a `input.json` file for transpilation +## Create an `input.json` file for transpilation -For the transpilation we need an example of the input data, in this case we will use the `sample` variable to create the `input.json` file: +For the transpilation we need an example of the input data. In this case, we will use the `sample` variable to create the `input.json` file: ```python with open("input.json", "w") as f: @@ -82,7 +82,7 @@ with open("input.json", "w") as f: ) ``` -## Deploy the verifiable model using EZKL framework +## Deploy the verifiable model using the EZKL framework The first step is to use the `giza-cli` to transpile the model and create a version job. Once this job finishes we will be able to deploy the model as a service. @@ -104,7 +104,7 @@ Using the `predict_action.py` you can add the generated `model_id` and `version_ python predict_action.py ``` -This will start the action to perform the prediction, it includes two tasks, an example of how to perform a prediction using the `GizaModel`: +This will start the action to perform the prediction. It includes two tasks, an example of how to perform a prediction using the `GizaModel`: ```python model = GizaModel(id=MODEL_ID, version=VERSION) @@ -114,4 +114,4 @@ result, request_id = model.predict(input_feed=[7, 2], verifiable=True, job_size= print(f"Result: {result}, request_id: {request_id}") ``` -The latter will take the request and wait for the proof to be created, check the script for [more information](predict_action.py). +The latter will take the request and wait for the proof to be created. Check the script for [more information](predict_action.py). \ No newline at end of file diff --git a/examples/traditional-ml/decision_tree.ipynb b/examples/traditional-ml/decision_tree.ipynb index 18c719f..11bc96f 100644 --- a/examples/traditional-ml/decision_tree.ipynb +++ b/examples/traditional-ml/decision_tree.ipynb @@ -6,9 +6,9 @@ "source": [ "# Traditional ML Models for ZKML: Decision Tree\n", "\n", - "*In this series of tutorial, we delve into the world of traditional machine learning models for ZKML. Despite the hype surrounding advanced AI techniques, traditional ML models often offer superior performance or sufficiently robust results for specific applications. This is particularly true for ZKML use cases, where computational proof costs can be a critical factor. Our aim is to equip you with guides on how to implement machine learning algorithms suitable for Giza platform applications. This includes practical steps for converting your scikit-learn models to the ONNX format, transpiling them to Orion Cairo, and deploying inference endpoints for prediction in AI Action.*\n", + "*In this series of tutorials, we delve into the world of traditional machine learning models for ZKML. Despite the hype surrounding advanced AI techniques, traditional ML models often offer superior performance or sufficiently robust results for specific applications. This is particularly true for ZKML use cases, where computational proof costs can be a critical factor. We aim to equip you with guides on how to implement machine learning algorithms suitable for Giza platform applications. This includes practical steps for converting your scikit-learn models to the ONNX format, transpiling them to Orion Cairo, and deploying inference endpoints for prediction in AI Action.*\n", "\n", - "In this tutorial you will learn how to use the Giza tools though a Decision Tree model." + "In this tutorial, you will learn how to use the Giza tools through a Decision Tree model." ] }, { @@ -16,7 +16,7 @@ "metadata": {}, "source": [ "## Before Starting\n", - "Before we start, ensure you installed the Giza stack, created a user and logged-in. " + "Before we start, ensure that you have installed the Giza stack, created a user, and logged-in. " ] }, { @@ -42,7 +42,7 @@ "metadata": {}, "source": [ "## Create and Train a Decision Tree Model\n", - "We'll start by creating a simple decision tree model using Scikit-Learn and train on iris dataset. We will then use [Hummingbirds](https://github.com/microsoft/hummingbird) library to convert the model to torch graphs." + "We'll start by creating a simple decision tree model using Scikit-Learn and train it on the iris dataset. We will then use the [Hummingbirds](https://github.com/microsoft/hummingbird) library to convert the model to torch graphs." ] }, { @@ -77,7 +77,7 @@ "metadata": {}, "source": [ "## Convert the Model to ONNX Format\n", - "Giza only supports ONNX models so you'll need to convert the model to ONNX format. After the model is trained, you can convert it to ONNX format." + "Giza only supports ONNX models so you'll need to convert the model to ONNX format. This can be done post training." ] }, { @@ -112,7 +112,7 @@ "source": [ "## Transpile your model to Orion Cairo\n", "\n", - "We will use Giza-CLI to transpile our ONNX model to Orion Cairo." + "We will use the Giza-CLI to transpile our ONNX model to Orion Cairo." ] }, { @@ -151,7 +151,7 @@ "source": [ "## Deploy an inference endpoint\n", "\n", - "Now that our model is transpiled to Cairo we can deploy an endpoint to run verifiable inferences. We will use Giza CLI again to run deploy an endpoint.\n", + "Now that our model is transpiled to Cairo we can deploy an endpoint to run verifiable inferences. We will use Giza CLI again to run and deploy an endpoint.\n", "Ensure to replace `model-id` and `version-id` with your ids provided during transpilation." ] }, @@ -185,7 +185,7 @@ "source": [ "## Run a verifiable inference in AI Actions\n", "\n", - "To streamline verifiable inference, you might consider using the endpoint URL obtained after transpilation. However, this approach requires manual serialization of the input for the Cairo program and handling the deserialization process. To make this process more user-friendly and keep you within a Python environment, we've introduced AI Actions—a Python SDK designed to facilitate the creation of ML workflows and execution of verifiable predictions. When you initiate a prediction, our system automatically retrieves the endpoint URL you deployed earlier, converts your input into Cairo-compatible format, executes the prediction, and then converts the output back into a numpy object. More info about [AI Actions here.](https://actions.gizatech.xyz/)" + "To streamline a verifiable inference, you might consider using the endpoint URL obtained after transpilation. However, this approach requires manual serialization of the input for the Cairo program and handling the deserialization process. To make this process more user-friendly and keep you within a Python environment, we've introduced AI Actions—a Python SDK designed to facilitate the creation of ML workflows and execution of verifiable predictions. When you initiate a prediction, our system automatically retrieves the endpoint URL you deployed earlier, converts your input into Cairo-compatible format, executes the prediction, and then converts the output back into a numpy object. More info about [AI Actions here.](https://actions.gizatech.xyz/)" ] }, { @@ -228,7 +228,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Now let's run a verifiable inference with AI Actions. To design your workflow in AI Actions, you will need to define your task with `@task` decorator and then action your tasks with `@action` decorator. You can track the progress of your workflow via the workspace URL previously provided." + "Now let's run a verifiable inference with AI Actions. To design your workflow in AI Actions, you will need to define your task with the `@task` decorator and then action your tasks with the `@action` decorator. You can track the progress of your workflow via the workspace URL previously provided." ] }, { diff --git a/examples/traditional-ml/linear_regression.ipynb b/examples/traditional-ml/linear_regression.ipynb index 8435247..cd96fd9 100644 --- a/examples/traditional-ml/linear_regression.ipynb +++ b/examples/traditional-ml/linear_regression.ipynb @@ -6,7 +6,7 @@ "source": [ "# Traditional ML Models for ZKML: Linear Regression\n", "\n", - "*In this series of tutorial, we delve into the world of traditional machine learning models for ZKML. Despite the hype surrounding advanced AI techniques, traditional ML models often offer superior performance or sufficiently robust results for specific applications. This is particularly true for ZKML use cases, where computational proof costs can be a critical factor. Our aim is to equip you with guides on how to implement machine learning algorithms suitable for Giza platform applications. This includes practical steps for converting your scikit-learn models to the ONNX format, transpiling them to Orion Cairo, and deploying inference endpoints for prediction in AI Action.*\n", + "*In this series of tutorials, we delve into the world of traditional machine learning models for ZKML. Despite the hype surrounding advanced AI techniques, traditional ML models often offer superior performance or sufficiently robust results for specific applications. This is particularly true for ZKML use cases, where computational proof costs can be a critical factor. We aim to equip you with guides on how to implement machine learning algorithms suitable for Giza platform applications. This includes practical steps for converting your scikit-learn models to the ONNX format, transpiling them to Orion Cairo, and deploying inference endpoints for prediction in AI Action.*\n", "\n", "In this tutorial you will learn how to use the Giza tools though a Linear Regression model." ] @@ -16,7 +16,7 @@ "metadata": {}, "source": [ "## Before Starting\n", - "Before we start, ensure you installed the Giza stack, created a user and logged-in. " + "Before we start, ensure that you have installed the Giza stack, created a user, and logged-in. " ] }, { @@ -559,7 +559,7 @@ "source": [ "## Deploy an inference endpoint\n", "\n", - "Now that our model is transpiled to Cairo we can deploy an endpoint to run verifiable inferences. We will use Giza CLI again to run deploy an endpoint.\n", + "Now that our model is transpiled to Cairo we can deploy an endpoint to run verifiable inferences. We will use Giza CLI again to run and deploy an endpoint.\n", "Ensure to replace `model-id` and `version-id` with your ids provided during transpilation." ] }, @@ -593,7 +593,7 @@ "source": [ "## Run a verifiable inference in AI Actions\n", "\n", - "To streamline verifiable inference, you might consider using the endpoint URL obtained after transpilation. However, this approach requires manual serialization of the input for the Cairo program and handling the deserialization process. To make this process more user-friendly and keep you within a Python environment, we've introduced AI Actions—a Python SDK designed to facilitate the creation of ML workflows and execution of verifiable predictions. When you initiate a prediction, our system automatically retrieves the endpoint URL you deployed earlier, converts your input into Cairo-compatible format, executes the prediction, and then converts the output back into a numpy object. More info about [AI Actions here.](https://actions.gizatech.xyz/)" + "To streamline a verifiable inference, you might consider using the endpoint URL obtained after transpilation. However, this approach requires manual serialization of the input for the Cairo program and handling the deserialization process. To make this process more user-friendly and keep you within a Python environment, we've introduced AI Actions—a Python SDK designed to facilitate the creation of ML workflows and execution of verifiable predictions. When you initiate a prediction, our system automatically retrieves the endpoint URL you deployed earlier, converts your input into Cairo-compatible format, executes the prediction, and then converts the output back into a numpy object. More info about [AI Actions here.](https://actions.gizatech.xyz/)" ] }, { @@ -636,7 +636,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Now let's run a verifiable inference with AI Actions. To design your workflow in AI Actions, you will need to define your task with `@task` decorator and then action your tasks with `@action` decorator. You can track the progress of your workflow via the workspace URL previously provided." + "Now let's run a verifiable inference with AI Actions. To design your workflow in AI Actions, you will need to define your task with the `@task` decorator and then action your tasks with the `@action` decorator. You can track the progress of your workflow via the workspace URL previously provided." ] }, { diff --git a/examples/verifiable_mnist/verifiable_mnist.ipynb b/examples/verifiable_mnist/verifiable_mnist.ipynb index dbb8c4e..9fb8890 100644 --- a/examples/verifiable_mnist/verifiable_mnist.ipynb +++ b/examples/verifiable_mnist/verifiable_mnist.ipynb @@ -13,14 +13,14 @@ "source": [ "Giza Actions provides developers with the tools to easily create and expand Verifiable Machine Learning solutions, transforming their Python scripts and ML models into robust, repeatable workflows. Models developed using the Action SDK possess a verifiable property, enabling you to encapsulate your model within a Zero-Knowledge cryptographic layer, thereby ensuring the integrity of the inference.\n", "\n", - "In this tutorial, we will explore the process of building your first Neural Network using MNIST dataset, [Pytorch](https://pytorch.org/), and Giza Action SDK and demonstrating its verifiability." + "In this tutorial, we will explore the process of building your first Neural Network using the MNIST dataset, [Pytorch](https://pytorch.org/), and Giza Action SDK and demonstrate its verifiability." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "# What is MNIST dataset?" + "# What is the MNIST dataset?" ] }, { @@ -29,7 +29,7 @@ "source": [ "The MNIST dataset is an extensive collection of handwritten digits, very popular in the field of image processing. Often, it's used as a reference point for machine learning algorithms. This dataset conveniently comes already partitioned into training and testing sets, a feature we'll delve into later in this tutorial.\n", "\n", - "The MNIST database comprises a collection of 70,000 images of handwritten digits, ranging from 0 to 9. Each image measures 28 x 28 pixels. For the purpose of this tutorial, we will resize image to 14 x 14 pixels.\n", + "The MNIST database comprises a collection of 70,000 images of handwritten digits, ranging from 0 to 9. Each image measures 28 x 28 pixels. For this tutorial, we will resize the image to 14 x 14 pixels.\n", "\n", "![MNIST Dataset illustration](./imgs/mnist_dataset_illustration.png)" ] @@ -161,7 +161,7 @@ "metadata": {}, "source": [ "### Prepare datasets and create loaders\n", - "We need to download datasets and create loarders for both training and testing purposes." + "We need to download datasets and create loaders for both training and testing purposes." ] }, { @@ -292,7 +292,7 @@ "source": [ "# Action the tasks\n", "\n", - "Now that we've prepared the taks, we need to execute them. This will be done using the `action` decorator." + "Now that we've prepared the tasks, we need to execute them. This will be done using the `action` decorator." ] }, { @@ -1000,7 +1000,7 @@ "\n", "To generate ZK proofs for your model inferences, you must first convert your model into ZK circuits. This conversion process involves leveraging programming languages that specialize in building ZK circuits, such as [Cairo-lang](https://www.cairo-lang.org/). Subsequently, using the Giza-CLI, you can transpile your model from ONNX to Cairo. This process will be covered in the upcoming sections.\n", "\n", - "It's worth mentioning that at present, Orion and Action-SDK exclusively supports Cairo as a ZK backend. However, we are actively working on expanding support for other ZK backends (e.g; EZKL, Noir ...).\n", + "It's worth mentioning that at present, Orion and Action-SDK exclusively support Cairo as a ZK backend. However, we are actively working on expanding support to other ZK backends (e.g; EZKL, Noir ...).\n", "\n", "![Giza Stack](./imgs/giza_stack.png)" ] @@ -1699,7 +1699,7 @@ "```\n", "\n", "### Step 2: Deploy Your Model\n", - "Thanks to full support for all operators used by MNIST model in the transpiler, your transpilation process is completely compatible. This ensures that your project compiles smoothly and has already been compiled behind the scenes on our platform. \n", + "Thanks to the full support for all operators used by the MNIST model in the transpiler, your transpilation process is completely compatible. This ensures that your project compiles smoothly and has already been compiled behind the scenes on our platform. \n", "\n", "🚨: If your model incorporates operators that aren't supported by the transpiler, you may need to refine your Cairo project to ensure successful compilation. For more details, refer to the to [how-to-guide](https://actions.gizatech.xyz/how-to-guides/gizamodel#executing-verifiable-inference-with-gizamodel-and-onnx).\n", "\n", @@ -1730,7 +1730,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "First, let's make a prediction with the ONNX model (`veriable=False`) " + "First, let's make a prediction with the ONNX model (`verifiable=False`) " ] }, { @@ -1956,7 +1956,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Now, let's make a prediction with the Cairo model (`veriable=True`)." + "Now, let's make a prediction with the Cairo model (`verifiable=True`)." ] }, { @@ -2248,7 +2248,7 @@ "metadata": {}, "source": [ "Now, let's verify the proof!\n", - "All you need to do is simply running: \n", + "All you need to do is simply run: \n", "```bash\n", "giza verify --proof PATH_TO_PROOF\n", "```" @@ -2258,7 +2258,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Voilà 🎉! You've learned how to use the entire Giza stack, from training your model to transpiling it to Cairo for verifiable execution. You've also learned how to verify the proof. We hope you've enjoyed this journey! If you have any questions, please feel free to join us in our [Discord](https://discord.gg/zF2dxSYk6Z), or [open an issue](https://github.com/gizatechxyz/actions-sdk/issues). " + "Voilà 🎉! You've learned how to use the entire Giza stack, from training your model to transpiling it to Cairo for verifiable execution. You've also learned how to verify the proof. We hope you've enjoyed this journey! If you have any questions, please feel free to join us on our [Discord](https://discord.gg/zF2dxSYk6Z), or [open an issue](https://github.com/gizatechxyz/actions-sdk/issues). " ] } ], diff --git a/giza_actions/utils.py b/giza_actions/utils.py index b602582..5fc38fb 100644 --- a/giza_actions/utils.py +++ b/giza_actions/utils.py @@ -25,7 +25,7 @@ def get_workspace_uri(): except requests.exceptions.RequestException: logger.error("Failed to retrieve workspace") logger.error( - "Please check that you have create a workspaces using the Giza CLI" + "Please check that you have created a workspaces using the Giza CLI" ) raise return workspace.url